插件开发指南
NextList 提供了强大、轻量且高度灵活的插件系统：用标准前端技术栈（JavaScript / CSS / SVG）开发界面悬浮挂件、文件操作扩展、自定义主题、数据预览及系统集成工具。
[!NOTE] NextList 的插件清单格式（
plugin.json）、权限字典、OpenListPluginSDK、后台 API 与 ZIP 打包规范与 OpenListNext 完全一致：为 OpenListNext / NextList 开发的插件包可直接在两者之间互相安装运行。 示例插件见主仓库plugins_src/目录与插件市场。
一、插件系统特性
- 零构建门槛：无需 Webpack / Vite 编译链，纯原生 JavaScript（ES6+）与 CSS 即可编写；
- 安全隔离执行：每个插件在独立封装的函数作用域内运行，避免全局变量污染；
- 后台可视化配置：在
plugin.json中声明config_schema，后台自动生成设置表单（下拉、布尔、输入框、多行文本等）； - 一键打包分发：以标准
.zip压缩包分发，后台支持拖拽上传、一键解压热加载。
二、插件包文件结构
my-plugin.zip
├── plugin.json # [必须] 插件清单与配置元数据
├── index.js # [必须] 插件主逻辑脚本
├── style.css # [可选] 插件专属样式表
├── icon.svg # [推荐] 插件图标（或 icon.png）
└── README.md # [推荐] 使用说明压缩时将这 5 个文件直接置于 ZIP 根目录。
三、清单文件 plugin.json
{
"id": "my-plugin-demo",
"name": "示例插件",
"version": "1.0.0",
"description": "在界面右下角提供便捷工具面板",
"author": "Your Name",
"homepage": "https://github.com/you/my-plugin",
"entry": "index.js",
"style": "style.css",
"icon": "icon.svg",
"config_schema": [
{
"key": "greeting",
"label": "问候语",
"type": "string",
"default": "Hello NextList"
}
],
"permissions": ["ui:widget", "fs:read", "notify"]
}关键字段说明：
| 字段 | 说明 |
|---|---|
id | 全局唯一标识，建议 插件名-功能 命名 |
name | 插件展示名（必填）：插件市场、后台插件列表均以此名称展示插件，而非 GitHub 仓库名；支持中文，如 动态视频背景 |
description | 插件描述：市场卡片与详情页优先展示清单里的描述（未填时回退仓库描述） |
version | 插件版本号（SemVer 风格，如 1.0.0），市场与后台展示为 v1.0.0 版本徽标 |
author | 作者署名（可用 GitHub 用户名或显示名） |
tags | 标签数组（支持中文，如 ["背景", "美化"]），市场的筛选与搜索使用；未填时回退仓库 topics |
entry / style / icon | 入口脚本 / 样式 / 图标在 ZIP 内的相对路径 |
config_schema | 可视化配置项数组（key / label / type / default） |
permissions | 权限声明字典，见下表 |
常用权限：ui:widget（悬浮挂件）、ui:file-action（文件操作扩展）、fs:read / fs:write（文件系统读写）、admin:read（管理接口）、notify（消息通知）、dom:inject（页面样式 / DOM 注入）。
[!IMPORTANT] 插件市场收录规则：插件仓库被收录时，市场会读取仓库根目录的
plugin.json，并以清单中的name/description/version/tags作为展示元数据（缺失的字段才回退到 GitHub 仓库名与描述）。 因此请在仓库根目录放一份有效的plugin.json，其中name务必填写为用户友好的插件名 （建议中文或自然语言名称），而不是类似my-plugin-demo的仓库名/英文标识。
四、运行时 SDK 概览
index.js 默认导出一个接收执行上下文的工厂函数，上下文提供：
- ctx.config：用户在后台填写的可视化配置；
- ctx.ui：注册悬浮挂件、注入文件操作菜单项；
- ctx.events：事件总线与生命周期钩子（挂载 / 卸载 / 文件选中 / 目录切换等）；
- ctx.notify：消息与弹窗提示；
- ctx.fs：文件系统 API（列目录 / 读文件 / 写文件等，需对应权限）；
- ctx.admin：管理员与系统配置 API（需
admin:*权限）； - ctx.resources：动态资源与样式注入。
完整 SDK 签名与示例代码见主仓库 docs/plugin-development.md（764 行完整指南，含从零到一的实战范例）。
五、打包、安装与调试
# 在插件目录内打包（5 个文件置于 zip 根目录）
zip -r ../my-plugin.zip plugin.json index.js style.css icon.svg README.md- 进入管理面板 → 插件管理；
- 上传
my-plugin.zip（或填入托管在 GitHub Release 的 ZIP 直链）； - 启用插件，在「配置」中调整
config_schema生成的表单； - 刷新前端页面即可看到插件生效；开发时可反复上传覆盖调试。
六、发布到插件市场
将插件仓库发布到 GitHub 并打上 nextlist-plugin topic 后，在插件市场用 GitHub 登录并点击「刷新我的插件」，你的插件就会被自动收录（含 README 展示、Release 下载直链与评论互动）。
收录时市场会以仓库根目录 plugin.json 的 name（插件展示名）、description（描述）、version（版本号）、tags（标签）作为市场展示信息，因此请确保这些字段填写完整、语义清晰；作者更新清单后重新「刷新我的插件」即可同步到市场。
评论