# 内置组件:文本
文字元素只画一行。要让长文字按宽度折行、逐字显示或自动向上滚动时,用内置的文本组件。这一篇讲 `TextContent` 和 `ScrollText`,每个都先说它解决什么问题,再给最小写法,最后接一个 live。
## 前置知识
阅读本篇前,建议先读完:
- [什么是组件](./what-is-component.md)
- [内置组件:基础](./builtin-basic.md)
## TextContent
要让长文字按宽度自动折行,用 `TextContent`。
第一步:必须给 `width`,排版只按这个宽度折行;`text` 放内容,`loc` 前两项决定位置。
```tsx
import { TextContent } from '@user/client-base';
// 组件内容
;
```
高度默认由 `loc` 的第四项决定;不想自己算高度时加 `autoHeight`,组件按内容算高度。
想让文字逐字显示,加 `interval`,单位是毫秒,`0` 表示一次显示完:
```tsx
```
打字结束时要做点什么,用 `onTypeEnd`。
```tsx
{
// 打字结束时执行
}}
/>
```
全部参数:
| 属性 | 作用 | 默认或常用值 |
| --------------------------- | ------------------------------------------- | ------------------- |
| `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]`:
```tsx
```
要改字号,写 `[s=字号]...[/s]`:
```tsx
```
要换行,写 `\n`;在 TSX 里用模板字符串或字符串拼接:
```tsx
```
`[[` 输出一个普通的 `[`,`]]` 输出一个普通的 `]`。要显示 `[[` 和 `]]` 本身,源文本里写成 `[[[[` 和 `]]]]`:
```tsx
```
`[c=...]` 与 `[s=...]` 要成对闭合,可以嵌套,例如 `[c=#f2b84b][s=20]标题[/s][/c]`。只写 `[c]` 没有颜色参数,不会按标记处理,会原样显示。
需要粗体、斜体、换字体、等待或图标时,再用这些标记:
| 标记 | 作用 |
| ------------------- | ------------------ |
| `[b]` | 切换粗体 |
| `[i]` | 切换斜体 |
| `[f=字体名]...[/f]` | 改字体族 |
| `[w=字数]` | 等待若干个字的时间 |
| `[icon=图标名]` | 插入图标 |
`[b]` 和 `[i]` 是切换,不是成对闭合:写一次切换一次。标记可以组合使用,也可以跨行书写。
把颜色、字号、换行与方括号放在一起:
```tsx
```
渲染示例需要浏览器环境。
同一段文字里混用了颜色、字号、手动换行与方括号字面量,长句会按 `width` 折行。
## ScrollText
要让文字自动向上滚动,用 `ScrollText`。
基本写法里,`width` 是文字的最大宽度,`speed` 是每秒滚动的像素数,`text` 放内容,`loc` 是滚动区域的视口。
```tsx
import { ScrollText } from '@user/client-base';
// setup
const notice = '这是一条会自己向上滚动的公告。'.repeat(8);
// 组件内容
;
```
文字从下往上滚过视口,超出视口的部分不显示。
开始滚动前想先留一点空白,用 `pad` 给预留的像素数,默认 `16`:
```tsx
```
排版参数与 `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()`。
渲染示例需要浏览器环境。
公告在固定视口里持续向上滚动。