# Anchor 锚点 滚动监听当前章节并自动高亮，点击锚点平滑滚动定位。支持指定滚动容器、点击落点偏移、多级嵌套、横向模式、吸附、轨道墨水条、样式变体与历史控制等能力。 ## 基础用法 `scroll-container` 指定局部滚动容器（选择器或元素 id）：观察根与点击落点都以它为准；未设置时监听视口。

第一章

第一节内容：用于演示滚动监听与高亮跟随。

第二章

滚动该容器时，左侧锚点自动高亮当前章节。

第三章

点击锚点可平滑滚动定位到对应章节。

 ## 高亮判定偏移与触发边界 `offset` 控制高亮判定线（章节顶越检测线的提前量）；`bounds` 是触发边界的额外提前量（默认 5），避免高亮切换抖动。

第一章

offset 控制顶部高亮判定区的偏移量。

第二章

章节顶进入偏移线即切换高亮，比默认更早。

第一章

bounds 越大，章节顶越检测线的提前量越大。

第二章

默认 5px，这里调大到 40px 便于观察切换点差异。

 ## 点击事件 `oas-click` 与 `oas-change` 分离：**点击**锚点派发 `oas-click`（`detail: { href, item }`），点击与**滚动联动**切换高亮都派发 `oas-change`（`detail: { href, prevHref }`）——宿主想只响应用户操作时监听 `oas-click` 即可。

第一章

点击左侧锚点：仅派发 oas-click；滚动该容器切换高亮：仅派发 oas-change。

第二章

oas-click 的 detail 含完整 item（href/title 等）。

尚未点击 无 oas-click ## 受控高亮 `active` 为受控属性：外部设置 / 移除 `active` 可直接控制当前高亮项（滚动监听仍会随滚动接管）。 高亮第一章 高亮第二章 高亮第三章 清除高亮

第一章

点击左侧按钮设置 active，锚点立即高亮对应项。

第二章

滚动该容器时，scroll spy 会接管高亮。

第三章

「清除高亮」移除 active，恢复无高亮状态。

 ## 点击落点偏移与对齐 `target-offset` 控制点击后目标距容器顶的距离（避让固定头），未设置时回退 `offset`；`block` 控制落点对齐（`start` / `center` / `end` / `nearest`——nearest 目标已可见则不滚动、最小滚动量）；`duration` 控制平滑滚动时长，`animation="false"` 或 `duration="0"` 立即定位。

第一章

虚线标记 80px 落点线：点击后第一章顶对齐到虚线。

第二章

duration=500 平滑滚动约 500ms。

第一章

block="center"：目标章节垂直居中于容器。

第二章

点我试试居中落点效果。

第一章

block="nearest"：目标已完全可见则完全不滚动。

先点「第三章」滚到底，再点「第一章」——若第一章已可见则不发生滚动（最小滚动量）。

第二章

目标在容器下方时只滚到其底部刚可见。

第三章

目标在容器上方时只滚到其顶部刚可见。

第一章

animation="false"：点击后立即定位，无平滑过渡。

第二章

等价于 duration="0"。

 ## 嵌套层级与目标标记 `items` 支持 `children` 多级嵌套（层级缩进展示，子项同样参与滚动高亮）；`` 以组件方式标记滚动目标（`id` 同步到内部 `part=target`），替代手写标题 id；`internal-scrollable` 让锚点栏自身内部滚动。

第一章

oas-anchor-target 包裹的标题作为滚动定位目标。

1.1 小节

子级锚点缩进展示，同样参与高亮判定。

1.2 小节

子级锚点缩进展示，同样参与高亮判定。

1.3 小节

子级锚点缩进展示，同样参与高亮判定。

1.4 小节

子级锚点缩进展示，同样参与高亮判定。

1.5 小节

子级锚点缩进展示，同样参与高亮判定。

第二章

internal-scrollable：锚点栏内容超高时自身滚动。

 ## 横向模式

第一章

横向模式下锚点项水平排布，墨水条横向随动。

第二章

滚动容器观察高亮切换。

第三章

点击锚点同样定位到对应章节。

 ## 吸附 `affix` 开启后锚点栏随滚动吸附（sticky 定位），`affix-offset` 控制吸附后距视口顶的距离；本 demo 锚点监听视口滚动。

第一章

向下滚动页面：左侧锚点栏吸附在视口顶部 16px 处。

第二章

页面滚动时高亮跟随当前章节。

第三章

配合固定头部导航时，affix-offset 避让固定头。

 ## 样式变体与尺寸

default

underline

lineless

block

size=small

size=large

 ## 历史控制 点击锚点默认更新 URL hash（`history.pushState`）；`replace` 改用 `replaceState` 替换历史；`hash="false"` 完全不写历史。

第一章

三个锚点监听同一容器：默认 pushState、replace 替换历史、hash=false 不写。

第二章

点击第一列锚点查看 URL hash 变化。

尚未点击 ## 自定义高亮 `get-current-anchor` 指定自定义高亮策略：属性值为全局函数名，函数接收滚动算出的候选 href，返回实际应高亮 href；框架场景也可用 property `getCurrentAnchor` 传入函数。

第一章

无论滚动到哪，自定义策略都强制高亮第三章。

第二章

滚动时事件 detail.href 也来自自定义策略。

第三章

实际高亮项。

尚未滚动 ## 外部链接 锚点项设置 `target`（如 `_blank`）后不拦截默认行为，交由浏览器打开（自动补 `rel="noopener noreferrer"`），不参与滚动与高亮。 ## 子元素声明式通道 除 `items` JSON 外，可用 `` 子元素声明式书写（`items` 属性**显式设置时优先**）。默认插槽文本为 title；属性对齐 `AnchorItem` 字段：`href`/`target`/`target-offset`；直接子 `` 递归为 `children` 多级嵌套（层级缩进，同样参与滚动高亮）。子元素增删、属性与文本变化会自动重渲染。
第一章 第二章

第一章

用 oas-anchor-item 声明式书写锚点项；滚动联动高亮与 items 通道一致。

第二章

点击锚点平滑滚动定位到对应章节。
第一章 1.1 小节 1.2 小节 第二章

第一章
1.1 小节
1.2 小节

第二章

项级 `target-offset` 覆盖全局落点偏移；子项同样参与滚动高亮。

滚动到本节底部，左侧高亮会随滚动联动迁移。

点击左侧「第二章」可平滑滚动定位到本节。

内容撑高以演示滚动联动（容器 240px 高）。

再多一段文字确保溢出可滚。

 ## API ### oas-anchor #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `active` | 当前高亮 href（受控：外部设置/清除立即生效；滚动联动接管后回写） | `string` | — | | `affix` | 启用吸附（sticky 定位，随滚动视口/容器吸附） | `boolean` | — | | `affix-offset` | 吸附时距滚动视口顶部的距离（px） | `string` | `0` | | `animation` | 平滑滚动开关（默认 true；`false` 立即定位） | `string` | `true` | | `block` | 滚动落点对齐：`start` / `center` / `end` / `nearest`（目标已可见则不滚动，最小滚动量；在上方对齐顶部、在下方对齐底部） | `ScrollBlock` | `start` | | `bounds` | 触发边界（px，默认 5）：章节顶越检测线的额外提前量，避免高亮抖动 | `string` | `5` | | `direction` | 布局方向：`vertical` / `horizontal` | `string` | `vertical` | | `duration` | 平滑滚动时长（ms，默认 300；`0` 立即定位） | `string` | `300` | | `get-current-anchor` | 自定义高亮策略：属性指定全局函数名，接收滚动算出的候选 href，返回实际应高亮 href；亦可用 property `getCurrentAnchor` 传入函数 | `((activeHref: string) => string) \| null` | — | | `hash` | 点击是否更新 URL hash（默认 true；`false` 关闭） | `string` | `true` | | `internal-scrollable` | 锚点栏自身内部滚动（max-height + overflow-y: auto） | `boolean` | — | | `items` | 锚点项 JSON；项支持 `children` 多级嵌套、`target`（如 `_blank`）、`targetOffset` 项级落点偏移 | `AnchorItem[] \| string` | `[]` | | `offset` | 高亮判定偏移（px）：章节顶越检测线的提前量 | `string` | `0` | | `replace` | 历史控制：用 `history.replaceState` 替换历史而非 pushState | `boolean` | — | | `scroll-container` | 滚动容器选择器或元素 id；未设置时监听视口（window） | `HTMLElement \| string \| null` | — | | `size` | 尺寸档位：`small` / `medium` / `large` | `string` | `medium` | | `target-offset` | 点击定位落点偏移（px），避让固定头；未设置时回退 `offset`；项级 `targetOffset` 优先 | `string` | — | | `variant` | 样式变体：`default`（轨道+墨水条）/ `underline`（滑动下划线）/ `lineless`（无轴线）/ `block`（块状背景） | `string` | `default` | #### 事件 | 事件 | 说明 | | --- | --- | | `oas-change` | 高亮切换（点击或滚动联动均派发），`detail: { href, prevHref }` | | `oas-click` | 用户点击锚点项（与滚动联动的 `oas-change` 分离，宿主可只响应用户操作；外部链接 `target` 项同样派发），`detail: { href, item }` | ### oas-anchor-target #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `id` | 目标标记 id：同步到内部 `part=target` 元素，锚点项以此为滚动定位目标 | — | — | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 被标记的目标内容（如多级标题） | ### oas-anchor-item #### 属性 | 属性 | 说明 | 类型 | 默认值 | | --- | --- | --- | --- | | `href` | 锚点目标：`#id`（或外链地址；外链建议搭配 `target`） | — | — | | `target` | 链接 target（如 `_blank`）：设置后不拦截默认行为，交由浏览器打开（自动补 `rel="noopener noreferrer"`） | — | — | | `target-offset` | 项级点击落点偏移（px），优先于全局 `target-offset`；非法值忽略 | — | — | #### 插槽 | 名称 | 说明 | | --- | --- | | 默认 | 锚点项 title 内容（默认插槽文本；直接子 `oas-anchor-item` 不计入） | 基于滚动容器（默认视口）的 scroll spy；点击平滑滚动定位；`nav` + `aria-label="锚点导航"`，当前项 `aria-current="true"`。 基于 `oas-anchor-target` 的目标标记组件：包裹真实多级标题，作为锚点项滚动定位目标；默认插槽为被标记内容。