原始JSON文本格式

原始JSON文本（Raw JSON Text）是Minecraft用于给玩家发送并显示富文本的格式，它也可以通过命令和数据包发送。原始JSON文本使用JSON编写。

Java版

原始JSON文本由聊天组件组成。结构本身只有一个根对象，但这个根对象可包含有子对象，而这些子对象也可以有自己的子对象，依此类推。对象可以包含格式和交互事件，这些也会应用到他们的子对象上。

聊天组件的格式可以是JSON字符串、JSON数组或JSON对象。字符串和数组用于简写较长的对象，见下文所述。

聊天组件内存在的数值和布尔值将会视为字符串处理。

• 直接显示原始文本的字符串。与只有标签 text的对象效果相同。例如，"A"和{"text": "A"}是等价的。
• 包含多个文本对象的列表。与含有 extra数组的文本对象效果相同。例如，["A", "B", "C"]和{"text": "A", "extra": ["B", "C"]}是等价的。
• 一个聊天组件。若要生效，则必须包含内容组件：text、translate、score、selector、keybind或nbt。含有多个组件是允许的，但只会有一个生效。其他组件是可选的。
  • 内容：纯文本
  •  text：直接显示原始文本。里面的内容会进行转义。
  • 内容：已翻译文本
  •  translate：包含翻译标识符的字符串，会以玩家所选择的语言显示对应的文字。若未找到对应的译文，则会检查en_us.json中对应的译文。若依旧未找到，则直接输出标识符。标识符与从assets文件夹或资源包中找到的语言文件的标识符一致。
  •  with：可选。列表内的参数将为译文中的变量赋值。不存在 translate时忽略。
    • 译文可以包含使用于未知文本的变量。这些变量直接在标识符中定义，与JSON对象无关。变量通常会以%s（显示下一个参数）或%1$s（显示第1个参数；可以将1替换为其他数字，对应指定的其他参数）的形式出现。如果未给某变量提供参数，该变量将不会显示。
  • 内容：记分板的值（需要解析）
  •  score：显示一个持有者在指定记分项下当前的分数。若指定持有者或记分项不存在，或持有者未被记分项追踪则不会显示任何内容。
    •  name：要被显示分数的持有者。可使用指定名称、选择器或“*”。若为选择器，则选择器不能选择多个实体。若为*，则会显示读者自己的分数（例如，/tellraw @a {"score":{"name":"*","objective":"obj"}}将给每个在线玩家显示他们自己在“obj”目标里的分数）。
    •  objective：要显示分数的记分项的内部名称。
    •  value：可选。如果存在，将以此参数的值覆盖目标原先的分数。
  • 内容：实体名称（需要解析）
  •  selector：包含目标选择器的字符串，显示被选中玩家和实体的名称。若选择器发现了多个实体，则会显示所有被选中的实体的名称，用半角逗号分隔。悬浮在名称上时会显示包含名称、类型和UUID的工具提示；点击一个玩家的名称会出现私信该玩家的命令建议；按住⇧ Shift点击玩家名称会将其名称填入聊天框中；按住⇧ Shift点击非玩家实体的名称会将其UUID填入聊天框中。
  • 内容：按键键位
  •  keybind：包含键位标识符的字符串，会显示某操作当前绑定的按钮的名称。例如，若使用默认配置，{"keybind": "key.inventory"}将显示“e”。
  • 内容：NBT的值（需要解析）
  •  nbt：包含一段NBT路径的字符串，用于从实体、方块或存储处查找指定NBT数据标签的值。若值为字符串，则显示它的内容；其他值将显示为SNBT，没有空格和换行符。若值为聊天组件，显示方式受 interpret影响。若发现多个值（通常由选择了多个对象或路径会选择多个值造成），则会显示所有值，之间用半角逗号分隔。需要同时存在block、entity或storage。含有多个组件是允许的，但只会有一个生效。
  •  interpret：可选，默认为“false”。若指定为“true”，则会尝试将获取到的每个值视为原始JSON文本聊天组件并解析。若解析失败，则不会显示任何内容。不存在 nbt时忽略。
  •  block：指定要获取NBT数据标签的方块实体的坐标。坐标可以是绝对坐标或相对坐标。不存在 nbt时忽略。
  •  entity:以目标选择器的形式指定要获取NBT数据标签的实体。不存在 nbt时忽略。
  •  storage：指定要获取NBT数据标签的命令存储的命名空间ID。不存在 nbt时忽略。
  • 子对象
  •  extra：包含在文本之后显示的附加原始JSON文本对象的列表。
    • 子文本对象。子对象将继承父对象的所有格式和交互事件，除非额外指定。
  • 格式
  •  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位十六进制颜色格式定义的颜色。
  •  bold：可选。是否将文字渲染为粗体。
  •  italic：可选。是否将文字渲染为斜体。原本为斜体的自定义物品名称也可以通过将此值设置为“false”来取消斜体。
  •  underlined：可选。是否为文字附加下划线。
  •  strikethrough：可选。是否为文字附加删除线。
  •  obfuscated：可选。是否将文字模糊处理。
  •  font：可选。使用在assets/<namespace>/font里定义的字体渲染文本。默认为minecraft:default。
  •  separator：可选。替换在显示多个值时使用的符号（默认为“,”）。可以为字符串或另一个聊天组件。
  • 交互事件
  •  insertion：可选。当玩家按住⇧ Shift并点击文字时，此组件指定的字符串会自动填入聊天框中，不会覆盖原有的文字。仅在聊天页面中生效。
  •  clickEvent：可选。允许在玩家点击文字时产生事件。若无附加说明，仅在聊天页面和成书中生效。
    •  action：点击时发生的事件。有效值有：
      • “open_url”：在默认浏览器中打开 value中的URL地址。
      • “open_file”：打开计算机上位于 value的文件。其用于游戏自动生成的消息中（如截图时显示的信息），且出于安全原因禁止玩家使用。
      • “run_command”：可用于告示牌上，但仅支持在父对象中使用。在使用告示牌时生效。在聊天页面和成书中，将以玩家的身份输入 value并发送。这可以用于执行命令，但需要玩家拥有权限；命令必须拥有“/”前缀，否则将会视为聊天信息。在告示牌中，命令将由服务器在告示牌所在的位置执行，并将使用告示牌的玩家视为执行者。因为命令由服务器执行，告示牌命令无视玩家的权限等级，其与命令方块的权限等级相同；且其不受聊天框长度的限制，可以省略“/”前缀。
      • “suggest_command”：打开聊天页面并输入 value。若聊天框已有内容，其将会被覆盖。
      • “change_page”：仅在成书中生效。若指定页面存在，将翻至第 value页。
      • “copy_to_clipboard”：将 value复制到剪贴板中。
    •  value：指定的URL、文件路径、信息、命令或页码。
  •  hoverEvent：可选。允许在玩家将鼠标指针悬浮在文字之上时显示提示文字。
    •  action：提示文字的类型。有效值有：
      • “show_text”：显示原始JSON文本对象。
      • “show_item”：显示一个物品的提示文字。与在物品栏中悬浮在物品上时出现的提示文字相同。
      • “show_entity”：显示实体的名称、类型和UUID。用于 selector中。
    •  value：此标签的格式取决于 action的值。不推荐使用，请使用 contents代替。
      • “show_text”：另一个JSON文本对象。可以使用字符串、数组或对象。
      • “show_item”：包含一个物品的SNBT的字符串。参见player.dat格式#物品结构。
      • “show_entity”：包含SNBT的字符串。其不包含所有的实体数据，仅存有实体的名称、类型和UUID。
        •  name：可选，若未指定则隐藏本参数。指定该实体的名称并显示。包含将被解析为文本对象的JSON文本。若字符串无法被解析为文本对象，整个提示文字将会显示为“无效的实体！”。
        •  type：可选，若未指定则隐藏本参数。指定该实体的类型。包含将视为实体类型的纯文本，可以为任何文字。
        •  id：可选，若未指定则显示为空行。指定该实体的UUID。包含将视为UUID的纯文本，可以为任何文字。
    •  contents：此标签的格式取决于 action的值。
      • “show_text”：另一个JSON文本对象。可以使用字符串、数组或对象。
      • “show_item”：将要显示的物品。
        •  id：物品的命名空间物品ID。若无效则视为minecraft:air。
        •  count：可选。物品的数量。
        •  tag：可选。包含物品的NBT标签。参见player.dat格式#物品结构。
      • “show_entity”：将要显示的实体。
        •  name：可选，若未指定则隐藏本参数。将显示为实体名称的原始JSON文本对象。
        •  type：指定实体的类型。应为一个命名空间实体ID。若无效则视为minecraft:pig。
        •  id：指定实体的UUID。应为一个有效的由连字符连接的十六进制UUID。

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

解析组件

部分组件（“score”、“selector”和“nbt”）不会一直存在于对象中。这些内容会被解析：从世界中取得指定数据后将会把数据转化为文本组件，之后用这个转化后的组件替换原来的组件。解析会通过告示牌、第一次打开成书和使用命令完成。它也可以通过战利品表函数“set_name”和“set_lore”完成。在自定义名称中不会自行解析这些组件。

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

基岩版

与Java版不同，基岩版里的原始JSON文本更为简单且严格。

• 根标签。
  •  rawtext：包含所有文本对象的列表。
    • 基础聊天对象。
      •  text：在文本中直接出现的原始文本的字符串。存在 translate时忽略。
      •  selector：在文本中直接将"@a"，"@s"等选择器会被转换。
      •  translate：使用玩家所选择的语言显示的翻译识别符。此识别符与在assets文件或材质包的lang文件中所发现的识别符相同。
      •  with：包含 translate使用的聊天字符串参数的列表。在其他情况下没有效果。
        • 与当前语言中使用的参数按顺序所对应的文本（例如，列表中的第一个元素对应于translate中的“%%1”）。
      • score
        •  score：在文本中可用显示计分板中的数值。
          •  name ：可使用“@s”，“@a” 等目标选择器或假名，与 selector无关。如果为*，则会显示阅读者自己的分数（例如，/tellraw @a {"rawtext":[{"score":{"name":"*","objective":"obj"}}]}会向每个在线玩家显示他们自己在“obj”记分项的分数）。
          •  objective ：选定要显示分数的 name所在记分项的名称。

历史

Java版
1.7.2		13w37a			加入了/tellraw，原始JSON文本用于支持该命令。
1.8		14w02a			加入了文本组件insertion。
		14w07a			加入了文本组件score。
		14w20a			加入了/title，其使用原始JSON文本。
					加入了文本组件selector。
		14w25a			现在支持在告示牌和成书内使用。
1.12		17w16a			加入了文本组件keybind。
1.13		18w01a			现在支持在自定义名称内使用。
		18w05a			加入了/bossbar，参数<name>使用原始JSON文本。
1.14		18w43a			加入了文本组件nbt、block和entity。
					现在支持在物品描述标签内使用。
		18w44a			加入了文本组件interpret。
1.15		19w39a			加入了文本组件storage。
		19w41a			为clickEvent加入了copy_to_clipboard。
1.16		20w17a			加入了文本组件font。
					为hoverEvent加入了contents。value不再使用，但仍受支持。
					文本组件color现在可以使用十六进制颜色码来自定义颜色。
Java版（即将到来）
1.17		21w15a			加入了文本组件separator。
基岩版
1.9.0		1.9.0.0			加入了/tellraw，原始JSON文本用于支持该命令。
1.16.100		1.16.100.55			加入了文本组件score和selector。

参见

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

外部链接

• Tellraw命令生成器
• 键位名称一览表