TREK插件开发完整教程用plugin-sdk打造你的第一个仪表盘小部件【免费下载链接】TREKA self-hosted travel/trip planner with real-time collaboration, interactive maps, PWA support, SSO, budgets, packing lists, and more.项目地址: https://gitcode.com/GitHub_Trending/nomad22/TREKTREK 是一款自托管的旅行规划应用支持实时协作、交互式地图与 PWA。它的plugin-sdk提供了一整套 CLI 工具让你只需四步命令就能构建、调试并发布一个仪表盘小部件dashboard widget。本教程带你走完整条 TREK 插件开发流程从脚手架、写逻辑、搭界面到本地热重载调试与安装验证全程代码量极少新手也能快速上手 一、TREK 插件系统是什么插件让你不改 TREK 源码就能给实例添加新功能。每个插件都在隔离的子进程中运行只能通过清单文件里声明的权限与宿主通信——没有授权的调用会被直接拒绝所以权限列表是真正的安全边界。TREK 共有四种插件类型决定插件出现在哪里类型展示位置典型用途widget仪表盘侧边栏 / hero 横幅 / 详情页面板航班状态、倒计时等一眼可见的小卡片page顶部导航的独立页面完整自包含工具trip-page每个行程规划器内的标签页针对单个行程的工具integration无界面通过钩子接入照片源、日历源、通知渠道widget 还能通过slot字段选择更具体的位置默认的sidebar仪表盘侧栏、hero登机牌横幅以及行程规划器内的place-detail/day-detail/reservation-detail详情面板。想看官方对隔离模型和插件面板的完整说明可阅读 wiki/Plugins.md。二、第一步一条命令生成插件脚手架打开终端执行npx trek-plugin-sdk create trip-status --type widget cd trip-status向导会询问 id、图标自动校验 lucide 图标名、权限、出网主机等生成的目录开箱即可运行和打包trip-status/ trek-plugin.json # 清单id、type、权限、widget 插槽 server/index.js # 你的后端逻辑 client/index.html # 小部件界面沙盒 iframe README.md # 发布前需要补全 docs/ # 截图放这里清单文件是插件的身份证一个最小化的 widget 清单长这样可参考现成示例 plugin-sdk/examples/koffi/trek-plugin.json{ id: trip-status, name: Trip Status, version: 1.0.0, type: widget, trek: 3.4.0 4.0.0, permissions: [db:read:trips], capabilities: { widget: { title: Trip Status, slot: sidebar } } }常用权限速查db:read:trips读行程按成员身份校验、db:own拥有自己的 SQLite 数据库、notify:send发通知。完整权限目录见 wiki/Plugin-Permissions.md。三、第二步写一个路由和界面服务端只需导出一个definePlugin对象所有能力都通过ctx提供。一个最小路由const { definePlugin } require(trek-plugin-sdk) module.exports definePlugin({ routes: [ { method: GET, path: /status, auth: true, async (req, ctx) { const trip await ctx.trips.getById(1) return { status: 200, body: JSON.stringify({ name: trip.name }) } }}, ], })界面部分有个偷懒神器——设计套件Design Kit。在client/index.html的head里加一行标记!-- trek:ui --打包时它会自动展开成完整的 TREK 风格样式玻璃拟态卡片、按钮、暗色主题跟随宿主和window.trek桥接对象界面代码因此只剩几行trek.onContext((ctx) { /* ctx.theme / ctx.user / ctx.tripId */ }) const data await trek.invoke(/status) // 调用你自己的路由 trek.notify(success, 已加载) // 弹一个原生 toast这样你的小部件在浅色/暗色主题下都自动与 TREK 浑然一体无需手写任何 CSS。四、第三步本地热重载调试无需启动 TREKnpx trek-plugin-sdk dev # http://localhost:4317dev会注入一个真实的ctx严格按清单授权执行——少声明的权限会抛出PERMISSION_DENIED让你在安装前就发现漏配。打开/preview页面可以看到小部件渲染在真实的沙盒框架里还能切换主题和强调色。想模拟数据在清单旁放一个dev-fixtures.json即可喂给ctx.trips等。保存代码即自动重载开发循环非常顺滑 五、第四步打包并安装到你的 TREK 实例npx trek-plugin-sdk pack # 生成 plugin.zip输出 sha256然后进入实例的Admin → Plugins面板点Upload上传plugin.zip插件会以未激活状态注册打开行尾的开关完成激活授予你审核过的权限小部件立刻出现在仪表盘上 ✅提示pack只负责打包不会强制 README/截图等发布检查——这正适合自测。发布到社区仓库时由status/publish把关。六、进阶status 自查与一键发布npx trek-plugin-sdk status—— 永不失败的进度地图列出清单、代码、文档、发布各阶段还差什么并告诉你下一条该跑的命令npx trek-plugin-sdk shot—— 自动启动 dev 服务在主题化框架中渲染小部件并输出 1600×900 的docs/screenshot.png需先安装 Playwrightnpx trek-plugin-sdk publish --repo you/repo --tag v1.0.0—— 按check → pack → release → preflight → submit五步完成整个发布还支持 Ed25519 签名。命令细节见 plugin-sdk/README.md。七、学习资源清单官方插件开发 Wikiwiki/Plugin-Development.md可复制的菜谱合集wiki/Plugin-Cookbook.md带 UI 的 widget 示例吉祥物 Koffiplugin-sdk/examples/koffi/client/index.html纯钩子 integration 示例plugin-sdk/examples/trip-doctor/server/index.js无实例单测工具createMockHostplugin-sdk/src/mock-host.ts脚手架源码入口plugin-sdk/src/cli/create.ts四步命令create → dev → status → publish就是 TREK 插件开发的完整路径。现在就动手打造属于你的第一个仪表盘小部件吧 ✈️【免费下载链接】TREKA self-hosted travel/trip planner with real-time collaboration, interactive maps, PWA support, SSO, budgets, packing lists, and more.项目地址: https://gitcode.com/GitHub_Trending/nomad22/TREK创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考