文本 (Text)

Kanzi 具有以下文本节点：

• 使用 Text Block 节点在应用程序中显示少量文本。

  请参阅 使用 Text Block 节点。

  

• 使用 Text Box 节点为您的应用程序添加单行文本输入。

  请参阅 使用 Text Box 节点。

  

字体类型

Kanzi 中的默认字体系列是 Fira Sans Regular。字体文件存储在 <KanziInstallation>/Studio/Asset Library/Fonts。 当您想使用自己的字体时，将其导入到您的 Kanzi Studio 项目中。

请参阅 导入字体。

您可以在 Kanzi 应用程序中使用这些字体类型：

• TrueType 和 OpenType 字体 (ttf 和 otf 文件)

• iType 链接字体（ltt 文件）。请参阅 iType 关联字体。

• 位图字体（fnt 文件）。请参阅 使用位图字体。

确保您使用的字体提供应用程序中文本所需的字形。使用 FreeType 字体引擎时，您可以为不同的 Unicode 书写系统配置后备 Font Families。请参阅 使用字体后备。

字号 (Font Size)

Kanzi 以像素为单位设置字体的大小。当您设置 Font Size 属性时，Kanzi 将该值传递给 Freetype 库，Kanzi 使用该库通过 FT_Set_Char_Size 函数以默认 dpi 值 72 渲染字体。

例如，以下都显示相同字号的字母“H”。

• Text Block 或 Text Box 节点设置了以下属性：

  • Text 到 H。

  • 将 Font Family 设置为 Arial。

  • Font Size 到 36

• HTML 标记

  <p style="font-family:arial; font-size:36px;">H</p>
  

如果您想控制 dpi 缩放或以像素以外的单位设置字体大小，您必须在您的 Kanzi 应用程序中实现该功能。例如，如果您想根据 dpi 设置自动选择项目中图像和布局使用的内容，请在您的 Kanzi 应用程序中实现该功能。

为 Preview 设置字体引擎

Kanzi 支持两种字体渲染后端：

• FreeType 是 Kanzi 附带的基于开源软件的字体引擎。它适用于大多数常规用例，并支持多种字体格式。它使用 FreeType 光栅化器、HarfBuzz 字形整形器、ICU 双向库以及用于换行的 libunibreak。这是默认字体引擎。

• iType 是基于商业软件的字体引擎，需要从 Monotype 单独获取许可证。它提供高级字体渲染功能和优化。它使用 Monotype iType 光栅化器，并使用 WorldType® Shaper™ 进行字形整形。请参阅 安装 iType 字体引擎。

要为 Preview 设置字体引擎：

1. 在主菜单中选择 Project > Properties。

   

2. 在 Properties 中的 Profile 下，将 Font Engine 属性设置为：

   • FreeType 使用 FreeType 字体引擎。

   • iType 使用 iType 字体引擎。

   • None 不加载字体引擎。当您不加载字体引擎时，Kanzi 不会在您的应用程序中渲染文本。

   

要了解如何设置在应用程序启动时加载哪个字体引擎，请参阅 FontEngine。

备注

iType 和 FreeType 字体引擎使用不同的渲染和字形整形算法。因此，文本渲染和布局可能会存在一些差异。在某些情况下，这些字体引擎还可能解析字体文件的不同部分。

如果您从一种 Font Engine 切换到另一种，可能需要更新或调整字体文件本身，以尽量减少或消除这些差异。

设置字体提示

字体提示为光栅化提供了指令：将字体的轮廓映射到屏幕像素。字体提示旨在既保持字体的设计美感，又优化字体在不同大小下的可读性。

Kanzi 中的文本节点默认情况下使用字体中包含的字体提示数据。

例如，字体提示可能会影响字符的高度和宽度、线条的宽度、边缘对比度以及字符之间的间距。

要为 Text Block 或 Text Box 节点设置字体提示，请在 Node Tree 中选择该节点，在 Properties 中添加 Font Hinting Preference 属性，并将其设置为：

• No hinting 用于渲染没有字体提示的文本。

• Native hinting 使用字体中包含的提示数据来渲染文本。如果字体不包含提示数据，Kanzi 使用字体引擎光栅化器的提示器。这是默认值。

• Auto hinting 使用字体引擎光栅化器的提示器来渲染文本。请参阅 为 Preview 设置字体引擎。

使用 iType 字体引擎自定义泰文文本中的自动换行功能。

您可以通过设置要使用的泰语词典来自定义 Kanzi iType 字体引擎在泰语文本中如何换行，而不是使用内置于 iType 字体引擎中的词典。

WorldType® SDK 随附：

• 泰语字典

• Python 工具，可创建您的应用程序可以使用的泰语字典。

您可以在 WorldType® SDK 的 wtle/product/tools/language_dictionaries/thai 目录中找到这些资源。

要在泰文文本中自动换行：

1. 通过传递给 GenerateThaiDictionary.py 来为 iType 字体引擎创建泰语字典：

   • 纯文本格式的泰语字典

   • 要存储生成的字典的文件。

   py -2 GenerateThaiDictionary.py thai-dictionary.txt thai-dictionary.wtd
   

   GenerateThaiDictionary.py 创建一个 wtd 文件，您可以在 Kanzi 应用程序的应用程序配置中设置：

   Reading lines from file "thai-dictionary.txt"... done.
   Extracting, filtering, and normalizing words... done.
   Adding words to trie... done.
      number of words: 8
      number of characters: 31
      longest word length: 7
      number of trie nodes: 32
      number of trie edges: 31
   Compressing trie into a DAWG (Directed Acyclic Word Graph)... done.
      number of edges in root node: 9
      number of DAWG nodes: 24
      number of DAWG edges: 30
      edges / characters = 96.8 %
      dawgEdges / trieEdges = 96.0 %
      dawgNodes / trieNodes = 75.0 %
      DAWG array elements: 31
   Writing DAWG to file "thai-dictionary.wtd"... done.
      file size: 0 k
   

2. 要将您的应用程序设置为使用您创建的泰语词典，请在文本编辑器中设置 <ProjectName>/Application/bin/application.cfg 文件中的 iType 字体引擎词典：

   # Set additional backend dictionaries.
   ITypeDictionaryUrls = file:///usr/share/itype/thai-dictionary.wtd
   

   请参阅 字体引擎字典。

3. （可选） 要设置 Kanzi Studio Preview 以在使用 iType 字体引擎时正确渲染泰文文本， 在 Kanzi Studio 中打开您的项目，并在主菜单中选择 Project > Properties。在 Properties 中，将 Preview Working Directory 属性设置为包含您在上一步中创建的 application.cfg 文件的目录。

   

使用字体回退

备注

使用 FreeType 字体引擎时可以使用字体回退。

使用字体回退来渲染包含多种书写系统、符号或表情符号的文本。保留分配给文本节点的主 Font Family，并将其他 Font Family 添加到其 Fallback Font Family 属性中。Kanzi 会为文本的每个部分选择一个 Font Family。

下图显示了未使用字体回退（左）和使用字体回退（右）的文本。

Font Family 提供以下用于配置字体回退的属性：

• Font UScriptCode 标识与该 Font Family 关联的 Unicode 书写系统。

• Fallback Font Family 列出用于补充主 Font Family 字符覆盖范围的 Font Family。

设置 Font UScriptCode

Font UScriptCode 的默认值为 Common。

要为 Font Family 设置 Font UScriptCode：

1. 将要使用的字体导入到您的 Kanzi Studio 工程中。

2. 在 Library > Font Families 中，选择导入的 Font Family。

3. 在 Properties 中，将 Font UScriptCode 设置为与该字体对应的 Unicode 书写系统。

   例如，对于用于渲染日语平假名字符的字体，将 Font UScriptCode 设置为 Hiragana。

4. 对要用于字体回退的其他 Font Family 重复这些步骤。

Font UScriptCode 值

Font UScriptCode 中列出的 Unicode 书写系统对应于 ICU（International Components for Unicode）中的 UScriptCode 值。对于有效的 Unicode 文字，该表还列出了对应的 ISO 15924 文字代码。Extended 是 Kanzi 中用于此属性未列出的书写系统的 Font Family 标签，而不是 ICU 文字。

显示名称	UScriptCode	ISO 15924	描述和主要语言
Invalid	USCRIPT_INVALID_CODE		无效或未指定的书写系统。
Common	USCRIPT_COMMON	Zyyy	不属于特定书写系统的通用字符，例如标点符号、数字、数学符号和货币符号。
Inherited	USCRIPT_INHERITED	Zinh	通常沿用前一个字符的书写系统属性的继承字符，例如组合标记。
Arabic	USCRIPT_ARABIC	Arab	阿拉伯语、波斯语、乌尔都语、维吾尔语以及其他使用阿拉伯文字的语言。
Bengali	USCRIPT_BENGALI	Beng	孟加拉语、阿萨姆语以及其他使用孟加拉文字的语言。
Cyrillic	USCRIPT_CYRILLIC	Cyrl	俄语、乌克兰语、保加利亚语、塞尔维亚语以及其他使用西里尔文字的语言。
Devanagari	USCRIPT_DEVANAGARI	Deva	印地语、梵语、尼泊尔语、马拉地语以及其他使用天城文的语言。
Greek	USCRIPT_GREEK	Grek	希腊语。
Han	USCRIPT_HAN	Hani	中文、日语和韩文中使用的汉字。
Hangul	USCRIPT_HANGUL	Hang	韩文谚文。
Hebrew	USCRIPT_HEBREW	Hebr	希伯来语。
Hiragana	USCRIPT_HIRAGANA	Hira	日语平假名。
Katakana	USCRIPT_KATAKANA	Kana	日语片假名。
Latin	USCRIPT_LATIN	Latn	英语、法语、德语、西班牙语、大多数其他西欧语言、越南语、土耳其语以及其他使用拉丁文字的语言。
Thai	USCRIPT_THAI	Thai	泰语。
Extended			用于此属性中未列出的书写系统的后备字体。

设置后备字体系列

使用 Fallback Font Family 添加一个或多个字体系列，以补充主字体系列。

要添加后备字体系列：

1. 在 Library > Font Families 中，选择您要用作主字体系列的字体系列。

2. 在 Properties 中，找到 Fallback Font Family 属性。

3. 在 <Select to Add> 下拉菜单中，选择您要添加的字体系列。

4. 根据需要添加更多字体系列。

   对于每个后备字体系列，将 Font UScriptCode 设置为与该字体对应的 Unicode 书写系统。

字体系列优先级

对于 Font UScriptCode 中列出的书写系统，Kanzi 按以下顺序选择具有匹配设置的字体系列：

1. 主字体系列具有最高优先级。

2. Kanzi 按列表顺序检查 Fallback Font Family 中的字体系列，并使用第一个匹配的字体系列。

例如，假设主字体系列的 Font UScriptCode 为 Latin，并且您按以下顺序将这些字体系列添加到 Fallback Font Family：

1. 一个 Font UScriptCode 设置为 Han 的字体系列。

2. 一个 Font UScriptCode 设置为 Hiragana 的字体系列。

3. 另一个 Font UScriptCode 设置为 Han 的字体系列。

对于汉字字符，Kanzi 使用后备列表中的第一个汉字字体系列。对于平假名字符，Kanzi 使用为平假名配置的字体系列。

以下各节介绍 Extended 字体、表情符号和私用区字符各自的选择规则。

使用 Extended 字体

对于支持 Font UScriptCode 中未列出的书写系统（例如藏文、缅甸文、高棉文和古波斯文）的字体，请使用 Extended。您可以添加一个或多个 Font UScriptCode 设置为 Extended 的字体系列。

Kanzi 仅对未列出的书写系统中的文本使用 Extended Font Families。它不会将其用于：

• 已列出的书写系统，例如 Latin、Han、Arabic 和 Thai，即使 Fallback Font Family 中没有为该书写系统配置字体系列。

• 表情符号。

• 私用区 (PUA) 字符。

对于同一未列出书写系统中的每个文本串，Kanzi 按列表顺序检查 Extended 字体系列，并选择包含该文本串中所有字符的第一个字体系列。对整个文本串使用同一个字体系列，可避免将复杂书写系统中的一个音节拆分到不同字体中。

如果没有 Extended 字体系列能覆盖该文本串，Kanzi 将使用主字体。该字体中缺失的字符会显示为缺失字形占位符。

要配置 Extended 字体系列：

1. 在 Library > Font Families 中，为您需要的每个未列出的书写系统创建一个字体系列。

   例如，创建名为 Tibetan 和 Old Persian 的字体系列。

2. 将相应的字体文件添加到这些字体系列中。

3. 选择文本块使用的主字体系列，并将新的字体系列添加到 Fallback Font Family。

4. 将每个这些字体系列的 Font UScriptCode 设置为 Extended。

   

5. 在后备列表中，将更常用或更专门的 Extended 字体系列放在靠前的位置。

备注

Extended 字体系列不会填补所列书写系统在字形覆盖上的空缺。例如，如果配置的 Han 字体系列缺少某个汉字，Kanzi 不会在 Extended 字体系列中搜索该字符。请使用包含所需字形的汉字字体，或者将该字形添加到该字体中。

使用表情符号字体

使用字体后备功能可以在正文旁边显示表情符号。让文本块保持使用主字体系列，将包含表情符号的字体系列添加到 Fallback Font Family，并将其 Font UScriptCode 设置为 Common。

使用 FreeType 字体引擎时，字体系列可以包含单色或彩色表情符号字体。有关以彩色渲染表情符号的信息，请参阅 使用 FreeType 显示彩色表情符号。

Kanzi 将表情符号作为单独的文本段处理。表情符号不会继承相邻拉丁文或汉字文本的字体系列。对于表情符号，Kanzi 按以下顺序搜索：

1. 主字体系列中包含该表情符号的其他字体文件，正文字体文件除外。

2. Fallback Font Family 中 Font UScriptCode 为 Common 且包含该表情符号的字体系列。

   

3. 主字体。如果主字体不包含该表情符号字形，结果可能显示为缺失字形占位符或错误的字符。

要使用表情符号字体：

1. 在 Library > Font Families 中，创建仅包含表情符号字体文件的字体系列。

   例如，将其命名为 Emoji。

2. 选择文本块使用的主字体系列。

3. 将包含表情符号的字体系列添加到 Fallback Font Family。

4. 将该字体系列的 Font UScriptCode 设置为 Common。

Kanzi 对以下内容使用表情符号字体选择：

• 默认以表情符号形式呈现的字符，例如 😀。

• 零宽连接符序列，例如 👨‍💻 和 👨‍👩‍👧。

• 由成对的区域指示符号构成的旗帜序列。

• 肤色修饰符。

• 键帽序列，例如 1️⃣。

普通数字、# 和 * 不使用表情符号字体选择。例如，即使表情符号字体包含数字字形，1111 仍然使用正文字体。

使用私用字符

私用区 (PUA) 码位通常用于自定义图标。Kanzi 将其视为未知书写系统，对这些字符既不使用 Extended 字体选择，也不使用表情符号字体选择。

对于 PUA 字符，Kanzi 使用文本块的主字体，或其字体系列可以为该节点选择的其他字体文件。

要显示 PUA 图标：

1. 将图标字形包含在主字体文件中，或包含在分配给文本块的字体系列中的某个字体文件中。

2. 在 Text 属性中，输入字体中映射到这些字形的 PUA 码位。

备注

PUA 码位在不同字体之间没有统一的含义。请使用图标字体所定义的码位映射。如果所选字体没有对应某个 PUA 码位的字形，Kanzi 会显示缺失字形占位符。

使用 FreeType 显示彩色表情符号

将受支持的彩色表情符号字体与 FreeType 字体引擎配合使用，即可以表情符号的固有颜色显示表情符号。首先按照 使用表情符号字体 中的说明配置字体系列。

要在正文中显示彩色表情符号：

1. 在包含表情符号的字体系列中，使用彩色表情符号字体文件。

2. 将 Text Block 2D 的 Foreground 设置为 Color Brush，或保留默认设置。

   当 Foreground 为 Color Brush 时，其颜色仅影响正文。Color Brush 和节点的不透明度仍会影响彩色字形。

支持的彩色表情符号字体格式

Kanzi 以彩色渲染以下字体格式中的表情符号字形：

• CBDT

• SBIX

• COLRv0

Kanzi 支持导入使用 SVG 或 COLRv1 的字体，但不会以彩色渲染这些格式。对于这些字体，Kanzi 使用灰度轮廓。

彩色表情符号渲染限制

• 彩色表情符号仅在使用 FreeType 字体引擎时可用。iType 不渲染彩色字形。

• 当 2D 文本块 (Text Block 2D) 或 2D 文本框 (Text Box 2D) 中的 Foreground 为 Color Brush 时，Kanzi 会保留彩色字形的固有颜色。当您使用其他笔刷 (Brush)、3D 文本块 (Text Block 3D) 或 3D 文本框 (Text Box 3D) 时，字形可能会被着色。

• Color Workflow 对彩色字形的影响与对其他彩色内容的影响相同。在 Legacy 工作流中颜色更饱和，在 Linear 工作流中颜色更浅。

• 彩色字形使用至少 2048 x 2048 像素的 RGBA 字形缓存，因此比灰度正文文本占用更多内存。缓存已满时，Kanzi 会移除较少使用的字形。如果正文文本仍然可见，但部分表情符号未显示，请增大 GlyphCacheWidth 和 GlyphCacheHeight。

• 某些表情符号字体为空格字符设置了与表情符号相同的前进宽度。当前进宽度大于 0.5 em 时，Kanzi 会将空格宽度设置为约 0.25 em。

• 在目标设备上，FreeType 必须启用 FT_CONFIG_OPTION_USE_PNG 并链接 libpng，才能解码 CBDT 位图。如果表情符号在 Preview 中以彩色显示，而在目标设备上以灰度显示，请使用支持 PNG 的 FreeType 版本重新构建字体引擎插件。

另请参阅

使用 Text Block 节点

使用 Text Box 节点

导入字体

图形缓存纹理大小