开发工具
SDK(构建、校验、打包、测试与组合件)、开发模式热重载、组件画廊与检查器
SDK
类型:在 tsconfig.json 里把 astra 指向 SDK("paths": { "astra": ["./node_modules/@astragate/plugin-sdk"] });JSX 用 jsxImportSource: '@astragate/plugin-sdk'。
组合件(@astragate/plugin-sdk/patterns):SettingsPage、ListDetail(窄宽度下变为导航)、Wizard、Dashboard、CrudTable。它们只是用基础组件拼成的函数,和你自己的代码一起打包。
测试
测试工具(@astragate/plugin-sdk/testing)在 Node 里运行与 Astra 相同的运行时脚本:
-
mount(view, { storage, secrets, config, permissions, fetch, confirm, prompt, … })打开视图,返回find/findAll/press/change/render/effects/storage; -
每次渲染都按组件模式检查:未知组件或属性、类型不符、事件指向不存在的动作、缺少
a11yLabel/alt是错误(默认抛出,strict: false时收集到view.warnings),列表缺key、超过限额 80% 是警告; -
runCommand(plugin, id, args)、runHook(hooks, setId, 'request', input, { shared, config })。 -
runProvider(plugin, id, 'prepare', req, { key, secret })、runClient(plugin, id, input):服务商和客户端。
在测试运行器里把 astra 指向 @astragate/plugin-sdk/runtime(vitest:resolve.alias)。
在 Astra 的沙箱里跑同一组测试:
test/**/*.test.js(或 .mjs)里的测试在 Astra 自己的 JavaScript 引擎里运行:真实的 astra 模块、真实的宿主调用和权限检查,但用一份独立的临时存储(不碰已安装插件的数据),没有网络(http.fetch 返回 404)。测试从 vitest 和 @astragate/plugin-sdk/testing 导入,沙箱提供这两个模块,所以同一个文件在 Node 和沙箱里都能跑。只允许本机。
开发模式
把目录作为开发插件挂载(只允许本机),确认权限后开始打印插件日志,Ctrl+C 卸载(--keep 保留)。开发插件:
- 保存即重载:目录里任何文件变化(
node_modules、dist、.git除外)都会重新加载插件;打开着的视图用原来的状态重新渲染,界面不会丢;新代码与旧状态不兼容时视图重新初始化; - 可以用 http 访问本机地址(连本地的测试服务):在
net:里声明它,并以ASTRA_PLUGIN_DEV_LOOPBACK=1启动服务端; - 视图右上角有 检查器:当前组件树、状态与本地输入、每次动作的耗时(排队、处理、渲染、求差、补丁大小)、宿主调用与日志、模式警告;还可以把视图切换到
compact/regular/wide宽度、明暗主题、页面 / 侧板 / 托盘位置预览。
组件画廊
插件页在有开发插件时显示 组件画廊(/plugins/dev/gallery,桌面端同样有):每个组件、每种状态(变体、色调、尺寸、加载、错误、禁用)和几个组合场景,可以切换宽度、主题和位置,并查看产生它的组件树。画廊的场景就是 Web 与桌面端视觉比对用的同一组场景(tests/fixtures/plugin-ui/)。