BackTop 回到顶部
滚动超过指定距离后显示返回入口。
用法
滚动后显示回到顶部按钮
概览相关内容
安装相关内容
主题相关内容
发布相关内容
组件结构
加粗的是必需部件。
data-scope="back-top"：root · trigger
示例
显示阈值
提前显示回到顶部按钮
快速开始相关内容
基础配置相关内容
主题定制相关内容
部署相关内容
滚动方式
平滑返回或立即返回
平滑 · 概览
平滑 · 配置
平滑 · 接口
平滑 · 发布
立即 · 概览
立即 · 配置
立即 · 接口
立即 · 发布
变体
选择与所在表面匹配的样式
线框（默认）
实心
幽灵
设计指引
何时使用
- 长页面或独立滚动区域。
何时不用
- 短页面不需要返回入口。
- 多个悬浮操作使用浮动按钮。
特性
visibilityHeight设置显示阈值。behavior支持平滑或立即返回。- 触发器走 Action Control floating 档：默认 48px 圆形、图标 24px，按下缩放并换底；默认（outline）使用磨砂浮动表面，也可通过
variant切换为 solid / subtle / ghost。 - 减少动效、减少透明度与强制色模式会自动降级。
组合
- 指定
target后监听并滚动该容器；未指定时作用于页面。
最佳实践
- 避开固定工具条和移动端手势区。
- 保持默认的按需显示，不在页面顶部常驻。
反模式
- 在短页面或已有返回入口的位置重复使用。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-back-top> |
| Vue 组件 | XhBackTopRoot XhBackTopTrigger |
| 组合式函数 | useBackTop |
| 状态机 | backTopMachine |
| 皮肤 | @xihan-ui/styles/back-top.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
visibilityHeight | number | 滚动超过该像素数后按钮才显示，默认 200。 | |
behavior | BackTopBehavior | 滚回顶部的方式，默认 smooth。 | |
translations | Partial<BackTopTranslations> | ||
variant | ActionVariant | 形态：solid / subtle / outline / ghost，默认 outline（缺省中性，描边 + 磨砂面；solid 才品牌实心）。 | |
tone | Tone | 语气：brand / neutral / success / warning / danger / info，决定按钮使用哪族颜色。 | |
size | Size | 尺寸：sm / md / lg，默认 md；触发器走 Action Control floating 档（40 / 48 / 56px）。 | |
onVisibilityChange | (details: BackTopVisibilityChangeDetails) => void | 显隐变化时回调。 |
事件
自定义元素将载荷放在 detail；Vue 使用同名 emit。
| 事件 | 载荷 | 说明 |
|---|---|---|
visibility-change | BackTopVisibilityChangeDetails | 显隐变化；detail 为 { visible: boolean } |
插槽
仅列出带载荷的插槽。
| Vue 组件 | 插槽 | 载荷 | 说明 |
|---|---|---|---|
XhBackTopRoot | default | BackTopRootSlotProps |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhBackTopRoot | target | () => HTMLElement | null | 滚动容器取值器，默认即整页滚动；挂载效应执行时求值。 | |
XhBackTopRoot | children | SlotChildren<BackTopRootSlotProps> |
状态
公开状态写入 data-state。
| 部件 | 取值 |
|---|---|
root | 'visible' | 'hidden' |
trigger | 'visible' | 'hidden' |
以下名称仅用于内部状态机。
状态：hidden · visible
事件：SCROLL.RESOLVE · TRIGGER.CLICK · PRESS.START · PRESS.END · TRIGGER.RENDERED
判据：shouldShow · shouldHide
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
visible | boolean | 按钮当前是否显示。 |
scrollToTop | () => void | 程序化滚回顶部，与点击按钮走同一路径。 |
getRootProps | () => T['element'] | |
getTriggerProps | () => T['button'] |
无障碍
键盘
规格出处：W3C APG
| 按键 | 生效条件 | 行为 |
|---|---|---|
Enter / Space | focus in trigger | 滚回顶部；按 behavior 决定是一步到位还是平滑滚过去 |
Enter / Space | held in trigger | 按住期间投影 data-pressed，与指针 :active 同一副按压面；抬起或失焦撤下 |
Tab / Shift+Tab | trigger 露面时 | 走到按钮上；收起时整个 root 带 hidden，按钮不在 Tab 序列里 |
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
trigger | aria-label | props.translations.trigger |
样式参考
皮肤
@xihan-ui/styles/back-top.css 使用 [data-scope="back-top"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-size | props.size |
root | data-state | 'visible' | 'hidden' |
root | data-tone | props.tone |
root | data-variant | props.variant |
trigger | data-pressed | ''（条件成立时才出现） |
trigger | data-state | 'visible' | 'hidden' |
trigger | data-xh-action-control | '' |
trigger | data-xh-action-display | 'always' |
trigger | data-xh-action-profile | 'floating' |
trigger | data-xh-action-size | props.size |
trigger | data-xh-action-variant | props.variant |
trigger | data-xh-ink-surface | ''（条件成立时才出现） |
trigger | data-xh-liquid | '' |
trigger | data-xh-material | 'frosted' | undefined |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-back-top-bg | roottrigger | --xh-ink-surfacebackground-color | defaultdisabledfocus-visiblevariant=outlinexh-ink-surface | --xh-_action-variant-bg-disabled--xh-_action-variant-bg-focus-visible--xh-_action-variant-bg-rest--xh-_material-bg--xh-_material-bg-focus | back-top 的 root、trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-back-top-bg-active | roottrigger | background-color | disabledis(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressedvariant=outline | --xh-_action-variant-bg-pressed--xh-_material-bg-pressed | back-top 的 root、trigger 部件 background-color 覆盖槽。 |
--xh-back-top-bg-hover | roottrigger | background-color | disabledhoverloadingnot([data-disabled])not([data-loading])variant=outline | --xh-_action-variant-bg-hover--xh-_material-bg-hover | back-top 的 root、trigger 部件 background-color 覆盖槽。 |
--xh-back-top-border | roottrigger | borderborder-color | defaultdisabledfocus-visiblevariant=outline | --xh-_action-variant-border-disabled--xh-_action-variant-border-focus-visible--xh-_action-variant-border-rest--xh-_material-border | back-top 的 root、trigger 部件 border、border-color 覆盖槽。 |
--xh-back-top-border-hover | roottrigger | border-color | disabledhoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressedvariant=outline | --xh-_action-variant-border-hover--xh-_action-variant-border-pressed--xh-_material-border | back-top 的 root、trigger 部件 border-color 覆盖槽。 |
--xh-back-top-fg | roottrigger | color | defaultdisabledfocus-visiblehoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressedvariant=outline | --xh-_action-variant-fg-focus-visible--xh-_action-variant-fg-hover--xh-_action-variant-fg-pressed--xh-_action-variant-fg-rest--xh-_material-fg | back-top 的 root、trigger 部件 color 覆盖槽。 |
--xh-back-top-icon-size | trigger | --xh-icon-size | default | --xh-_action-profile-glyph-size | back-top 的 trigger 部件 --xh-icon-size 覆盖槽。 |
--xh-back-top-inset-block | root | inset-block-end | default | --xh-space-8 | back-top 的 root 部件 inset-block-end 覆盖槽。 |
--xh-back-top-inset-inline | root | inset-inline-end | default | --xh-space-8 | back-top 的 root 部件 inset-inline-end 覆盖槽。 |
--xh-back-top-layer | root | z-index | default | --xh-layer-sticky | back-top 的 root 部件 z-index 覆盖槽。 |
--xh-back-top-radius | trigger | border-radius | default | --xh-_action-profile-radius | back-top 的 trigger 部件 border-radius 覆盖槽。 |
--xh-back-top-shadow | roottrigger | box-shadow | defaultdisabledfocus-visiblehoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressedvariant=outline | --xh-_material-shadownone | back-top 的 root、trigger 部件 box-shadow 覆盖槽。 |
--xh-back-top-size | trigger | block-sizeinline-size | defaultxh-action-profile=floating | --xh-_action-profile-visual-size | back-top 的 trigger 部件 block-size、inline-size 覆盖槽。 |
动效
动效角色：按压 · 状态 · 出现（锚定面板） · 出现（无锚定弹出）（见动效规范）。
共享关键帧 xh-pop-in · xh-pop-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立。时长与缓动读动效令牌，改令牌即改全局节奏。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。