BackTop
返回长页面顶部。中文惯用名：回到顶部。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.back-top |
| 名称 | BackTop |
| 二级分类 | 导航（navigation） |
| 用途 | 返回长页面顶部 |
| 描述 | 中文惯用名：回到顶部。 |
预览
静态结构：滚动超过 visibilityHeight（默认 400px）后渲染 <button data-slot="back-top">（fixed right-10 bottom-10，rounded-full 边框 + 阴影，默认 arrow-up 图标，children 可自定义内容）；点击 window.scrollTo 平滑回顶，未超阈值不渲染。组件监听 window 滚动（本站点为容器内滚动，预览以负阈值强制展示按钮形态）。
DSL 结构
{
"type": "BackTop",
"props": {
"visibilityHeight": 400
}
}何时用
何时使用
- 长页面快速返回顶部：列表、文档、信息流滚动超过一屏后。
- 页面无固定头部时的兜底导航。
何时不用
- 短页面（滚动不足 visibilityHeight 时组件本就不出现）。
- 局部滚动区域：BackTop 监听 window 滚动，局部滚动用 ScrollArea 自带滚动条。
- 需要章节级定位：使用 Anchor。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认按钮 | 圆形向上箭头 | 通用长页面 |
| 自定义内容 | children DSL 子树 | 品牌化悬浮入口 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
visibilityHeight | number | 400 | 滚动超过该高度（像素）后显示按钮 |
children | DslNode[] | — | 自定义按钮内容（DSL 子树） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 一页最多一个 BackTop，位置固定右下，不与其他悬浮按钮重叠。
- visibilityHeight 按页面长度调整（短列表可降至 200）。
- 已有固定头部提供回顶能力时可不启用。
正例
- ✓ 长列表页：滚动两屏后右下浮出回到顶部按钮。
- ✓ 文档页配合 Anchor：章节定位用 Anchor，快速回顶用 BackTop。
反例
- ✕ 在弹窗 / 抽屉内的局部滚动区使用（监听不到局部滚动）。
- ✕ 与右下角在线客服悬浮钮叠放（应错开位置或取舍）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。