Files
template/docs/render-guide/advanced/builtin-text.md
T

8.9 KiB
Raw Blame History

内置组件:文本

文字元素只画一行。要让长文字按宽度折行、逐字显示或自动向上滚动时,用内置的文本组件。这一篇讲 TextContent 和 ScrollText,每个都先说它解决什么问题,再给最小写法,最后接一个 live。

前置知识

阅读本篇前,建议先读完:

TextContent

要让长文字按宽度自动折行,用 TextContent。

第一步:必须给 width,排版只按这个宽度折行;text 放内容,loc 前两项决定位置。

import { TextContent } from '@user/client-base';

// 组件内容
<TextContent
    loc={[40, 40]}
    width={360}
    text="这段文字会按 width 折行,超出的部分换到下一行。"
/>;

高度默认由 loc 的第四项决定;不想自己算高度时加 autoHeight,组件按内容算高度。

想让文字逐字显示,加 interval,单位是毫秒,0 表示一次显示完:

<TextContent
    loc={[40, 40]}
    width={360}
    autoHeight
    interval={30}
    text="这段文字会按 width 折行,并逐字显示。"
/>

打字结束时要做点什么,用 onTypeEnd。

<TextContent
    loc={[40, 40]}
    width={360}
    autoHeight
    interval={30}
    text="打完这段文字后会触发回调。"
    onTypeEnd={() => {
        // 打字结束时执行
    }}
/>

全部参数:

属性 作用 默认或常用值
text 显示的文字 ''
width 折行宽度 必填
loc 位置与高度 [](即 [0, 0])
autoHeight 按内容计算高度 false
interval 逐字间隔,单位毫秒 0
font 文字字体 new Font()
lineHeight 行与行之间的额外间距 0
fill / stroke 填充 / 描边文字 true / false
fillStyle / strokeStyle 填充 / 描边颜色 #fff / #000
strokeWidth 描边线宽 2
textAlign 多行文字左对齐 / 居中 / 右对齐 TextAlign.Left
wordBreak 断词规则:不换行 / 空格与 CJK 处 / 任意字符 WordBreak.Space
breakChars 额外参与分词的字符 ''
ignoreLineStart 不放在行首的字符 ''
ignoreLineEnd 不放在行尾的字符 ''
onTypeStart / onTypeEnd 开始 / 结束打字时触发 无
onUpdateHeight 高度重算后触发,参数为新高度 无

多行文字时,lineHeight 默认为 0,行与行会贴得比较紧;通常设成 8 左右阅读起来更舒展。

需要重播或立刻显示全文时,组件实例还暴露 retype()、showAll() 和 getHeight()。

文本标记

要在文本里改颜色,写 [c=颜色]...[/c]:

<TextContent loc={[40, 40]} width={360} text="[c=#f2b84b]这一段是黄色[/c]" />

要改字号,写 [s=字号]...[/s]:

<TextContent loc={[40, 40]} width={360} text="[s=20]这一段字更大[/s]" />

要换行,写 \n;在 TSX 里用模板字符串或字符串拼接:

<TextContent loc={[40, 40]} width={360} text={'第一行\n第二行'} />

[[ 输出一个普通的 [,]] 输出一个普通的 ]。要显示 [[ 和 ]] 本身,源文本里写成 [[[[ 和 ]]]]:

<TextContent loc={[40, 40]} width={360} text="这里显示 [[[[方括号]]]] 本身" />

[c=...] 与 [s=...] 要成对闭合,可以嵌套,例如 [c=#f2b84b][s=20]标题[/s][/c]。只写 [c] 没有颜色参数,不会按标记处理,会原样显示。

需要粗体、斜体、换字体、等待或图标时,再用这些标记:

标记 作用
[b] 切换粗体
[i] 切换斜体
[f=字体名]...[/f] 改字体族
[w=字数] 等待若干个字的时间
[icon=图标名] 插入图标

[b] 和 [i] 是切换,不是成对闭合:写一次切换一次。标记可以组合使用,也可以跨行书写。

把颜色、字号、换行与方括号放在一起:

<TextContent
    loc={[40, 40]}
    width={360}
    autoHeight
    lineHeight={8}
    text={
        '[c=#f2b84b][s=20]标题[/s][/c]\n' +
        '[c=#7ee787]正文里的 [[[[方括号]]]] 会原样显示[/c]\n' +
        '[c=#8aa0b8][s=13]小字注释[/s][/c]'
    }
/>
渲染示例需要浏览器环境。

同一段文字里混用了颜色、字号、手动换行与方括号字面量,长句会按 width 折行。

ScrollText

要让文字自动向上滚动,用 ScrollText。

基本写法里,width 是文字的最大宽度,speed 是每秒滚动的像素数,text 放内容,loc 是滚动区域的视口。

import { ScrollText } from '@user/client-base';

// setup
const notice = '这是一条会自己向上滚动的公告。'.repeat(8);

// 组件内容
<ScrollText
    loc={[40, 40, 400, 160]}
    width={400}
    speed={50}
    text={notice}
    fillStyle="#e8f0ff"
/>;

文字从下往上滚过视口,超出视口的部分不显示。

开始滚动前想先留一点空白,用 pad 给预留的像素数,默认 16:

<ScrollText
    loc={[40, 40, 400, 160]}
    width={400}
    speed={50}
    pad={32}
    text={notice}
/>

排版参数与 TextContent 相同,fillStyle、font、lineHeight 照常写。width 是滚动区宽度,文字实际按 width - 16 折行;loc 的第四项是视口高度,省略时取 width。

全部参数:

属性 作用 默认或常用值
loc 滚动视口的位置与大小 必填
width 滚动区宽度 必填
speed 每秒滚动像素数 必填
pad 开始滚动前预留的像素 16
text 滚动文字 ''
font 文字字体 new Font()
fillStyle / strokeStyle 填充 / 描边颜色 #fff / #000
fill / stroke 填充 / 描边文字 true / false
strokeWidth 描边线宽 2
lineHeight 行与行之间的额外间距 0
textAlign 多行文字左对齐 / 居中 / 右对齐 TextAlign.Left
wordBreak 断词规则:不换行 / 空格与 CJK 处 / 任意字符 WordBreak.Space
onScrollEnd 滚动到底时触发一次,随后停止 无

需要中途控制滚动时,组件实例还暴露 pause()、resume()、setSpeed(speed) 和 rescroll()。

渲染示例需要浏览器环境。

公告在固定视口里持续向上滚动。

<script setup> import RenderDemo from '../../.vitepress/components/renderDemo.vue'; const textContentLoader = () => import('../../.vitepress/components/demos/ui/builtin-textcontent-demo.tsx'); const scrollTextLoader = () => import('../../.vitepress/components/demos/ui/builtin-scrolltext-demo.tsx'); </script>