原始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`。

參見[]

備註[]

↑ 請注意，之後的組件將視為第一個組件的子組件，因此第一個組件的格式和互動事件將應用於之後的組件。例如，[{"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的順序檢查。若提供了多個標籤，則會使用此列表中最靠前的標籤。