文本组件

Wiki上有与该主题相关的教程！

见教程:文本组件。

Wiki上有与该主题相关的教程！

见教程:文本组件。

文本组件（Text Component），过去亦作原始JSON文本（Raw JSON Text），Minecraft通过它向玩家发送和显示富文本。

上下文与解析

在游戏使用文本组件进行渲染时，会根据当前环境的上下文（Context）进行解析（Parsing），成为格式文本（Formatted Text），并最终使用格式文本渲染。

文本组件解析上下文包括下列数据：

静态上下文：当前的语言、键位等。
动态上下文：世界记分板、实体、方块实体、命令存储及触发预解析行为的实体、位置与朝向。

游戏解析文本组件分为两步：

预解析动态组件：读取当前世界信息的组件都是动态组件，这些组件在发送到客户端前就需要在服务端使用动态上下文进行预解析成为预解析文本组件，以固定内部的动态组件内容。
解析静态组件：发送到客户端的文本组件仅含静态组件，游戏客户端根据静态上下文进行最终解析，获得的格式文本仅包含文本及其样式信息，以让客户端渲染。

当游戏上下文变动时，动态组件不会跟随变化，因为这些组件已被预解析，即动态组件体现为动态上下文的快照（Snapshot）；而静态组件可以跟随静态上下文的变动而重新解析。

Java版

基础结构

文本组件有非常复杂的格式以支持各种高级用法，并在NBT、SNBT和JSON中都有对应的格式。

NBT格式用于序列化与持久化，存档数据中保存与网络传输中使用的文本组件就使用了NBT格式。
SNBT格式用于方便输入，主要用于各种需要输入文本组件的命令、函数等。
JSON格式用于各种注册定义格式，例如各种数据包注册项。

下文中将主要以SNBT格式介绍；同时，JSON格式与SNBT格式相同，仅在语法上有差异，因此两者基本上可以互相转换。

文本组件主要分为三种基础结构：字符串形式、列表形式和复合标签形式。游戏不会使用列表形式进行序列化，仅使用字符串形式和复合标签形式存储与传输。

复合标签格式作为文本组件的最基础格式，具有下列结构：

复合标签格式根标签
- type：文本组件类型。多数情况下此标签可以被省略，见下文§ 组件类型。
- extra：此文本组件的子组件。见下文§ 组件继承。
  - ：子文本组件。
- 其余可选项，见§ 组件样式。
- 与组件类型相关的项，见§ 组件类型中对应的组件格式。

字符串格式是纯文本组件的简写形式。在实际使用中，字符串格式等价于复合标签格式的{|text: <字符串>}。如果一个文本组件所有样式均为默认值、不包含子组件且为纯文本组件，游戏在序列化或持久化此组件时会直接使用字符串格式而非复合标签格式。

列表格式是多个组件拼接的简写形式，列表中每个元素都是一个有效的文本组件，格式可以为复合标签、列表或字符串。由于SNBT与JSON都支持异构列表或数组，所以列表格式中的元素允许混搭，即文本组件的三种格式可以同时存在于一个列表中。游戏在读取列表格式时会自动将其转换为复合标签格式，转换遵照下列规则：

游戏将以第一个文本组件作为根组件，并将剩余所有组件作为子组件写入第一个文本组件的extra中。
如果第一个文本组件的extra不为空，游戏自动将剩余组件拼接在第一个文本组件extra列表的后方。
在转换过程中，所有子组件将以原样直接写入子组件列表中，不会修改子组件的任何信息。

组件继承

文本组件以树状形式保存，以复用样式并增强结构性。

具有非空extra的文本组件即为文本组件树节点。为简化说明，这里定义extra内的文本组件即为此组件的子组件，而此组件为extra内的所有文本组件的父组件，游戏在渲染时使用的最外层父组件称为根组件。

子组件会自动继承父组件内的样式信息，但不会继承组件类型及其他组件数据；如果子组件内定义了与父组件内相同的标签，则子组件定义的信息将替代继承自父组件的信息。如果继承链上没有任何组件定义了某项标签，游戏会使用当前渲染环境的样式默认值。例如，文本组件{text: 'A', color: 'red', extra: ['B', {text: 'C', color: 'yellow'}]}中，AB将以红色渲染，C将以黄色渲染。

当文本组件解析成为格式文本时，父组件解析结果会在整个结果的最前方，子组件按照extra内的顺序一个一个拼接到后方，即渲染时文本组件树将以深度优先搜索的方式进行渲染。例如，文本组件{text: 'A', extra: ['B', {text: 'C', extra:['E', 'F']}, {text: 'D', extra: ['G']}]}将渲染为ABCEFDG。

根据文本组件列表格式的解析机制，第一个列表元素将成为根组件，同时也代表了第一个列表元素的样式会继承到所有后续组件中，即成为了整个文本组件的全局样式。如果使用列表格式时不想让第一个列表元素的样式控制整个文本组件，可以在第一个元素前插入空纯文本组件""以防止样式污染。

预解析触发

对于动态组件，游戏在发送到客户端前需要进行预解析。下列行为可以触发预解析：

传入文本组件的命令会进行预解析，但行为并不一致：
- 使用/tellraw、/title显示文本组件时，文本组件将在发送到各个客户端前进行预解析，触发预解析的实体是将要发送到的客户端的玩家。
- 其他所有命令，在接收文本组件参数时，都会立刻进行预解析，触发预解析的实体是执行此命令的玩家。
打开未预解析的成书（resolved不存在或为false）。
- 如果在讲台上打开未解析的成书，则缺失触发预解析行为的实体，造成部分动态组件行为异常。^[1]
- 如果由玩家打开未解析的成书，则触发实体为打开此书的玩家，动态组件可正常预解析。
加载或设置告示牌的文本时会立刻触发预解析，但这种触发不存在触发预解析的实体。^[2]
加载或设置文本展示实体的text时将预解析内部的文本组件，触发实体为文本展示实体自身。
- 实体不会在加载或设置CustomName时进行预解析，此类预解析由selector类型的文本组件创建此文本组件副本进行预解析后使用。
使用物品修饰器set_lore和set_name时，如果指定了entity，且entity所指代的实体存在，游戏将以此实体作为触发实体进行预解析。

更详细的动态上下文信息，见命令上下文 § 文本组件解析。

当文本组件进行预解析时，游戏将从根组件开始，遍历树中所有子组件以及样式、类型中定义的其他文本组件进行预解析。如果树的深度超过100，则深度超过100的部分将无法预解析。在下文中，如果没有明确提及，则默认所有文本组件都能被有效预解析。

如果在MOTD中显示文本组件^{[注 1]}，则遍历树的深度超过16的部分将替换为省略号...，若解析失败则强制显示为空字符串。

组件类型

文本组件具有多种类型，游戏内共有下列7种组件类型，这些类型也是type的可选值：

text：静态组件，纯文本组件类型。
translatable：静态组件，本地化文本组件类型。做标签时名称为translate。
keybind：静态组件，键位绑定组件类型。
score：动态组件，记分板数据组件类型。
selector：动态组件，实体名称组件类型。
nbt：动态组件，NBT组件类型。
object：静态组件，精灵图组件类型。做标签时的名称见§ 精灵图组件。

当游戏解析组件时，首先会读取type确定组件类型，并根据组件类型定义的必须项和可选项读取组件内容并进行相应解析，如果必选项不存在或组件的附加条件不满足，解析时将报错；如果type不存在，游戏会按照上文顺序，找到第一个具有对应名称且类型对应的标签，作为此组件的组件类型；如果type不存在或无效、且上文定义的所有标签都不存在或类型不对应，文本组件解析失败。

例如，{text: {}, keybind: 'key.inventory', translate: 'addServer.add'}在进行解析时会判定为本地化文本组件，而非纯文本组件或键位绑定组件：text组件要求使用字符串标签类型，而此处为复合标签，因而条件不满足而跳过解析；translate（即translatable类型）的顺序高于keybind，且标签类型正确对应为字符串，所以满足条件而成为此组件的类型。

换言之，type是用于严格校验组件正确性的标签。因为游戏保持了文本组件的旧版本兼容性，此项为非必须项，且在序列化与持久化时type不会保存。

纯文本组件

纯文本组件直接定义了组件解析后的文本。

复合标签格式根标签
- type：text。
- *
  *text：要渲染的文字。

本地化文本组件

本地化文本组件定义了本地化键名，并提供了替换参数。

复合标签格式根标签
- type：translatable。
- *
  *translate：本地化键名，游戏将使用此键名查找对应本地化文本。查询算法见下文。
- fallback：回落文本。当本地化文本无法查询得到时使用此文本作为本地化文本使用。具体算法见下文。
- with：替换本地化文本内的参数。参数替换算法见下文。
  - ：一个文本组件、字符串、数字或布尔值。作为JSON格式时不可以为null。

作为静态组件，此组件将以原样（不包括with及其递归子组件内的动态组件）发送到客户端，并由客户端在渲染前解析为格式文本渲染，因此此组件在不同的客户端上渲染可以不一致。

客户端在解析此组件时会先读取本地化键名*
*translate，从当前语言中查找此键名对应的本地化文本。如果没有找到，则寻找默认语言（英语（美国），即en_us）中是否有此键名的对应本地化文本。如果仍然没有找到，则尝试使用回落文本fallback。如果fallback没有定义，则使用键名直接作为本地化文本使用。

与UI中使用的本地化文本类似，文本组件内的本地化文本也可以使用%%、%s及其带序号的形式。但是，如果本地化文本不在语言文件中而回落使用*
*translate或者fallback时，其内部包含的%d、%f等不支持的格式字符不会自动转换为%s，使得本地化文本解析失败。对于成功解析的本地化文本，游戏会计算有多少个参数需要填入，如果with中定义的参数数量小于需要的参数数量，解析也会失败。无论解析因为何种原因失败，游戏都会直接使用解析过程中查找到的本地化文本作为解析结果。

对于填入的参数，如果参数不是文本组件，那么游戏事先将这些内容转换为无样式的纯文本组件。填入的参数类似文本组件子组件行为，即继承父组件（本地化文本组件）的样式，并允许自行覆盖样式。例如，本地化文本组件{translate: '%s%s', with: [{text: 'A', color: 'red'}, 'B'], color: 'yellow'}中A将渲染为红色而B将渲染为黄色。

键位绑定组件

渲染当前玩家客户端所绑定的键位名称。

复合标签格式根标签
- type：keybind。
- *
  *keybind：一个绑定键位标识符。将显示为当前所绑定的按键名称。比如，{keybind: "key.inventory"}将显示"E"（默认物品栏打开按键）。若找不到相应按键标识符将尝试显示为对应的翻译名称。

与本地化文本组件类似，键位绑定组件也是静态组件，将以原样发送到客户端，并由客户端在渲染前解析为格式文本渲染，因此此组件在不同的客户端上渲染可以不一致。

记分板数据组件

记分板数据组件可以读取服务端内的记分板数据，并在服务端预解析成为静态组件后发送到客户端。

复合标签格式根标签
- type：score。
- *
  *score：要获取的分数信息。
  - *
    *name：分数持有者信息。此项的详细格式见下文。
  - *
    *objective：要获取的记分项信息。

游戏在预解析此组件时，会先计算分数持有者信息。*
*name可以为下列3种格式，分别对应了不同的计算方式：

有效的目标选择器：游戏会根据目标选择器在世界中查找符合条件的实体，将查找到的唯一实体作为分数持有者。如果查找到的实体不止一个，预解析将直接报错（只允许一个实体，但提供的选择器允许多个实体）；如果没有查找到实体，则认为此目标选择器的文本本身为玩家名称或UUID，进行第二次预解析。
玩家名称或UUID：游戏直接将对应实体作为分数持有者。
分数持有者通配符*：游戏将使用当前动态上下文内触发预解析行为的实体作为分数持有者。

如果分数持有者为空，或分数持有者的对应记分项信息不存在，则游戏预解析后此项直接转变为空纯文本组件；如果不为空，游戏先根据记分项返回的分数使用记分项对应的数字格式进行格式化。

如果此动态组件未被成功预解析，在客户端渲染此组件时将直接渲染为空文本。

实体名称组件

实体名称组件可以读取世界内的实体数据，并在预解析时处理为对应的静态组件发送到客户端。

复合标签格式根标签
- type：selector。
- *
  *selector：有效的目标选择器、玩家名称或UUID。
- separator：多个实体名称间的分隔符。

此组件进行预解析时，游戏会先预解析separator内定义的名称分隔符；如果separator不存在，则游戏默认使用灰色的逗号（{text: ', ', color: 'gray'}）作为名称分隔符。

在预解析名称分隔符后，游戏根据目标选择器、玩家名称或UUID在世界中查找匹配的实体，并获取所有匹配实体的显示名称。其中，显示名称文本组件的获取算法如下：

获取实体未格式化的名称：
- 如果实体是玩家，获取玩家名称。玩家名称为纯文本组件，内部为玩家档案名称。
- 如果实体是带有自定义名称的实体，获取CustomName。
  - 如果CustomName内定义了点击事件样式，则抹除此点击事件样式，其他样式将保留。^[3]
- 如果实体不满足上述两个条件，则使用实体类型名称作为实体名称，即{|translate: 'entity.<实体类型命名空间ID>'}。
添加队伍样式，如果实体不在任何队伍中则不进行此步骤。
1. 为名称添加前缀（MemberNamePrefix）和尾缀（MemberNameSuffix）。此步骤中，游戏会自动创建一个新的空纯文本组件，并将前缀、名称、尾缀作为此组件的子组件放入。
2. 为上一步修饰好的名称添加样式，由队伍中的TeamColor决定。如果此值为reset（重置样式），则不进行此步骤。
添加悬浮事件样式，此样式为show_entity类型，并添加此实体的类型、UUID和未格式化的名称数据。
添加插入事件样式，此样式信息为实体的带分隔符形式的UUID。
如果此实体为玩家，继续添加点击事件样式，此样式为suggest_command类型，补全信息为/tell <玩家档案名称> 。

获取显示名称文本组件列表后，游戏将进行预解析的最后步骤，拼接出静态组件：

如果列表为空，即未找到匹配实体，则返回空纯文本组件。
如果列表内只有一个元素，则直接返回此元素。
如果列表内有多个元素，游戏会先创建一个空纯文本组件，并按照列表顺序取出元素作为子组件加入到纯文本组件中，同时两个元素中间会插入名称分隔符文本组件进行分隔。

如果此动态组件未被成功预解析，在客户端渲染此组件时将直接渲染为*
*selector。

NBT组件

NBT组件能获取游戏内方块实体、实体及命令存储中的信息，并预解析为对应的静态组件发送到客户端。

复合标签格式根标签
- type：nbt。
- *
  *nbt：NBT路径。详细使用见下文。
- interpret：（默认为false，plain为true时必须为false）是否将获取到的NBT数据解析为文本组件。此值为false时，游戏会将获取到的NBT数据整理为与/data get一致的经过语法高亮的SNBT。
- plain：（默认为false，interpret为true时必须为false）interpret为false时，游戏是否将获取到的数据输出为简单的单一文本，而非经过语法高亮处理的富文本。
- separator：多个NBT数据展示时使用的分隔符。
- source：NBT数据源类型。详情见下文。
- 下列标签必须至少包含一个，作为NBT数据源使用：
- entity：将实体数据作为NBT数据源使用。此标签需要为有效的目标选择器、玩家名称或UUID。
- block：将指定位置的方块实体数据作为NBT数据源使用。此标签需要为有效的方块位置参数，相对坐标与局部坐标解析时使用触发预解析行为时的坐标和朝向。
- storage：将指定命名空间ID的命令存储作为NBT数据源使用。

source与文本组件中的基础标签type类似，作用是用于检验数据结构的正确性，可选值为entity、block和storage，分别对应字符串类型标签。当source不存在时，游戏按照entity、block、storage的顺序尝试读取。如果这三项都不存在，此文本组件解析无效。

这三种数据源能获取的NBT数据如下：

block获取方块实体的数据。数据包括方块实体的位置、ID、数据组件信息，详情见方块实体数据格式。此数据与/data block获取的数据一致。
entity获取一系列实体的数据。数据包括实体的所有数据，但不包括实体ID。如果实体为玩家且选中物品非空，则还额外包括SelectedItem数据。此数据与/data entity获取的数据一致。
storage获取命令存储中的数据。此数据与/data storage获取的数据一致。

如果数据源找不到相应数据（坐标位置上不存在方块实体、目标选择器未选中到实体，指定命令存储不存在），则直接预解析为空纯文本组件；如果具有数据，则将所有数据放入数组中（实体可能具有多个数据，方块和命令存储仅可能有一个数据），并根据指定的NBT路径选中所有元素进行映射后进行扁平化（Flatten Mapping）。

例如，如果一个实体数据源@e获取到了两个实体，并且位置数据Motion分别为[1d, 0d, -1d]和[-2d, 0d, 2d]：

如果NBT路径为Motion，则获取到的数据为[1d, 0d, -1d]和[-2d, 0d, 2d]共2项数据。
如果NBT路径为Motion[]，则获取到的数据为1d、0d、-1d、-2d、0d、2d共6项数据。
如果NBT路径为Motion[0]，则获取到的数据为1d和-2d共2项数据。

获取到数据数组后，根据interpret的取值，游戏会进行不同的预解析步骤：

如果interpret为false，游戏先将所有数据转换为SNBT字符串。如果日志级别为调试级别，则游戏会对标签按标签名进行排序整理。若plain为true，则直接拼接为简单的单一字符串进行输出，否则游戏会将各字符串重新整理为更复杂的文本组件，使其按照SNBT的语法结构渲染。各SNBT字符串之间的拼接字符由separator决定，不存在时游戏将使用无样式的逗号, 拼接字符串。
如果interpret为true，游戏先将所有数据转换为文本组件，如果不能转换，则直接删除对应数据。与为false时不同，如果separator不存在游戏将以无样式的逗号（', '）作为默认分隔符。数据的第一个文本组件将作为根组件，separator和剩余组件依次放入根组件作为子组件拼接为最终的文本组件。这种拼接方式代表了数据的第一个文本组件将控制影响所有后续文本组件的样式数据。

例如，如果一个实体数据源@e获取到了三个实体，并且data分别为{color: 'red', text: 'A'}、{test: 'B'}和{text: 'C'}，且NBT路径为data：

如果interpret为false，则预解析后的文本组件为'{color:"red",text:"A"}, {test:"B"}, {text:"C"}'。
如果interpret为true，则预解析后的文本组件为{color: 'red', text: 'A', extra: [', ', 'C']}，显示为红色的A, C。

如果此动态组件未被成功预解析，在客户端渲染此组件时将直接渲染为空文本。

精灵图组件

精灵图组件，亦称对象组件，可以指定游戏客户端渲染精灵图。

复合标签格式根标签
- type：object。
- fallback：当精灵图组件渲染失败时，作为回落的文本组件。
- object：精灵图类型，取值见下文。
- 剩余标签与精灵图类型相关。

精灵图组件自身具有多种类型，目前游戏内的精灵图类型如下：

atlas：渲染纹理图集中的精灵图。做标签时名称为sprite。
player：渲染玩家的头的正面图像。

与文本组件解析组件类型类似，当游戏需要解析精灵图组件时，会先读取object字段确定精灵图类型，使用此精灵图类型进行解析；如果未指定object字段，则自动按照上述顺序进行解析；如果object未指定或且上述标签均不存在，则此精灵图组件无效。

游戏在渲染精灵图组件时，将自动替换精灵图组件所在位置的字符为U+FFFC（Object Replacement Character），并将此文字的渲染替换为对应要渲染的精灵图。

精灵图渲染时，游戏会自动将原始的精灵图转换为字体度量中的8×8像素大小，而非将整个精灵图缩放到8×8像素渲染。

组件样式中强行指定精灵图组件的字体无效，粗体、斜体和随机字符样式会被忽略。

纹理图集精灵图

复合标签格式根标签
- type：object。
- fallback：（默认为[<精灵图命名空间ID>]（默认值）或[<精灵图命名空间ID>@<纹理图集命名空间ID>]）当纹理图集精灵图组件渲染失败时，作为回落的文本组件。
- object：atlas。
- atlas：（默认为blocks）使用的纹理图集。
- *
  *sprite：要渲染的精灵图在指定纹理图集中的命名空间ID。

玩家皮肤精灵图

复合标签格式根标签
- type：object。
- fallback：（默认为[<玩家名称> head]（存在玩家名称时）或[unknown player head]）当玩家皮肤精灵图组件渲染失败时，作为回落的文本组件。
- object：player。
- *
  *player：要使用的玩家皮肤。设置为字符串时相当于直接设置name。
  - 游戏档案，见Template:Nbt inherit/resolvable profile/source
- hat：（默认为true）是否渲染皮肤的“帽子”部分。

在MOTD中使用玩家皮肤精灵图会被强制渲染为回落文本。^{[注 1]}

组件样式

文本组件可以附加样式，以修改文本组件渲染时的效果，或给文本增加相应事件。

文字颜色

文本组件可以指定文字渲染的颜色和阴影颜色，标签如下：

复合标签格式根标签
- color：文本渲染颜色。
- shadow_color：文本的阴影颜色。游戏只以整数形式保存。
  - ARGB颜色，见Template:Nbt inherit/argb color/source

文本渲染颜色color可以使用两种格式：

直接使用16进制颜色，此时字符串需要以#开头，后方为16进制数字。其中16进制数字不能大于0xFFFFFF（16777215），也不能小于0，不包含A（透明度）通道。例如#FF0000。
使用颜色代码，有效的颜色代码及相应的颜色见格式化代码 § 颜色代码，使用其名称作为有效值。例如yellow。

文本阴影颜色shadow_color与渲染颜色不同，可以指定A通道。由于着色器限制，当A通道小于0.1（整数形式为0x1A）时，文本阴影无法渲染。

文字字体

使用游戏中存在的4种字体显示文本“Minecraft Wiki”，从上到下依次是预设字体、Unicode字体、标准银河字母和“illageralt”字体

文字字体也可以使用文本组件样式设置：

复合标签格式根标签
- font：命名空间ID，指定渲染使用的字体。默认使用minecraft:default。

文字可以使用的字体由资源包定义在assets/<命名空间>/font/<路径>.json中。如果字体不存在，则游戏直接将所有字符替换为缺失的字形渲染。

文字样式

文本组件也可以设置文字的显示样式和装饰：

复合标签格式根标签
- bold：将文字渲染为粗体。
- italic：将文字渲染为斜体。
- underlined：为文字渲染添加下划线。
- strikethrough：为文字渲染添加删除线。
- obfuscated：渲染为随机字符。

各种文字样式的渲染效果如下：

标签	渲染效果	渲染原理（像素以未缩放计）
bold	hello	文本重复渲染两次，两次渲染中存在渲染偏移
italic	hello	修改文字顶部顶点偏移，倾斜角度为14°（[math]\displaystyle{ \text{arctan}\left(0.25\right) }[/math]）
underlined	hello	在字身框顶下方8像素处渲染1像素的线
strikethrough	hello	在字身框顶下方3.5像素处渲染1像素的线
obfuscated		从字体中挑选相同宽度的字符替代渲染原字符

文本插入

文本组件可以指定被玩家按住⇧ Shift并进行有效点击时插入的文本。

复合标签格式根标签
- insertion：当按住⇧ Shift并进行有效点击时插入文本。

文本插入只在聊天屏幕中生效，点击时将替换聊天栏内选中文本，如果未选中文本则在光标处插入指定文本。

点击事件

在不同位置渲染的文本组件可以执行点击事件，当鼠标指针点击文本后即可执行对应行为。虽然文本插入也需要玩家点击但游戏内部不认为其属于点击事件。

复合标签格式根标签
- click_event：定义点击事件，有效具体行为及条件见下文。
  - *
    *action：点击后的执行行为。
  - 如果*
    *action为change_page：
  - *
    *page：（值>0）要跳转到的书页。
  - 如果*
    *action为copy_to_clipboard：
  - *
    *value：要复制到剪贴板的字符串。
  - 如果*
    *action为custom：
  - *
    *id：要发送的自定义网络负载命名空间ID。
  - payload：要发送的自定义网络负载。嵌套不允许超过16层，且序列化后长度不能超过32768字节。
  - 如果*
    *action为open_file：
  - *path：要打开的文件。
  - 如果*
    *action为open_url：
  - *
    *url：要打开的URL。URL的协议（Scheme）必须为http或https，其他协议无法解析。
  - 如果*
    *action为run_command：
  - *
    *command：要发送到服务端执行的命令，可以不带前导正斜杠（/）。此字符串中不允许出现\u00a7（分节符）、\u007f（DEL）和小于\u0020的字符。
  - 如果*
    *action为show_dialog：
  - *
    *dialog：要打开的对话框。可以指定对话框的命名空间ID，也可以内联定义。
  - 如果*
    *action为suggest_command：
  - *
    *command：要替换聊天栏中的命令。此字符串中不允许出现\u00a7（分节符）、\u007f（DEL）和小于\u0020的字符。

文本组件的有效点击事件只有在下列情况下才可以触发：

点击死亡屏幕中的死亡消息文本组件，且点击事件类型必须为open_url。
点击告示牌，要求点击事件必须在根组件上，且类型必须为run_command、custom或show_dialog。
点击聊天屏幕中的任何文本组件（不包括悬停文本框）。
成书书预览屏幕中的书内部的文本组件（不包括悬停文本框）。

下列是各种点击事件的详细行为：

change_page必须在成书的预览屏幕中才能生效，点击后游戏会将成书翻开到指定页数。如果页数超出成书页码范围，则跳转到第一页或最后一页。
copy_to_clipboard在聊天屏幕和成书预览屏幕中生效，将指定文本写入系统剪贴板中。
custom在聊天屏幕、成书预览屏幕和告示牌中生效，点击后客户端将向服务端发送指定命名空间ID和负载的custom_click_action网络数据包。
- 预留给自定义服务端，原版服务端只会以调试等级日志输出一条信息Received custom click action <网络负载ID> with payload <网络负载>。
open_file在聊天屏幕和成书预览屏幕中生效，且此点击事件类型无法被序列化与反序列化，仅用于客户端内部使用。此事件用于打开指定文件，在不同系统下，此点击事件行为不同：
- Windows系统下，游戏实际上调用rundll32 url.dll,FileProtocolHandler file:<文件路径>。
- macOS下，游戏实际上调用open file:<文件路径>。
- 其他操作系统下（例如Linux），游戏实际上调用xdg-open file://<文件路径>。
open_url在死亡屏幕、聊天屏幕和成书预览屏幕中生效，用于打开指定的URL。
- 如果客户端选项文件中的chatLinks为false，则此点击事件不生效。
- 如果客户端选项文件中的chatLinksPrompt为true，则在点击后弹出询问是否打开此URL的屏幕，确认后进行跳转；如果为false，则直接跳转。
- 不同系统下此点击事件行为不一致，与打开文件类似使用相同命令（rundll32/open/xdg-open），区别仅在最后参数的URL。
run_command在告示牌、聊天屏幕和成书预览屏幕中生效，用于执行指定命令。
- 在告示牌内点击生效时，由服务端处理行为，命令上下文权限等级与触发者无关。详细上下文见命令上下文 § 告示牌。
- 在聊天屏幕和成书预览屏幕生效时，由客户端处理行为，命令上下文与客户端在聊天栏内执行命令一致。
- 在网络阶段为配置（Configuration）阶段中的对话框内此事件不生效。
show_dialog在聊天屏幕、成书预览屏幕和告示牌中生效，点击后将打开指定的对话框。
suggest_command在聊天屏幕中生效，点击时将直接替代当前聊天栏内的信息。

悬停事件

与点击事件类似，当鼠标指针悬停在渲染的文本组件区域内时，会触发悬停事件并使游戏展示指定的数据。

复合标签格式根标签
- hover_event：定义悬停事件。
  - *
    *action：悬停事件的类型，控制悬停渲染的行为。
  - 如果*
    *action为show_entity：
  - *
    *id：（命名空间ID）实体类型。
  - name：（文本组件）实体的显示名称。此文本组件无法被预解析。
  - *
    *uuid：实体的UUID。可以为带有连字符的UUID字符串，也可以为4个整数组成UUID。
  - 如果*
    *action为show_item：
  - *
    *id：（命名空间ID）表示某种类的物品堆叠。若未指定，游戏会在加载区块或者生成物品时将其变更为空气。
  - components：当前物品的组件修订，将修改物品的数据组件信息。
    - <数据组件ID>：一项组件和其对应的数据，代表物品拥有此组件。设置组件数据时可以不写命名空间，但游戏在导出时会自行加上minecraft:前缀。
    - !<数据组件ID>：存在时，使一个数据组件失效。此复合标签的内容不影响行为。设置组件数据时可以不写命名空间，但游戏在导出时会自行加上minecraft:前缀。
  - count：（0<值≤物品最大堆叠数量）物品的堆叠数。不存在或无效时则默认为1。
  - 如果*
    *action为show_text：
  - *
    *value：（文本组件）要显示的文本组件。^[4]

文本组件的悬停事件在下列情况下才可触发：

死亡屏幕中的死亡消息文本组件。
聊天屏幕中的所有文本组件（不包括悬停文本框）。
成书书预览屏幕中的书内部的文本组件（不包括悬停文本框）。

下列是各种悬停事件的详细行为：

show_entity将展示实体的信息，包括实体类型、名称和UUID。此悬停事件必须在客户端选项文件中advancedItemTooltips（高级提示框，可使用F3 + H切换）为true时才能生效。
- 游戏将按照三行显示数据，分别为实体的名称、类型和UUID。如果悬停事件中未定义实体名称，则名称行不存在，只渲染类型和UUID两行。
- show_entity中name无法被预解析。例如{text: 'test', hover_event: {action: 'show_entity', uuid: [I; 0, 0, 0, 0], id: 'player', name: {selector: '@e'}}}在悬停时实体名称直接显示为@e而不是预解析后的具体实体名称列表。
show_item将展示物品的信息，渲染结果与物品栏内物品悬浮提示框一致。此渲染也受到客户端选项文件中advancedItemTooltips值的影响。
show_text将直接展示指定的文本组件。

基岩版

此章节缺失以下信息：需要更多基岩版文本组件信息

请协助补充相关内容的描述，讨论页可能有更多细节。

基岩版有着较为精简的文本组件格式，它以文本显示为主，目前为止不具备任何交互功能。文本的字体样式可通过格式化代码进行修饰。

在基岩版中，文本组件被应用在/tellraw的内容、/titleraw的标题、NPC的名字、书与笔的文本（题目和作者除外）、告示牌的文本以及大部分富文本信息中。但记分板分数组件（Score）和实体名称组件（Selector）只能在流动的文本信息中生效，即聊天室讯息和屏幕标题，否则将不显示内容。

数据格式

基岩版的文本组件的根节点只能是纯文本或具有rawtext属性的对象。玩家在游戏中一般只能使用到文本组件。

文本组件根节点。
- 如果根节点为：纯文本形式，一般只能在文件代码中碰见。
- 如果根节点为：对象形式的文本组件。
- rawtext：必须包含一个或多个内容组件。若为空列表将出错。
  - ：一个内容组件。“没有内容”的内容组件将被忽略。

内容组件

内容组件是文本组件的一部分，无法独立存在，用于定义一个文本组件所显示的内容。一个内容组件只能显示一种内容类型和一个扩展的内容组件列表rawtext，内容组件内容的类型由对象内出现的必要字段决定。各类内容组件内容对应的必要字段如下：

纯文本组件内容：text
翻译文本组件内容：translate
记分板分数组件内容：score
实体名称组件内容：selector

若内容组件中没有任何必要字段和扩展的内容组件列表，则不显示任何内容。

：内容组件根节点。
- rawtext：（可选）扩展的内容组件列表，将始终显示在内容组件的基础内容之后。可以包含零个或多个内容组件，若为空则不显示内容。
  - ：一个内容组件。
- 根据内容类型而指定的额外字段。详见下方后续。

纯文本（Text）

一段纯文本内容。

纯文本内容类型的内容组件有以下字段：

- text：值是允许转义字符的字符串。

示例：

这是最简单的纯文本组件。会显示hello。

{"rawtext": [{"text": "hello"}]}

hello

文本组件中的换行必须通过\n完成。

{"rawtext": [{"text": "第一行\n第二行\n\n第四行"}]}

第一行
第二行

第四行

多个内容组件将依序显示。

{"rawtext": [{"text": "hello "}, {"text": "world"}]}

hello world

翻译文本（Translate）

一段可根据所选语言翻译成译文的本地化键名或一段格式化字符串（Format String）。翻译文本会被转译成格式化字符串，可以包含纯文本的格式说明符（Format Specifier），使文本内容可变。

翻译文本内容类型的内容组件有以下字段：

- translate：一个本地化键名，它将会以玩家所选语言显示对应的语言文件下相应的译文。若未找到当前语言下有该本地化键名，则默认检查en_us.lang中是否有对应的译文。^{[需要在基岩版上验证]}若未找到，则该值将被视为允许格式说明符的格式化字符串。
- with字段（可选）可以是列表或对象。它的值将用作translate的匹配项列表，而不是直接显示。若未提供with字段，则translate内的格式说明符会显示自身。
- with：（可选）with字段的常见类型，只能使用纯文本。
  - ：一个文本匹配项，值是允许转义字符的字符串，可以包含纯文本的格式说明符（%x %）。载入translate时会被转译成格式化字符串和真正的格式说明符%%x %%。
- with：（可选）比with支持更多的文本组件类型。值必然是对象形式的文本组件，组件中rawtext的值将用作匹配项列表。匹配项可以包含纯文本的格式说明符（%x %），载入translate时会被转译成格式化字符串和真正的格式说明符%%x %%。

示例：

翻译文本组件中的本地化键名会被翻译。

{"rawtext": [{"translate": "commands.op.success"}]}

已将 %s 设为管理员

如果提供了with字段内容，会进一步对格式说明符进行匹配。

{"rawtext": [{"translate": "commands.op.success", "with": ["朋友", "外人"]}]}

已将朋友设为管理员

翻译文本组件的%%最终会输出为纯文本%，而纯文本%载入格式化字符串时会转译成%%。

{"rawtext": [{"translate": "原文 %% 纯文本 %%1 翻译文本 %%s", "with": {"rawtext": [{"translate": "%%"}, {"text": "%"}]}}]}

原文 % 纯文本 % 翻译文本 %

记分板分数（Score）

显示记分板中，目标分数持有者（Score Holder）在指定记分项（Objective）中的分数。

记分板分数内容类型的内容组件有以下字段：

- score：要显示的目标分数来源。分数不存在时不显示内容，多个分数以逗号加一个空格, 分隔。
  - name：目标分数持有者。可以使用目标选择器、玩家名称、虚拟玩家名称（通过一个自定义键名直接在记分项中创建的分数持有者，#开头的虚拟玩家名称会在记分板中隐藏显示）、实体的记分板ID或分数持有者通配符*。若为目标选择器，允许匹配多个目标。若为*则表示为信息读者本身。
  - objective：指定记分项的名称。必须与创建记分项时使用的名称一致。

示例：

当记分板分数组件同时显示多个分数时，情况如下。

{"rawtext": [{"score": {"name": "@e", "objective": "obj"}}]}

2, -3, 15

记分板分数组件会输出纯文本，并与§组合成格式化代码。

{"rawtext": [{"text": "颜色：§"}, {"score": {"name": "*", "objective": "obj"}}]}

假如读者在obj中的分数是3456.

颜色：456

无论分数或记分项是否存在，当name的值是*时，将必定显示一个内容。

{"rawtext": [{"score": {"name": "*", "objective": ""}}]}

下方显示的是一个空内容。

实体名称（Selector）

显示被选中的实体的名称，若该实体没有自定义名称（Custom Name）则显示其实体类型的本地化名称（例如：狼）。

实体名称内容类型的内容组件有以下字段：

- selector：目标实体。可以使用目标选择器、玩家名称或实体通配符*，若为*则表示为信息读者本身。没有匹配的目标时不显示内容，多个匹配目标的名称以逗号加一个空格, 分隔。

示例：

实体名称组件会显示实体的名称或类型。

{"rawtext": [{"selector": "@e[type=wolf]"}]}

假如有一只被命名为小白的狼和一只没有被命名的狼。

小白, 狼

文本中的目标选择器必须经过转义。如特殊字符"必须写成\"。

{"rawtext": [{"selector": "@a[name=\"Alex\"]"}]}

假如玩家Alex在线。

Alex

当实体名称组件没有匹配到目标时，不会显示内容。

{"rawtext": [{"selector": "@e[c=0]"}]}

以上是一个无意义的文本组件。

组件解析

组件的解析遵循固定的规律和优先级。一个文本组件中包含的多个内容组件，将依照排列顺序解析成文本后组合起来。当遇到嵌套的内容组件或文本组件时，子级组件会先被解析成文本后再回传给父级组件。

一个完整的解析过程：

步骤1：解析第一个内容组件的rawtext的内容。

{"rawtext": [
  // rawtext的内容是子级组件
  {"text": "A", "rawtext": [{"text": "B"}, {"text": "C"}]},
  {"translate":"%%s", "with": {"rawtext": [
    {"text":"D"},
    {          },
    {"text":"E"}
  ]}}
]}

步骤2：合并第一个内容组件的rawtext。

{"rawtext": [
  {"text": "A", "rawtext": ["B", "C"]},  // 列表内容会合并
  {"translate":"%%s", "with": {"rawtext": [
    {"text":"D"},
    {          },
    {"text":"E"}
  ]}}
]}

步骤3：合并第一个内容组件。

{"rawtext": [
  {"text": "A", "rawtext": "BC"},  //主内容和扩展内容会合并
  {"translate":"%%s", "with": {"rawtext": [
    {"text":"D"},
    {          },
    {"text":"E"}
  ]}}
]}

步骤4：解析第二个内容组件的with字段的rawtext。

{"rawtext": [
  "ABC",
  {"translate":"%%s", "with": {"rawtext": [  // rawtext是子级组件
    {"text":"D"},
    {          },  // 无内容组件会被忽略
    {"text":"E"}
  ]}}
]}

步骤5：生成匹配项列表。

{"rawtext": [
  "ABC",
  // rawtext会解析成匹配项列表
  {"translate":"%%s", "with": {"rawtext": ["D", "E"]}}
]}

步骤6：解析第二个内容组件。

{"rawtext": [
  "ABC",
  // translate的格式化字符串开始解析
  {"translate":"%%s", "with": ["D", "E"]}
]}

步骤7：合并所有内容。

{"rawtext": [  // 所有内容合并
  "ABC",
  "D"
]}

最终的显示结果如下。

ABCD

最终一个文本组件会生成一个纯文本，只有当真正显示出来时格式化代码才会被解析。这意味着记分板分数组件的内容可以与§组合成格式化代码。

不停变换色彩的标题：

创建一个记分项/scoreboard objectives add var dummy，然后不断地依次执行下方命令：

scoreboard players add color var 1
execute if score color var matches 10.. run scoreboard players set color var 0
titleraw @a title {"rawtext":[{"text":"§"},{"score":{"name":"color","objective":"var"}},{"text":"Rainbow"}]}

当一个内容组件内包含多个必要字段时，内容组件的内容类型将由优先级最大的字段决定而无关顺序。必要字段优先级如下：translate>text>score>selector。这意味着translate将覆盖text的内容。

示例：

{"rawtext": [{"translate":"内容A", "translate": "内容B", "text": "内容C"}]}

内容组件中优先级最大的字段是translate，并且第二个translate字段将覆盖先前的translate字段。最终将显示内容B。

内容B

内容的定义

内容在文本组件上下文中具有特定的含义，“内容”只能由四个基本字段定义（translate、text、score和selector）。而在特定条件下score和selector可能无法显示内容。

值得注意的是，“不显示内容”与“显示空内容”是不同的概念，前者将导致难以预料或不符合预期的结果。

不显示内容（无内容）：可以被视为是一次失败的结果。当一个内容组件不显示内容时，它将直接被忽略；当文本组件不显示内容时，将“无事发生”。
显示空内容（空内容）：空内容可以通过{"text": ""}轻易获取。显示空内容的内容组件不会被忽略，因此可以通过组合可能不显示内容的内容组件和空内容以避免不可预期的结果。

字符串与格式化字符串

文本组件中的所有字符串都是纯文本形式的文本组件，因此可以接受部分转义字符和Unicode编码。所有的转义字符都会在进行复杂的组件解析前完成转义。

特殊字符：尽管\0并不能被成功转义，但与之对应的\u0000却能正常地将当前字符串强行截断。

允许的转义字符及对应结果

转义字符	结果	对应编码
`\n`	换行	`\u000A`
`\r`	`õ`	`\u00F5`
`\t`	`õ`	`\u00F5`
`\b`	`ô`	`\u00F4`
`\f`	`ã`	`\u00E3`
`\\`	`\`	`\u005C`
`\"`	`"`	`\u0022`

格式化字符串

格式化字符串（Format String）被应用在了翻译文本组件中，是一种存在变量的文本，具有普通字符串的所有特性。实际上它是源于Java编程语言的一种字符串规范^[5]，而在基岩版中它是通过C++编程语言模仿实现的。^{[需要验证]}

格式化字符串中的变量被称为格式说明符(Format Specifier)，又分为按序匹配和按位匹配。

按序匹配：%%<数据类型>会匹配到匹配项列表中的“下一项”内容，并将基准点后移一位。优先级高于按位匹配，且按序匹配间会从左到右逐一进行匹配。
按位匹配：%%<索引位置>会匹配到从基准点算起的第n项内容，0即为基准点的位置。所有按位匹配是同时完成的。
带类型的按位匹配：%%<索引位置>$<数据类型>一般会在语言文件中看到，但在翻译文本组件的with字段内不生效。

参数

数据类型：只能是s表示文本格式（String）或d表示数字格式（Digit）。在文本组件中两者没有区别。
索引位置：可以是0到9之间任意整数。

任何纯文本被载入格式化字符串时会被转译为格式化字符串，其中所有%将转译为%%。同理当格式化字符串输出内容成纯文本时，%%会转译为%。这也是区分纯文本和格式化字符串的主要方法。