自定义设置页
需要「去获取 Key」「测试连接」、双通道切换、动态列表这类定制 UX 时，
config_schema不够用——自带一个 QML 设置视图。
声明
json
{
"has_settings_tab": true,
"tab_id": "my_plugin",
"tab_title": "我的插件",
"ui_extensions": { "settings_view": "CustomSettingsView.qml" }
}has_settings_tab: true→ 主设置窗口里出现一个独立 Tab。tab_id唯一；tab_title是 Tab 标题（走locales/可自动翻译，见 i18n）。settings_view不参与 UI 插槽互斥——每个插件有自己的表单。
注入属性
组件声明了对应 property 才会被赋值：
| 属性 | 说明 |
|---|---|
pluginId | 你的插件 id |
bridge | 宿主 bridge（公开槽，与 Host SPI 对齐） |
rootWin | 宿主设置窗口实例（需要挂弹窗/定位时用） |
pluginConfig | 当前配置字典（快照） |
qml
import QtQuick 2.15
Item {
id: root
property string pluginId: ""
property var bridge: null
property var rootWin: null
property var pluginConfig: ({})
// 配置热刷新：getPluginConfig 是瞬态调用，必须监听信号
property var cfg: (typeof bridge !== "undefined" && bridge && bridge.getPluginConfig)
? bridge.getPluginConfig(root.pluginId) : ({})
Connections {
target: (typeof bridge !== "undefined") ? bridge : null
function onPluginConfigChanged(pid) {
if (pid === root.pluginId) {
root.cfg = bridge.getPluginConfig(root.pluginId) || ({})
}
}
}
// 写入：持久化 + 热同步插件 update_config
function setVal(key, value) {
if (typeof bridge !== "undefined" && bridge && bridge.setPluginConfigValue)
bridge.setPluginConfigValue(root.pluginId, key, value)
}
}常见定制 UX 怎么写
| 需求 | 写法 |
|---|---|
| 「去获取 Key」按钮 | 按钮 → Qt.openUrlExternally("https://…")；旁边写清要复制哪几个字段 |
| 「测试连接」 | 按钮 → bridge.invokePluginActionAsync(pluginId, "test_connection", {})；插件侧后台请求，emit_event("test_result", {...}) 回结果 |
| 选文件 / 选目录 | bridge.pickFile(title, filter) / bridge.pickFolder()（等价 host.pick_file / host.pick_folder） |
| 展示动态列表（音色/模型/设备） | 优先用宿主已有组件或走 pluginEvent 推数据；不要自己拉 HTTP |
| 长任务进度 | bridge.beginProgress 系列，或由插件 emit_event 上报状态 |
插件侧的动作入口统一是
action_<name>（见 tool 与 热键）。QML 用bridge.invokePluginAction(pluginId, name, params)（同步，仅瞬时动作）或bridge.invokePluginActionAsync(...)（推荐）。
视觉规范
- 用
ThemeTokens与PluggableWindowBackground自动适配主题。 - 禁止 Emoji / 字符当图标，必须矢量 SVG。
- 按钮、输入框优先复用宿主组件风格，别自创一套（换主题时容易割裂）。
- 面向用户的文案走
I18n.t(...)，并放进插件自己的locales/。
与 config_schema 的分工
config_schema | settings_view | |
|---|---|---|
| 适用 | 普通字段（字符串/数字/开关/下拉） | 定制交互、动态数据、外部链接 |
| 渲染 | 宿主自动 | 你自己写 |
| 保存 | 自动持久化 + 热同步 | 你调 bridge.setPluginConfigValue / savePluginConfig |
| 两者共存 | ✅ 可以：设置 Tab 里先渲染 config_schema，再挂 settings_view 的额外区块 |
推荐：能用 config_schema 表达的全部放进 config_schema（免费拿到存储、热刷新、i18n 兜底）， 只把真正定制的部分写进 settings_view。
参考实现
extensions/community_cloud_dashscope_asr/SettingsView.qml— 「去获取 Key」+ 双通道extensions/community_cloud_xunfei_si/SettingsView.qml— 多字段凭据表单extensions/community_ai_interview_copilot/— assistant 的完整设置 Tab