L2 · 设置表单

前置：L0。声明式 schema：插件声明「要什么配置」，宿主负责渲染、持久化、实时回推。不用写任何 UI 代码。

1. 声明设置

export default function definePlugin(api) {
  api.ui.registerSettings({
    items: [
      { type: 'string', key: 'apiKey', label: 'API Token', password: true, placeholder: 'sk-...' },
      { type: 'boolean', key: 'verbose', label: '详细日志', default: false },
      {
        type: 'select', key: 'endpoint', label: '接入点', default: 'prod',
        options: [
          { value: 'prod', label: '生产' },
          { value: 'staging', label: '预发' }
        ]
      },
      { type: 'button', key: 'test', label: '测试连接', variant: 'primary' }
    ]
  })
}

保存后（开关切换或重启）：

设置 → 插件 → 全局/项目 作用域里，该插件行内出现 ⚙ 按钮（打开配置页）和「一级入口」开关
items 为空或不声明 → 两个控件都不出现（这正是"留空则无一级入口按钮"的规则）

2. 一级入口

行内「一级入口」开关打开后，设置弹窗左侧导航「Agent 能力」组末尾出现以插件名命名的入口，点击进入该插件的独立配置页。用户随时可以关掉。

3. 读写值

const values = api.ui.getSettingValues()   // { apiKey: '...', verbose: false, endpoint: 'prod' }
// schema 里的 default 已合并——没被用户改过的键直接拿默认值

api.ui.onSettingsChange((next) => {        // 用户在设置页改值后实时推送
  values = next
  api.log.info('settings changed', { endpoint: next.endpoint })
})

api.ui.onSettingsAction((key) => {         // button 条目点击（key = 按钮项 key）
  if (key === 'test') {
    const ok = values.apiKey ? '✅' : '❌ 缺少 API Token'
    api.ui.setStatusItem('test', { text: `连接测试 ${ok}`, tone: 'accent' })
  }
})

值持久化在 userData/aso-plugin-values.json（按插件隔离），重装插件后仍在。

4. 13 种标准控件

type	说明	关键字段
`string`	单行输入	`password` 掩码、`placeholder`
`text`	多行文本	`rows`
`number`	数字	`min` / `max` / `step`
`boolean`	开关	—
`select`	下拉单选	`options[{value,label}]`
`multiSelect`	多选（chip 组）	`options`
`slider`	滑条	`min` / `max` 必填、`step`
`color`	颜色（#rrggbb）	—
`path`	文件/目录选择	`mode: 'file' \| 'directory'`
`image`	图片选择 + 缩略图	—
`button`	动作按钮	`variant: 'primary' \| 'ghost'`
`info`	静态说明	—
`divider`	分割线/小节标题	`label?`

全部条目支持 label / description / default（button/info/divider 除外）。

5. 设计约束（为什么是数据不是代码）

schema 是纯数据：不允许函数/React 元素——宿主跨进程渲染并持久化快照
需要动态选项（比如扫描出来的设备列表）？在激活时计算好再 registerSettings，每次激活都会重新声明
需要复杂交互 UI？那不是设置的职责——走 L4 React 组件

6. 验证

重载插件 → 插件页该行出现 ⚙ 与「一级入口」
打开配置页改一个值 → 日志出现 settings changed（onSettingsChange 生效）
点按钮 → 状态胶囊出现（动作回调生效）
userData/aso-plugin-values.json 里能看到写入的键值

上一篇 L1 · 下一篇：L3 UI 槽位——状态胶囊、面板、视图与 iframe 页。

3.6 KiB Raw Blame History Unescape Escape