完善拓展模块的元信息

AutumnBox

# 开始

在前面的章节中，我们大概了解到秋之盒模块的名字应当class上的特性(Attribute)来声明模块的元信息(Metadata)：

[ExtName("Hello world!")]
class EHelloAutumnBox : LeafExtensionBase{
    //.....
}

在运行时，秋之盒会通过反射技术获取拓展模块特性中的元信息。

# 先导知识: I18N

在开始学习更多知识前，首先了解一下秋之盒中常见的多语言化方法，例如：

ExtName("Happy","zh-cn:开心","zh-tw:開心")

上面的代码中表明了：秋之盒使用简体中文语言时，该拓展模块名为开心，台湾繁体中文时为開心，如果不是以上两种语言，则使用首个参数作为默认值：Happy。
当然，你可以可以选择不使用这个玩法：

//无论如何,都只会是"你好"
[ExtName("你好")]

# 主要的特性

秋之盒SDK还提供了许多预置特性以及一些新的可拓展逻辑供你更好地个性化模块信息。

主要的特性均位于源码中的此目录中(在Github浏览) (opens new window)。命名空间是AutumnBox.OpenFramework.Extension。
EmptyExtension (opens new window)包含了默认的特性，建议拓展模块可以继承于其。

# ExtName

支持I18N，接收String类型的变长参数，用于表达拓展模块的人类可读名字。

[ExtName("Example Extension","zh-cn:示例拓展模块")]

# ExtRequiredDeviceStates

接收DeviceState (opens new window)作为参数，用于表明拓展模块运行所必须的设备状态，秋之盒将确保模块不会在设备不满足条件的情况下被用户启动。

[ExtRequiredDeviceStates(DeviceState.Poweron)]

扩展用法

如果想要表明拓展模块运行与设备状态无关(甚至是没有插入设备)，请传入AutumnBoxExtension.NoMatter (opens new window)。如果不插入设备不可以的话，则请传入该类中的AllState常量。
想要支持多个状态，可以使用或运算符。(可以观察到DeviceState (opens new window)中的值支持这样的操作)

[ExtRequiredDeviceStates(DeviceState.Poweron | DeviceState.Recovery)]

# ExtAuth (opens new window)

支持I18N，传入一个变长String以表示拓展模块所有者信息。

[ExtAuth("Seymour Zhang","zh-cn:张三"]

# ExtDesc (opens new window)

支持I18N，传入一个变长String以表示拓展模块的简单解释信息。

[ExtDesc("此模块与地球三体组织无关","en-us:This extension have nothing to do with ETO")]

# ExtDeveloperMode (opens new window)

传入布尔值表示该模块是否开启开发者模式。如果是,则该拓展模块只会在秋之盒设置中开启调试模式后才会显示。

[ExtDeveloperMode] //Default value is true

# ExtHidden (opens new window)

传入布尔值表示该模块是否被隐藏。如果隐藏，则用户将无法直接启动该模块，即便开启调试模式。

[ExtHidden] //Default value is true

# ExtIcon (opens new window)

表示一个拓展模块的图标。目前提供两种方式。
第一种方式，嵌入资源：直接传入图标的在项目中的绝对路径即可。例如：使用这个位置的图标的代码是：

[ExtIcon("Icons.android.png")]

图标文件一定要调整为"嵌入的资源"

第二种方式,base64字符串。声明你的方式，并将图标的base64字符串传入。

[ExtIcon("THE BASE64 STRING OF THE ICON",SourceType =ExtIconAttribute.IconSourceType.Base64Image)]

# ExtRequireRoot (opens new window)

传入布尔值，表明此模块需要设备获取ROOT才能够运行。秋之盒也会在显眼的位置标明该模块需要ROOT权限。

考虑到ROOT检测的复杂情况，秋之盒不会阻止可能没有ROOT的设备执行拓展模块，如有需要，请开发者另行测试，或贡献相关代码 (opens new window)。

# ExtRegions (opens new window)

传入String类型变长参数，表明一个可运行语言地区白名单。

[ExtRegions("zh-cn","zh-tw","en-us")]

不挂此特性则默认无地区限制。

# ExtVersion (opens new window)

传入一个至三个整型数字，表明拓展模块的版本信息。

[ExtVersion(2,1,9)]
//[ExtVersion(1,1)]
//[ExtVersion(2)]

# ExtRunnablePolicy (opens new window)

一个抽象类，开发者可继承并实现该抽象类以创建自定义的运行检测策略，用于限制模块可否被用户运行。

事实上，继承自EmptyExtension (opens new window)的拓展模块默认包含了一个基础的运行检测策略：ExtNormalRunnablePolicy (opens new window)，这个默认策略确保了拓展模块只会在设备状态正确时被启动。

此外，还有一些策略由于各种原因，暂且不在此处进行介绍，如果需要请阅读相关源码 (opens new window)注释。

# 获取拓展模块本身的信息

我们可以通过LeafExtensionBase.GetExtensionInfo() (opens new window)方法获取到拓展模块所有元信息。然后使用ExtensionInfoExtension (opens new window)中提供了一系列拓展方法帮助我们获取更加特定的值。

//...
[ExtName("Test","zh-cn:测试")]
class ETest{
    [LMain]
    void Main(){
        var extInf = this.GetExtensionInfo();
        var extName = extInf.Name(); //Test 或 测试 取决于具体的语言环境
        var reqState = extInf.RequiredDeviceState();
    }
}
//....

# 自定义的元信息

你可以继承自ExtensionInfoAttribute (opens new window)或ExtensionI18NTextInfoAttribute (opens new window)实现你自己的元信息。

# 获取自定义的元信息

获取到ExtensionInfo后，获取对应键的值即可。

//...
void Main(){
    var extInf = this.GetExtensionInfo();
    var value = extInf["CustomKey"]();//直接获取到的是`ValueReader`函数指针，需要再次执行才能获取到真正的值
}
//...

事实上，秋之盒开放框架里大部分内置的特性都是这个原理。

更多内容，请阅读相关源码 (opens new window)。

快速开始【非常重要】获取基础API的通用之道