原始JSON文本格式

原始JSON文本（Raw JSON Text）是Minecraft用于给玩家发送并显示富文本的格式。原始JSON文本使用JSON编写。

Java版[]

原始JSON文本由聊天组件（Chat Component）组成。根组件可包含有子组件，而子组件也可以有自己的子组件。组件可以包含格式和交互事件，这些也会应用到他们的子组件上。

聊天组件可以使用除“null”外的所有JSON数据类型。数值和布尔值将会视为字符串处理，而字符串和数组用于简写较长的对象结构，见下文所述。

含有纯文本的字符串。与只有标签 text的对象效果相同。例如，"A"和{"text": "A"}等价。
布尔值将会转换为字符串直接显示。与只有标签 text的对象效果相同。例如，true、"true"和{"text": "true"}等价。
数值将会转换为字符串直接显示。与只有标签 text的对象效果相同。例如，1.9E10、"1.9E10"和{"text": "1.9E10"}等价。
含有多个聊天组件对象的列表。与含有 extra数组的聊天组件效果相同。^{[注 1]}例如，["A", "B", "C"]和{"text": "A", "extra": ["B", "C"]}等价。
一个聊天组件对象。所有非内容标签都是可选的。
- 内容
- 一个对象需要包含内容标签才能生效。不同的内容类型及它们对应的标签将于下方说明。可以含有多个内容标签，但最终只有一个会生效。^{[注 2]}
- type：可选，用于提升解析与错误检查的速度。有效值有：text、translatable、score、nbt、keybind。^{[新增：JE 1.20.3]}
- 子对象
- extra：含有在此组件之后显示的附加聊天组件的列表。
  - 子聊天组件。除非额外指定，子组件将继承父组件的所有格式和交互事件。
- 格式
- color：渲染文字时使用的颜色。有效值有：black、dark_blue、dark_green、dark_aqua、dark_red、dark_purple、gold、gray、dark_gray、blue、green、aqua、red、light_purple、yellow、white、reset（取消父对象使用的颜色效果）。
  设置为"#<hex>"可以使用以6位十六进制RGB颜色格式定义的颜色。
- font：渲染文字时使用的字体的资源路径。使用的字体在assets/<namespace>/font里定义，默认为minecraft:default。
- bold：是否将文字渲染为粗体。
- italic：是否将文字渲染为斜体。原本为斜体的自定义物品名称可以通过将此值设置为“false”来取消斜体。
- underlined：是否为文字添加下划线。
- strikethrough：是否为文字添加删除线。
- obfuscated：是否将文字混淆处理。
- 交互事件
- insertion：玩家按住⇧ Shift并点击文字时，填入聊天框的的文字。其不会覆盖聊天框内原有的文字。仅在聊天页面中生效。
- clickEvent：允许在玩家点击文字时产生事件。若无附加说明，其仅在聊天页面和成书中生效。
  - action：点击后发生的事件。有效值有：
    - “open_url”：在默认浏览器中将 value作为URL地址打开。
    - “open_file”：打开计算机上位于 value的文件。其用于游戏自动生成的信息中（如截图后显示的信息），且出于安全原因禁止玩家使用。
    - “run_command”：执行一条命令。可用于告示牌上，但仅支持在父组件中使用；通过使用告示牌触发。在聊天页面和成书中触发则会以玩家的身份和位置执行命令，但需要玩家拥有相应的权限；命令必须拥有“/”前缀，且不能为聊天命令（/say、/tell和/teammsg）。在告示牌中，命令将由服务器在告示牌所在的位置执行，并将使用告示牌的玩家视为执行者。因为命令由服务器执行，告示牌命令的权限等级与命令方块相同，玩家的权限等级会被忽略；且其不受聊天框长度的限制，可以省略“/”前缀。
    - “suggest_command”：打开聊天页面并输入 value。若聊天框已有内容，其将会被覆盖。在成书中无效。^[1]
    - “change_page”：仅在成书中生效。若指定页面存在，将成书翻至第 value页。
    - “copy_to_clipboard”：将 value复制到剪贴板中。
  - value：指定的URL、文件路径、信息、命令或页码。
- hoverEvent：允许在玩家将鼠标悬停在文本上时显示提示文字。
  - action：提示文字的类型。有效值有：
    - “show_text”：显示一个聊天组件。
    - “show_item”：显示一个物品的工具提示。与在物品栏中悬浮在物品上时出现的工具提示相同。
    - “show_entity”：显示实体的名称、类型和UUID。用于 selector中。
  - contents：此标签的格式取决于 action的值。
    - “show_text”：一个聊天组件。可以使用字符串、数组或对象。
    - “show_item”：要显示的物品。
      - id：物品的命名空间物品ID。若无效则视为minecraft:air。
      - count：可选，物品的数量。
      - tag：可选，物品的NBT标签。参见player.dat格式#物品结构。
    - “show_entity”：要显示的实体。
      - name：可选，若未指定则隐藏本参数。将显示为实体名称的聊天组件。
      - type：指定实体的类型。应为一个命名空间实体ID。若无效则视为minecraft:pig。
      - id：指定实体的UUID。应为一个有效的由连字符连接的十六进制UUID或4个整型值所构成的整型数组UUID。^{[新增：JE 1.20.3]}
  - ~~value~~：此标签的格式取决于 action的值。已弃用，请使用 contents代替。
    - “show_text”：一个聊天组件。可以使用字符串、数组或对象。
    - “show_item”：一个物品的NBT标签。参见player.dat格式#物品结构。
    - “show_entity”：一个NBT标签。其不包含所有的实体数据，仅储存实体的名称、类型和UUID。
      - name：可选，若未指定则隐藏本参数。指定该实体的名称并显示。包含将被解析聊天组件的JSON文本。若字符串无法被解析为聊天组件，整个提示文字会显示为“无效的实体！”。
      - type：可选，若未指定则隐藏本参数。指定该实体的类型。包含将视为实体类型的纯文本，可以为任何文字。
      - id：可选，若未指定则显示为空行。指定该实体的UUID。包含将视为UUID的纯文本，可以为任何文字。

由于 extra标签的存在，以上格式可递归嵌套成非常复杂与多样的文本。然而，原始JSON文本不必弄得如此复杂：几乎所有的标签都是可选的。

内容类型[]

聊天组件可以显示多种类型的内容。这些标签应直接包含于聊天组件对象中。

纯文本[]

显示纯文本。

聊天组件。
- text：一段文本。里面的内容会进行转义。

已翻译文本[]

以当前语言显示一段已翻译的文本。使用的语言取决于客户端选择的语言，所以不同客户端在收到同一服务器的同一翻译标识符后，客户端会使用各自的语言显示文本。若在客户端内未找到对应的译文，则会检查en_us.json中对应的译文。若依旧未找到，则输出 fallback的值或直接输出翻译标识符本身。

翻译标识符可以在资源包的语言文件内指定。也可以使用游戏内置资源包内的翻译标识符。

翻译标识符指向的译文、翻译标识符本身和 fallback可以包含应用于未知文本的变量。变量通常会以%s（显示列表中的下一个对象）或%1$s（显示列表中的第1个对象；可以将1替换为其他数字，对应列表中的第N个对象）的形式出现。^{[注 3]}显示已翻译文本时，这些变量将由 with提供的聊天组件列表填充。

如果未给某变量提供参数，输出的文本会将所有变量按原样输出，不使用 with提供的值。

聊天组件。
- translate：一个翻译标识符。
- fallback：可选，翻译标识符无对应译文时输出的文本。不存在 translate时忽略。
- with：可选，含有用于替换译文内变量的聊天组件的列表。不存在 translate时忽略。
  - 一个聊天组件。

记分板分数[]

显示实体在记分板中某个记分项的分数。

需要解析组件。
此标签会解析为值为记分板分数的 text标签。

聊天组件。
- score：显示分数持有者在指定记分项下的当前分数。若指定分数持有者或记分项不存在，或分数持有者未被记分项追踪则不会显示任何内容。
  - name：分数持有者的名字。可以使用目标选择器、具体名称或“*”。若为选择器，则选择器不能选择多个实体。若为*，则会显示读者自己的分数（例如，/tellraw @a {"score":{"name":"*","objective":"obj"}}会给每个在线玩家显示他们自己在“obj”记分项里的分数）。^{[注 4]}
  - objective：记分项的内部名称。
  - value（可选）：如果存在，则无论分数是多少，都会显示此值。

实体名称[]

显示由目标选择器找到的实体的名称。

若选择器发现了一个实体，则会显示这个实体的名称。若发现了多个实体，则会显示所有被选中的实体的名称，用分隔符（默认为灰色的半角逗号）分隔。若没有发现实体，则不会显示任何文本。

悬浮在名称上时会显示包含名称、类型和UUID的工具提示。点击一个玩家的名称会出现私信该玩家的命令建议；按住⇧ Shift点击玩家名称会将其名称填入聊天框中；按住⇧ Shift点击非玩家实体的名称会将其UUID填入聊天框中。

需要解析组件。
如果选择器发现了一个实体：如果此实体是一名玩家，此标签会解析为值为此玩家的名称的 text标签。如果此实体拥有自定义名称，它会解析为代表此自定义名称的聊天组件。如果此实体不是玩家且没有自定义名称，它会解析为值为此实体类型对应的翻译标识符的 translate标签。解析后的组件会拥有 insertion标签、类型为`show_entity`的 hoverEvent标签和类型为`suggest_command`的 clickEvent标签（若此实体是一名玩家）以实现上文所述的功能。如果这些标签已经存在于原组件上，对应标签的值将使用原组件上的值。如果选择器发现了多个实体，此组件会解析为无内容的 text标签，并带有含有代表单个实体的对象的 extra标签，各对象之间使用 separator标签的值（若未指定则为默认值）分隔。如果选择器没有发现实体，此组件会解析为无内容的 text标签。

聊天组件。
- selector：一个目标选择器。
- separator：可选，用作分隔符的聊天组件。默认为{"color": "gray", "text": ", "}。在组件显示多个实体时，使用此标签指定的聊天组件分隔各个实体的名称。

按键绑定[]

显示可设置键位的动作当前绑定的键位的名称。其取决于客户端的绑定配置，所以不同客户端在收到同一服务器的同一标识符后，客户端会使用各自的配置显示键位名称。

例如，若使用默认配置，{"keybind": "key.inventory"}将显示为“e”。

聊天组件。
- keybind：一个键位标识符。

NBT标签值[]

显示从实体、方块实体或命令存储处获取的NBT标签的值。

如果NBT标签的值为字符串，则显示它的内容；其他值则将显示为SNBT。如果 interpret为真，游戏会尝试将获取的值解析为聊天组件并显示。因为JSON和SNBT之间并不相通，这种解析通常只在值为字符串时成功。如果 interpret为真且解析失败，则不会显示任何文本。如果发现多个值（通常由选择了多个对象或路径会选择多个值造成），则会显示所有值，用分隔符（默认为半角逗号）分隔。

需要解析组件。
如果 interpret为假，此标签会解析为值为NBT标签的值的 text标签。如果选择了多个值且未提供 separator标签，它仍然会解析为单个 text标签，各个值之间使用半角逗号分隔。如果选择了多个值且提供了 separator标签，每个值会解析为单独的 text标签，第一个值之后的值均会放入第一个值的 extra标签，各对象之间使用 separator标签的值分隔。如果 interpret为真，组件会解析为对应的聊天组件。对于同时存在于被解析的组件和原组件上的非内容标签，标签将使用原组件的值。如果选择了多个值，每个值会解析为对应的聊天组件，第一个值之后的值均会放入第一个值的 extra标签，各对象之间使用 separator标签的值（若未指定则为默认值）分隔。这意味着第一个值的格式标签会应用于之后的值里。

聊天组件。
- nbt：一段NBT路径，用于指定NBT标签。需要同时存在 block、 entity或 storage。可以含有多个相应标签，但只会有一个生效。^{[注 5]}
- interpret：可选，默认为“false”。若指定为“true”，则会将获取到的每个值视为聊天组件并解析。不存在 nbt时忽略。
- separator：可选，用作分隔符的聊天组件。默认为{"text": ", "}。在组件显示多个值时，使用此标签指定的聊天组件分隔各个值。
- block：一个坐标，指定要获取NBT标签的方块实体。坐标可以是绝对坐标、相对坐标或局部坐标。不存在 nbt时忽略。
- entity：一个目标选择器，指定要获取NBT标签的实体。不存在 nbt时忽略。
- storage：一个命名空间ID，指定要获取NBT标签的命令存储。不存在 nbt时忽略。

解析组件[]

部分聊天组件不会一直存在。含有 score、 selector或 nbt标签的组件会被解析：从世界中取得指定数据，将数据转化为相应的聊天组件，之后用转化后的组件替换原来的组件。解析会通过放置告示牌、第一次打开成书、将成书置于讲台上和使用命令完成。它也可以通过物品修饰器“set_name”和“set_lore”完成，但同时需要物品修饰器含有 entity标签。在自定义名称中无法解析这些组件。

此外，解析会固定获取的值。因此，这些组件的内容不再变化，不会因环境的变化而调整相应值。

基岩版[]

根标签。
- rawtext：包含所有文本对象的列表。
  - ：基础聊天对象。
    - text：直接显示原始文本的字符串。存在 translate时忽略。
    - selector：发送后转换为实体名称的目标选择器。
    - translate：将以所选语言显示的本地化键名。语言文件中可找到所有有效的本地化键名。
    - with：与 translate配合使用，以此列表内容替换翻译字符串中的参数。
      - ：参数将替换为的内容，按顺序对应（如：列表中的第一个元素对应 translate中的%%1）。
    - score：显示记分项内指定实体的分数。
      - name：指定一个分数持有者，可使用“@s”、“@a”等目标选择器或虚拟玩家名，与 selector无关。如果为*，则显示阅读者分数（如：/tellraw @a {"rawtext":[{"score":{"name":"*","objective":"obj"}}]}会向在线玩家显示自己在“obj”记分项的分数）。
      - objective：指定要显示记分项的名称。

历史[]

Java版
1.7.2	13w37a	加入了`/tellraw`，原始JSON文本用于支持该命令。
1.8	14w02a	加入了`insertion`。
	14w07a	加入了`score`。
	14w20a	加入了`/title`，其使用原始JSON文本。
	14w20a	加入了`selector`。
	14w25a	现在支持在告示牌和成书内使用。
1.12	17w16a	加入了`keybind`。
1.13	18w01a	现在支持在自定义名称内使用。
1.13	18w05a	加入了`/bossbar`，参数`<name>`使用原始JSON文本。
1.14	18w43a	加入了`nbt`、`block`和`entity`。
	18w43a	现在支持在物品描述标签内使用。
	18w44a	加入了`interpret`。
1.15	19w39a	加入了`storage`。
1.15	19w41a	为`clickEvent`加入了`copy_to_clipboard`。
1.16	20w17a	加入了`font`。
		为`hoverEvent`加入了`contents`。`value`不再使用，但仍受支持。
		`color`现在可以使用十六进制颜色码来自定义颜色。
		不再使用`score`中的`value`。
1.17	21w15a	加入了`separator`。
1.19.1	rc1	`clickEvent`的`run_command`事件现在不再支持直接发送聊天信息。这意味着现在所有的值都需要以`/`为前缀。
1.19.1	pre6	`clickEvent`的`run_command`事件现在不再支持任何可发送聊天消息的命令。
1.19.4	23w03a	加入了`fallback`。
1.19.4	23w03a	`translate`格式中的越界参数不再被静默忽略。
Java版（即将到来）
1.20.3	23w40a	加入了`type`，用于提升解析与错误检查的速度。
		纯文本聊天组件（只有文本内容，无并列的组件，无格式）现在总会被序列化成字符串，而非`{"text": "字符串"}`。
		聊天组件现在会在通过网络发送时序列化。
		`show_entity`的`id`字段现在可接受4个整型值所构成的数组形式的UUID。
		`translate`组件内的数值与布尔型参数不再被转换成字符串。
		不再支持`null`和`[]`JSON文本表达式。
		若`color`、`clickEvent`和`hoverEvent`类型字段中出现错误，现在将不再被静默忽略。
基岩版
1.9.0	1.9.0.0	加入了`/tellraw`，原始JSON文本用于支持该命令。
1.16.100	1.16.100.55	加入了`score`和`selector`。

参见[]

JSON
命令
格式化代码
教程/原始JSON文本

备注[]

↑ 请注意，之后的组件将视为第一个组件的子组件，因此第一个组件的格式和交互事件将应用于之后的组件。例如，[{"text": "A", "color": "red"}, "B", "C"]将会输出都被渲染为红色的文本。
↑ 按照 text、 translate、 score、 selector、 keybind、 nbt的顺序检查。若提供了多个内容标签，则会使用此列表中最靠前的标签。
↑ 选择“下一个”对象时忽略已索引变量。所以若译文“Hello %s, %2$s, and %s.”被赋予参数“John”和“Becky”，它将显示为“Hello John, Becky, and Becky.”
↑ 显示读者自己的分数仅在发送的信息不会被不同玩家同时阅读时生效。显示在聊天信息、/title或被独自阅读的成书上时会生效，但在告示牌、讲台上的成书等地方将无法生效。
↑ 按 block、 entity、 storage的顺序检查。若提供了多个标签，则会使用此列表中最靠前的标签。