v2_advanced

进阶

在 2.x 版本中，引入了大量的新概念。如果你想要制作复杂的扩展，请仔细阅读进阶篇目。

概念

拓展内容

拓展内容指资源包、扩展和工具。

（请注意区分拓展和扩展，如果有想到什么名字概括这三个也可以 issue 提醒）

描述文件

描述文件是用来描述 雀魂 Plus 2.x 拓展内容的 JSON 文件。不同类型的拓展内容有不同的内容，但是有相同的部分。相同的部分被成为元数据（Metadata）。

元数据（Metadata）

元数据的内容如下所示：

export interface Metadata {
  id: string
  version: string
  name?: string
  author?: string | string[]
  description?: string
  preview?: string
  dependencies?: { [key: string]: string }
}

可以看到，ID 和 version 是必须的，而其他的都是可选项。各项内容的说明如下表所示：

字段	格式限制	简介
id	/^[_a-zA-Z0-9]+$/	表示拓展的唯一标识符，必须和目录名保持一致。
version	semver	表示扩展的版本，需要符合 [语义化版本（semver）][semver-url] 规则
name	无	拓展名
author	无	拓展作者，多人时可用 string[] 表示
description	无	拓展的描述
preview	无	预览图片，默认为 preview.png （注：1.x 为 jpg）
dependencies	见下	描述拓展的依赖项，对于工具无效

JSON Schema

JSON Schema 是一种基于 JSON 格式定义 JSON 数据结构的规范。在雀魂 Plus 2.x 中，JSON Schema 被用于检查拓展的描述文件是否正确。

依赖

在雀魂 Plus 2.x 中，资源包和扩展可以选择其前置资源包和扩展，即依赖项。存在依赖项后，资源包/扩展会在依赖项之后加载。

加载顺序

根据依赖项选择的顺序，雀魂 Plus 2.x 会顺序加载对应内容。如果遇到冲突的问题，后加载的会覆盖先加载的。

拓展的检查顺序

下面简单介绍拓展加载前的检查顺序：

1. 检查 ID 是否符合 /^[_a-zA-Z0-9]+$/
2. 检查目录及对于描述文件的存在性
3. 检查 ID 与目录名称的一致性
4. 检查 ID 的唯一性（此步骤疑似多余，后续可能移除）
5. 对描述文件进行 JSON Schema
6. 对描述文件的版本（version）进行语义化版本格式检查
7. 对各依赖的版本进行语义化版本格式检查

需要注意的是，上述检查只要有一项不通过，就不会显示在雀魂 Plus 的管理器（Manager）界面中。

可以通过设置环境变量 NODE_ENV=development 在控制台看到输出的日志信息

TODO: 在加载错误的目录下生成日志文件

加载文件

加载文件是指拓展目录下的 active.json。这个文件记录了加载的顺序，因此不建议手动更改。