ab30b28f3d
common: - 新增 autoInit.ts 自动初始化（对齐 Android ContentProvider 模式） - 新增 configCrypto.ts 内置配置文件解密 - XuqmSDK 新增 initWithConfigFile / setUserInfo / getUserInfo - 新增 crypto-types.d.ts Web Crypto 类型声明 update: - 重写 UpdateSDK：checkAppUpdate / checkPluginUpdate / checkAndCachePlugin - 移除 checkAndPromptAppUpdate（SDK 不做 UI） - 新增插件脚手架 create-plugin.mjs - 重命名 RnUpdateInfo → PluginUpdateInfo license: - crypto.ts 支持 XUQM-CONFIG-V1 + XUQM-LICENSE-V1 双格式 - 新增 decryptConfigFile 导出 docs: - 重写 README.md - 新增 docs/SDK-API参考.md - 新增 docs/插件脚手架.md - 新增 docs/配置文件规范.md
165 行
4.4 KiB
Markdown
165 行
4.4 KiB
Markdown
# 插件脚手架工具
|
||
|
||
> 脚本位置：`packages/update/scripts/create-plugin.mjs`
|
||
> 最后更新：2026-06-15
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
`create-plugin.mjs` 是 UpdateSDK 提供的插件脚手架工具，用于一键创建完整的插件骨架项目。
|
||
|
||
**功能**：
|
||
|
||
- 交互式或命令行输入插件参数
|
||
- 校验 moduleId 唯一性
|
||
- 自动生成插件文件（bundle.ts / Screen / plugin.json）
|
||
- 自动注册到宿主（pluginCatalog / debugPlugins / build scripts / metro config / babel alias / tsconfig）
|
||
|
||
---
|
||
|
||
## 用法
|
||
|
||
### 命令行模式（推荐）
|
||
|
||
```bash
|
||
node scripts/create-plugin.mjs <moduleId> [title] [subtitle] [accentColor]
|
||
```
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 完整参数
|
||
node scripts/create-plugin.mjs buz4 "IM 消息" "即时通讯业务组件" "#E74C3C"
|
||
|
||
# 最简（title/subtitle/accentColor 使用默认值）
|
||
node scripts/create-plugin.mjs buz5
|
||
```
|
||
|
||
### 交互模式
|
||
|
||
```bash
|
||
node scripts/create-plugin.mjs
|
||
```
|
||
|
||
按提示依次输入 moduleId、title、subtitle、accentColor。
|
||
|
||
---
|
||
|
||
## 参数说明
|
||
|
||
| 参数 | 必填 | 格式 | 默认值 | 说明 |
|
||
| ----------- | ---- | ------------------ | ----------------- | ----------------------- |
|
||
| moduleId | ✅ | `^[a-z][a-z0-9]*$` | — | 插件唯一标识，如 `buz4` |
|
||
| title | ❌ | 任意文本 | = moduleId | 插件标题 |
|
||
| subtitle | ❌ | 任意文本 | `{title}业务组件` | 插件副标题 |
|
||
| accentColor | ❌ | CSS 颜色值 | `#0E84FA` | 主题色 |
|
||
|
||
---
|
||
|
||
## 自动生成的文件
|
||
|
||
### 插件目录 `src/plugins/{moduleId}/`
|
||
|
||
#### `bundle.ts` — 入口文件
|
||
|
||
```typescript
|
||
import { UpdateSDK } from "@xuqm/rn-update";
|
||
import { registerPluginFromBridge } from "@plugins/runtimeBridge";
|
||
import { Buz4Screen } from "@buz4/Buz4Screen";
|
||
|
||
// 自动注册插件版本（bundle 加载时执行）
|
||
UpdateSDK.registerPlugin({ moduleId: "buz4", version: "1.0.0" });
|
||
|
||
// 注册 UI 组件到宿主运行时
|
||
registerPluginFromBridge({
|
||
id: "buz4",
|
||
title: "IM 消息",
|
||
subtitle: "即时通讯业务组件",
|
||
accentColor: "#E74C3C",
|
||
Component: Buz4Screen,
|
||
});
|
||
```
|
||
|
||
#### `{ModuleId}Screen.tsx` — Screen 骨架
|
||
|
||
```typescript
|
||
import { StyleSheet, Text, View } from 'react-native';
|
||
|
||
export function Buz4Screen() {
|
||
return (
|
||
<View style={styles.container}>
|
||
<Text style={styles.title}>buz4</Text>
|
||
<Text style={styles.subtitle}>TODO: 实现buz4功能</Text>
|
||
</View>
|
||
);
|
||
}
|
||
```
|
||
|
||
#### `plugin.json` — 插件元数据
|
||
|
||
```json
|
||
{ "moduleId": "buz4", "version": "1.0.0" }
|
||
```
|
||
|
||
---
|
||
|
||
## 自动更新的宿主文件
|
||
|
||
| 文件 | 变更内容 |
|
||
| ------------------------------- | --------------------------------------------------------------- |
|
||
| `src/app/pluginCatalog.ts` | 添加插件目录条目（id/title/summary/accentColor） |
|
||
| `src/bootstrap/debugPlugins.ts` | 注册 debug loader（`require('../plugins/{id}/bundle')`） |
|
||
| `package.json` | 添加 `build:android:{id}` / `build:ios:{id}` 脚本，更新聚合脚本 |
|
||
| `metro.split.config.js` | 添加 moduleId 的 offset 分支 |
|
||
| `babel.config.js` | 添加 `@{id}` alias |
|
||
| `tsconfig.json` | 添加 `@{id}/*` path mapping |
|
||
|
||
---
|
||
|
||
## 唯一性校验
|
||
|
||
脚本会检查两处来确保 moduleId 唯一：
|
||
|
||
1. `src/app/pluginCatalog.ts` 中已注册的 id
|
||
2. `src/plugins/` 目录下已存在的目录名
|
||
|
||
如果 moduleId 已存在，脚本会报错并退出：
|
||
|
||
```
|
||
❌ moduleId "buz4" 已存在，请使用其他 ID
|
||
```
|
||
|
||
---
|
||
|
||
## moduleId 命名规范
|
||
|
||
- 必须以**小写字母**开头
|
||
- 只能包含**小写字母和数字**
|
||
- 推荐格式：`buz{N}`（如 `buz4`、`buz5`）
|
||
|
||
Metro module ID offset 自动计算：`buz1` → 11M，`buz2` → 12M，`buzN` → (10+N)M。
|
||
|
||
---
|
||
|
||
## 创建后的开发流程
|
||
|
||
```bash
|
||
# 1. 生成插件骨架
|
||
node scripts/create-plugin.mjs buz4 "IM 消息" "即时通讯业务组件" "#E74C3C"
|
||
|
||
# 2. 实现业务 UI
|
||
# 编辑 src/plugins/buz4/Buz4Screen.tsx
|
||
|
||
# 3. 创建子目录
|
||
mkdir -p src/plugins/buz4/services
|
||
mkdir -p src/plugins/buz4/pages
|
||
|
||
# 4. 验证
|
||
yarn validate
|
||
|
||
# 5. 构建
|
||
yarn build:android:buz4
|
||
yarn build:ios:buz4
|
||
```
|
