mirror of
https://github.com/unanmed/HumanBreak.git
synced 2025-10-31 12:12:58 +08:00
161 lines
4.1 KiB
Markdown
161 lines
4.1 KiB
Markdown
# ScrollText 组件 API 文档
|
||
|
||
本文档由 `DeepSeek R1` 模型生成并微调。
|
||
|
||
---
|
||
|
||
## 核心特性
|
||
|
||
- **自动滚动**：支持设定滚动速度的纵向滚动效果
|
||
- **长文本支持**：内置高性能文本渲染引擎
|
||
- **精准控制**：提供播放/暂停/调速等操作接口
|
||
- **智能布局**：自动计算文本高度和滚动距离
|
||
|
||
---
|
||
|
||
## Props 属性说明
|
||
|
||
```mermaid
|
||
graph LR
|
||
ScrollTextProps --> TextContentProps
|
||
ScrollTextProps --> ScrollProps
|
||
|
||
click TextContentProps "./组件%20TextContent"
|
||
click ScrollProps "./组件%20Scroll"
|
||
```
|
||
|
||
完全继承 `TextContent` 组件和 `Scroll` 组件的参数和事件。
|
||
|
||
| 属性名 | 类型 | 默认值 | 描述 |
|
||
| ------- | ---------------- | ------ | --------------------------- |
|
||
| `speed` | `number` | 必填 | 滚动速度（像素/秒） |
|
||
| `width` | `number` | 必填 | 文本区域固定宽度（像素） |
|
||
| `loc` | `ElementLocator` | 必填 | 容器定位 [x,y,width,height] |
|
||
| `pad` | `number` | `16` | 首行前空白距离（像素） |
|
||
|
||
---
|
||
|
||
## 事件说明
|
||
|
||
| 事件名 | 参数 | 触发时机 |
|
||
| ----------- | ---- | -------------------- |
|
||
| `scrollEnd` | - | 滚动到文本末尾时触发 |
|
||
|
||
---
|
||
|
||
## Exposed Methods 暴露方法
|
||
|
||
| 方法名 | 参数 | 返回值 | 描述 |
|
||
| ---------- | --------------- | ------ | --------------------------- |
|
||
| `pause` | - | void | 暂停滚动 |
|
||
| `resume` | - | void | 继续滚动 |
|
||
| `setSpeed` | `speed: number` | void | 动态调整滚动速度（像素/秒） |
|
||
| `rescroll` | - | void | 立即重置到起始位置重新滚动 |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 基础滚动
|
||
|
||
```tsx
|
||
import { defineComponent } from 'vue';
|
||
import { ScrollText } from '@user/client-modules';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
const longText = '序幕\n'.repeat(100) + '——全剧终——';
|
||
|
||
return () => (
|
||
<ScrollText
|
||
text={longText}
|
||
speed={80} // 每秒滚动80像素
|
||
width={416} // 文本区域宽度
|
||
loc={[0, 0, 416, 416]} // 容器位置和尺寸
|
||
fillStyle="#E6E6FA" // 薰衣草色文字
|
||
/>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 动态控制
|
||
|
||
```tsx
|
||
import { defineComponent, ref } from 'vue';
|
||
import { ScrollText } from '@user/client-modules';
|
||
|
||
export const MyCom = defineComponent(() => {
|
||
const longText = '序幕\n'.repeat(100) + '——全剧终——';
|
||
const scrollRef = ref<ScrollTextExpose>();
|
||
|
||
// 暂停/恢复控制
|
||
const toggleScroll = () => {
|
||
if (scrollRef.value?.isPaused) {
|
||
scrollRef.value.resume();
|
||
} else {
|
||
scrollRef.value?.pause();
|
||
}
|
||
};
|
||
|
||
// 速度控制
|
||
const accelerate = () => {
|
||
scrollRef.value?.setSpeed(200);
|
||
};
|
||
|
||
return () => (
|
||
<ScrollText
|
||
ref={scrollRef}
|
||
text={longText}
|
||
speed={100}
|
||
width={416}
|
||
loc={[0, 0, 416, 416]}
|
||
onScrollEnd={() => console.log('滚动结束')}
|
||
/>
|
||
);
|
||
});
|
||
```
|
||
|
||
### 复杂排版
|
||
|
||
```tsx
|
||
const staffText =
|
||
'\\c[32]====制作人员====\\c\n\n' +
|
||
'\\r[#FFD700]总监督\\r\t\t张三\n' +
|
||
'\\r[#00FF00]美术指导\\r\\t李四\n' +
|
||
'\\i[logo]\n' +
|
||
'特别感谢：某某公司';
|
||
|
||
<ScrollText
|
||
text={staffText}
|
||
speed={120}
|
||
width={720}
|
||
loc={[40, 40, 720, 560]}
|
||
pad={40} // 顶部留白
|
||
font={new Font('黑体', 24)}
|
||
lineHeight={8} // 行间距
|
||
interval={0} // 禁用打字机效果
|
||
/>;
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **容器尺寸**
|
||
实际可滚动区域计算公式：
|
||
|
||
```
|
||
可视高度 = loc[3]（容器高度）
|
||
滚动距离 = 文本总高度 + pad（首行前空白）
|
||
```
|
||
|
||
2. **速度控制**
|
||
推荐速度范围 50-200 像素/秒
|
||
|
||
3. **组合动画**
|
||
可与容器变换配合实现复杂效果：
|
||
```tsx
|
||
<container rotation={-5} alpha={0.9}>
|
||
<ScrollText />
|
||
</container>
|
||
```
|