跳到正文

Outline 大纲轨

要在长对话或长文档的边上放一条窄窄的导航、平时几乎不占宽度、悬停或聚焦时才展开时,用 Outline。一直完整显示的「本页目录」请用 Anchor。

Outline 是一个贴边放置的紧凑大纲导航组件,源自长对话与技术工作区中的侧边刻度条:平时只占用一条极窄的短横线刻度(不挤占正文宽度),鼠标移入或键盘聚焦时原位展开浮层卡片,显示每一节或每一轮提问的摘要、时间与预览,点击即可跳转。

既可以像 Anchor 一样通过 targetId + offsetTarget 自动跟随容器滚动,也可以只用 value + onSelect 与 VirtualList 等虚拟滚动列表配合(目标行尚未挂载到 DOM 时同样能跳转)。

演示

长对话大纲

每一轮关键发言对应一根刻度线:emphasized 把当前用户自己的提问画得更清晰,meta 展示时间,tooltip 在浮层行旁弹出完整预览。滚动面板时翡翠绿主刻度自动跟进并保持在轨道中央;移入右侧刻度条即可展开卡片跳转。

层级、左右贴边与常驻展开

通过 depth 表示章节缩进层级,placement="left" 切换到左侧贴边,或用受控 show 将浮层卡片固定展开。

受控与虚拟列表联动

不传 targetId 时,Outline 完全由 value、onUpdateValue 和 onSelect 驱动——适合与 VirtualList 搭配,在回调里调用 listRef.current?.scrollTo({ key }) 按数据项定位。

Outline Props

名称类型默认值说明版本
itemsreadonly OutlineItem[]大纲条目列表;为空数组时不渲染。未发布
valuestring | nullundefined当前激活条目的 key,设置后为受控模式。未发布
defaultValuestring | nullnull非受控模式下的初始激活 key。未发布
onUpdateValue(value: string | null) => voidundefined滚动监听或点击切换当前条目时触发。未发布
onSelect(key: string, item: OutlineItem) => voidundefined点击刻度或浮层行时触发。未发布
placement'right' | 'left''right'刻度条贴靠的边;浮层卡片向内侧展开。未发布
showbooleanundefined控制浮层卡片是否展开。未发布
defaultShowbooleanfalse非受控模式下浮层卡片初始是否展开。未发布
onUpdateShow(show: boolean) => voidundefined悬停、键盘聚焦、Escape 或外部点击改变展开状态时触发。未发布
closeOnSelectbooleanfalse点击条目后是否立即收起浮层卡片。未发布
maxVisibleItemsnumber10浮层卡片单屏最多展示的行数,超出后在内置 ScrollArea 中滚动。未发布
maxRailHeightnumber | string240紧凑刻度条的最大高度,超出后自动居中滚动当前刻度。未发布
boundnumber24使用 targetId 跟随滚动时,目标距容器顶部多少 px 内视为到达。未发布
ignoreGapbooleantrue在两个目标之间的空白区保持上一个经过的条目处于激活态。未发布
offsetTargetOutlineOffsetTargetwindowtargetId 所在的滚动容器(选择器、元素、ref 或返回元素的函数)。未发布
zIndexnumberundefined浮层卡片的固定层级;不设时自动排在已有浮层之上。未发布
aria-labelstring语言包 Outline.labelnav 地标名称(中文默认「大纲」)。未发布

OutlineItem

名称类型默认值说明
keystring唯一标识,对应 value 与 onSelect 的第一个参数。
labelReactNode浮层卡片里的单行标题;字符串标题也会作为紧凑刻度按钮的无障碍名称。
textValuestringundefined当 label 是复杂 JSX 时,为紧凑刻度按钮提供纯文本无障碍名称。
metaReactNodeundefined浮层行尾辅助信息(如时间戳、序号)。
tooltipReactNode | (() => ReactNode)undefined悬停浮层行时在侧边弹出的详细预览提示。
targetIdstringundefined滚动容器内对应元素的 id(可带或不带 #)。
emphasizedbooleanundefined在静止态画更醒目的刻度(例如标出“我发送的消息”或一级大节)。
depthnumber0层级缩进深度(0、1、2…),子级刻度更短、浮层文字自动缩进。