FmScrollArea 滚动区域组件

自定义滚动条的滚动容器，支持水平/垂直滚动、渐变遮罩和滚动事件监听。

基础用法

<template>
  <FmScrollArea class="h-64">
    <div>长内容...</div>
  </FmScrollArea>
</template>

Props

属性	类型	默认值	说明
horizontal	boolean	false	是否启用水平滚动
scrollbar	boolean	true	是否显示滚动条
mask	boolean	false	是否显示渐变遮罩
class	HTMLAttributes['class']	-	容器 CSS 类
contentClass	HTMLAttributes['class']	-	滚动内容区 CSS 类

Slots

名称	说明
default	滚动内容

Events

事件名	参数	说明
onScroll	Event	滚动时触发

Exposed Methods

方法名	参数	说明
scrollTo	(scrollNumber: number, behavior?: ScrollBehavior) => void	滚动到指定位置
ref	-	内部 ScrollArea 引用

示例

垂直滚动

<template>
  <FmScrollArea class="h-64 w-96">
    <div class="space-y-2">
      <p v-for="i in 50" :key="i">滚动内容 {{ i }}</p>
    </div>
  </FmScrollArea>
</template>

水平滚动

<template>
  <FmScrollArea horizontal class="w-96">
    <div class="flex gap-4">
      <div v-for="i in 20" :key="i" class="w-32 h-32 bg-muted flex-center">
        项目 {{ i }}
      </div>
    </div>
  </FmScrollArea>
</template>

隐藏滚动条

<template>
  <FmScrollArea :scrollbar="false" class="h-64">
    <div>内容（无滚动条）</div>
  </FmScrollArea>
</template>

渐变遮罩

<template>
  <FmScrollArea :mask="true" class="h-64">
    <div class="space-y-2">
      <p v-for="i in 50" :key="i">内容 {{ i }}</p>
    </div>
  </FmScrollArea>
</template>

自定义遮罩颜色

<template>
  <FmScrollArea
    :mask="true"
    class="h-64"
  >
    <div>内容</div>
  </FmScrollArea>
</template>

监听滚动事件

<script setup lang="ts">
function onScroll(event: Event) {
  const target = event.target as HTMLElement
  console.log('scrollTop:', target.scrollTop)
}
</script>

<template>
  <FmScrollArea class="h-64" @on-scroll="onScroll">
    <div>滚动内容...</div>
  </FmScrollArea>
</template>

编程式滚动

<script setup lang="ts">
const scrollRef = ref<InstanceType<typeof FmScrollArea>>()

function scrollToTop() {
  scrollRef.value?.scrollTo(0, 'smooth')
}

function scrollToBottom() {
  scrollRef.value?.scrollTo(9999, 'smooth')
}
</script>

<template>
  <FmScrollArea ref="scrollRef" class="h-64">
    <div class="space-y-2">
      <p v-for="i in 50" :key="i">内容 {{ i }}</p>
    </div>
  </FmScrollArea>

  <div class="flex gap-2 mt-4">
    <FmButton @click="scrollToTop">回到顶部</FmButton>
    <FmButton @click="scrollToBottom">滚动到底部</FmButton>
  </div>
</template>

注意事项

1. 必须设置尺寸：需要设置 height 或 max-height 等限制高度的样式才能触发滚动
2. 水平滚动：启用 horizontal 时，内容需要超出容器宽度才能触发水平滚动
3. 渐变遮罩：mask 为 true 时会在内容顶部/底部显示渐变遮罩效果
4. 滚动条样式：使用自定义滚动条样式，与系统默认滚动条不同

典型使用场景

• 长列表内容滚动
• 侧边栏滚动区域
• 聊天消息滚动
• 水平滚动的卡片列表
• 固定高度的内容容器