Files
template/docs/advanced/ii/ui/text.md
T

9.0 KiB
Raw Blame History

文字

文字元素只画一行。它的宽高由字体测量结果决定,不能自动换行,也没有行高与对齐属性;字号、字重、斜体这些信息由 Font 描述,<text> 负责把内容画出来。这一篇先讲 Font,再讲文字元素怎么用、尺寸与锚点怎么定。

字体:Font

Font 是描述字体的值对象,不负责绘制。它只有五项配置:

属性 默认值 说明
family 'Verdana' 字体族名称
size 16 字号数值
sizeUnit 'px' 字号单位,通常用 px
weight 400 字重,0–1000,可写数字或 FontWeight 枚举
italic false 是否斜体

weight 除了直接写数字,也可以用 FontWeight 枚举。FontWeight 从 @motajs/render 导入,提供三个常用档位:FontWeight.Light = 300、FontWeight.Normal = 400、FontWeight.Bold = 700。枚举值本身就是数字,两种写法等价。

构造函数按位置传参:Font(family, size, sizeUnit, weight, italic)。省略的项用上面的默认值。例如在 TSX 里直接内联:

// 24px 粗体:字重可以用 FontWeight 枚举,也可以直接写数字
<text
    text="标题"
    font={new Font('Verdana', 24, 'px', FontWeight.Bold)}
    fillStyle="#ffffff"
/>

Font 与 FontWeight 都从 @motajs/render 导入。font 只接受 Font 实例,不接收 CSS 字符串;不写 font 时使用默认 Font,也就是 Verdana、16px、400、非斜体。

五项配置在构造后是只读的:要换字号或字重,就再构造一个 Font。修改 Font.defaultFamily 这类默认值只影响之后创建的实例,已经创建的 Font 保留构造时的值。

需要基于默认值或已有字体做局部修改时,用静态方法:

  • Font.defaults() 返回一个默认 Font;也可以传配置对象,例如 Font.defaults({ size: 20 }),没传的项仍用默认值。
  • Font.clone(base, patch) 复制一份字体,用 patch 覆盖部分字段,例如 Font.clone(font, { weight: FontWeight.Bold })。
  • Font.setDefaults(font) 一次性写入五项默认值;之后的 new Font() 都从它开始。
  • addFallback(...fonts) 给字体加后备字体;主字体不可用时按添加顺序尝试。后备字体也可以再加后备,但不要形成循环。

Font 没有行高、字距、下划线、对齐这些属性;它们不属于字体,文字元素也不提供行高或对齐属性。斜体只有 italic 一个开关。

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

同一个字符串换成不同字号、字重与斜体后的效果。

文字元素用法

container 里不能直接写裸文字:空白文字会变成注释节点,非空白文字会创建文字元素并告警。文字内容一律放在 text 属性里:

// 一行文字:内容只写在 text 属性
<text loc={[40, 40]} text="一行文字" fillStyle="#ffffff" />
渲染示例需要浏览器环境。

最基本的一行文字:内容写在 text,位置由 loc 决定。

text 只支持单行;字符串里的换行符不会产生第二行。需要多行、折行或输入时,用内置的文本组件。

文字属性

文字元素自己的属性不多,全部列在下面:

属性 默认值 作用
text '' 要显示的内容,只支持单行
font 默认 Font 字体,必须是 Font 实例
fillStyle '#fff' 填充颜色
strokeStyle 无 描边颜色,设置后才描边
strokeWidth 1 描边宽度,参与尺寸测量
  • fillStyle 默认白色,且不从父容器继承:父容器设了 fillStyle,文字也不会跟着变色。需要统一颜色时,在每个文字上显式写,或把同一个颜色变量传给每个文字。
  • strokeStyle 没有默认值。不写就不描边;写了之后才按这个颜色描边。
  • strokeWidth 默认 1,只在有描边时看得出效果。描边宽度会参与尺寸测量,改大之后文字占用的矩形也会变大。
  • 绘制时先画描边、再画填充,填充会盖住描边靠内的一半,所以描边看起来是沿字形外沿的一条边。
  • text 只支持单行,换行符不会生效。
渲染示例需要浏览器环境。

填充、描边颜色与描边宽度的对照。

尺寸、锚点与对齐

文字没有固定宽度。宽高由字体测量结果决定:内容、字号、字重、斜体、描边宽度一变,尺寸就重新计算。给 <text> 写 width / height 不会裁剪文字,只会暂时改变元素的定位框;下一次测量会把它覆盖回去。需要固定占位或裁剪时,在外面包一个容器。

默认锚点是 anc={[0, 0]},loc 的 x / y 是测量矩形的左上角。锚点用 anc={[ax, ay]} 表示,两个值分别是横向、纵向的锚点比例:anc={[0.5, 0.5]} 同时把横纵锚点设成中心,anc={[1, 0]} 让 x 落在右边缘、y 仍落在顶边,anc={[1, 1]} 则是右下角。

// 锚点居中:loc 的 x / y 落在文字中心
<text loc={[240, 160]} anc={[0.5, 0.5]} text="居中文字" fillStyle="#ffffff" />

本篇统一用 loc + anc 写位置和锚点。loc 只写 [x, y],锚点统一用 anc。loc 的完整形式还能在坐标后写宽高与锚点([x, y, width, height, ax, ay]),但文字尺寸由测量决定,宽高会被覆盖,所以文字页不采用;锚点也不塞进 loc。anchorX / anchorY 是 anc 的等价独立属性写法,例如 anc={[0.5, 0.5]} 等价于 anchorX={0.5} anchorY={0.5};同一处只选一种写法,不要混用。

右对齐数值时用 anc={[1, 0]},让文字的右边缘落在 x 上,y 仍是顶边:

// 锚点 [1, 0]:x 是文字右边缘,适合数量、金币这类右对齐数字
<text loc={[440, 24]} anc={[1, 0]} text="128" fillStyle="#f2b84b" />

这段文字无论内容多长,右边缘都固定在 (440, 24),左侧按测量宽度向左延伸。做数值列时,把这一列都设成同一个 x 与 anc={[1, 0]},数字就会沿右边缘对齐。

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

三行文字分别用不同的锚点,白点标出 loc 的位置。

文字没有 textAlign、textBaseline、lineHeight 这些属性。对齐只能靠锚点;单行文字基线固定,垂直居中按实际字形的上下沿算,不按行高;也不会自动换行。

文字在界面里的常见用法

  • 标题:用较大字号与较粗字重,与正文拉开层级。
  • 标签:小字号、浅色,做说明,不抢主内容的视觉重心。
  • 按钮文字:放在按钮底容器里,点击由按钮底统一处理。
  • 数值显示:用 anc={[1, 0]} 右对齐;不要用 width 裁剪,长度变化靠锚点对齐。

换行、打字机与输入

文字元素只画一行,text 里的换行符不会生效,长文本也不会按宽度折行。多行说明、按宽度折行与打字机效果不要用多个 <text> 硬拼;用内置组件:文本里的 TextContent。

<script setup> import RenderDemo from '../../../.vitepress/components/renderDemo.vue'; const basicTextLoader = () => import('../../../.vitepress/components/demos/ui/text-basic.tsx'); const fontTextLoader = () => import('../../../.vitepress/components/demos/ui/text-font.tsx'); const styleTextLoader = () => import('../../../.vitepress/components/demos/ui/text-style.tsx'); const anchorTextLoader = () => import('../../../.vitepress/components/demos/ui/text-anchor.tsx'); </script>

边界与注意

  • fillStyle 默认是白色。浅色背景上直接写字要显式改色。
  • strokeWidth 默认是 1,描边会计入尺寸;给 strokeStyle 时记得一起考虑宽度,靠边摆放要留出空间。
  • 给文字设 width / height 不会截断内容,下一次测量还会覆盖它们。需要固定占位或裁剪时,用外层容器。
  • 长文本不要用文字元素硬排。它只适合标题、标签、数值这类单行内容。
  • 本篇统一用 loc + anc;anchorX / anchorY 是等价写法,同一处只写一种。