xtf-back-top

组件说明

xtf-back-top 是回到顶部按钮组件，当页面滚动超过指定阈值时自动显示，点击后平滑滚动回页面顶部。支持多种视觉变体（实心、柔和、描边、玻璃、极简、渐变）、图标/图片/文字自定义和插槽定制，适用于长页面快速返回顶部的场景。

基础用法

1. 最简示例

通过 scrollTop 绑定页面滚动位置，当滚动超过 threshold（默认 400px）时自动显示：

vue

<template>
  <view>
    <view v-for="i in 50" :key="i" style="padding: 24rpx; border-bottom: 1rpx solid #eee">
      列表项 {{ i }}
    </view>
    <xtf-back-top :scroll-top="scrollTop" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0
    }
  },
  onPageScroll(e) {
    this.scrollTop = e.scrollTop
  }
}
</script>

2. 带文字与变体切换

通过 text 添加辅助文字，通过 variant 切换视觉风格：

vue

<template>
  <view>
    <view
      style="display: flex; gap: 16rpx; position: fixed; top: 40rpx; right: 20rpx; z-index: 999"
    >
      <xtf-button size="small" @click="variant = 'solid'">实心</xtf-button>
      <xtf-button size="small" @click="variant = 'soft'">柔和</xtf-button>
      <xtf-button size="small" @click="variant = 'outline'">描边</xtf-button>
      <xtf-button size="small" @click="variant = 'glass'">玻璃</xtf-button>
    </view>
    <view v-for="i in 50" :key="i" style="padding: 24rpx; border-bottom: 1rpx solid #eee">
      列表项 {{ i }}
    </view>
    <xtf-back-top :scroll-top="scrollTop" text="顶部" :variant="variant" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0,
      variant: 'solid'
    }
  },
  onPageScroll(e) {
    this.scrollTop = e.scrollTop
  }
}
</script>

3. 自定义图标与图片

通过 icon 更换图标，通过 image 使用自定义图片替代图标：

vue

<template>
  <view>
    <view v-for="i in 50" :key="i" style="padding: 24rpx; border-bottom: 1rpx solid #eee">
      列表项 {{ i }}
    </view>
    <xtf-back-top
      :scroll-top="scrollTop"
      image="https://picsum.photos/80/80?random=20"
      image-mode="aspectFit"
      variant="soft"
      shape="round"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0
    }
  },
  onPageScroll(e) {
    this.scrollTop = e.scrollTop
  }
}
</script>

4. 尺寸与形状

通过 size 控制按钮大小，通过 shape 切换形状，通过 right / bottom 调整位置：

vue

<template>
  <view>
    <view v-for="i in 50" :key="i" style="padding: 24rpx; border-bottom: 1rpx solid #eee">
      列表项 {{ i }}
    </view>
    <xtf-back-top
      :scroll-top="scrollTop"
      size="lg"
      shape="square"
      :right="40"
      :bottom="200"
      variant="elevated"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      scrollTop: 0
    }
  },
  onPageScroll(e) {
    this.scrollTop = e.scrollTop
  }
}
</script>

全部属性

属性	类型	默认值	作用描述	适用范围
`scrollTop`	`String \| Number`	`0`	当前页面滚动位置，需手动绑定 `onPageScroll`	控制显隐
`threshold`	`String \| Number`	`400`	显示按钮的滚动阈值（px），`scrollTop` 超过此值时显示	调整出现时机
`target`	`String`	`''`	滚动目标选择器，为空时回退到页面级滚动	指定滚动容器
`right`	`String \| Number`	`28`	距右侧距离（rpx）	调整水平位置
`bottom`	`String \| Number`	`120`	距底部距离（rpx）	调整垂直位置
`duration`	`Number`	`320`	滚动动画时长（毫秒）	调整滚动速度
`icon`	`String`	`'north'`	按钮图标名，支持 `xtf-icon` 图标库	自定义图标
`text`	`String`	`''`	按钮辅助文字	添加文字说明
`variant`	`String`	`'solid'`	视觉变体：`'solid'` / `'soft'` / `'outline'` / `'glass'` / `'minimal'` / `'elevated'`	切换视觉风格
`size`	`String`	`'md'`	按钮尺寸：`'sm'` / `'md'` / `'lg'`	控制按钮大小
`shape`	`String`	`'round'`	按钮形状：`'round'` 圆形 / `'square'` 圆角方形 / `'pill'` 胶囊形	切换形状
`image`	`String`	`''`	自定义图片地址，设置后替代图标	使用图片替代图标
`imageMode`	`String`	`'aspectFit'`	图片填充模式，对应 uni-app image 的 `mode`	控制图片裁切
`imageSize`	`String \| Number`	`''`	图片尺寸（rpx），默认跟随图标大小	自定义图片大小
`imageRadius`	`String \| Number`	`''`	图片圆角（rpx）	自定义图片圆角
`iconSize`	`String \| Number`	`''`	图标大小，默认按 `size` 自动计算	自定义图标大小
`iconColor`	`String`	`''`	图标颜色，默认按 `variant` 自动计算	自定义图标颜色
`textColor`	`String`	`''`	文字颜色，默认按 `variant` 自动计算	自定义文字颜色
`contentDirection`	`String`	`'column'`	内容排列方向：`'column'` 纵向 / `'row'` 横向	调整图标文字排列
`backgroundColor`	`String`	`''`	自定义背景色，覆盖 `variant` 默认背景	精确控制背景色
`borderColor`	`String`	`''`	自定义边框色	精确控制边框色
`shadow`	`String`	`''`	自定义阴影	精确控制阴影
`customClass`	`String`	`''`	按钮自定义类名	样式覆盖
`contentClass`	`String`	`''`	内容区域自定义类名	内容样式定制
`contentStyle`	`String \| Object`	`''`	内容区域自定义样式	内容样式定制
`iconClass`	`String`	`''`	图标自定义类名	图标样式定制
`iconStyle`	`String \| Object`	`''`	图标自定义样式	图标样式定制
`imageClass`	`String`	`''`	图片自定义类名	图片样式定制
`imageStyle`	`String \| Object`	`''`	图片自定义样式	图片样式定制
`textClass`	`String`	`''`	文字自定义类名	文字样式定制
`textStyle`	`String \| Object`	`''`	文字自定义样式	文字样式定制
`customStyle`	`String \| Object`	`''`	按钮自定义样式	动态样式覆盖

事件

事件名称	触发时机	回调参数	参数说明
`click`	点击按钮并执行滚动后触发	无	—

插槽

插槽名	说明
默认插槽	替换整个返回顶部按钮内容。

vue

<template>
  <xtf-back-top :scroll-top="scrollTop">
    <xtf-button shape="circle" size="sm" type="solid">
      <template #prefix><xtf-icon name="north" size="sm" /></template>
    </xtf-button>
  </xtf-back-top>
</template>

<script>
export default {
  data() {
    return { scrollTop: 0 }
  },
  onPageScroll(event) {
    this.scrollTop = event.scrollTop
  }
}
</script>

方法

方法名	参数	说明
`scrollToTop()`	无	立即调用页面或 `target` 指定容器的回顶逻辑，并触发 `click`。

主题说明

按钮背景使用 var(--xtf-back-top-bg)，边框使用 var(--xtf-back-top-border)，阴影使用 var(--xtf-back-top-shadow)
solid 变体背景为 var(--xtf-color-primary)，带主题色阴影
soft 变体背景为半透明白色，带浅灰边框
outline 变体背景为半透明白色，边框为主题色
glass 变体背景为半透明白色，带毛玻璃模糊效果
minimal 变体背景为半透明白色，无阴影
elevated 变体背景为主题色渐变，带加强阴影
出现动画为 xtf-back-top-pop（缩放 + 上移），时长 220ms

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

xtf-back-top ​

组件说明 ​

基础用法 ​

1. 最简示例 ​

2. 带文字与变体切换 ​

3. 自定义图标与图片 ​

4. 尺寸与形状 ​

全部属性 ​

事件 ​

插槽 ​

方法 ​

主题说明 ​