العودة للأعلى 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

الخاصية	الوصف	النوع	الافتراضي
target	حاوية التمرير (محدد أو عنصر، الافتراضي إطار العرض)	string | HTMLElement	—
visibilityHeight	عدد البكسلات التي بعد تجاوزها يظهر الزر	number	200
right	الإزاحة عن الحافة الجانبية px	number	40
bottom	الإزاحة عن الحافة السفلية px	number	40
smooth	ما إذا كان التمرير سلسًا	boolean	true
sx	خصائص التخطيط السريع sx	LhSxProps	—

أحداث LhBackTop

الحدث	الوصف	معاملات الاستدعاء
click	يُطلق عند النقر على الزر (ينفّذ بعده التمرير إلى الأعلى)	(event: MouseEvent)
scrollend	يُطلق عند توقّف التمرير، حاملًا مسافة التمرير الحالية	(scrollTop: number)

الفتحات: default (محتوى مخصص).

إمكانية الوصول

• عنصر <button> حقيقي، وفي حالة الأيقونة فقط يجب تسميته (حزمة اللغة backtop.label)
• لا يسبب الظهور/الاختفاء تعارضًا في شجرة التركيز (يُزال عبر v-if عند الإخفاء)

تعريفات الأنواع

بنى TypeScript التي يصدّرها هذا المكوّن خارجيًا (مستخرَجة تلقائيًا من packages/components/backtop/src/types.ts و@lh-ui/share/core/*؛ انقر كل عنصر لعرض التعريف كاملًا؛ وصف الخصائص في جدول الخصائص أعلاه):

LhBackTopProps

export interface LhBackTopProps {
  /** حاوية التمرير (محدد أو عنصر، الافتراضي إطار العرض) */
  target?: string | HTMLElement
  /** عدد البكسلات التي بعد تجاوزها يظهر الزر */
  visibilityHeight?: number
  /** الإزاحة عن الحافة الجانبية px */
  right?: number
  /** الإزاحة عن الحافة السفلية px */
  bottom?: number
  /** ما إذا كان التمرير سلسًا */
  smooth?: boolean
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

الثوابت

الثوابت العامة التي يستخدمها هذا المكوّن (يمكن النقر على العنصر الذي يحمل الاسم نفسه في عمودَي «النوع / الافتراضي» بجدول الخصائص للقفز إلى هنا):

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