# 插件完整目录结构解析

# 目录结构

插件的目录结构：

前面简单的介绍了脚手架生成的插件目录, 这个章节会详细介绍里面每个属性的作用

. (插件根目录)
├── ext.ucdext (插件压缩文件, 里面包括了 main.js, manifest.json, logo.svg 等文件)
├── manifest.json (清单文件)
├── main.js (插件入口)
├── logo.svg (插件图标)

ext.ucdext 最终 uCode 需要导入的插件格式, 里面包含了 manifest.json, logo.svg, main.js 所有文件

WARNING

下面这些文件只是一个副本, 更改它们, 不会导致插件的变更

manifest.json 插件清单文件
main.js 程序入口文件，该文件名可以随意修改，但是要在 manifest.json 中 entry 字段定义
logo.svg 插件图标，该文件名可以随意修改，但是要在 manifest.json 中 icon 字段定义

# Manifest 清单文件

Manifest 是 uCode 定义一个插件的入口，也就是 uCode 会根据 Manifest 的数据，区分这是一个什么插件，支持什么功能，什么版本等等，下面的字段会随着 uCode 的开放标准更新

字段	必填	类型	默认值	描述
id	✅	string		插件唯一标识码, 支持 32 位和 37 位的标准 (32 位不带横杠符号`-`)
version	✅	string		插件版本号，要符合 Semver 语义化版本 2.0 规范 (opens new window)
type	✅	string		插件的类型，硬件是: hardware, 软件是: software ，全部都是小写
name	✅	string		显示用的插件名字，支持翻译，可以是任意字符串
supportModes	✅	string[]		插件支持的模式, 'online' 是在线模式, 'upload' 是烧录模式, ["online","upload"]
USV	✅	string		USV 版本号, 必填, 用于 uCode 判断开放标准的版本号, 后面会详细说明
entry		string	main.js	插件入口文件名字，支持相对文件路径，暂时只支持当前目录下，区分大小写
icon		string		插件图标名字，支持相对文件路径，暂时只支持当前目录下，区分大小写，如果找不到会分配系统默认图标，支持 svg, png, jpg
author		string		插件作者名字，可以是任意字符
description		string		插件简要描述，可选，支持翻译，支持任意字符串
readme		string		插件的详细描述，支持外链 url，支持 markdown 语法

下面是一个 manifest.json 的模板

{
  "id": "ec7e6c47-df66-4fcd-bf59-1d535cfc17a6",
  "version": "0.0.1",
  "name": "我的插件",
  "type": "hardware",
  "supportModes": ["online"],
  "description": "这是一个demo",
  "icon": "logo.svg",
  "entry": "main.js",
  "author": "你的名字",
  "readme": "这是一个测试",
  "USV": "0.3.0"
}

# 插件唯一标识 id

uCode v4 使用 UUID (维基百科 (opens new window) 百度百科 (opens new window))作为插件的唯一标识 ID，uCode 会验证插件的 ID 是否合法，如果不合法会报错，并且会校验插件的 ID 是否是唯一，如果有和当前的插件重复也会报错。

插件在创建的时候，例如使用: 内置插件模板 和 脚手架 都会自动生成一个 UUID

案例 ID	是否符合	说明
ec7e6c47-df66-4fcd-bf59-1d535cfc17a6	✅	带 - 符号 37 位
ec7e6c47df664fcdbf591d535cfc17a6	✅	不带 - 符号 32 位
foo.bar	❌	不符合 UUID 规范

唯一性

插件需要发布到我们的应用商城的时候，服务器会再一次做二次校验，一旦发布成功，插件的 ID 不能再修改

本地的开发插件，也是具有唯一性，一旦有 ucd 作品引用了该插件，插件 ID 无法更改

手动生成 UUID

如果你想手动生成生成 UUID ，在前端上可以使用 Crypto.randomUUID()

要求环境：Chrome >= 92 或者 Node.js >= 16.7.0

详细可以参照 randomUUID (opens new window)

# USV

USV 全称 uCode Standard Version, 中文 uCode 开放能力标准版本号

每个 USV 对应的开放能力的标准不一样
USV 符合 Semver 语义化版本 2.0 规范 (opens new window)
USV 第一个版本号是大版本号 (Major Version), 一般插件无法兼容
USV 第二版本号, 是迭代版本号 (Minor Version), 向下兼容, 但不向上兼容
兼容策略向下兼容, 向上不一定兼容

例如: USV 1.0 的插件, 在 USV 1.0 - 1.x 的范围的 uCode 都兼容但是 USV 1.1 的插件, USV 1.0 的 uCode 不一定兼容因为迭代版本, 会增加新功能, 新版本的插件用到了一些新的能力, 在旧版本的 uCode 上无法使用
USV 第三个版本号, 是修复版本号 (BugFix/HotFix Version), 细微的修改, 上下都兼容
最新的脚手架创建的项目都会默认标记为最新的 USV
建议插件重新编译和发版, 与最新的 USV 绑定(就是同步更新版本), 除非能确认没有用到最新的 USV 的新能力

# 插件图标

插件图标目前支持的格式:

格式	大小	说明
svg	无要求	推荐使用
png	256x256	注意背景透明在某些场景会有问题
jpg	256x256	无特别说明
gif	256x256	不建议使用
ico	256x256	无特别说明

我们优先推荐使用矢量图的 svg，如果要使用 png 和 jpg 的话，大小在 256x256 左右的分辨率大小，太小的分辨率在某些平台上，可能会有失真

我们目前支持三种形式的数据：

文件名 (只支持当前目录，子目录和目录外均不支持)

在 manifest.json 你可以使用当前目录下的文件

案例	是否符合	说明
./logo.svg	❌	带有路径`./`
logo.svg	✅	不带有路径
foo/bar.svg	❌	不能含有子目录名

Base64 编码

虽然叫 Base64 编码，但实际上只支持是 Data URLs (opens new window) 的数据格式

案例	是否符合	说明
data:image/gif;base64,R0lGODl.....	✅	前面有描述 data 格式
R0lGODl.....	❌	前面没有描述 data 格式

URL

我们支持 URL 链接，但由于链接有非常多不标准的使用，我们只支持标准的 URL，可以参照 RFC3986 (opens new window)

案例	是否符合	说明
www.foo.com/bar.png	❌	前面没有协议
/bar.png	❌	不是合法的 url
ftp://foo/bar	❌	只支持 http 和 https
http://foo.com/bar.png	✅	合法的 url
http://foo/bar.png	✅	合法的 url
http://foo/bar	✅	合法的 url
https://foo/bar	✅	合法的 url

← ESP32 插件程序入口 →