toc文件頭格式註釋

從這裏開始，我們將一起學習魔獸世界插件(Addons)的知識，這是一門很有趣的學科。只要你玩WoW就不可能沒用過插件，檢查一下你的WoW安裝目錄下的Interface/Addons/文件夾，插件並非第三方專有，暴雪同樣需要這玩意，只不過和凡人玩的有所區別。

　　關於插件的基本概念，在之前的文章我已經做了解釋，今天着重介紹.toc。WoW的插件由3個文件組成，分別是.toc、.xml和.lua。.toc中標註了關於插件信息的定義，以及需要加載的.xml的位置。.xml是插件的核心，包括界面、功能等元素都在其內。lua是一種嵌入式腳本語言，在WoW中實現.xml調用的函數。換句話說，.toc告訴WoW插件的名字和.xml的位置，.xml告訴WoW插件都有什麼，怎樣工作，具體事宜則交由.lua來處理。

　　今天講解.toc的結構和寫法，TOC全稱爲Table of Contents，就是目錄的意思。

　　.toc的位置在World of Warcraft/Interface/AddOns/MyAddon/MyAddon.toc。其中紅色部分爲你的插件名稱，必須保證完全一致，包括大小寫。Windows系統不區分大小寫，但WoW客戶端區分(case-sensitive)，在開發過程中一定要注意。WoW只能讀取1024字節/行，富裕出的部分將被忽略並且不報錯。

　　客戶端識別標籤(Client Recognized Tags):

　　Interface:

　　格式:##Interface:11200

　　所有標籤都要以"##"開頭，到行尾結束，這裏Interface表示插件對應的遊戲客戶端的版本號，也就是我這個插件是爲哪個版本的WoW開發的。紅色部分11200就表示我這個插件適用於1.12。如果插件的Interface號和當前遊戲客戶端版本號不一致，那麼遊戲默認不會加載插件，這也就是爲什麼遊戲一升級，好多插件就不能用了的原因，但你可以在插件管理面板中手動加載"過期插件"，這樣遊戲就會忽略Interface，最好的辦法還是儘快升級插件到新的版本以避免不必要的麻煩。

　　獲取當前客戶端版本號有點麻煩，你當然可以啓動遊戲然後看看屏幕上顯示的一串數字，但那個是錯誤的。WoW的每次更新會寫一個版本號在FrameXML.toc裏，但這個文件被埋在一個MPQ中。暴雪爲此專門提供了一個工具http://ftp.blizzard.com/pub/WoW/other/InterfaceAdd OnKit_Win.zip類似一個解壓縮工具，用這東西打開World of Warcraft/Data/patch.mpq，文件較大可能需要需要一點時間。打開之後你會看到一個列表，找到Interface/FrameXML/FrameXML.toc，雙擊然後用隨便什麼文本編輯器打開就可以看到版本號了。

　　Title:

　　格式: ##Title: My Addon

　　##Title-zhCN: 我的插件

　　Title表示插件的名稱，也就是插件管理面板裏顯示的那個。支持多語言定義，默認爲英語。其他語言要在Title後面加上後綴，就像上面那樣。zhCN表示簡體中文，zhTW就是臺灣的繁體中文。前面2個小寫是語言，後面2個大寫是國家和地區。

　　還有個好玩的東西就是顏色，WoW支持字串形式的顏色定義。插件面板默認字體顏色是黃，你可以根據自己的喜好自行定義文本顏色，這裏就用到顏色字串。顏色字串以"|c"開頭"|r"結束。中間是16進制αRGB顏色代碼和要顯示的文本。比如我要將"我的插件"幾個字顯示爲藍色。那麼就應該是:

　　##Title: |cff0000ff我的插件|r

　　其中|c表示接下來的8位字符是顏色代碼，以α(alpha透明度)、R(紅)、G(綠)、B(藍)順序排列。前面2位ff表示被着色的文本完全不透明，但需要指出的是並非所有的地方都支持透明。之後就是着色的文本了，這裏就是"我的插件"，|r表示顏色結束，如果沒有結束標記，那麼WoW將顏色代碼以後到這一行結束的全部文本都進行着色。

　　值得一提的是，這個顏色字串應用相當廣泛，包括人物ID也可以，這也是爲什麼暴雪禁止使用符號和數字以及英文漢字混合的原因了，當然也是考慮到搜索的方便。

　　Note:

　　格式:## Notes: This is my first AddOn.

　　## Notes-zhCN: 這是我的第一個插件。

　　只有Title和Notes標籤支持其他語言，除此之外都要用英語書寫。Notes包含插件的說明內容，就是對插件功能的簡單描述，將出現在插件管理面板中鼠標經過的地方。

　　RequiredDeps:

　　格式:## Dependencies: someAddOn, someOtherAddOn

　　## RequiredDeps: someAddOn, someOtherAddOn

　　Depend是依賴的意思。爲了讓插件更好地工作，某些插件開發者會使用第三方庫或其他現成的插件作爲基礎和輔助，這麼做的有點就是節約了開發成本，也使開發過程簡便了許多，不足的地方就是，要讓插件正常工作，系統必須確保所依賴的文件都要存在，否則，如果任何依賴的庫或插件缺失，當前插件加載都會失敗。依賴的名稱即依賴插件的名稱，也就是目錄文件夾的名稱。如果需要依賴多個庫或插件，彼此用逗號","隔開。注意大小寫一致。

　　注: Dependencies、RequiredDeps、Dependancies[sic]結果是一樣的。

　　OptionalDeps:

　　格式:## OptionalDeps: someAddOn, someOtherAddOn

　　可選依賴是當前插件爲了實現某些附加功能而依賴的外部庫或插件，但如果依賴的東西不存在，那麼當前插件也可以正常工作，但是使用可選依賴的插件必須寫明當依賴不存在的時候也可以工作。

　　LoadOnDemand:

　　格式:## LoadOnDemand: 1

　　## LoadOnDemand: 0

　　從1.7開始，插件可以用命令來加載，而不用非得在用戶第一次登錄的時候加載。如果啓用這一功能，此插件則必須在未來某個時候被另一個插件加載。這是爲了避免加載一些特殊的不常用的插件而導致內存資源佔用，非常有效。副魔助手(Enchantrix)就用到了這一特性。

　　LoadWith:

　　格式:## LoadWith: someAddOn, someOtherAddOn

　　1.9新加的。和LoadOnDemand一起用，這使你的插件跟隨某個插件一起被加載(通常是暴雪的UI模塊，像Blizzard_AuctionUI)。

　　SavedVariables:

　　格式:## SavedVariables: someVariable, someOtherVariable

　　從Interface版本2150開始有的，保存的變量是當前流行的存儲不同人物角色的方式。這些變量在客戶端啓動或UI重載(reload)時被載入。SavedVariables標籤現以取代RegisterForSave函數，後者已經不再受客戶端支持。注意在OnLoad事件過程中，SavedVariables並未完全加載所以必須假設包含nil(空)值直到以插件文件名爲參數的ADDON_LOADED事件被觸發。

　　這比以前那個爲保存註冊變量的腳本強的多，因爲即便你的插件被禁用或因爲錯誤、版本不匹配等問題沒有加載，SavedVariables依然會被保存。

　　SavedVariablesPerCharacter:

　　格式:## SavedVariablesPerCharacter: somePercharVariable

　　這個標籤和SavedVariables工作方式一樣，只不過是給予每個角色創建的。以前這個標籤只能用角色名來區分不同的角色，現在可以根據服務器和角色名一起來區分了。

　　DefaultState:

　　格式:## DefaultState: enabled

　　## DefaultState: disabled

　　這裏的enabled/disabled狀態被寫在WTF/Account/{youraccount}/AddOns.txt裏，紅色部分是你的帳號名。並且這個文件會覆蓋的DisabledAddOns.txt，後者爲了保持兼容仍然會被老版本的加載。

　　Secure:

　　格式:## Secure: 1

　　這個標籤被添加到Blizzard_UI(1.11中作爲默認UI一部分)。它的確切目的無從知曉，但一個可能就是它告訴客戶端是否要爲插件尋找一個簽名。

　　非標準標籤:

　　用##標示還可以添加更多額外的信息，某些第三方插件甚至使用自行提供的信息。下面是一些常用的標籤:

　　插件元數據標籤:

　　這些標籤和Title、Notes放在一起，並可用GetAddOnMetadata("addon", "field")來調用。

　　Author:

　　格式:## Author: MyName

　　作者的名字，也可以是Email地址。

　　Version:

　　格式:## Version: 1.0

　　插件的版本號。可以是任何字符串，因爲自動更新的工具會解析數字，所以最好是以數字版本開頭。

　　X-<data>:

　　格式:## X-email: [email protected]

　　## X-Foo: I love pancakes

　　## X-Foo-zhCN:我愛煎餅

　　任何以X-開頭的標籤。

　　Ace2注視標籤:

　　和Ace不一樣，Ace2直接從TOC文件提取插件元數據，特定的域(field)進行特定的處理，即Version和X-Date，那麼你就可以用CVS和Subversion關鍵字例如$Rev$作爲它們的值。

　　除了正經域以外，它還可以尋找下列自定義的域。

　　X-Date:

　　格式:## X-Date: 12-06-2007

　　插件的發佈日期。

　　X-eMail

　　插件的網站。

　　X-Category:

　　格式:## X-Category: Raid

　　插件的Ace2目錄。

　　此目錄在AceAddon.lua中聲明。

　　local CATEGORIES = {

　　["Action Bars"] = "Action Bars",

　　["Auction"] = "Auction",

　　["Audio"] = "Audio",

　　["Battlegrounds/PvP"] = "Battlegrounds/PvP",

　　["Buffs"] = "Buffs",

　　["Chat/Communication"] = "Chat/Communication",

　　["Druid"] = "Druid",

　　["Hunter"] = "Hunter",

　　["Mage"] = "Mage",

　　["Paladin"] = "Paladin",

　　["Priest"] = "Priest",

　　["Rogue"] = "Rogue",

　　["Shaman"] = "Shaman",

　　["Warlock"] = "Warlock",

　　["Warrior"] = "Warrior",

　　["Healer"] = "Healer",

　　["Tank"] = "Tank",

　　["Caster"] = "Caster",

　　["Combat"] = "Combat",

　　["Compilations"] = "Compilations",

　　["Data Export"] = "Data Export",

　　["Development Tools "] = "Development Tools ",

　　["Guild"] = "Guild",

　　["Frame Modification"] = "Frame Modification",

　　["Interface Enhancements"] = "Interface Enhancements",

　　["Inventory"] = "Inventory",

　　["Library"] = "Library",

　　["Map"] = "Map",

　　["Mail"] = "Mail",

　　["Miscellaneous"] = "Miscellaneous",

　　["Quest"] = "Quest",

　　["Raid"] = "Raid",

　　["Tradeskill"] = "Tradeskill",

　　["UnitFrame"] = "UnitFrame",

　　}

　　其他注視標籤:

　　Email:

　　格式:## eMail: [email protected]

　　插件作者Email地址。