Skip to content

Latest commit

 

History

History
79 lines (52 loc) · 3.39 KB

v2_advanced.md

File metadata and controls

79 lines (52 loc) · 3.39 KB

进阶

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.xjpg
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。这个文件记录了加载的顺序,因此不建议手动更改。