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: [e-mail]

　　## 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: [e-mail]

　　插件作者Email地址。