固钉 affix

导航组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

滚过判定线就把内容钉在滚动容器可视区的上边；占位盒留在原位，页面不跳

往下滚，下面那条会钉在容器顶边。

我会钉在顶边

后面还有很长的内容，一直滚到底再滚回去。

<script setup lang="ts">
import { ref } from "vue";
import { XhAffixContent, XhAffixRoot } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
</script>

<template>
  <div
    ref="scrollEl"
    style="
      block-size: 240px;
      overflow: auto;
      padding: 12px;
      border: 1px solid var(--xh-border-default);
      border-radius: 8px;
    "
  >
    <p style="block-size: 120px">往下滚，下面那条会钉在容器顶边。</p>

    <!-- target 指向真正在滚的那层；不给就按整页滚动算 -->
    <XhAffixRoot :target="scrollEl">
      <XhAffixContent
        style="
          padding: 8px 12px;
          border-radius: 6px;
          background: var(--xh-bg-brand);
          color: var(--xh-fg-on-brand);
        "
      >
        我会钉在顶边
      </XhAffixContent>
    </XhAffixRoot>

    <p style="block-size: 600px">后面还有很长的内容，一直滚到底再滚回去。</p>
  </div>
</template>

让出吸顶栏

offset-top 把判定线往下挪，钉住后也在同一位置留出这段高度

吸顶栏

往下滚。

钉在吸顶栏下方 40px 处

后面还有很长的内容。

<script setup lang="ts">
import { ref } from "vue";
import { XhAffixContent, XhAffixRoot } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
</script>

<template>
  <div
    ref="scrollEl"
    style="
      position: relative;
      block-size: 240px;
      overflow: auto;
      padding: 12px;
      border: 1px solid var(--xh-border-default);
      border-radius: 8px;
    "
  >
    <!-- 容器自带一条 40px 的吸顶栏，钉住的内容要躲开它 -->
    <div
      style="
        position: sticky;
        inset-block-start: 0;
        z-index: 1;
        block-size: 40px;
        display: flex;
        align-items: center;
        padding-inline: 8px;
        background: var(--xh-bg-subtle);
      "
    >
      吸顶栏
    </div>

    <p style="block-size: 120px">往下滚。</p>

    <XhAffixRoot :target="scrollEl" :offset-top="40">
      <XhAffixContent
        style="
          padding: 8px 12px;
          border-radius: 6px;
          background: var(--xh-bg-brand);
          color: var(--xh-fg-on-brand);
        "
      >
        钉在吸顶栏下方 40px 处
      </XhAffixContent>
    </XhAffixRoot>

    <p style="block-size: 600px">后面还有很长的内容。</p>
  </div>
</template>

贴下边

给了 offset-bottom 就改贴可视区的下边，判定线也换到下边

这块工具条在滚到它之前就贴在容器底边，滚过去之后回到常规流。

共 42 项已选 3 项

下面是很长的列表内容。

<script setup lang="ts">
import { ref } from "vue";
import { XhAffixContent, XhAffixRoot } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
</script>

<template>
  <div
    ref="scrollEl"
    style="
      block-size: 240px;
      overflow: auto;
      padding: 12px;
      border: 1px solid var(--xh-border-default);
      border-radius: 8px;
    "
  >
    <p style="block-size: 80px">这块工具条在滚到它之前就贴在容器底边，滚过去之后回到常规流。</p>

    <XhAffixRoot :target="scrollEl" :offset-bottom="12">
      <XhAffixContent
        style="
          display: flex;
          gap: 8px;
          padding: 8px 12px;
          border-radius: 6px;
          background: var(--xh-bg-surface-raised);
          box-shadow: var(--xh-elevation-2);
        "
      >
        <span>共 42 项</span>
        <span>已选 3 项</span>
      </XhAffixContent>
    </XhAffixRoot>

    <p style="block-size: 600px">下面是很长的列表内容。</p>
  </div>
</template>

监听吸附状态

affix-change 报吸住与松开；默认插槽也把 affixed 透出来

往下滚，下面的状态会跟着变。

在常规流里

后面还有很长的内容。

affix-change 最近一次报的是：松开

<script setup lang="ts">
import { ref } from "vue";
import { XhAffixContent, XhAffixRoot } from "@xihan-ui/vue";

const scrollEl = ref<HTMLElement | null>(null);
const affixed = ref(false);

function onAffixChange(details: { affixed: boolean }): void {
  affixed.value = details.affixed;
}
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%">
    <div
      ref="scrollEl"
      style="
        block-size: 220px;
        overflow: auto;
        padding: 12px;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <p style="block-size: 120px">往下滚，下面的状态会跟着变。</p>

      <XhAffixRoot v-slot="{ affixed: pinned }" :target="scrollEl" @affix-change="onAffixChange">
        <XhAffixContent
          style="padding: 8px 12px; border-radius: 6px; background: var(--xh-bg-subtle)"
        >
          {{ pinned ? "已钉住" : "在常规流里" }}
        </XhAffixContent>
      </XhAffixRoot>

      <p style="block-size: 600px">后面还有很长的内容。</p>
    </div>

    <span>affix-change 最近一次报的是：{{ affixed ? "吸住" : "松开" }}</span>
  </div>
</template>

产物

层	值
自定义元素	<xh-affix>
Vue 组件	XhAffixContent XhAffixRoot
组合式函数	useAffix
状态机	affixMachine
皮肤	@xihan-ui/styles/affix.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="affix"：root · content

Props

属性	类型	必填	说明
offsetTop	number		吸住后距滚动容器可视区上边的距离（px）。
offsetBottom	number		吸住后距滚动容器可视区下边的距离（px）；给了它就改贴下边。
onAffixChange	(details: AffixChangeDetails) => void		吸附状态变化回调。

状态机

状态：released · affixed

事件：SCROLL.RESOLVE

判据：shouldAffix · shouldRelease

connect API

useAffix 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
affixed	boolean	此刻是不是吸住了。
getRootProps	() => T['element']
getContentProps	() => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。