Such 插件开发文档
Such Music 插件系统开发完整指南
Such 插件开发文档
简介
Such 插件系统允许开发者使用 JavaScript / TypeScript 编写自定义插件，为 Such Music 音乐播放器扩展功能。插件运行时基于 CeruPlugins 引擎，采用 window.source 注入模式，开发者只需编写一个 .ts 或 .js 文件即可完成插件注册与功能实现。
插件分类
Such 插件按形态分为三类，可自由组合：
| 类型 | 说明 | 典型场景 |
|---|---|---|
| 功能插件 | 提供功能性扩展，如格式转换、文件解析、数据处理 | NCM 文件解析、音频格式转换 |
| JSON UI Schema 插件 | 通过声明式 JSON Schema 定义界面，由宿主自动渲染 | 配置面板、状态监控、歌单导入 |
| JSX UI 插件 | 通过 render 方法返回 JSX 元素自定义界面 | 复杂可视化面板、自定义播放器 |
ℹ️ 三种类型可叠加。例如一个插件可以同时是「功能插件 + JSON UI Schema 插件」。
核心特性
- 零依赖注册：通过
window.source赋值即可注册，无需module.exports - 沙箱隔离：插件代码在受限作用域中执行，无法访问 Node.js API 和 Electron API
- 权限系统：5 种权限类型 (
local_program/file_system/fetch/app_info/playlist)，按需声明 - 敏感操作确认：涉及本地系统的操作每次执行前需要用户确认，支持批量合并
- JSON UI Schema：声明式定义插件界面，宿主自动渲染为 Naive UI 组件
- 丰富宿主 API：本地程序调用、文件操作、网络请求、歌单管理、音乐元数据写入