Super Productivity 插件开发快速上手从纯 JavaScript 到 TypeScript 全流程实战指南【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity本篇指南面向希望为 Super Productivity 扩展功能自定义任务操作、快捷录入、集成外部服务等的开发者。核心围绕 QUICK_START.md 提供的三条开发路线——纯 JavaScript、简单 TypeScript、TypeScript Webpack——展开并辅以 插件开发工作区 README 与插件 API 类型定义types.ts中的源码级细节。读完本文你将能够根据需求复杂度选择正确的工程方案完成从脚手架搭建、插件打包到在 Super Productivity 中上传测试的完整闭环。三条开发路线按复杂度选择合适的起点QUICK_START 给出的核心决策模型是「三档递进」先用最轻量的方式验证 API再按需引入类型系统和构建工具。下面逐条展开并补充仓库中对应的真实示例。路线一纯 JavaScript最简单零构建cd minimal-plugin # 编辑 plugin.js # 将文件打包为 zip 后上传优点没有构建步骤改完即可刷新验证反馈即时。缺点没有 TypeScript 类型提示也没有代码打包能力只能以单文件形式分发。这条路线在仓库里有多个可直接参考的真实实现brain-dump/plugin.js约 500 行的头脑风暴插件把文本区每一行解析成一条任务支持- [x]勾选、缩进子任务、草稿自动保存完整演示了getAllProjects、loadSyncedData、openDialog、addTask、persistDataSynced、registerMenuEntry、registerShortcut、showSnack的组合用法voice-reminder/plugin.js 与 yesterday-tasks-plugin均为纯 JS 小插件。纯 JS 插件同样需要一份 manifest.json 声明元数据与权限例如 Brain Dump 声明了getAllProjects、addTask、showSnack、openDialog、persistDataSynced、loadSyncedData六个权限并设置iFrame: false、isSkipMenuEntry: true不在菜单里显示入口仅通过注册的菜单项与快捷键触发。路线二简单 TypeScript推荐cd simple-typescript-plugin npm install npm run build # 在 dist/ 目录下找到 plugin.zip优点获得 TypeScript 类型支持与完整 IDE 智能提示构建流程简单。缺点工程结构被限制为单文件产物不适合拆分多源文件的大型插件。类型支持来自独立的 super-productivity/plugin-api 包其 index.ts 统一导出了 types.ts任务、项目、标签、API 接口等核心类型与issue-provider-types.ts议题提供者插件类型。在plugin-dev工作区的 package.json 中该包以file:../plugin-api形式作为 devDependency 关联保证类型定义与仓库代码同步。路线三完整 TypeScript Webpack进阶cd example-plugin npm install npm run build npm run package优点支持多源文件、完整工具链webpack 打包、lint、typecheck。缺点工程配置更复杂学习成本更高。需要说明的是从当前仓库目录结构看minimal-plugin、simple-typescript-plugin、example-plugin这三个 QUICK_START 中命名的目录并未随仓库保留实际可参考的现代工程化示例是 boilerplate-solid-jsSolid.js Vite i18n 的官方样板与 procrastination-buster同样基于 SolidJS 的完整示例二者均以vite.config.ts构建、产出dist/并支持插件与 iframe 的通信。我该选哪条路线场景选择只是想快速测试 API路线一纯 JSminimal-plugin 思路参考 brain-dump需要类型安全路线二简单 TypeScript构建复杂、多文件的插件路线三完整 TypeScript Webpack/Vite开发建议来自 QUICK_START 的 Development Tips先用纯 JS 插件理解 PluginAPI 的用法与调用模式需要类型安全时再迁移到 TypeScript只有确实需要多个源文件时才引入 webpack 这类打包器避免过度工程化。前置准备与工作区命令开始之前建议先了解插件开发工作区packages/plugin-dev提供的命令脚本定义于 package.json# 构建工作区内全部插件 npm run build # 安装全部插件的依赖 npm run install:all # 清理构建产物 npm run clean:dist # 列出可用的插件目录 npm run list其中install:all与build分别由scripts/install-all.js与scripts/build-all.js驱动便于批量管理多个插件工程。前提条件为 Node.js 18 及以上版本以及 npm 或 yarn若走 TypeScript 路线还需要基本的 TS 知识。插件工程结构与 manifest 详解以工作区 README 给出的工程结构为骨架my-plugin/ ├── package.json # npm 包配置 ├── tsconfig.json # TypeScript 配置 ├── webpack.config.js # 构建配置 ├── manifest.json # 插件清单元数据与权限 ├── src/ │ └── index.ts # 主插件代码 ├── assets/ │ ├── index.html # 可选 UIiframe 插件用 │ └── icon.svg # 插件图标 ├── scripts/ │ └── package.js # 生成 plugin.zip 的脚本 └── dist/ # 构建输出 ├── plugin.js # 编译后的插件代码纯 iframe 插件可缺省 ├── manifest.json # 拷贝后的清单 └── plugin.zip # 打包产物manifest.json 是插件的身份证。结合 types.ts 中 PluginManifest 的定义关键字段包括字段说明示例值id插件唯一标识brain-dumpname插件显示名称Brain DumpmanifestVersion清单格式版本1version插件版本号1.0.0minSupVersion兼容的 Super Productivity 最低版本13.0.0permissions声明所需 API 权限白名单[addTask, showSnack, ...]hooks声明要监听的生命周期钩子[taskComplete, taskUpdate]iFrame是否为 iframe 型插件带独立 UItrue/falseicon图标路径相对插件根目录icon.svgjsonSchemaCfg插件配置的 JSON Schema 路径config-schema.jsoni18n.languages支持的国际化语言代码[en, de, fr]isSkipMenuEntry是否跳过默认菜单入口true/falseallowedHosts允许通过PluginAPI.request访问的主机白名单[api.example.com]allowedHosts采用 fail-closed 策略未在permissions中声明http能力、或目标主机不在allowedHosts中时PluginAPI.request会被直接拒绝且该白名单会在安装时呈现给用户审查。真实参考可见 api-test-plugin/manifest.json——它同时声明了iFrame: true、jsonSchemaCfg和四个钩子是演示全 API 调用 iframe UI的典型样本。PluginAPI插件的全部能力入口插件在运行时获得全局PluginAPI对象完整签名见 types.ts 中 PluginAPI 接口能力可归纳为五类配置与 UI 集成cfg当前应用配置主题light | dark、平台web | desktop | android | ios、应用版本、是否开发模式registerMenuEntry()/registerHeaderButton()/registerSidePanelButton()/registerWorkContextHeaderButton()在菜单、顶栏、侧栏及特定工作上下文PROJECT/TAG/TODAY中注册入口registerShortcut()/unregisterShortcut()注册与移除键盘快捷键showIndexHtmlAsView()/showInWorkContext()/closeWorkContextView()在独立视图或工作区正文中渲染插件 UI。数据访问getTasks()、getArchivedTasks()、getCurrentContextTasks()、getSelectedTask()、getFocusedTask()、getAppState()updateTask()、addTask()、deleteTask()、batchUpdateForProject()getAllProjects()、addProject()、updateProject()、deleteProject()getAllTags()、addTag()、updateTag()reorderTasks()、selectTask()、getActiveWorkContext()。注意getAppState()返回的是调用瞬间的只读快照不会响应式更新getActiveWorkContext()返回的taskIds同样是发射时的快照需要最新排序时应按需重新读取见 types.ts 中的 ActiveWorkContext 说明。用户交互showSnack()Snackbar 提示支持SUCCESS | ERROR | WARNING | INFO类型与图标notify()系统级通知openDialog()打开自定义对话框htmlContent会被宿主按白名单净化后渲染脚本、事件属性、内联svg与url(样式均被移除未转义的用户输入需自行处理。数据持久化与安全persistDataSynced(dataStr, key?)/loadSyncedData(key?)读写随同步机制分发的插件数据key可拆分多个独立 LWW 解决冲突的数据项setSecret()/getSecret()/deleteSecret()按设备保存的密钥存储永不进入同步、导出与备份适合 IMAP 密码、API Token 等敏感信息request()经宿主 HTTP 桥发起受保护请求需http权限 allowedHosts白名单startOAuthFlow()/getOAuthToken()/clearOAuthToken()OAuth 流程支持可针对 desktop/web/Android/iOS 分别配置 clientId。i18n 与钩子translate(key, params?)、formatDate(date, format)、getCurrentLanguage()多语言与本地化日期格式化完整指南见 PLUGIN_I18N.mdregisterHook()注册生命周期钩子。从 PluginHooks 枚举 可见钩子远不止 QUICK_START 列出的六种完整清单为taskCreated、taskComplete、taskUpdate、taskDelete、currentTaskChange、finishDay、languageChange、persistedDataChanged、action、anyTaskUpdate、projectListUpdate、workContextChange且每种钩子都有对应的强类型 payload见 HookPayloadMap。示例注册钩子与快捷键// 监听任务完成事件 PluginAPI.registerHook(taskComplete, async (task) { console.log(Task completed:, task); PluginAPI.showSnack({ msg: Great job completing: ${task.title}, type: SUCCESS, }); }); // 注册键盘快捷键 PluginAPI.registerShortcut({ id: my-action, label: My Plugin Action, onExec: async () { const tasks await PluginAPI.getTasks(); console.log(You have ${tasks.length} tasks); }, }); // 国际化与日期格式化 const greeting PluginAPI.translate(MESSAGES.GREETING); const taskCount PluginAPI.translate(TASK_COUNT, { count: tasks.length }); const dueDate PluginAPI.formatDate(task.dueDate, short);开发工作流本地联调、Watch、类型检查与 Lint在 Super Productivity 仓库内开发时README 的 Development Workflow# 1. 构建并安装到本地 Super Productivity npm run install-local # 该命令会把构建产物拷贝到 ../../../src/assets/my-plugin/ # 2. 开启 Watch 模式改动自动重建 npm run dev # 3. 类型检查 npm run typecheck # 4. 代码质量检查 npm run lintinstall-local将插件输出到src/assets/目录后直接以开发模式运行 Super Productivity 即可加载插件这是迭代速度最快的方式。随后进入cd ../../.. npm start启动应用验证。构建、打包与发布生成可分发产物npm run build npm run package以上命令在dist/下生成plugin.zip可直接分发或上传。文件大小限制以源码为准插件上传有明确的大小硬限制定义在 src/app/plugins/plugin.const.ts项目限制常量插件 ZIP 包10MBMAX_PLUGIN_ZIP_SIZEmanifest.json100KBMAX_PLUGIN_MANIFEST_SIZEplugin.js 代码5MBMAX_PLUGIN_CODE_SIZE全部 i18n 翻译文件合计5MBMAX_PLUGIN_TRANSLATIONS_TOTAL_SIZE需要提示工作区 README 中记载的 ZIP 50MB 上限与当前 plugin.const.ts 中的 10MB 实现不一致实际校验以源码常量为准——服务端校验逻辑可在 plugin.service.ts 中看到maxSize的具体应用相关解析测试见 plugin.service.load-from-zip.spec.ts。ZIP 内必含文件必须包含manifest.json—— 插件元数据与权限声明plugin.js—— 主插件代码若为纯 iframe 插件iFrame: true且带index.html可缺省。可选文件index.html—— iframe 插件的 UIicon.svg—— 插件图标i18n/*.json—— 多语言翻译文件。发布渠道GitHub Release推荐创建插件仓库后用 GitHub Actions 在 release 触发时自动构建并上传dist/plugin.zipname: Build Plugin on: release: types: [created] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: npm ci - run: npm run build - run: npm run package - uses: softprops/action-gh-releasev1 with: files: dist/plugin.zip用户可直接从 Releases 页面下载 zip。npm 包也可以把插件源码发布到 npm修改package.json的 scope →npm run build→npm publish但用户需要自行构建或由你在发布包中附带构建产物。测试你的插件方式一开发模式本地测试最快迭代# 构建插件 npm run build # 拷贝到 Super Productivity 的 assets 目录 npm run install-local # 启动开发服务器 cd ../../.. npm start方式二生产构建后上传执行npm run package生成plugin.zip打开 Super Productivity进入Settings → Plugins点击Upload Plugin选择 zip 文件上传。上传校验与插件管理界面实现在 src/app/plugins/ui/plugin-management/plugin-management.component.ts加载/校验核心逻辑在 src/app/plugins/plugin.service.ts。调试技巧插件运行在主窗口上下文中打开浏览器 DevTools 即可查看 console 日志在插件代码中使用console.log()输出调试信息插件未加载时优先检查浏览器控制台报错、manifest 是否为合法 JSON、必填字段是否齐全以及文件大小是否超限仓库还提供了 api-test-plugin——一个演示并测试所有可用 API 方法的插件非常适合作为调试参考。TypeScript 开发类型安全的收益使用super-productivity/plugin-api的类型定义可以获得完整的 IntelliSense 自动补全、编译期类型检查、安全重构与 IDE 内联文档。import type { TaskData, ProjectData } from super-productivity/plugin-api; // 类型安全的任务处理 async function processTask(task: TaskData): Promisevoid { if (task.projectId) { const projects await PluginAPI.getAllProjects(); const project projects.find((p) p.id task.projectId); if (project) { console.log(Task ${task.title} belongs to project ${project.title}); } } } // 类型安全的钩子注册 PluginAPI.registerHook(taskUpdate, (data: unknown) { const task data as TaskData; processTask(task); });注意TaskData、ProjectData等别名在 types.ts 中已标记为deprecated新代码应直接使用Task、Project、Tag等正式类型。遇到 TS 报错时依次检查npm run typecheck、super-productivity/plugin-api是否已安装、tsconfig.json 配置是否正确。最佳实践清单错误处理异步操作一律包 try-catch避免未捕获的 Promise 拒绝性能不要在插件代码中阻塞主线程重计算放到异步或拆分执行状态管理插件自有状态统一使用persistDataSynced()持久化保证跨会话与多端同步用户体验关键操作后通过showSnack()给出明确反馈参考 brain-dump/plugin.js 中添加任务后弹出成功 Snackbar的写法权限最小化只声明实际需要的permissions降低安装审查成本版本兼容在 manifest 中设置合适的minSupVersion避免 API 不兼容导致加载失败国际化接入 i18n 以触达更多用户规范见 PLUGIN_I18N.md。常见故障排查症状排查步骤插件不加载检查浏览器 console 报错验证 manifest.json 是合法 JSON 且必填字段齐全核对文件大小限制见上文常量表TypeScript 报错运行npm run typecheck查看全部错误确认已安装super-productivity/plugin-api检查 tsconfig.json构建失败删除dist/后重新构建检查 webpack.config.js或 vite.config.ts确认依赖已全部安装钩子不触发确认 manifest 的hooks数组中已声明对应钩子名如taskComplete仅registerHook不够仓库内可参考的示例插件当前 plugin-dev 工作区 内的真实示例覆盖了从简单到复杂的完整梯度纯 JS 路线brain-dump任务批量录入、voice-reminder语音提醒、yesterday-tasks-plugin昨日任务API 演示api-test-plugin——遍历全部 API 方法含 iframe UI 与配置 Schema现代 TS 工程boilerplate-solid-jsSolid.js Vite i18n 官方样板、procrastination-buster完整真实场景、automations自动化规则引擎、sync-mdMarkdown 双向同步议题/日历提供者github-issue-provider、gitlab 系 gitea-issue-provider、caldav-calendar-provider 等展示了registerIssueProvider这一能力类型见 issue-provider-types.ts。支持与进一步阅读插件 API 的完整类型定义与文档见 packages/plugin-api/README.md 与 types.tsi18n 规范见 PLUGIN_I18N.md插件开发理念与约束可参考仓库根目录的 docs/plugin-development.md。建议动手时从拷贝一个纯 JS 示例开始在 DevTools 里观察每个 API 的调用与返回再逐步向 TypeScript 工程化演进。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考