HumanBreak/docs/api/user-client-modules/组件 ScrollText.md

ScrollText 组件 API 文档

本文档由 DeepSeek R1 模型生成并微调。

---

核心特性

• 自动滚动：支持设定滚动速度的纵向滚动效果
• 长文本支持：内置高性能文本渲染引擎
• 精准控制：提供播放/暂停/调速等操作接口
• 智能布局：自动计算文本高度和滚动距离

---

Props 属性说明

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	立即重置到起始位置重新滚动

---

使用示例

基础滚动

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" // 薰衣草色文字
        />
    );
});

动态控制

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('滚动结束')}
        />
    );
});

复杂排版

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. 组合动画
   可与容器变换配合实现复杂效果：

   <container rotation={-5} alpha={0.9}>
       <ScrollText />
   </container>