Repository navigation
Controller Panel zh TW
English | 繁體中文
本頁說明正在播放控制面板：它是什麼、如何用 /controller 編輯它的版面，以及它所理解的確切樣板語法。
控制面板是機器人在播放音樂時，於音樂文字頻道中張貼（並持續更新）的嵌入訊息。它會顯示目前的曲目， 以及一排大家實際會用到的操作按鈕——暫停、跳過、音量、重複播放等等——讓大部分的播放控制都不需要 再輸入斜線指令。這是機器人 Vocard 風格介面的一部分：它是依伺服器各自渲染、由資料驅動的版面， 而不是固定不變的嵌入訊息。
面板是否顯示按鈕、以及使用完整版面還是精簡版面，是由 /npbuttons 與 /nplayout 設定的（見
Commands-zh-TW）。本頁討論的是版面本身——也就是面板裡面放了什麼內容。
/controller 會開啟目前伺服器面板版面的編輯器。這是一個僅限 Admin（管理員）使用的指令
（機器人擁有者，或擁有 MANAGE_SERVER 權限的成員——見 Permissions-and-Server-Settings-zh-TW）。
你在這裡設定的版面只套用於這個伺服器；在 Discord 內部並沒有全域的版面覆寫設定。
一個版面就是一個小型樣板：主要由字面文字與嵌入訊息結構組成，並搭配三種在渲染時會被替換的 預留位置。由於這套樣板語法的設計是為了對應 Vocard 的語法，因此可以直接貼上一個既有的 Vocard 版面，它在這裡的渲染結果會相同。
| 語法 | 意義 |
|---|---|
{{ cond ?? yes // no }} |
條件式區塊 |
@@t_some.key@@ |
從語言檔解析出的翻譯文字 |
@@variable@@ |
被替換的數值 |
求值順序是固定的：先解析條件式，接著解析翻譯，最後才解析變數。因此，一個條件式可以在兩個區塊之間 擇一，而這兩個區塊各自可以包含自己的翻譯鍵或變數，這些內容會在條件式決定之後才被填入。
這是最容易讓人踩雷的部分。渲染器只會辨識剛好四個 @@variable@@ 預留位置：
| 變數 | 數值 |
|---|---|
@@volume@@ |
目前音量 |
@@queue_length@@ |
佇列中的曲目數量 |
@@loop_mode@@ |
重複模式的易讀名稱，或 Off
|
@@track_name@@ |
目前曲目標題，或 None
|
沒有第五個。像 artist、duration、requester、thumbnail 這類名稱，不論看起來與上面四個
有多相似、多合理，在這裡都不是真正存在的變數——把它們包在 @@...@@ 標記裡並不會讓它們生效。
參照任何不在這張表裡的名稱不會產生錯誤，也不會有任何警告：它只會原地悄悄地被渲染成空字串。
如果一個版面看起來有問題——某個原本該有數值的地方變成空白行，或句子中間出現一個缺口——第一件該
檢查的事，就是它是不是參照了這份清單以外的變數。
共有十種按鈕動作：
previous、pause、skip、stop、shuffle、repeat、favorite、volup、voldown、back
共有四種按鈕樣式（在 Discord 按鈕樣式意義下的顏色）：
red、green、blue、grey（gray 也是最後一種顏色的可接受拼法）
十種動作中有四種並非靜態的——它們會依目前的播放器狀態改變外觀：
-
pause——反映目前是正在播放還是已暫停 -
repeat——反映目前的重複模式 -
favorite——反映目前曲目是否已加入最愛 -
stop——有一個獨立的按下／確認狀態
其餘六種動作（previous、skip、shuffle、volup、voldown、back）在任何狀態下都會以相同
方式渲染。對版面設計來說，這主要影響 pause 與 repeat：不論你為按鈕設定的標籤或表情符號是什麼，
每個狀態下顯示的都會是同一個標籤或表情符號，但按鈕實際渲染出的樣式／狀態指示仍會反映底層的模型
狀態，所以測試一個版面時，必須在不只一種播放器狀態下檢查它——例如暫停時與播放時都要檢查——而不是
只在儲存的那一刻檢查一次。
一個只顯示曲目名稱，以及暫停／跳過／停止按鈕列，完全沒有任何條件式邏輯的版面：
Now playing: @@track_name@@
Queue: @@queue_length@@ track(s)
按鈕：pause（grey）、skip（grey）、stop（red）
這會渲染成一個單純的兩行嵌入訊息內文——字面文字 Now playing: 後面接著 @@track_name@@ 解析
出的內容（若目前沒有播放中的內容則是 None），下一行則是佇列數量——底下再加上三個按鈕。這裡沒有
任何分支邏輯，所以除了被替換的數值本身之外，每種狀態下看起來都一樣。
{{ queue_length ?? @@t_player.queued@@ // @@t_player.empty@@ }}
這會依 queue_length 是否非零（真值）在兩段翻譯字串之間擇一：如果佇列中有曲目，會渲染
player.queued 這個位置的翻譯；如果佇列是空的，則會改為渲染 player.empty 這個位置的翻譯。
由於翻譯是在條件式之後才解析，所以每個分支都可以帶有各自的語言檔鍵值，而沒有被選中的那個分支
永遠不會被查詢。一個分支並不限於只能放一個翻譯——@@queue_length@@ 或其他變數也可以與
@@t_...@@ 文字一起出現在 // 任一側，因為條件式、翻譯與變數是分別以獨立的處理階段，套用在
最終被選中的文字上。
/controller、/npbuttons、/nplayout 的語法請見 Commands-zh-TW。誰能執行 /controller
請見 Permissions-and-Server-Settings-zh-TW。讓機器人先跑起來的方法請見
Getting-Started-zh-TW。若版面渲染出空白內容、或按鈕看起來沒有作用，請見
Troubleshooting-zh-TW。