BackTop 返回頂部

捲動超過閾值出現、點選回頂。平滑捲動走原生 scrollTo({ behavior: 'smooth' })，prefers-reduced-motion 自動降級。

基礎用法

基礎用法（向下捲動查看）

<script setup lang="ts">
</script>

<template>
  <!-- 基礎用法 -->
  <LhBackTop :right="24" :bottom="24" />
</template>

<script>
export default {}
</script>

<template>
  <!-- 基礎用法 -->
  <LhBackTop :right="24" :bottom="24" />
</template>

visibility-height 自訂出現閾值，smooth 關閉平滑捲動，target 監聽指定捲動容器。

自訂閾值與關閉平滑

<script setup lang="ts">
</script>

<template>
  <!-- 自訂閾值與關閉平滑 -->
  <LhBackTop :visibility-height="80" :smooth="false" :right="24" :bottom="90" />
</template>

<script>
export default {}
</script>

<template>
  <!-- 自訂閾值與關閉平滑 -->
  <LhBackTop :visibility-height="80" :smooth="false" :right="24" :bottom="90" />
</template>

捲動停止（scrollend）

@scrollend 在捲動停止時拋出目前捲動距離：原生 scrollend 事件優先 （Chromium 114+ / Safari 18.2+），舊瀏覽器自動退回 scroll + 150ms 防抖。常用於錨點連動、資料延遲載入。

scrollend 事件

最近一次停止位置：（未滾動）

<script setup>
import { ref } from 'vue'

const lastStop = ref('（未滚动）')

function onScrollEnd(scrollTop) {
  lastStop.value = `${scrollTop}px`
}
</script>

<template>
  <LhBackTop :right="24" :bottom="160" @scrollend="onScrollEnd" />
</template>

<script>
export default {
  data() {
    return { lastStop: '（未滚动）' }
  },
  methods: {
    onScrollEnd(scrollTop) {
      this.lastStop = `${scrollTop}px`
    },
  },
}
</script>

<template>
  <LhBackTop :right="24" :bottom="160" @scrollend="onScrollEnd" />
</template>

API

LhBackTop Props

屬性名	說明	類型	預設值
target	捲動容器（選擇器或元素，預設視窗）	string | HTMLElement	—
visibilityHeight	捲動多少像素後出現	number	200
right	距右側偏移 px	number	40
bottom	距底部偏移 px	number	40
smooth	是否平滑捲動	boolean	true
sx	sx 快速版面配置屬性	LhSxProps	—

Events

事件名	說明	回呼參數
click	點選按鈕時觸發（隨後執行回頂捲動）	(event: MouseEvent)
scrollend	捲動停止時觸發，攜帶目前捲動距離	(scrollTop: number)

插槽：default（自訂內容）。

無障礙

• 真實 <button>，純圖示形態必須命名（語言包 backtop.label）
• 出現/消失不進入焦點樹衝突（隱藏時 v-if 移出）

類型定義

本元件對外匯出的 TypeScript 類型結構如下（自動提取自 packages/components/backtop/src/types.ts 與 @lh-ui/share/core/* 原始碼，點選各條目展開檢視完整定義；屬性說明見上方 Props 表）：

LhBackTopProps

export interface LhBackTopProps {
  /** 捲動容器（選擇器或元素，預設視窗） */
  target?: string | HTMLElement
  /** 捲動多少像素後出現 */
  visibilityHeight?: number
  /** 距右側偏移 px */
  right?: number
  /** 距底部偏移 px */
  bottom?: number
  /** 是否平滑捲動 */
  smooth?: boolean
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

常數

本元件用到的公開常數如下（可在 Props 表的「類型 / 預設值」欄點選同名條目跳轉至此）：

LH_BACKTOP_VISIBILITY_HEIGHT_DEFAULT _{（來自 @lh-ui/share/core/backtop）}

/** 預設捲動閾值 px */
export const LH_BACKTOP_VISIBILITY_HEIGHT_DEFAULT = 200

LH_BACKTOP_SCROLLEND_DELAY _{（來自 @lh-ui/share/core/backtop）}

/** scrollend 防抖兜底的靜止閾值 ms（僅在不支援原生 scrollend 的瀏覽器使用） */
export const LH_BACKTOP_SCROLLEND_DELAY = 150