@linkdesk/plugin-docs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +58 -0
  2. package/docs/00-readme.md +189 -0
  3. package/docs/01-plugin-api-contract.md +171 -0
  4. package/docs/02-plugin-lifecycle.md +348 -0
  5. package/docs/03-contributes-spec.md +800 -0
  6. package/docs/04-distribution-format.md +172 -0
  7. package/docs/05-ui-conventions.md +549 -0
  8. package/docs/06-plugin-json-spec.md +640 -0
  9. package/docs/07-plugin-to-plugin-communication.md +299 -0
  10. package/docs/08-view-container-api.md +405 -0
  11. package/docs/09-plugin-directory-layout.md +301 -0
  12. package/docs/10-building-a-settings-plugin.md +164 -0
  13. package/docs/11-authoring-themes.md +173 -0
  14. package/docs/12-readme-media-contract.md +74 -0
  15. package/docs/13-development-guide.md +259 -0
  16. package/docs/14-data-pipeline-command-conventions.md +173 -0
  17. package/docs/15-multi-repo-and-local-workspace.md +86 -0
  18. package/docs/16-naming-conventions.md +77 -0
  19. package/docs/17-region-map.md +225 -0
  20. package/docs/18-cross-region-wiring.md +192 -0
  21. package/docs/19-component-cheatsheet.md +108 -0
  22. package/docs/20-adding-a-setting.md +159 -0
  23. package/docs/themes/01-build-a-theme-plugin.md +150 -0
  24. package/docs/themes/02-theme-field-index.md +145 -0
  25. package/docs/zh/00-README.md +189 -0
  26. package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
  27. package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
  28. package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
  29. package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
  30. package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
  31. package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
  32. package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
  33. package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
  34. package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
  35. package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
  36. package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
  37. package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
  38. package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
  39. package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
  40. package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
  41. package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
  42. package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
  43. package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
  44. package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
  45. package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
  46. package/docs/zh/plugin.schema.json +687 -0
  47. package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
  48. package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
  49. package/package.json +20 -0
@@ -0,0 +1,192 @@
1
+ # 18 — 区域间互动:侧栏选中 → 主区切换 → 状态栏更新
2
+
3
+ > **本页回答一个问题:** 我的插件横跨好几个区域(图标栏 / 侧栏 / 主区 / 底部面板 / 状态栏),**它们之间怎么对上**?
4
+ > 例:"侧栏里选中一个会话 → 主区切到那个会话的标签页 → 状态栏显示当前会话名。"
5
+
6
+ | | |
7
+ |---|---|
8
+ | 读者 | 已经知道区域在哪(→ [17-区域地图](17-区域地图.md)),现在要让它们**联动**的作者 |
9
+ | 形态 | **配方集**——每个场景一段可抄的骨架 |
10
+ | 不是 | 通信机制字典(→ [07-插件间通信](07-插件间通信.md) 讲"有哪些机制")· 数据管道命令命名(→ [14-数据管道命令约定](14-数据管道命令约定.md)) |
11
+
12
+ > **一句话分工:`07` 回答"插件之间怎么传数据",本页回答"同一个插件的几个区域怎么对上"。** 前者是机制,后者是**组网**——先在本页选出手段,再去 `07` 看机制细节。
13
+
14
+ ---
15
+
16
+ ## 一、五种联动手段(先选手段,再写代码)
17
+
18
+ | 想达到的效果 | 用什么 | 方向 | 耦合 |
19
+ |:--|:--|:--|:--|
20
+ | **点一下 → 另一个区域做件事** | `window.linkdesk.commands.executeCommand("id", args)` | 定向(一对一) | 紧——调用方知道命令名 |
21
+ | **一个区域变了 → 谁关心谁自己刷新** | `window.linkdesk.events.emit(channel, payload)` + `events.on` | 广播(一对多) | 松——发布方不知道谁在听 |
22
+ | **某个状态决定按钮/菜单/视图显不显示** | `window.linkdesk.contextKey.set(key, value)` + 声明里的 `when` | 声明式(零代码联动) | 最松——壳读键,你不碰对方 |
23
+ | **跨区域的"导航"**(打开/聚焦别处) | `tabs.create` / `tabs.openOrFocus` / `tabs.focus` / `panel.reveal(viewId)` / `panel.revealFloating(viewId)` | 定向 | 紧——你在指定去哪 |
24
+ | **用户在设置页改了值 → 各区域跟随** | `window.linkdesk.configuration.onChange(key, cb)` | 广播(壳替你发) | 最松——零额外声明(→ [20-我的插件加一条配置项](20-我的插件加一条配置项.md)) |
25
+
26
+ **还有一条零代码的:** 颜色/字体/圆角/玻璃这些**外观**随主题自动变——你只要用 `var(--xxx)`,主题一切全区域跟着变,不需要任何订阅。
27
+
28
+ ---
29
+
30
+ ## 二、四个典型配方
31
+
32
+ ### 配方 A —— 侧栏选中 → 主区打开/聚焦对应标签页
33
+
34
+ 侧栏视图里选中一项,让主区出现/聚焦对应内容。这是**"命令 + 打开"**的组合:
35
+
36
+ ```tsx
37
+ // 侧栏视图(src/views/SessionListView.tsx)
38
+ function onPick(id: string) {
39
+ // ① 让主区把对应内容亮出来(幂等:已有就聚焦,没有就建)
40
+ void window.linkdesk.tabs.openOrFocus("my-plugin", { sourceId: id, label: `会话 ${id}` });
41
+ }
42
+ ```
43
+
44
+ ```tsx
45
+ // 主区入口组件(src/index.tsx)——靠 sourceId 知道该显示哪一个
46
+ export default function MyView({ isActive, sourceId }: { isActive: boolean; sourceId?: string }) {
47
+ // sourceId 变了 → 这是"同一个插件、不同标签页",各自独立
48
+ return <SessionDetail id={sourceId} />;
49
+ }
50
+ ```
51
+
52
+ > **`openOrFocus` 比 `create` 更常用**——用户连点两次不该出现两个一样的标签页。
53
+ > 同一个插件的多个标签页靠 **`sourceId`** 区分(不是靠各自的 React state)——见 [17 §五 props 契约](17-区域地图.md)。
54
+
55
+ ### 配方 B —— 选中与否 → 状态栏条目 / 标题栏按钮自动显隐
56
+
57
+ **想让"有选中时才出现的按钮"出现,不要用 React 往下传 prop——用 context key 让壳自己判:**
58
+
59
+ ```tsx
60
+ // 侧栏视图:把状态写进 context key(键名建议带插件前缀,避免和别的插件撞)
61
+ useEffect(() => {
62
+ void window.linkdesk.contextKey.set("my-plugin.hasSelection", !!selectedId);
63
+ }, [selectedId]);
64
+ ```
65
+
66
+ ```jsonc
67
+ // plugin.json —— 声明式消费这个键,两个区域各写各的 when
68
+ {
69
+ "contributes": {
70
+ "titleBar": { "right": [
71
+ { "command": "my-plugin.rename", "icon": "codicon-edit", "when": "my-plugin.hasSelection" }
72
+ ] },
73
+ "menus": { "editor/context": [ { "command": "my-plugin.rename", "when": "my-plugin.hasSelection" } ] }
74
+ }
75
+ }
76
+ ```
77
+
78
+ > **这是"零代码联动"**:标题栏按钮、右键菜单项、快捷键、侧栏视图都能用同一个 `when` 条件——你在一个地方 `set`,壳在 N 个地方读。`when` 的语法(`&&` / `||` / `==` / `in` / `!` / `()`)与壳自带的 key 表 → [03-插件contributes规范 §四](03-插件contributes规范.md)。
79
+
80
+ ### 配方 C —— 一个区域变了,分散在几处的 UI 一起刷新
81
+
82
+ 比如"串口断开"要同时影响:侧栏的连接行、主区的按钮、状态栏的计数。**发布一个事件,各处自己订阅:**
83
+
84
+ ```tsx
85
+ // 发布方(比如侧栏视图里检测到端口掉了)
86
+ window.linkdesk.events.emit("my-plugin:connectionChanged", { portName, open: false });
87
+ ```
88
+
89
+ ```tsx
90
+ // 订阅方 1 —— 主区组件
91
+ useEffect(() => window.linkdesk.events.on<{ open: boolean }>("my-plugin:connectionChanged", (p) => setOpen(p.open)), []);
92
+
93
+ // 订阅方 2 —— 状态栏组件(另一个文件、另一个区域,互不知道对方存在)
94
+ useEffect(() => window.linkdesk.events.on<{ open: boolean }>("my-plugin:connectionChanged", (p) => setText(p.open ? "已连接" : "未连接")), []);
95
+ ```
96
+
97
+ > 🔴 **频道名必须带插件前缀**(`<插件id>:<数据名>`)。所有插件共享同一个渲染进程,频道是**全池可见**的——叫 `changed` 会撞车。
98
+
99
+ ### 配方 D —— 用户改了设置 → 各区域立刻跟随
100
+
101
+ ```tsx
102
+ useEffect(() => {
103
+ return window.linkdesk.configuration.onChange<number>("my-plugin.refreshInterval", (ms) => {
104
+ restartTimer(ms); // 侧栏、主区、状态栏各自订阅各自关心的键
105
+ });
106
+ }, []);
107
+ ```
108
+
109
+ 设置项怎么声明、怎么出现在设置页 → [20-我的插件加一条配置项](20-我的插件加一条配置项.md)。
110
+
111
+ ---
112
+
113
+ ## 三、一个完整小例子(三个区域串起来)
114
+
115
+ 目标:侧栏列表选中 → 主区切过去 → 状态栏显示当前项 → 没选中时标题栏按钮藏起来。
116
+
117
+ ```tsx
118
+ // ① src/views/SessionListView.tsx —— 侧栏:唯一的"用户意图"产生地
119
+ export default function SessionListView() {
120
+ const [sel, setSel] = useState<string | null>(null);
121
+
122
+ const pick = (id: string) => {
123
+ setSel(id);
124
+ void window.linkdesk.contextKey.set("my-plugin.hasSelection", true); // → 配方 B
125
+ void window.linkdesk.tabs.openOrFocus("my-plugin", { sourceId: id }); // → 配方 A
126
+ window.linkdesk.events.emit("my-plugin:selectionChanged", { id }); // → 配方 C
127
+ };
128
+
129
+ return <ul>{items.map((it) => <li key={it.id} onClick={() => pick(it.id)}>{it.name}</li>)}</ul>;
130
+ }
131
+ ```
132
+
133
+ ```tsx
134
+ // ② src/index.tsx —— 主区入口:只认 sourceId,自己的状态自己管
135
+ export default function MyView({ sourceId }: { sourceId?: string }) {
136
+ return sourceId ? <Detail id={sourceId} /> : <Empty />;
137
+ }
138
+ ```
139
+
140
+ ```tsx
141
+ // ③ src/components/statusBar.tsx —— 状态栏:订阅事件而不问"谁选中的"
142
+ export default function StatusBar() {
143
+ const [label, setLabel] = useState("");
144
+ useEffect(
145
+ () => window.linkdesk.events.on<{ id: string }>("my-plugin:selectionChanged", (p) => setLabel(`当前:${p.id}`)),
146
+ [],
147
+ );
148
+ return <span>{label}</span>;
149
+ }
150
+ ```
151
+
152
+ ```jsonc
153
+ // ④ plugin.json —— 声明面:三个区域各就各位,按钮带 when
154
+ {
155
+ "pluginId": "my-plugin",
156
+ "appearsIn": { "iconBar": "top", "tabBar": true },
157
+ "entry": "src/index.tsx",
158
+ "contributes": {
159
+ "viewsContainers": { "my-plugin": { "title": "会话", "location": "sidebar" } },
160
+ "views": { "my-plugin": [ { "id": "sessions", "title": "", "render": "src/views/SessionListView.tsx", "order": 0 } ] },
161
+ "titleBar": { "right": [ { "command": "my-plugin.rename", "icon": "codicon-edit", "when": "my-plugin.hasSelection" } ] }
162
+ },
163
+ "statusBar": [ { "id": "current", "label": "", "align": "left" } ]
164
+ }
165
+ ```
166
+
167
+ ---
168
+
169
+ ## 四、铁律与反模式
170
+
171
+ | 别这么做 | 为什么 | 正确做法 |
172
+ |:--|:--|:--|
173
+ | 在**模块顶层**注册 `events.on` / IPC 监听 | 模块级 = 导入即执行 = 永不清理,卸载后变僵尸回调(硬约束 19,ESLint 机械拦截) | 放 `useEffect`,返回退订函数 |
174
+ | 用 `useRef` 存"跨区域传过来的状态" | ref 更新不触发重渲染 → UI 与实际状态脱节,下次别的事件触发时才"突然跳变"(硬约束 17) | 渲染相关的一律 `useState` |
175
+ | 用 `localStorage` / 全局变量当总线 | 绕过壳的统一通道,多窗口/卸载后行为不可预期 | `configuration`(要持久化)或 `events`(只要通知) |
176
+ | 频道名不带插件前缀 | 所有插件共用一个渲染进程,频道是全局可见的 | `<pluginId>:<数据名>` |
177
+ | 直接 `import` 别的插件 | 插件之间互不知道对方存在(圆形大厅模型) | 走命令 / 事件 / context key |
178
+ | 用 `isActive` 把内容整块 blank 掉 | keep-alive 下所有标签页始终挂载,条件渲染会丢状态 | `isActive` 只 gate 副作用 |
179
+ | 手写右键菜单来"串联"区域 | 硬约束:右键菜单走声明式(`contributes.menus` + `<ContextMenu>`) | 见 [05-插件UI写法规约](05-插件UI写法规约.md) |
180
+
181
+ ---
182
+
183
+ ## 五、相关篇目
184
+
185
+ | 你要做的 | 读这篇 |
186
+ |:--|:--|
187
+ | 区域有哪些、怎么进去 | [17-区域地图](17-区域地图.md) |
188
+ | 通信机制全表(事件 / 命令 / 数据管道三机制) | [07-插件间通信](07-插件间通信.md) |
189
+ | 数据管道命令的命名与注册约定 | [14-数据管道命令约定](14-数据管道命令约定.md) |
190
+ | `when` 语法与壳自带 context key | [03-插件contributes规范 §四](03-插件contributes规范.md) |
191
+ | 给插件加一条配置项 | [20-我的插件加一条配置项](20-我的插件加一条配置项.md) |
192
+ | `window.linkdesk.*` 全部方法签名 | [01-插件API契约](01-插件API契约.md) |
@@ -0,0 +1,108 @@
1
+ # 19 — 组件速查:壳提供了哪些 UI 零件
2
+
3
+ > **本页回答一个问题:** 界面上的按钮、下拉、开关、右键菜单……**哪些是壳已经给好的**?什么时候该用哪个?
4
+ >
5
+ > 🔴 **本页是"清单 + 选用判据",不是 API 手册。** 组件的 props、签名、默认值的**唯一真相源**在包里:
6
+ > `node_modules/@linkdesk/ui/` 的 README 与 `dist/index.d.ts`(编辑器里 `import` 就有补全)。
7
+ > **本页不抄 props 表**——抄了就会漂移,那正是要避免的第二份真相源。
8
+
9
+ | | |
10
+ |---|---|
11
+ | 读者 | 要写界面、不想自己造轮子的作者 |
12
+ | 形态 | 速查(按"我要什么控件"查一行) |
13
+ | 不是 | 组件的 props 文档(→ `@linkdesk/ui` 包内 README / d.ts)· 写法规约(→ [05-插件UI写法规约](05-插件UI写法规约.md)) |
14
+
15
+ ---
16
+
17
+ ## 一、什么时候**必须**用共享件(不是建议)
18
+
19
+ | 你要做 | 必须走 | 为什么 |
20
+ |:--|:--|:--|
21
+ | 右键菜单 | `contributes.menus` 声明 + `<ContextMenu>`(或 `window.linkdesk.menu.registerItems`) | 手写右键菜单 = 违反硬约束;且不会跟随主题/玻璃 |
22
+ | 弹窗 / 浮层 | `createPortal` 到 `document.body`(共享件 `OverlayPortal` 已封装位置约定) | 层级、焦点锁、窗口拖拽区冲突都在里面处理过 |
23
+ | 持久化"记住用户上次选的" | `window.linkdesk.configuration.get/set` | 禁止 `localStorage.setItem()` |
24
+ | 让用户选文件/目录 | `window.linkdesk.dialog.openFile` + `FilePathInput` | 路径解析与资产路径约定在壳侧 |
25
+
26
+ **理由一句话:** 这些控件的"玻璃 / 主题 / 焦点 / 层级"是**壳统一管**的。你自己写一个,主题一换就不跟随,用户在两种外观之间来回切会明显看出来。
27
+
28
+ ---
29
+
30
+ ## 二、装与引
31
+
32
+ ```bash
33
+ npm i @linkdesk/ui # 可选——想让界面跟内置同款时装
34
+ ```
35
+
36
+ ```tsx
37
+ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
38
+ ```
39
+
40
+ > 包是**单源码防漂移**的编译产物:壳改组件 → 包跟着变,所以"内置同款"是字面意义上的同一份实现。它也**不进**你的 `.linkdesk-plugin` bundle(构建时 external)——不用担心体积。
41
+
42
+ ---
43
+
44
+ ## 三、组件清单
45
+
46
+ | 组件 | 干什么 | 什么时候用它 |
47
+ |:--|:--|:--|
48
+ | `Button` | 按钮 | 任何"点一下就做"的动作;变体/尺寸跟着主题 |
49
+ | `Toggle` | 开关 | 二值设置项(开/关) |
50
+ | `Slider` | 滑杆 | 数值区间调节(配合 `inferSliderStep` 推步进) |
51
+ | `NumberInput` | 数字输入框 | 需要精确输入的数字(滑杆旁边常配一个) |
52
+ | `SelectBox` | 下拉选择(选项固定) | 枚举值,如单位 mm/cm/inch |
53
+ | `DynamicSelect` | 下拉选择(选项动态) | 选项来自运行时数据(串口列表、主题列表…) |
54
+ | `Combobox` | 可输入的下拉 | 选项多、允许用户自己填(如自定义路径) |
55
+ | `SegmentedRadio` | 分段单选 | 2–4 个互斥短选项,比下拉更直观(如 左/中/右) |
56
+ | `FormRow` | 表单一行(label + 控件) | 要跟设置页一样的排版:标签在左、控件在右 |
57
+ | `StringListEditor` | 字符串列表编辑(一行一条,可增删) | 路径列表 / 扩展名列表 / 市场源列表 |
58
+ | `FilePathInput` | 文件或目录路径输入 | 选路径,带浏览按钮与校验 |
59
+ | `FontFamilySelect` | 字体族选择 | 让用户选 UI/编辑器字体 |
60
+ | `ColorPicker` | 取色器 | 让用户挑颜色(记得存成配置值,别写死进组件) |
61
+ | `ThemePicker` | 主题选择器 | 你要列出/预览可选主题时(一般直接用壳的设置页即可) |
62
+ | `MarkdownView` | Markdown 渲染(含安全清洗) | 展示 README / 说明 / 变更日志——**唯一指定组件**,别自己引 markdown 库 |
63
+ | `Badge` | 小标记 / 计数 | 未读数、已安装数量这类角标 |
64
+ | `PluginIcon` | 渲染插件图标 | 显示某个插件的图标(自动处理 codicon / 自定义 svg / 身份彩色图) |
65
+ | `ContextMenu` | 右键菜单组件 | 配合 `contributes.menus` —— 见 [05-插件UI写法规约](05-插件UI写法规约.md) |
66
+ | `InlineInput` | 行内输入(命令式句柄) | 树/列表里就地改名(拿 `ref` 调 `InlineInputHandle`) |
67
+ | `OverlayPortal` | 弹层 portal 宿主 | 自绘弹窗要 portal 到 body 时用它,别裸写 `createPortal` 到处飘 |
68
+
69
+ > 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
70
+
71
+ ---
72
+
73
+ ## 四、Hooks 与工具函数
74
+
75
+ | 名字 | 干什么 | 什么时候用 |
76
+ |:--|:--|:--|
77
+ | `useDebouncedInput` | 输入防抖 | 边打字边算/边搜(避免每个字符都触发重活) |
78
+ | `useClipboardKeys` | 剪贴板快捷键(三轨道) | 你要在自己的控件里支持复制粘贴(文本键走容器 `onKeyDown`——见 05 号文档) |
79
+ | `useClickPreview` | 单击/双击区分预览 | 列表项"单击预览、双击打开"这类交互 |
80
+ | `inferSliderStep` | 按区间推滑杆步进 | 配 `Slider` 用(浮点区间自动给 0.01 这种步进) |
81
+ | `urlSourceKey` | URL 源去重键(owner/repo,分支无关) | 你自己做"加一个源"的列表时,键要跟壳同款 |
82
+ | `FileIconResolver` | 文件图标解析器 | 你要显示文件图标(按扩展名/文件名映射,跟壳同一个解析器) |
83
+ | `pickIdentityArt` / `DEFAULT_PLUGIN_IDENTITY_URI` | 插件身份图裁决与兜底 | 自己画插件身份图时用同一条裁决链 |
84
+ | `IconDescriptor` / `ContextMenuProps` / `ManifestIconShape` / `ResolvedIcon` / `InlineInputHandle` | 类型 | 需要显式标注类型时 `import type` |
85
+
86
+ ---
87
+
88
+ ## 五、常见错误
89
+
90
+ | 症状 | 病根 | 正确做法 |
91
+ |:--|:--|:--|
92
+ | 主题一换,我的下拉/菜单还是老样子 | 自己写了一套控件 | 换 `@linkdesk/ui` 的共享件 |
93
+ | 右键菜单点不出来 / 位置飘 | 手写 `contextmenu` 事件 | `contributes.menus` + `<ContextMenu>` |
94
+ | 弹窗被标题栏吃掉一半点击 | 弹层放到 `top: 0`,撞上窗口拖拽区 | 用共享弹层组件(它已避开拖拽区) |
95
+ | 用户设置没保存住 | 用了 `localStorage` | `window.linkdesk.configuration.set` |
96
+ | 装了两个 UI 库,样式互相污染 | 自己引了第三方组件库 | 能用共享件就用;确需第三方时注意样式隔离 |
97
+
98
+ ---
99
+
100
+ ## 六、相关篇目
101
+
102
+ | 你要做的 | 读这篇 |
103
+ |:--|:--|
104
+ | UI 写法规约(右键菜单 / 浮层 / 持久化 / 快捷键两轨道 / 剪贴板三通道) | [05-插件UI写法规约](05-插件UI写法规约.md) |
105
+ | 组件放进哪个区域、怎么声明 | [17-区域地图](17-区域地图.md) |
106
+ | 组件之间怎么联动 | [18-区域间互动](18-区域间互动.md) |
107
+ | 组件的 props 与签名(真相源) | `@linkdesk/ui` 包内 README / `dist/index.d.ts` |
108
+ | `window.linkdesk.*` 全部方法签名 | [01-插件API契约](01-插件API契约.md) |
@@ -0,0 +1,159 @@
1
+ # 20 — 我的插件加一条配置项
2
+
3
+ > **本页回答一个问题:** 我的插件需要一个"用户可调的开关/数值/下拉"——**最少要写什么**?
4
+ >
5
+ > **三步:声明一条 → 设置页自动出现 → 代码里读它。** 不用写任何设置界面。
6
+
7
+ | | |
8
+ |---|---|
9
+ | 读者 | 已经有插件在跑,现在想加个可配置项的作者 |
10
+ | 形态 | **最小做法**(能抄完就完事) |
11
+ | 不是 | 「做一个设置插件」(那是**替换整套设置界面**,另一件事 → [10-如何造一个设置插件](10-如何造一个设置插件.md))· 字段全表(→ [03-插件contributes规范](03-插件contributes规范.md)) |
12
+
13
+ > **两件事别混**(这是最常见的误会):
14
+ > - **本页**:**给你的插件**加一条配置项 —— 出现在**已有的**设置页里,一个分组,零界面代码。
15
+ > - [10-如何造一个设置插件](10-如何造一个设置插件.md):**你自己做一整套设置 UI** 去替代壳的设置页(`factoryRole: "settings"`)。绝大多数插件**永远不需要**这个。
16
+
17
+ ---
18
+
19
+ ## 一、第 1 步:在 `plugin.json` 里声明
20
+
21
+ ```jsonc
22
+ {
23
+ "pluginId": "my-plugin",
24
+ "contributes": {
25
+ "configuration": {
26
+ "title": "我的插件", // ← 设置页左侧导航里的分组名
27
+ "properties": {
28
+ "my-plugin.autoSave": { // ← key 必须带 <pluginId>. 前缀
29
+ "type": "boolean",
30
+ "default": true, // ← default 必填
31
+ "description": "退出时自动保存" // ← description 必填(渲染成提示)
32
+ },
33
+ "my-plugin.refreshInterval": {
34
+ "type": "number",
35
+ "default": 1000,
36
+ "description": "刷新间隔(毫秒)"
37
+ },
38
+ "my-plugin.units": {
39
+ "type": "string",
40
+ "default": "mm",
41
+ "enum": ["mm", "cm", "inch"],
42
+ "enumDescriptions": ["毫米", "厘米", "英寸"], // ← 与 enum 一一对应
43
+ "description": "显示单位"
44
+ }
45
+ }
46
+ }
47
+ }
48
+ }
49
+ ```
50
+
51
+ **做对了的标志:**
52
+
53
+ ```bash
54
+ npm run validate # 校验 plugin.json 合法
55
+ ```
56
+
57
+ 装进 LinkDesk 后,设置页左侧出现「我的插件」分组,右侧自动渲染出这三个控件——**布尔变开关、枚举变下拉、数字变输入框**。你没写一行界面代码。
58
+
59
+ ---
60
+
61
+ ## 二、第 2 步(可选):让它长得更像样
62
+
63
+ | 想要的效果 | 加什么 |
64
+ |:--|:--|
65
+ | **换一个更合适的控件**(取色器 / 滑杆 / 文件选择…) | `uiHint`——见下表 |
66
+ | 同一分组里再分小标题 | `group`——同 `group` 值的几条会归到一个二级标题下 |
67
+ | 下拉选项**显示短标签**、鼠标悬停看全句 | `enum` + `enumDescriptions`,并配 `uiHint: "segmented"` |
68
+
69
+ **`uiHint` 已知值**(未知值会降级回按 `type` 默认渲染,不会报错):
70
+
71
+ | `uiHint` | 渲染成 |
72
+ |:--|:--|
73
+ | `"color"` | 取色器 |
74
+ | `"slider"` | 滑杆(配 `minimum` / `maximum` / `step`,不写就按区间推) |
75
+ | `"segmented"` | 分段单选(配 `enum` + `enumDescriptions`) |
76
+ | `"fontFamily"` | 字体族选择(`monoOnly: true` 只列等宽族) |
77
+ | `"fontSize"` / `"file"` / `"directory"` / `"image"` | 对应专用控件 |
78
+
79
+ ```jsonc
80
+ "my-plugin.accent": {
81
+ "type": "string", "default": "#3B82F6",
82
+ "uiHint": "color", "description": "强调色"
83
+ },
84
+ "my-plugin.level": {
85
+ "type": "number", "default": 50,
86
+ "uiHint": "slider", "minimum": 0, "maximum": 100, "step": 5,
87
+ "description": "灵敏度"
88
+ }
89
+ ```
90
+
91
+ > ⚠️ **没有 `"integer"`**——整数也用 `"number"`(配 `step: 1`)。
92
+
93
+ ---
94
+
95
+ ## 三、第 3 步:在代码里读它
96
+
97
+ **读写一律走 `window.linkdesk.configuration`**(禁止 `localStorage`):
98
+
99
+ ```ts
100
+ // 读一次
101
+ const autoSave = await window.linkdesk.configuration.get<boolean>("my-plugin.autoSave");
102
+
103
+ // 订变化(用户在设置页一改,你这边立刻收到)
104
+ useEffect(() => {
105
+ return window.linkdesk.configuration.onChange<number>("my-plugin.refreshInterval", (ms) => {
106
+ restartTimer(ms);
107
+ });
108
+ }, []);
109
+ ```
110
+
111
+ **别忘了退订**:`onChange` 的返回值就是退订函数——在 `useEffect` 里 `return` 它(订阅一律挂在 effect 上,不挂模块顶层)。
112
+
113
+ > 想让"用户改了设置 → 界面上好几处同时跟着变",见 [18-区域间互动 §配方 D](18-区域间互动.md)。
114
+
115
+ ---
116
+
117
+ ## 四、进阶:给**别人的**配置项提建议值
118
+
119
+ 如果你想让某个键"默认值更好",但**那个键不是你的**(比如给内置编辑器的字号提个建议),用 `configurationDefaults`:
120
+
121
+ ```jsonc
122
+ {
123
+ "contributes": {
124
+ "configurationDefaults": {
125
+ "editor.fontSize": 14
126
+ }
127
+ }
128
+ }
129
+ ```
130
+
131
+ | 对比 | `configuration` | `configurationDefaults` |
132
+ |:--|:--|:--|
133
+ | 定义**自己的**设置项 | ✅ | ❌ |
134
+ | 给**别人的**键提默认值 | ❌ | ✅ |
135
+ | 用户手动设过之后 | 用户值优先 | 用户值优先(弱默认只在用户从未设过时生效) |
136
+
137
+ ---
138
+
139
+ ## 五、常见错误
140
+
141
+ | 症状 | 病根 | 正确做法 |
142
+ |:--|:--|:--|
143
+ | 设置项没出现在设置页 | `key` 没带 `<pluginId>.` 前缀,或漏了 `default` | key 一律 `my-plugin.xxx`;`type`/`default`/`description` 三个都得有 |
144
+ | 改完设置要重启才生效 | 只 `get` 了一次,没订变化 | `configuration.onChange` |
145
+ | `npm run validate` 报错 | `configuration` 写成了数组 / 少了 `properties` | 形状照本页 §一 抄 |
146
+ | 值重启就丢 | 用了 `localStorage` 或组件 state | `configuration.set` |
147
+ | 想要一个整页设置界面,但只是改字号 | 走错门了 | 本页三步就够;整页替代才去 [10](10-如何造一个设置插件.md) |
148
+
149
+ ---
150
+
151
+ ## 六、相关篇目
152
+
153
+ | 你要做的 | 读这篇 |
154
+ |:--|:--|
155
+ | 完整字段表 / 更多示例 | [03-插件contributes规范](03-插件contributes规范.md) |
156
+ | 做一整套设置 UI(替代壳的设置页) | [10-如何造一个设置插件](10-如何造一个设置插件.md) |
157
+ | 配置变了怎么让多个区域跟着变 | [18-区域间互动](18-区域间互动.md) |
158
+ | 设置页长什么样、有哪些控件 | [19-组件速查](19-组件速查.md) |
159
+ | 字段类型定义 | `plugin.schema.json` |