npm package: @frameui/fui-scroll-rect
Description: A scroll rect component for FrameUI
Author: liuzhaolei
Latest version: 2.0.1

# FUI Scroll Rect 2.0

一个功能强大的 Vue 3 滚动矩形组件，提供自定义滚动条、多方向滚动支持和丰富的配置选项。

## ✨ 特性

- 🚀 **Vue 3 支持** - 基于 Vue 3 Composition API 构建
- 🎯 **多方向滚动** - 支持垂直、水平、双向滚动或无滚动
- 🎨 **自定义滚动条** - 可自定义滚动条样式和行为
- 📱 **响应式设计** - 自动检测内容变化和容器大小变化
- 🖱️ **鼠标拖拽** - 支持拖拽滚动条进行滚动
- 🎭 **插槽支持** - 提供滚动条插槽用于自定义滚动条
- 📦 **TypeScript** - 完整的 TypeScript 类型支持
- 🎪 **事件系统** - 丰富的滚动事件和生命周期事件

## 📦 安装

```bash
npm install @frameui/fui-scroll-rect
```

## 🚀 快速开始

### 全局注册

```typescript
import { createApp } from 'vue'
import App from './App.vue'
import ScrollRect from '@frameui/fui-scroll-rect'

const app = createApp(App)
app.use(ScrollRect)
app.mount('#app')
```

### 局部引入

```vue
<template>
  <ScrollRect class="scroll-container" :height="300">
    <div class="content">
      <!-- 你的滚动内容 -->
      <p v-for="i in 50" :key="i">这是第 {{ i }} 行内容</p>
    </div>
  </ScrollRect>
</template>

<script setup lang="ts">
import { ScrollRect } from '@frameui/fui-scroll-rect'
</script>

<style>
.scroll-container {
  width: 100%;
  border: 1px solid #ddd;
}

.content {
  padding: 20px;
}
</style>
```

## 📖 基础用法

### 基本滚动容器

```vue
<template>
  <ScrollRect class="basic-scroll" :height="300">
    <div class="long-content">
      <h1>长内容标题</h1>
      <p>这是一段很长的内容，需要滚动才能看到全部...</p>
      <!-- 更多内容 -->
    </div>
  </ScrollRect>
</template>
```

### 设置最大高度

```vue
<template>
  <ScrollRect :maxHeight="300">
    <div class="dynamic-content">
      <!-- 内容高度小于300px时不会滚动，超出时自动滚动 -->
    </div>
  </ScrollRect>
</template>
```

### 水平滚动

```vue
<template>
  <ScrollRect scroll="horizontal" :width="400" :height="200">
    <div class="wide-content" style="width: 800px;">
      <!-- 宽度超出400px的内容 -->
    </div>
  </ScrollRect>
</template>
```

### 双向滚动

```vue
<template>
  <ScrollRect scroll="both" :width="400" :height="300">
    <div class="large-content" style="width: 600px; height: 500px;">
      <!-- 宽高都超出的内容 -->
    </div>
  </ScrollRect>
</template>
```

## ⚙️ 属性配置

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `scroll` | `'both' \| 'none' \| 'vertical' \| 'horizontal'` | `'both'` | 滚动方向 |
| `scrollBarAlwaysShow` | `boolean` | `false` | 是否始终显示滚动条 |
| `scrollBarBackgroundClickable` | `boolean` | `false` | 滚动条背景是否可点击 |
| `height` | `number` | `undefined` | 容器高度（像素） |
| `width` | `number` | `undefined` | 容器宽度（像素） |
| `maxHeight` | `number` | `undefined` | 内容最大高度 |
| `maxWidth` | `number` | `undefined` | 内容最大宽度 |
| `containerClass` | `string` | `''` | 内容容器CSS类名 |
| `containerStyle` | `object` | `{}` | 内容容器样式对象 |
| `scrollToStartThreshold` | `number` | `50` | 触发滚动到开始事件的阈值 |
| `scrollToEndThreshold` | `number` | `50` | 触发滚动到结束事件的阈值 |

## 🎯 事件

| 事件名 | 参数 | 说明 |
|--------|------|------|
| `scroll` | `event: Event` | 滚动事件 |
| `resized` | - | 容器大小变化事件 |
| `scrollToStart` | - | 滚动到开始位置事件 |
| `scrollToEnd` | - | 滚动到结束位置事件 |

## 🎨 插槽

### 默认插槽
用于放置滚动内容。

### 滚动条插槽

#### `scrollBarX` - 水平滚动条
```vue
<template #scrollBarX="{ scrollBarValue, onScroll }">
  <div class="custom-horizontal-scrollbar">
    <!-- 自定义水平滚动条 -->
  </div>
</template>
```

#### `scrollBarY` - 垂直滚动条
```vue
<template #scrollBarY="{ scrollBarValue, onScroll }">
  <div class="custom-vertical-scrollbar">
    <!-- 自定义垂直滚动条 -->
  </div>
</template>
```

## 🔧 高级用法

### 自定义滚动条样式

```vue
<template>
  <ScrollRect class="custom-scroll" :height="300">
    <div class="content">
      <!-- 内容 -->
    </div>
  </ScrollRect>
</template>

<style>
.custom-scroll {
  --scrollbar-width: 8px;
  --scrollbar-track-color: #f1f1f1;
  --scrollbar-thumb-color: #888;
  --scrollbar-thumb-hover-color: #555;
}

.custom-scroll .scrollbar {
  background: var(--scrollbar-track-color);
}

.custom-scroll .thumb {
  background: var(--scrollbar-thumb-color);
}

.custom-scroll .thumb:hover {
  background: var(--scrollbar-thumb-hover-color);
}
</style>
```

### 监听滚动事件

```vue
<template>
  <ScrollRect 
    :height="300" 
    @scroll="handleScroll"
    @scrollToStart="handleScrollToStart"
    @scrollToEnd="handleScrollToEnd"
  >
    <!-- 内容 -->
  </ScrollRect>
</template>

<script setup lang="ts">
const handleScroll = (event: Event) => {
  console.log('滚动事件:', event)
}

const handleScrollToStart = () => {
  console.log('滚动到开始位置')
}

const handleScrollToEnd = () => {
  console.log('滚动到结束位置')
}
</script>
```

## 🏗️ 开发

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run dev
```

### 构建库

```bash
npm run build-lib
```

### 构建文档

```bash
npm run build
```

## 📄 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 支持

如有问题，请通过以下方式联系：

- 提交 [Issue](https://github.com/your-repo/issues)
- 发送邮件至：your-email@example.com

---

**FUI Scroll Rect 2.0** - 让滚动更简单，让体验更流畅 🚀