mdk-skills 2.2.0 → 2.2.2

package/.claude/backups/20260510.145651/skills/v3-fe-biz-patterns/references/tab-anchor.md

@@ -0,0 +1,1125 @@
+# TabAnchor 锚点 Tab 组件
+
+## 概述
+
+TabAnchor 是一个带锚点滚动功能的 Tab 组件，支持：
+
+- 自动 / 手动两种模式
+- 水平栏 / 侧边栏两种布局
+- slide / scale 两种指示器样式
+- sticky 吸顶 / float 浮动两种定位方式
+- floatThreshold 阈值控制浮动栏显示时机
+- IntersectionObserver 自动追踪可见 section，驱动 activeKey 切换
+- 自定义 Tab 按钮渲染
+
+**文件构成：**
+
+| 文件 | 职责 |
+|------|------|
+| `src/components/TabAnchor.vue` | 组件入口：模板、逻辑、样式 |
+| `src/hooks/useTabAnchor.ts` | 核心锚点滚动逻辑（IntersectionObserver、scrollIntoView） |
+| `src/hooks/useTabFloat.ts` | 浮动模式（position: fixed + 阈值控制） |
+| `src/hooks/useTabIndicator.ts` | 滑动指示器位置计算 |
+| `src/types/anchor.ts` | 类型定义 |
+
+## 完整源码
+
+### types/anchor.ts
+
+```ts
+/** Tab 配置项 */
+export interface TabItem<T extends string | number = string> {
+  /** 显示文案 */
+  label: string
+  /** 唯一标识 */
+  key: T
+  /** 是否禁用 */
+  disabled?: boolean
+}
+
+/** Tab 栏布局方向 */
+export type TabLayout = 'top' | 'left'
+
+/** 滑动指示器类型 */
+export type IndicatorType = 'slide' | 'scale'
+
+/** TabAnchor 组件 Props */
+export interface TabAnchorProps<T extends string | number = string> {
+  /** Tab 配置数组 */
+  tabs: TabItem<T>[]
+  /** 当前激活的 key（v-model） */
+  modelValue?: T
+  /** 默认激活的 key */
+  defaultActiveKey?: T
+  /** 是否吸顶 */
+  sticky?: boolean
+  /** 吸顶偏移量 */
+  stickyTop?: number
+  /** 手动模式——组件只渲染 Tab 栏，内容由外部管理 */
+  manual?: boolean
+  /** 手动模式下，接收外部内容区元素的 refs 数组（支持 Ref 或普通数组） */
+  contentRefs?: import('vue').MaybeRef<(HTMLElement | null)[]>
+  /** 滚动容器元素，用于局部滚动容器（如 overflow:auto 的父容器） */
+  scrollContainer?: HTMLElement | null
+  /** 滑动指示器类型，默认 slide */
+  indicatorType?: IndicatorType
+  /** 滑动指示器颜色，默认 red */
+  color?: string
+  /** 布局方向：top（上方栏）| left（左侧栏），默认 top */
+  layout?: TabLayout
+  /** 滚动到内容区时额外的顶部偏移像素，在 stickyTop + tabBar 高度基础上追加 */
+  scrollOffset?: number
+
+  /** 是否启用浮动模式（position: fixed），脱离文档流固定在视口位置 */
+  float?: boolean
+  /** 浮动模式下 left 布局的手动 left 偏移，不传则自动取元素初始位置 */
+  floatLeft?: number
+  /** 滚动超过此高度(px)后显示浮动栏，默认 0 表示一直显示 */
+  floatThreshold?: number
+}
+```
+
+### useTabAnchor.ts
+
+```ts
+import { ref, shallowRef, computed, watch, onMounted, onUnmounted } from 'vue'
+import type { Ref, MaybeRef } from 'vue'
+import { unref } from 'vue'
+import type { TabItem } from '@/types/anchor'
+
+interface UseTabAnchorOptions<T extends string | number = string> {
+  /** Tab 配置数组 */
+  tabs: MaybeRef<TabItem<T>[]>
+  /** 各 tab 对应的内容区 DOM 引用 */
+  contentRefs: Ref<(HTMLElement | null)[]>
+  /** 受控的 activeKey（v-model） */
+  activeKey?: Ref<T>
+  /** 默认激活的 key */
+  defaultActiveKey?: T
+  /** sticky Tab 栏高度 + stickyTop 偏移 */
+  headerOffset?: MaybeRef<number>
+  /** 点击滚动时内容区的 scroll-margin-top 补偿 */
+  scrollMarginTop?: MaybeRef<number>
+  /** 滚动容器引用，作为 IntersectionObserver 的 root */
+  scrollContainer?: Ref<HTMLElement | null>
+}
+
+interface UseTabAnchorReturn<T> {
+  /** 当前激活的 key */
+  activeKey: Ref<T>
+  /** 是否正在动画滚动中（用于防连点） */
+  isScrolling: Ref<boolean>
+  /** 滚动到指定 Tab 对应的内容区 */
+  scrollToTab: (key: T) => void
+}
+
+export function useTabAnchor<T extends string | number = string>(
+  options: UseTabAnchorOptions<T>,
+): UseTabAnchorReturn<T> {
+  const {
+    tabs: tabsRef,
+    contentRefs,
+    activeKey: externalActiveKey,
+    defaultActiveKey,
+    headerOffset = 0,
+    scrollMarginTop = 0,
+    scrollContainer,
+  } = options
+
+  const tabList = computed(() => unref(tabsRef))
+
+  // 优先用外部受控 key，否则内部维护
+  const internalActiveKey = shallowRef<T>((defaultActiveKey ?? tabList.value[0]?.key ?? '') as T)
+  const activeKey = (externalActiveKey ?? internalActiveKey) as Ref<T>
+  const isScrolling = ref(false)
+
+  let observer: IntersectionObserver | null = null
+  let resizeObserver: ResizeObserver | null = null
+  let scrollTimer: number | null = null
+
+  /* ---------- 获取某个 key 对应的 DOM 元素 ---------- */
+  const getContentEl = (key: T): HTMLElement | null => {
+    const index = tabList.value.findIndex((t) => t.key === key)
+    return contentRefs.value[index] ?? null
+  }
+
+  /* ---------- 初始化/重建 IntersectionObserver ---------- */
+  const initObserver = () => {
+    destroyObserver()
+
+    const elements: HTMLElement[] = []
+    tabList.value.forEach((_, i) => {
+      const el = contentRefs.value[i]
+      if (el) elements.push(el)
+    })
+    if (elements.length === 0) return
+
+    // rootMargin: 顶部留出 headerOffset，底部留出一半作为触发缓冲
+    const offset = unref(headerOffset)
+    observer = new IntersectionObserver(
+      (entries) => {
+        if (isScrolling.value) return
+
+        // 只取可见元素，按可见面积降序排列
+        const visible = entries
+          .filter((e) => e.isIntersecting)
+          .sort((a, b) => b.intersectionRatio - a.intersectionRatio)
+
+        if (visible.length > 0) {
+          const key = (visible[0]!.target as HTMLElement).dataset.key as T | undefined
+          if (key !== undefined && key !== activeKey.value) {
+            activeKey.value = key
+          }
+        }
+      },
+      {
+        root: scrollContainer?.value ?? null,
+        rootMargin: `-${offset}px 0px -${Math.max(offset * 0.5, 40)}px 0px`,
+        threshold: [0, 0.25, 0.5, 0.75, 1],
+      },
+    )
+    elements.forEach((el) => observer!.observe(el))
+
+    // 内容区尺寸变化时重建 Observer
+    resizeObserver = new ResizeObserver(() => {
+      destroyObserver()
+      initObserver()
+    })
+    const container = contentRefs.value[0]?.parentElement
+    if (container) resizeObserver.observe(container)
+  }
+
+  const destroyObserver = () => {
+    observer?.disconnect()
+    observer = null
+    resizeObserver?.disconnect()
+    resizeObserver = null
+  }
+
+  /* ---------- 点击 Tab 滚动到对应内容区 ---------- */
+  const scrollToTab = (key: T) => {
+    const tab = tabList.value.find((t) => t.key === key)
+    if (!tab || tab.disabled) return
+
+    const el = getContentEl(key)
+    if (!el) return
+
+    isScrolling.value = true
+    activeKey.value = key
+
+    el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+
+    // 根据可视距离估算动画时长，防连点
+    const distance = Math.abs(el.getBoundingClientRect().top - unref(scrollMarginTop))
+    const duration = Math.min(Math.max(distance * 0.3, 200), 600)
+
+    if (scrollTimer !== null) clearTimeout(scrollTimer)
+    scrollTimer = window.setTimeout(() => {
+      isScrolling.value = false
+    }, duration)
+  }
+
+  /* ---------- 数据变化时重建 observer ---------- */
+  watch(
+    [() => tabList.value.length, () => unref(headerOffset)],
+    () => initObserver(),
+  )
+
+  onMounted(() => {
+    initObserver()
+  })
+
+  onUnmounted(() => {
+    destroyObserver()
+    if (scrollTimer !== null) clearTimeout(scrollTimer)
+  })
+
+  return { activeKey, isScrolling, scrollToTab }
+}
+```
+
+### useTabFloat.ts
+
+```ts
+import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
+import type { Ref } from 'vue'
+import type { TabLayout } from '@/types/anchor'
+
+interface UseTabFloatOptions {
+  tabBarRef: Ref<HTMLElement | null>
+  float: Ref<boolean>
+  layout: Ref<TabLayout>
+  stickyTop: Ref<number>
+  floatThreshold: Ref<number>
+  floatLeft: Ref<number | undefined>
+  /** 滚动容器，不传则监听 window */
+  scrollContainer?: Ref<HTMLElement | null>
+}
+
+export function useTabFloat(options: UseTabFloatOptions) {
+  const { tabBarRef, float, layout, stickyTop, floatThreshold, floatLeft, scrollContainer } =
+    options
+
+  /* 阈值 > 0 时初始隐藏，否则一直可见 */
+  const floatVisible = ref(floatThreshold.value <= 0)
+  /* 左侧布局下浮动的 left 值（自动取元素初始位置 / 用户指定） */
+  const floatLeftValue = ref(0)
+
+  /* 浮动栏定位样式 */
+  const tabBarStyle = computed(() => {
+    if (!float.value) return null
+
+    const style: Record<string, string | number> = {
+      position: 'fixed',
+      top: `${stickyTop.value}px`,
+      zIndex: 1000,
+    }
+    if (layout.value === 'left') {
+      style.left = `${floatLeftValue.value}px`
+    } else {
+      style.left = '0'
+      style.right = '0'
+      style.width = '100%'
+    }
+    return style
+  })
+
+  /* 浮动占位元素尺寸 */
+  const tabBarHeight = computed(() => tabBarRef.value?.offsetHeight ?? 44)
+
+  /* mount 后初始化：监听滚动、计算 left 值 */
+  onMounted(() => {
+    if (!float.value) return
+
+    // 无阈值（一直显示）时，直接测量 left 位置
+    if (layout.value === 'left' && floatThreshold.value <= 0) {
+      floatLeftValue.value = floatLeft.value ?? tabBarRef.value?.getBoundingClientRect().left ?? 0
+    }
+
+    // 阈值控制：监听滚动位置
+    if (floatThreshold.value > 0) {
+      const container = scrollContainer?.value ?? window
+
+      const update = () => {
+        const top =
+          container === window
+            ? window.scrollY || document.documentElement.scrollTop
+            : (container as HTMLElement).scrollTop
+        floatVisible.value = top > floatThreshold.value
+      }
+
+      update() // 初始化
+      container.addEventListener('scroll', update, { passive: true })
+      onUnmounted(() => container.removeEventListener('scroll', update))
+    }
+  })
+
+  /* 有阈值时：首次显示浮动栏再测量 left 位置（此时元素可见，rect 才有效） */
+  watch(floatVisible, (visible) => {
+    if (visible && layout.value === 'left' && floatThreshold.value > 0 && floatLeftValue.value === 0) {
+      floatLeftValue.value = floatLeft.value ?? tabBarRef.value?.getBoundingClientRect().left ?? 0
+    }
+  })
+
+  return { tabBarStyle, tabBarHeight, floatVisible }
+}
+```
+
+### useTabIndicator.ts
+
+```ts
+import { ref, watch, nextTick } from 'vue'
+import type { Ref } from 'vue'
+import type { IndicatorType, TabLayout } from '@/types/anchor'
+
+interface UseTabIndicatorOptions {
+  /** Tab 栏 DOM 引用 */
+  tabBarRef: Ref<HTMLElement | null>
+  /** 当前激活 key */
+  activeKey: Ref<string | number>
+  /** 指示器类型，非 slide 模式不计算位置 */
+  indicatorType: IndicatorType
+  /** 布局方向，影响指示器运动轴（水平/垂直） */
+  layout: TabLayout
+}
+
+/**
+ * 滑动指示器位置计算
+ * 监听 activeKey 变化，计算激活 tab 在 tabBar 中的偏移位置，
+ * 通过 translate 驱动指示器跟随动画，支持 top/left 两种布局。
+ */
+export function useTabIndicator(options: UseTabIndicatorOptions) {
+  const { tabBarRef, activeKey, indicatorType, layout } = options
+
+  const isHorizontal = layout !== 'left'
+  const indicatorStyle = ref<Record<string, string>>(
+    isHorizontal
+      ? { width: '0', transform: 'translateX(0)' }
+      : { height: '0', transform: 'translateY(0)' },
+  )
+
+  watch(
+    activeKey,
+    async () => {
+      if (indicatorType !== 'slide') return
+      await nextTick()
+      if (!tabBarRef.value) return
+      const activeEl = tabBarRef.value.querySelector('.tab-item--active') as HTMLElement | null
+      if (!activeEl) return
+
+      const parentRect = tabBarRef.value.getBoundingClientRect()
+      const rect = activeEl.getBoundingClientRect()
+
+      if (layout === 'left') {
+        indicatorStyle.value = {
+          height: `${rect.height * 0.6}px`,
+          transform: `translateY(${rect.top - parentRect.top + rect.height * 0.2}px)`,
+        }
+      } else {
+        indicatorStyle.value = {
+          width: `${rect.width * 0.6}px`,
+          transform: `translateX(${rect.left - parentRect.left + rect.width * 0.2}px)`,
+        }
+      }
+    },
+    { immediate: true },
+  )
+
+  return { indicatorStyle }
+}
+```
+
+### TabAnchor.vue
+
+```vue
+<template>
+  <div ref="containerRef" class="tab-anchor" :class="{ 'tab-anchor--left': layout === 'left' }">
+    <!-- ==================== 浮动占位（防止布局塌陷） ==================== -->
+    <div
+      v-if="float && floatVisible"
+      class="tab-bar-placeholder"
+      :class="{ 'tab-bar-placeholder--left': layout === 'left' }"
+    />
+
+    <!-- ==================== Tab 栏 ==================== -->
+    <div
+      ref="tabBarRef"
+      class="tab-bar"
+      :class="{
+        'tab-bar--sticky': sticky && !float,
+        'tab-bar--float': float,
+        'tab-bar--scale': indicatorType === 'scale',
+        'tab-bar--left': layout === 'left',
+      }"
+      :style="tabBarStyle"
+      v-show="!float || floatVisible"
+    >
+      <button
+        v-for="tab in tabs"
+        :key="tab.key"
+        class="tab-item"
+        :class="{
+          'tab-item--active': activeKey === tab.key,
+          'tab-item--disabled': tab.disabled,
+        }"
+        :disabled="tab.disabled"
+        @click="scrollToTab(tab.key)"
+      >
+        <slot name="tab" :item="tab" :active="activeKey === tab.key" :index="tabs.indexOf(tab)">
+          <span class="tab-label">{{ tab.label }}</span>
+        </slot>
+      </button>
+
+      <!-- 滑动指示器（仅 slide 模式） -->
+      <span v-if="indicatorType === 'slide'" class="tab-indicator" :style="indicatorStyle" />
+    </div>
+
+    <!-- ==================== 内容区（自动模式） ==================== -->
+    <div v-if="!manual" class="tab-content" :class="{ 'tab-content--left': layout === 'left' }">
+      <section
+        v-for="(tab, i) in tabs"
+        :key="tab.key"
+        :ref="(el: any) => setContentRef(el, i)"
+        :data-key="tab.key"
+        class="tab-section"
+        :style="{ scrollMarginTop: `${scrollMarginTop}px` }"
+      >
+        <slot :item="tab" :index="i" />
+      </section>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts" generic="T extends string | number">
+import { ref, computed, toValue } from 'vue'
+import type { TabAnchorProps } from '@/types/anchor'
+import { useTabAnchor } from '@/hooks/useTabAnchor'
+import { useTabIndicator } from '@/hooks/useTabIndicator'
+import { useTabFloat } from '@/hooks/useTabFloat'
+
+/* ==================== 组件接口 ==================== */
+
+const props = withDefaults(defineProps<TabAnchorProps<T>>(), {
+  sticky: false,
+  stickyTop: 0,
+  manual: false,
+  indicatorType: 'slide',
+  color: 'red',
+  layout: 'top',
+  float: false,
+  floatThreshold: 0,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: T]
+}>()
+
+/* ==================== DOM 引用 ==================== */
+
+const containerRef = ref<HTMLElement | null>(null)
+const tabBarRef = ref<HTMLElement | null>(null)
+const contentRefs = ref<(HTMLElement | null)[]>([])
+
+/* ==================== 滚动容器解析 ==================== */
+/* 优先级：外部传入 > 父级可滚动元素 > 组件自身 */
+
+const scrollContainer = computed(
+  () => props.scrollContainer ?? containerRef.value?.parentElement ?? containerRef.value,
+)
+
+/* ==================== 浮动模式 ==================== */
+
+const { tabBarStyle: floatStyle, tabBarHeight, floatVisible } = useTabFloat({
+  tabBarRef,
+  float: computed(() => props.float),
+  layout: computed(() => props.layout),
+  stickyTop: computed(() => props.stickyTop),
+  floatThreshold: computed(() => props.floatThreshold),
+  floatLeft: computed(() => props.floatLeft),
+  scrollContainer: scrollContainer,
+})
+
+/* float 优先，fallback 到 sticky */
+const tabBarStyle = computed(() => {
+  if (props.float) return floatStyle.value
+  if (props.sticky) return { top: `${props.stickyTop}px`, zIndex: 10 }
+  return undefined
+})
+
+/* ==================== 内容区引用管理 ==================== */
+/* 自动模式：收集模板中 section 的 DOM 引用到数组；手动模式：使用外部传入的 contentRefs */
+
+const setContentRef = (el: any, index: number) => {
+  contentRefs.value[index] = el as HTMLElement | null
+}
+
+const resolvedContentRefs = computed(() =>
+  props.manual && props.contentRefs ? toValue(props.contentRefs) : contentRefs.value,
+)
+
+/* sticky 吸顶 + tab 栏高度偏移量，用于 IntersectionObserver rootMargin 和 scrollIntoView 补偿 */
+const headerOffset = computed(() => {
+  if (props.layout === 'left') return props.stickyTop
+  return props.stickyTop + (tabBarRef.value?.offsetHeight ?? 44)
+})
+
+/* ==================== ActiveKey 双向绑定 ==================== */
+
+const activeKey = computed({
+  get: () => props.modelValue ?? ((props.tabs[0]?.key ?? '') as T),
+  set: (val: T) => emit('update:modelValue', val),
+})
+
+/* ==================== 滑动指示器 ==================== */
+
+const { indicatorStyle } = useTabIndicator({
+  tabBarRef,
+  activeKey,
+  indicatorType: props.indicatorType,
+  layout: props.layout,
+})
+
+const indicatorColor = computed(() => props.color)
+
+/* ==================== 核心锚点滚动逻辑 ==================== */
+
+const scrollMarginTop = computed(() => headerOffset.value + (props.scrollOffset ?? 0))
+
+const { scrollToTab } = useTabAnchor({
+  tabs: computed(() => props.tabs),
+  contentRefs: resolvedContentRefs,
+  activeKey,
+  headerOffset,
+  scrollMarginTop,
+  scrollContainer: scrollContainer,
+})
+
+/* ==================== 暴露方法 ==================== */
+
+defineExpose({ scrollToTab })
+</script>
+
+<style scoped>
+.tab-anchor {
+  position: relative;
+}
+
+/* ===== Tab 栏 ===== */
+.tab-bar {
+  display: flex;
+  align-items: stretch;
+  position: relative;
+  background: #fff;
+  border-bottom: 1px solid #f0f0f0;
+  width: 100%;
+  overflow-x: auto;
+  scrollbar-width: none;
+}
+
+.tab-bar::-webkit-scrollbar {
+  display: none;
+}
+
+.tab-bar--sticky {
+  position: sticky;
+}
+
+/* ===== 浮动模式 ===== */
+.tab-bar--float {
+  position: fixed;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.tab-bar--float.tab-bar--left {
+  box-shadow: 2px 0 8px rgba(0, 0, 0, 0.1);
+}
+
+/* 浮动占位元素：防止布局塌陷 */
+.tab-bar-placeholder {
+  height: v-bind('tabBarHeight + "px"');
+}
+
+.tab-bar-placeholder--left {
+  width: var(--tab-bar-width);
+  height: auto;
+  flex-shrink: 0;
+}
+
+/* ===== 单个 Tab ===== */
+.tab-item {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 12px 8px;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  color: #666;
+  font-size: 14px;
+  line-height: 1.4;
+  transition: color 0.25s;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+}
+
+.tab-item:hover {
+  color: #333;
+}
+
+.tab-item--active {
+  color: #333;
+  font-weight: 600;
+}
+
+.tab-item--disabled {
+  color: #ccc;
+  cursor: not-allowed;
+}
+
+.tab-label {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ===== 滑动指示器 ===== */
+.tab-indicator {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  height: 2px;
+  border-radius: 1px;
+  background: v-bind('indicatorColor');
+  transition:
+    transform 0.3s cubic-bezier(0.25, 0.1, 0.25, 1),
+    width 0.3s cubic-bezier(0.25, 0.1, 0.25, 1);
+  pointer-events: none;
+}
+
+/* ===== Scale 模式：每个 tab 自带伪元素指示器 ===== */
+.tab-bar--scale .tab-item {
+  position: relative;
+}
+
+.tab-bar--scale .tab-item::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 25%;
+  right: 25%;
+  height: 2px;
+  border-radius: 1px;
+  background: v-bind('indicatorColor');
+  transform: scaleX(0);
+  transition: transform 0.3s cubic-bezier(0.25, 0.1, 0.25, 1);
+}
+
+.tab-bar--scale .tab-item--active::after {
+  transform: scaleX(1);
+}
+
+/* ===== 内容区 ===== */
+.tab-content {
+  position: relative;
+  flex: 1;
+}
+
+/* ====================================================
+   左侧布局
+   ==================================================== */
+.tab-anchor--left {
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+  --tab-bar-width: 85px;
+}
+
+.tab-bar--left {
+  flex-direction: column;
+  width: var(--tab-bar-width);
+  flex-shrink: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+  border-bottom: none;
+  border-right: 1px solid #f0f0f0;
+}
+
+.tab-bar--left .tab-item {
+  flex: none;
+  width: 100%;
+  padding: 14px 8px;
+}
+
+/* 左侧布局滑动指示器 → 右侧竖条 */
+.tab-bar--left .tab-indicator {
+  bottom: auto;
+  top: 0;
+  left: auto;
+  right: 0;
+  width: 2px;
+  height: 20px;
+  transition:
+    transform 0.3s cubic-bezier(0.25, 0.1, 0.25, 1),
+    height 0.3s cubic-bezier(0.25, 0.1, 0.25, 1);
+}
+
+/* 左侧布局 Scale 指示器 */
+.tab-bar--scale.tab-bar--left .tab-item::after {
+  bottom: auto;
+  top: 25%;
+  bottom: 25%;
+  left: auto;
+  right: 0;
+  width: 2px;
+  height: auto;
+  transform: scaleY(0);
+}
+
+.tab-bar--scale.tab-bar--left .tab-item--active::after {
+  transform: scaleY(1);
+}
+
+/* sticky 吸左 */
+.tab-bar--sticky.tab-bar--left {
+  position: sticky;
+  top: v-bind('stickyTop + "px"');
+}
+</style>
+```
+
+## 核心机制说明
+
+### IntersectionObserver 自动追踪
+
+组件通过 `useTabAnchor` 创建 IntersectionObserver，监听各内容区 section 的可见性：
+
+- **root**：取 `props.scrollContainer` 或父级可滚动元素
+- **rootMargin**：`-${offset}px 0px -${Math.max(offset * 0.5, 40)}px 0px`，顶部切除 Tab 栏高度，底部留缓冲
+- **threshold**：`[0, 0.25, 0.5, 0.75, 1]` 精细追踪
+- **排序**：可见元素按 `intersectionRatio` 降序取最大的
+- **防连点**：动画滚动期间 `isScrolling = true`，跳过 Observer 回调
+
+### scrollIntoView 点击滚动
+
+点击 Tab 按钮时调用 `el.scrollIntoView({ behavior: 'smooth', block: 'start' })`，并估算动画时长防止连点：
+
+```ts
+const distance = Math.abs(el.getBoundingClientRect().top - unref(scrollMarginTop))
+const duration = Math.min(Math.max(distance * 0.3, 200), 600)
+```
+
+### float 浮动模式
+
+- `float` 启用 `position: fixed`
+- `floatThreshold > 0` 时初始隐藏，滚动超过阈值后显示
+- 浮动模式产生占位元素防止布局塌陷
+- float 优先级高于 sticky
+
+### slide 指示器位置计算
+
+- 取 `.tab-item--active` 元素和 `tabBarRef` 的 `getBoundingClientRect`
+- 水平布局：width = 60%，translateX = left offset + 20% width
+- 垂直布局：height = 60%，translateY = top offset + 20% height
+
+## Props 总览
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `tabs` | `TabItem<T>[]` | — | Tab 配置数组 |
+| `modelValue` | `T` | 第一个 tab 的 key | v-model 双向绑定 |
+| `defaultActiveKey` | `T` | 第一个 tab 的 key | 非受控默认值 |
+| `sticky` | `boolean` | `false` | sticky 吸顶 |
+| `stickyTop` | `number` | `0` | 吸顶/浮动偏移量 |
+| `manual` | `boolean` | `false` | 手动模式 |
+| `contentRefs` | `MaybeRef<(HTMLElement\|null)[]>` | — | 手动模式传 refs |
+| `scrollContainer` | `HTMLElement\|null` | 父级滚动元素 | 局部滚动容器 |
+| `indicatorType` | `'slide'\|'scale'` | `'slide'` | 指示器类型 |
+| `color` | `string` | `'red'` | 指示器颜色 |
+| `layout` | `'top'\|'left'` | `'top'` | 布局方向 |
+| `scrollOffset` | `number` | — | 额外偏移补偿 |
+| `float` | `boolean` | `false` | 浮动模式 |
+| `floatLeft` | `number` | — | 左侧浮动 left 值 |
+| `floatThreshold` | `number` | `0` | 浮动显示阈值 |
+
+## 插槽 & 事件 & Expose
+
+### Slots
+
+| 名称 | 绑定值 | 说明 |
+|------|--------|------|
+| `default` | `{ item: TabItem<T>, index: number }` | 内容区 |
+| `tab` | `{ item: TabItem<T>, active: boolean, index: number }` | 自定义 Tab 按钮 |
+
+### Events
+
+| 事件 | 回调 | 说明 |
+|------|------|------|
+| `update:modelValue` | `(value: T) => void` | v-model |
+
+### Expose
+
+| 方法 | 签名 | 说明 |
+|------|------|------|
+| `scrollToTab` | `(key: T) => void` | 滚动到指定 Tab |
+
+## 完整示例
+
+### 01 — 基础 v-model
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import TabAnchor from '@/components/TabAnchor.vue'
+import type { TabItem } from '@/types/anchor'
+
+const tabs: TabItem[] = [
+  { label: '推荐', key: 'recommend' },
+  { label: '景点', key: 'spot' },
+  { label: '酒店', key: 'hotel' },
+]
+const activeKey = ref('recommend')
+</script>
+
+<template>
+  <TabAnchor v-model="activeKey" :tabs="tabs">
+    <template #default="{ item }">
+      <div style="padding: 16px; min-height: 300px">{{ item.label }} 详情内容...</div>
+    </template>
+  </TabAnchor>
+</template>
+```
+
+### 02 — sticky 吸顶
+
+```vue
+<TabAnchor v-model="activeKey" :tabs="tabs" sticky :stickyTop="0" color="#07c160">
+  <template #default="{ item }">
+    <div style="height: 600px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 03 — float 浮动 + threshold
+
+```vue
+<TabAnchor
+  v-model="activeKey" :tabs="tabs"
+  float :stickyTop="0" :floatThreshold="300" color="#1989fa"
+>
+  <template #default="{ item }">
+    <div style="height: 800px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 04 — left 侧边布局
+
+```vue
+<TabAnchor v-model="activeKey" :tabs="tabs" layout="left" color="#ee0a24">
+  <template #default="{ item }">
+    <div style="height: 400px; padding: 16px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 05 — left + float
+
+```vue
+<TabAnchor
+  v-model="activeKey" :tabs="tabs"
+  layout="left" float :stickyTop="0" color="#7232dd"
+>
+  <template #default="{ item }">
+    <div style="height: 600px; padding: 16px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 06 — left + float + 自定义偏移
+
+```vue
+<TabAnchor
+  v-model="activeKey" :tabs="tabs"
+  layout="left" float :floatLeft="76" color="#fa36"
+>
+  <template #default="{ item }">
+    <div style="height: 400px; padding: 16px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 07 — scale 指示器
+
+```vue
+<TabAnchor v-model="activeKey" :tabs="tabs" indicator-type="scale" color="#07c160">
+  <template #default="{ item }">
+    <div style="height: 500px">{{ item.label }}</div>
+  </template>
+</TabAnchor>
+```
+
+### 08 — left + scale
+
+```vue
+<TabAnchor
+  v-model="activeKey" :tabs="tabs"
+  layout="left" indicator-type="scale" color="#ff976a"
+>
+  <template #default="{ item }">
+    <div style="height: 400px; padding: 16px">{{ item.label }}</div>
+  </template>
+</TabAnchor>
+```
+
+### 09 — 自定义 Tab 按钮
+
+```vue
+<TabAnchor v-model="activeKey" :tabs="tabs">
+  <template #tab="{ item, active }">
+    <span :style="{ fontWeight: active ? 700 : 400, color: active ? '#ee0a24' : '#666' }">
+      {{ item.label }}
+    </span>
+  </template>
+  <template #default="{ item }">
+    <div style="height: 400px; padding: 16px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 10 — 手动模式
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import TabAnchor from '@/components/TabAnchor.vue'
+import type { TabItem } from '@/types/anchor'
+
+const tabs: TabItem[] = [
+  { label: '简介', key: 'intro' },
+  { label: '参数', key: 'params' },
+  { label: '评价', key: 'reviews' },
+]
+const activeKey = ref('intro')
+const contentRefs = ref<(HTMLElement | null)[]>([])
+const tabAnchorRef = ref<InstanceType<typeof TabAnchor>>()
+</script>
+
+<template>
+  <TabAnchor ref="tabAnchorRef" v-model="activeKey" :tabs="tabs" manual :contentRefs="contentRefs" sticky :stickyTop="0" />
+
+  <div ref="el => contentRefs[0] = el" data-key="intro" style="height: 400px">简介</div>
+  <div ref="el => contentRefs[1] = el" data-key="params" style="height: 400px">参数</div>
+  <div ref="el => contentRefs[2] = el" data-key="reviews" style="height: 400px">评价</div>
+
+  <van-button @click="tabAnchorRef?.scrollToTab('reviews')">跳转评价</van-button>
+</template>
+```
+
+### 11 — 局部滚动容器
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import TabAnchor from '@/components/TabAnchor.vue'
+import type { TabItem } from '@/types/anchor'
+
+const tabs: TabItem[] = [
+  { label: '区域一', key: 'zone1' },
+  { label: '区域二', key: 'zone2' },
+]
+const activeKey = ref('zone1')
+const scrollContainerRef = ref<HTMLElement | null>(null)
+</script>
+
+<template>
+  <div ref="scrollContainerRef" style="height: 400px; overflow-y: auto; border: 1px solid #eee">
+    <TabAnchor v-model="activeKey" :tabs="tabs" sticky :scrollContainer="scrollContainerRef">
+      <template #default="{ item }">
+        <div style="height: 800px; padding: 16px">{{ item.label }} 内容</div>
+      </template>
+    </TabAnchor>
+  </div>
+</template>
+```
+
+### 12 — scrollOffset 补偿
+
+页面顶部有固定导航栏和二级栏，合计 92px：
+
+```vue
+<TabAnchor
+  v-model="activeKey" :tabs="tabs"
+  sticky :stickyTop="46" :scrollOffset="46"
+>
+  <template #default="{ item }">
+    <div style="height: 600px">{{ item.label }}</div>
+  </template>
+</TabAnchor>
+```
+
+### 13 — 禁用 Tab + 正上方导航
+
+```vue
+<script setup lang="ts">
+const tabs: TabItem[] = [
+  { label: '可用', key: 'active' },
+  { label: '已禁用', key: 'disabled', disabled: true },
+  { label: '可用二', key: 'active2' },
+]
+</script>
+
+<TabAnchor v-model="activeKey" :tabs="tabs" sticky :stickyTop="46" color="#07c160">
+  <template #default="{ item }">
+    <div style="height: 600px">{{ item.label }} 内容</div>
+  </template>
+</TabAnchor>
+```
+
+### 14 — 完整的页面级示例
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import TabAnchor from '@/components/TabAnchor.vue'
+import type { TabItem } from '@/types/anchor'
+
+const tabs: TabItem[] = [
+  { label: '景点', key: 'spot' },
+  { label: '酒店', key: 'hotel' },
+  { label: '美食', key: 'food' },
+  { label: '玩乐', key: 'fun' },
+]
+const activeKey = ref('spot')
+</script>
+
+<template>
+  <div class="page">
+    <!-- 顶部导航栏 -->
+    <div class="page-header">详情页</div>
+
+    <!-- Tab 锚点组件 -->
+    <TabAnchor
+      v-model="activeKey"
+      :tabs="tabs"
+      sticky
+      :stickyTop="46"
+      color="#ff6b35"
+    >
+      <template #default="{ item }">
+        <div class="section-content" v-if="item.key === 'spot'">
+          <img src="https://example.com/scenic.jpg" alt="景点" />
+          <p>景点详细介绍...</p>
+        </div>
+        <div class="section-content" v-else-if="item.key === 'hotel'">
+          <h3>推荐酒店</h3>
+          <div class="hotel-card">酒店 1</div>
+          <div class="hotel-card">酒店 2</div>
+        </div>
+        <div class="section-content" v-else-if="item.key === 'food'">
+          <p>美食推荐...</p>
+        </div>
+        <div class="section-content" v-else>
+          <p>娱乐项目...</p>
+        </div>
+      </template>
+    </TabAnchor>
+  </div>
+</template>
+
+<style scoped>
+.page-header {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  height: 46px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #fff;
+  border-bottom: 1px solid #f0f0f0;
+}
+.section-content {
+  padding: 16px;
+  min-height: 500px;
+}
+.hotel-card {
+  padding: 12px;
+  margin-bottom: 8px;
+  background: #f5f5f5;
+  border-radius: 8px;
+}
+</style>
+```
+
+## 常见问题
+
+| 场景 | 处理方式 |
+|------|---------|
+| 页面顶部有固定导航栏 | `:stickyTop="导航栏高度"` 让 Tab 栏定位在导航栏下方 |
+| 导航栏 + 二级栏 | `:stickyTop="46" :scrollOffset="46"` |
+| 需要跳到非当前 Tab | 调用 `scrollToTab(key)` 或直接改 `modelValue` |
+| 内容区有图片加载导致高度变化 | `ResizeObserver` 自动重建 Observer |
+| 浮动模式下左侧布局位置不准 | 用 `:floatLeft="数值"` 手动指定 left |
+| 只想要 Tab 切换不要自动检测 | 用 `manual` 模式自行管理内容区 |
+| 禁用 Tab | `disabled: true`，灰色不可点击 |