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> | — | — |
源码
/**
* 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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
设置页栏目跳转条:声明式 sections + IntersectionObserver 激活高亮;锚点缺失点击 no-op;与 chapter-scrubber 是不同组件。