mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-10-31 12:12:58 +08:00
130 lines
3.5 KiB
Markdown
130 lines
3.5 KiB
Markdown
# Scroll 滚动组件 API 文档
|
||
|
||
本文档由 `DeepSeek R1` 模型生成并微调。
|
||
|
||
## 组件特性
|
||
|
||
- **虚拟滚动**：自动裁剪可视区域外元素
|
||
- **双模式支持**：垂直/水平滚动（默认垂直）
|
||
- **性能优化**：动态计算可视区域，支持万级元素流畅滚动
|
||
- **编程控制**：支持精准定位滚动位置
|
||
|
||
---
|
||
|
||
## Props 属性说明
|
||
|
||
| 属性名 | 类型 | 默认值 | 描述 |
|
||
| ---------- | ---------------- | ------- | ------------------------------------------------- |
|
||
| `hor` | `boolean` | `false` | 启用水平滚动模式 |
|
||
| `noscroll` | `boolean` | `false` | 是否不显示滚动条，可用于一些特殊场景 |
|
||
| `loc` | `ElementLocator` | 必填 | 滚动容器定位配置 |
|
||
| `padEnd` | `number` | `0` | 滚动到底部/右侧的额外留白（用于修正自动计算误差） |
|
||
|
||
---
|
||
|
||
## Exposed Methods 暴露方法
|
||
|
||
| 方法名 | 参数 | 返回值 | 描述 |
|
||
| ----------------- | --------------------------------- | -------- | --------------------------------------------------- |
|
||
| `scrollTo` | `position: number, time?: number` | `void` | 滚动到指定位置（单位：像素），time 为过渡时间（ms） |
|
||
| `getScrollLength` | - | `number` | 获取最大可滚动距离（单位：像素） |
|
||
|
||
---
|
||
|
||
## Slots 插槽说明
|
||
|
||
### `default`
|
||
|
||
接收滚动内容，**必须直接包含可渲染元素**
|
||
⚠️ 禁止嵌套 container 包裹，推荐平铺结构：
|
||
|
||
```tsx
|
||
// ✅ 正确写法
|
||
<Scroll>
|
||
<item />
|
||
<item />
|
||
<item />
|
||
</Scroll>;
|
||
|
||
// ❌ 错误写法（影响虚拟滚动计算）
|
||
<Scroll>
|
||
<container>
|
||
// 会导致整体被视为单个元素
|
||
<item />
|
||
<item />
|
||
</container>
|
||
</Scroll>;
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 基础垂直滚动
|
||
|
||
```tsx
|
||
import { defineComponent } from 'vue';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
const list = Array(200).fill(0);
|
||
|
||
return () => (
|
||
<Scroll loc={[208, 208, 208, 208, 0.5, 0.5]}>
|
||
{list.map((_, index) => (
|
||
<text key={index} text={index.toString()} />
|
||
))}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 水平滚动 + 编程控制
|
||
|
||
```tsx
|
||
import { defineComponent, ref, onMounted } from 'vue';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
const list = Array(200).fill(0);
|
||
const scrollRef = ref<ScrollExpose>();
|
||
|
||
// 滚动水平 100 像素位置，动画时长 500 毫秒
|
||
onMounted(() => {
|
||
scrollRef.value?.scrollTo(100, 500);
|
||
});
|
||
|
||
return () => (
|
||
<Scroll hor loc={[208, 208, 208, 208, 0.5, 0.5]} ref={scrollRef}>
|
||
{list.map((_, index) => (
|
||
<text key={index} text={index.toString()} />
|
||
))}
|
||
</Scroll>
|
||
);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 性能优化指南
|
||
|
||
### 1. 替代方案建议
|
||
|
||
⚠️ **当子元素数量 > 1000 时**，推荐改用分页组件：
|
||
|
||
```tsx
|
||
// 使用 Page 组件处理超大数据集
|
||
<Page pages={Math.ceil(data.length / 50)}>
|
||
{page => renderChunk(data.slice(page * 50, (page + 1) * 50))}
|
||
</Page>
|
||
```
|
||
|
||
### 2. 缓存建议
|
||
|
||
如果子元素数量较多，建议给 `Scroll` 组件的所有子元素添加 `nocache` 标记：
|
||
|
||
```tsx {2}
|
||
<Scroll>
|
||
<item nocache />
|
||
{/* 更多内容 */}
|
||
</Scroll>
|
||
```
|