组件
    导航类

    回到顶部

    代码演示

    如何引入

    import { BackTop } from '@fibrous/semi-ui-react';

    基本用法

    BackTop 是一个 FloatButton，滚动超过 visibilityHeight 后出现，点击后把 target 滚动到顶部。默认显示回到顶部图标，可访问名称默认取自语言包（简体中文为「回到顶部」），可以通过 aria-label 覆盖。

    Scroll down to see the bottom-right gray button.
    代码
    import { BackTop } from '@fibrous/semi-ui-react';

export default function BackTopDemo() {
    return (
        <div>
            <span>Scroll down to see the bottom-right gray button.</span>
            <BackTop aria-label="Back to top" />
        </div>
    );
}

    自定义样式

    BackTop 默认距离底部 50px、距离右侧 100px（RTL 下为左侧），可以用 style 覆盖。

    外观通过 FloatButton 的 icon、shape、size、colorful、badge 定制。

    向下滚动，右下角会出现一个方形的多彩按钮。
    代码
    import { IconArrowUp } from '@fibrous/semi-icons-react';
import { BackTop } from '@fibrous/semi-ui-react';

export default function BackTopDemo() {
    return (
        <div>
            <span>向下滚动，右下角会出现一个方形的多彩按钮。</span>
            <BackTop aria-label="回到顶部" icon={<IconArrowUp />} shape="square" size="large" colorful style={{ bottom: 100 }} />
        </div>
    );
}

    API 参考

    Props

    属性说明类型默认值
    aria-label按钮的可访问名称；未传且没有 children 时取语言包中的「回到顶部」。string-
    badge徽章参数，同 FloatButton。BadgeProps-
    children按钮内的静态内容，传入时代替 icon 显示。不能包含链接、按钮、输入框等可交互元素，开发环境下检测到会警告。React.ReactNode-
    className类名，与组件自身的类名合并后落在 <button> 上。string-
    colorful多彩按钮，同 FloatButton；未设置时为 false。boolean-
    duration滚动到顶部所需的毫秒数；点击事件按此间隔节流。number450
    icon按钮图标，传入元素；未设置时为 IconBackTop。React.ReactNode-
    onClick点击时调用，参数为原生 click 事件；按 duration 节流，调用时滚动已开始。Type(e: React.MouseEvent) => void-
    ref指向按钮 <button>，只在按钮显示时存在。TypeReact.Ref<HTMLButtonElement>-
    shape形状，可选 round、square；未设置时为 FloatButton 的默认值 round。'square' | 'round'-
    size尺寸，可选 default、small、large；未设置时为 FloatButton 的默认值 default。'small' | 'default' | 'large'-
    style按钮的内联样式，可用于覆盖默认的位置等样式。React.CSSProperties-
    target返回被监听滚动元素的函数，未设置时为 window；返回 null 表示节点尚不可用。挂载后调用一次，此时父容器的 ref 已可读取；之后只在函数本身变化时重新调用。稳定的函数晚于挂载才返回元素时，需要重新挂载 BackTop。Type() => Target | null-
    visibilityHeight出现 BackTop 需要达到的滚动高度。number400

    其他原生属性（如 data-*、aria-*）经 ...rest 透传到 FloatButton，落在 <button> 上。

    Accessibility

    ARIA

    • BackTop 渲染为单个原生按钮 <button type="button">，读屏软件读作按钮
    • 可访问名称取自 aria-label；没有时，传入了按钮内容则取按钮内容，否则取语言包中的默认名称（简体中文为「回到顶部」）
    • children（Vue 中为默认插槽）是按钮内的静态内容，会成为按钮名称的一部分；按钮内不能嵌套可交互元素

    键盘和焦点

    • 按钮显示后可以用 Tab 及 Shift + Tab 聚焦，聚焦时按 Enter 或 Space 滚动到顶部
    • 键盘聚焦时显示聚焦轮廓

    设计变量

    下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。
    Sass 变量值用法
    $spacing-backtop-right100px返回顶部距离右侧距离
    $spacing-backtop-bottom50px返回顶部距离底侧距离