Ordo UI
PatternsSemantic

SectionScrubber

@mox-hub/patterns 模式 · Semantic · canonical

section-scrubber@mox-hub/patternsSemanticcanonicalsrc/components/section-scrubber.tsx
变体演示section-scrubber

Props API

Prop类型默认值说明
sections*ScrubberSection[]——
orientation*"horizontal" | "vertical""horizontal"—
labels*Partial<SectionScrubberLabels>——

源码

packages/patterns/src/components/section-scrubber.tsx
/**
 * SectionScrubber - 设置页栏目跳转条(section chips,2026-10-01 设置页语义组件批)
 *
 * 声明式 sections(锚点 id + 标签)渲染胶囊 chips:点击平滑滚动到对应
 * SettingsSectionCard(scrollIntoView + 卡片 scroll-mt-24 避让吸顶卡),
 * IntersectionObserver 监听栏目进出视口上部激活带(rootMargin 上 -20% 下 -60%)
 * 驱动当前项高亮(§21 observer 密度:每页一个 observer,非逐行)。
 * 命名注意:与 modules/document 的 chapter-scrubber(阅读页右缘刻度轨+指针放大波,
 * motion spring 形态)是不同组件——section(页面栏目 chips)≠ chapter(文档章节轨),
 * 2026-10-01 撞名裁决改名 section-scrubber 为后者保留 chapter-scrubber 名。
 * 形态裁决(2026-10-01):主落点是 SettingsHeader 吸顶卡 scrubber 槽,仅吸顶态
 * 出现——sticky 空间零浪费;独立常驻条/右侧竖点形态留作长页(>5 栏目)升级项。
 * 目标锚点缺失时点击为 no-op(消费方保证 sections 与页面锚点一致)。
 * props 面封闭(G8):不接 className、不透传样式。
 */
import { useEffect, useRef, useState } from "react";
import type { ReactNode } from "react";
import { RawButton } from "@mox-hub/ui/components/raw/raw-button";
import { cn } from "@mox-hub/ui";
import { usePatternLabels } from "../lib/i18n";

/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface SectionScrubberLabels {
  sectionNav: string;
}

export const SECTION_SCRUBBER_DEFAULT_LABELS: SectionScrubberLabels = {
  sectionNav: "栏目导航",
};

export interface ScrubberSection {
  /** 目标锚点 id(= SettingsSectionCard 的 id prop) */
  id: string;
  label: ReactNode;
}

export interface SectionScrubberProps {
  /** 栏目清单(声明顺序即展示顺序);建议模块级常量,避免每次渲染重建 observer */
  sections: ScrubberSection[];
  /** 形态:horizontal(缺省,横排 chips,设置页吸顶槽)/ vertical(详情页左侧栏竖排) */
  orientation?: "horizontal" | "vertical";
  /** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
  labels?: Partial<SectionScrubberLabels>;
}

export function SectionScrubber({
  sections,
  orientation = "horizontal",
  labels,
}: SectionScrubberProps) {
  const [activeId, setActiveId] = useState(sections[0]?.id);
  const visibleRef = useRef(new Set<string>());
  const vertical = orientation === "vertical";
  const D = usePatternLabels(
    "sectionScrubber",
    SECTION_SCRUBBER_DEFAULT_LABELS,
  );

  useEffect(() => {
    if (typeof IntersectionObserver === "undefined" || sections.length === 0)
      return;
    visibleRef.current = new Set();
    const io = new IntersectionObserver(
      (entries) => {
        for (const entry of entries) {
          const id = (entry.target as HTMLElement).id;
          if (entry.isIntersecting) visibleRef.current.add(id);
          else visibleRef.current.delete(id);
        }
        const next = sections.find((section) =>
          visibleRef.current.has(section.id),
        );
        if (next) setActiveId((prev) => (prev === next.id ? prev : next.id));
      },
      { rootMargin: "-20% 0px -60% 0px" },
    );
    for (const section of sections) {
      const el = document.getElementById(section.id);
      if (el) io.observe(el);
    }
    return () => io.disconnect();
  }, [sections]);

  return (
    <nav
      aria-label={labels?.sectionNav ?? D.sectionNav}
      data-slot="section-scrubber"
      data-orientation={orientation}
      className={cn(
        "min-w-0 items-center gap-1",
        vertical ? "flex flex-col items-stretch" : "flex overflow-x-auto",
      )}
    >
      {sections.map((section) => {
        const active = section.id === activeId;
        return (
          <RawButton
            key={section.id}
            onClick={() => {
              setActiveId(section.id);
              document
                .getElementById(section.id)
                ?.scrollIntoView({ behavior: "smooth", block: "start" });
            }}
            aria-current={active ? "true" : undefined}
            className={cn(
              "shrink-0 truncate rounded-full px-2.5 py-1 text-xs transition-colors duration-fast",
              vertical && "text-start",
              active
                ? "bg-muted font-medium text-foreground"
                : "text-content-text-muted hover:bg-muted hover:text-content-text-secondary",
            )}
          >
            {section.label}
          </RawButton>
        );
      })}
    </nav>
  );
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

设置页栏目跳转条:声明式 sections + IntersectionObserver 激活高亮;锚点缺失点击 no-op;与 chapter-scrubber 是不同组件。