iter(g101): 新增锚点导航组件 anchor

2026-10-26 13:50:12 +08:00
parent befed761d9
commit 265842ef63
13 changed files with 303 additions and 10 deletions
@@ -0,0 +1,77 @@
+import { h } from '@ui-arch/frame';
+import type { AnchorItem, AnchorProps } from './types.js';
+
+/*** 锚点导航：竖排区块链接，滚动时高亮当前区块，点击平滑跳转（尊重减少动效偏好） ***/
+export function anchor(props: AnchorProps): HTMLElement {
+  // —— 状态集中声明 ——
+  const items = props.items;                 // 锚点项，href 形如 #sec-xxx
+  const offset = props.offset ?? 0;          // 目标顶部预留距离（吸顶栏高度）
+  const scroller = props.container instanceof HTMLElement ? props.container : null; // 内滚容器：null 表示整页滚动
+  const links: HTMLAnchorElement[] = [];     // 与 items 一一对应的链接节点
+  const root = h('nav', { class: 'ua-anchor', 'aria-label': props.label ?? '锚点导航' });
+
+  /*** 目标元素：href 去掉 # 后按 id 查找，找不到返回 null ***/
+  const targetOf = (href: string): HTMLElement | null => document.getElementById(href.replace(/^#/, ''));
+
+  /*** 目标相对判定原点的垂直坐标：整页用视口坐标，容器用容器内偏移 ***/
+  const topOf = (el: HTMLElement): number => (scroller
+    ? el.getBoundingClientRect().top - scroller.getBoundingClientRect().top
+    : el.getBoundingClientRect().top);
+
+  /*** 当前区块：取最后一个已越过判定线的目标，全未越过时落到首项 ***/
+  const current = (): AnchorItem | undefined => {
+    let hit: AnchorItem | undefined = items[0];
+    for (const item of items) {
+      const el = targetOf(item.href);
+      if (!el) continue; // 卫语句：目标不存在就跳过，不打断整表判定
+      if (topOf(el) - offset <= 1) hit = item;
+    }
+    return hit;
+  };
+
+  /*** 同步高亮：类名与 aria-current 一起切换，读屏能念出当前所在区块 ***/
+  const sync = (): void => {
+    const hit = current();
+    links.forEach((link, i) => {
+      const on = items[i] === hit;
+      link.classList.toggle('is-active', on);
+      if (on) link.setAttribute('aria-current', 'true');
+      else link.removeAttribute('aria-current');
+    });
+  };
+
+  /*** 跳转：按偏移量滚动到位并回写 hash，减少动效偏好下改瞬移 ***/
+  const jump = (item: AnchorItem): void => {
+    const el = targetOf(item.href);
+    if (!el) return; // 卫语句：目标不在页面上就什么都不做
+    const smooth = !window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const behavior: ScrollBehavior = smooth ? 'smooth' : 'auto';
+    const top = topOf(el) + (scroller ? scroller.scrollTop : window.scrollY) - offset;
+    if (scroller) scroller.scrollTo({ top, behavior });
+    else window.scrollTo({ top, behavior });
+    history.replaceState(null, '', item.href); // 用 replaceState：跳转不堆积历史条目
+    props.onChange?.(item.href);
+    sync();
+  };
+
+  for (const item of items) {
+    const link = h('a', {
+      class: item.disabled ? 'ua-anchor-link is-disabled' : 'ua-anchor-link',
+      href: item.href,
+      'aria-disabled': item.disabled ? 'true' : undefined,
+      onClick: (e: Event) => {
+        e.preventDefault(); // 一律接管：自绘偏移量，不走浏览器默认锚点定位
+        if (item.disabled) return; // 卫语句：禁用项只吞掉点击
+        jump(item);
+      },
+    }, item.title) as HTMLAnchorElement;
+    links.push(link);
+    root.append(link);
+  }
+
+  const host: HTMLElement | Window = scroller ?? window;
+  host.addEventListener('scroll', sync, { passive: true }); // 被动监听：不阻塞滚动
+  window.addEventListener('resize', sync);                  // 视口变化会改变判定线
+  sync(); // 首屏同步一次，刷新后停在中间位置也能高亮正确项
+  return root;
+}
@@ -57,3 +57,4 @@ export { colorPicker } from './colorPicker.js';
 export { tour } from './tour.js';
 export { watermark } from './watermark.js';
 export { affix } from './affix.js';
+export { anchor } from './anchor.js';
@@ -679,4 +679,20 @@ export interface SpaceProps {
  block?: boolean;                           // 是否占满父容器宽度；缺省按内容收缩
 }

+/*** 锚点导航项 ***/
+export interface AnchorItem {
+  href: string;       // 目标区块地址（#id）；对应元素须存在于页面上
+  title: string;      // 链接文案
+  disabled?: boolean; // 是否禁用该项；缺省可用
+}
+
+/*** 锚点导出入参 ***/
+export interface AnchorProps {
+  items: AnchorItem[];               // 锚点项集合，按显示顺序
+  offset?: number;                   // 定位时预留的顶部距离（吸顶栏高度）；缺省 0
+  container?: HTMLElement | Window;  // 监听的滚动容器；缺省 window（整页）
+  label?: string;                    // nav 的无障碍名称；缺省「锚点导航」
+  onChange?: (href: string) => void; // 跳转后的回调（埋点或联动滚动）
+}
+
 export type { ColumnDef, RowKey }; // 再导出常用内核类型，方便调用方