@linkdesk/plugin-docs 0.1.57 → 0.1.58
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.
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -1,850 +1,850 @@
|
|
|
1
|
-
# 插件 UI 写法规约
|
|
2
|
-
|
|
3
|
-
> **一句话:核心已提供标准组件和注册表——不要手写轮子。手写 = 风格不一致 + 以后归一化时要拆。**
|
|
4
|
-
> 写插件前扫一眼,避免同类返工。
|
|
5
|
-
> **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 1. 右键菜单 → `<ContextMenu>` + MenuRegistry
|
|
10
|
-
|
|
11
|
-
**❌ 禁止:** 手写 `<div className="my-menu">` + `useState` + click-outside listener。
|
|
12
|
-
|
|
13
|
-
**✅ 正确:**
|
|
14
|
-
```json
|
|
15
|
-
// ① 声明菜单项——plugin.json contributes.menus(首选,声明式)
|
|
16
|
-
{
|
|
17
|
-
"contributes": {
|
|
18
|
-
"menus": {
|
|
19
|
-
"editorContext": [
|
|
20
|
-
{ "command": "myPlugin.copy", "group": "navigation" },
|
|
21
|
-
{ "command": "myPlugin.clear", "group": "edit" }
|
|
22
|
-
]
|
|
23
|
-
}
|
|
24
|
-
}
|
|
25
|
-
}
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
```tsx
|
|
29
|
-
// 运行时动态注册(等价)——window.linkdesk.menu.registerItems(menuId, pluginId, items)
|
|
30
|
-
window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
|
|
31
|
-
{ command: "myPlugin.copy", group: "navigation" },
|
|
32
|
-
{ command: "myPlugin.clear", group: "edit" },
|
|
33
|
-
]);
|
|
34
|
-
|
|
35
|
-
// ② 使用统一组件——MenuId 是开放 string,直接写字符串字面量
|
|
36
|
-
<ContextMenu menuId="editorContext" />
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
**理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when 条件过滤。手写做不到这四种失焦。
|
|
40
|
-
|
|
41
|
-
**MenuId 是开放 string(`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)——插件声明任意字符串即契约,无需壳加代码。** 壳内置注册点(MENU_SLOTS 常量表):
|
|
42
|
-
|
|
43
|
-
| MenuId(字符串字面量) | 场景 |
|
|
44
|
-
|---|---|
|
|
45
|
-
| `commandPalette` | Ctrl+Shift+P 命令面板 |
|
|
46
|
-
| `tabContext` | 标签栏标签右键 |
|
|
47
|
-
| `panelViewContext` | 面板标签栏右键(位置/对齐子菜单 + 视图显隐列表) |
|
|
48
|
-
| `editorContext` | 标签页主内容区右键 |
|
|
49
|
-
| `extensionGear` | 底部齿轮菜单(设置/命令面板/主题选择器) |
|
|
50
|
-
| `marketplaceItemGear` | 插件市场条目齿轮(启用/禁用/卸载) |
|
|
51
|
-
| `menuBar` | ☰ 汉堡菜单栏 |
|
|
52
|
-
| `panel` | 菜单栏「面板」菜单 |
|
|
53
|
-
| `fileContext` | 文件树右键 |
|
|
54
|
-
| `cardContext` | 卡片右键 |
|
|
55
|
-
| `quickSendContext` | 快捷发送药丸右键 |
|
|
56
|
-
| `iconBar` | 图标栏右键 |
|
|
57
|
-
| `settingItemGear` | 设置项齿轮(Settings Editor 行 hover) |
|
|
58
|
-
| `viewTitleContext` | 侧栏视图 title 右键(折叠/重置位置/视图同组) |
|
|
59
|
-
|
|
60
|
-
新增右键场景 → MenuId 开放 string 直接声明即可(如 `"myMenu"`):`contributes.menus.myMenu` 声明 + `<ContextMenu menuId="myMenu" />` 消费——**零壳改动**(插件独立铁律)。壳若要在此场景提供统一渲染点才需在 MENU_SLOTS 加条目。
|
|
61
|
-
|
|
62
|
-
---
|
|
63
|
-
|
|
64
|
-
## 2. 浮层 / 弹窗 → `createPortal`
|
|
65
|
-
|
|
66
|
-
**❌ 禁止:** 弹窗嵌在组件树的深层 div 里。
|
|
67
|
-
|
|
68
|
-
**✅ 正确:**
|
|
69
|
-
```tsx
|
|
70
|
-
import { createPortal } from "react-dom";
|
|
71
|
-
|
|
72
|
-
return createPortal(
|
|
73
|
-
<div className="my-dialog">{/* ... */}</div>,
|
|
74
|
-
document.body // ← 关键:渲染到 body
|
|
75
|
-
);
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed` 也看不见。render 到 `document.body` 才能突破组件树限制。
|
|
79
|
-
|
|
80
|
-
---
|
|
81
|
-
|
|
82
|
-
## 3. 持久化 → `window.linkdesk.configuration`(plugin.json contributes.configuration 声明)
|
|
83
|
-
|
|
84
|
-
**❌ 禁止:** `localStorage.setItem()` / `PreferenceService.loadPrefs()` / 手写文件读写 / `import ... from "@src/core/..."`。
|
|
85
|
-
|
|
86
|
-
**✅ 正确——走 `window.linkdesk.configuration`(插件通信铁律:只走 window.linkdesk.*,禁止 import @src/core):**
|
|
87
|
-
```tsx
|
|
88
|
-
// 读配置(Promise——值运行时动态)
|
|
89
|
-
useEffect(() => {
|
|
90
|
-
window.linkdesk.configuration.get<boolean>("myPlugin.showLineNumbers").then((v) => {
|
|
91
|
-
setShowLineNumbers(v);
|
|
92
|
-
});
|
|
93
|
-
}, []);
|
|
94
|
-
|
|
95
|
-
// 写配置
|
|
96
|
-
await window.linkdesk.configuration.set("myPlugin.showLineNumbers", true);
|
|
97
|
-
|
|
98
|
-
// 订阅变更——返回 unsubscribe,unmount 调用
|
|
99
|
-
useEffect(() => {
|
|
100
|
-
return window.linkdesk.configuration.onChange<boolean>("myPlugin.showLineNumbers", (v) => {
|
|
101
|
-
setShowLineNumbers(v);
|
|
102
|
-
});
|
|
103
|
-
}, []);
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
**plugin.json 声明配置项:**
|
|
107
|
-
```json
|
|
108
|
-
{
|
|
109
|
-
"contributes": {
|
|
110
|
-
"configuration": {
|
|
111
|
-
"title": "My Plugin",
|
|
112
|
-
"properties": {
|
|
113
|
-
"myPlugin.showLineNumbers": {
|
|
114
|
-
"type": "boolean",
|
|
115
|
-
"default": true,
|
|
116
|
-
"description": "显示行号"
|
|
117
|
-
}
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
}
|
|
121
|
-
}
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
**理由:** 壳自动持久化 + 重启恢复 + Settings Editor 自动渲染。手写 localStorage → 丢掉 Settings Editor 集成 + 下一个持久化 bug。
|
|
125
|
-
|
|
126
|
-
---
|
|
127
|
-
|
|
128
|
-
## 4. 快捷键 → 两轨道:声明式(非文本键)+ 池侧自处理(文本键/焦点绑定键)
|
|
129
|
-
|
|
130
|
-
快捷键有**两条轨道**,选哪条取决于键的性质。**选错轨道 = 键死或劫持全池**(教训)。
|
|
131
|
-
|
|
132
|
-
### 4.1 轨道一:`contributes.keybindings`(设置面板可见)——**仅限非文本键**
|
|
133
|
-
|
|
134
|
-
**❌ 禁止:** 把 `ctrl+c` / `ctrl+v` / `ctrl+x` / `ctrl+a` / `f2` 等**文本编辑键**写进 `contributes.keybindings`。
|
|
135
|
-
|
|
136
|
-
**✅ 正确:**(非文本键——如 `ctrl+k` / `ctrl+shift+e` / `f5`)
|
|
137
|
-
```json
|
|
138
|
-
{
|
|
139
|
-
"contributes": {
|
|
140
|
-
"keybindings": [
|
|
141
|
-
{
|
|
142
|
-
"key": "ctrl+k",
|
|
143
|
-
"command": "myPlugin.clear",
|
|
144
|
-
"when": "activeEditor == 'myPlugin'"
|
|
145
|
-
}
|
|
146
|
-
]
|
|
147
|
-
}
|
|
148
|
-
}
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
**理由(为什么文本键是雷):** 声明/注册的键会同步进主进程 keyCache → `before-input-event` 命中即**无条件吞键**(不认 when、不认可编辑状态、不认 handler 是否存在)。壳注册一个 `ctrl+c` 就吞掉全池所有输入框/Monaco 的原生 `ctrl+c`。文本键正解 = 轨道二。
|
|
152
|
-
|
|
153
|
-
### 4.2 轨道二:池侧自处理(容器 onKeyDown)——文本键 + 焦点绑定键正解
|
|
154
|
-
|
|
155
|
-
**✅ 正确:** 组件自己的键盘交互在自己的**容器 `onKeyDown`** 里处理:
|
|
156
|
-
|
|
157
|
-
```tsx
|
|
158
|
-
<div
|
|
159
|
-
tabIndex={0} // 让容器可聚焦——点击子项时浏览器把焦点给最近可聚焦祖先
|
|
160
|
-
onKeyDown={(e) => {
|
|
161
|
-
if (e.key === "F2") { e.preventDefault(); startRename(); }
|
|
162
|
-
}}
|
|
163
|
-
>
|
|
164
|
-
{items}
|
|
165
|
-
</div>
|
|
166
|
-
```
|
|
167
|
-
|
|
168
|
-
**为什么是正解:** 池内所有插件共用一个 document——**DOM 焦点天然分区**。容器聚焦才收键,Monaco 聚焦收不到,多插件各干各的 `ctrl+c` 互不打扰。不需要 when、不需要冲突检测。文件树剪贴板键 = 共享 `useClipboardKeys` hook + 命令链同款。剪贴板相关键可复用 `src/pool/hooks/useClipboardKeys`(`onCopy`/`onCut`/`onPaste` 声明式回调,机制一处实现一处修)。
|
|
169
|
-
|
|
170
|
-
**❌ 反模式(红字):** `document.addEventListener("keydown", ...)` / `window.addEventListener("keydown", ...)` = **全局劫持**——绕过分区前提,插件有活动会话时劫持全池同键(串口 F2 曾劫持文件树 F2)。**`tabIndex` + 容器 `onKeyDown` 才是焦点分区正解**;非焦点元素不触发,可加 `tabIndex={0}` 承接。
|
|
171
|
-
|
|
172
|
-
🔴 **这条反模式有腿了(2026-09-20,SDK 0.1.46 起)**:`linkdesk-plugin-sdk lint` 的 `linkdesk/no-global-key-listener` 腿机械拦截 window/document 的 keydown/keyup **字面量**监听,报错文案直接给正解与豁免写法。确需全局抓键的正当形态(如快捷键录制器要 capture 抓原始键)走标准 disable 注释+理由——判据本身无白名单。
|
|
173
|
-
|
|
174
|
-
**注意:** 轨道二键**不进快捷键设置面板**——面板只显示 KeybindingRegistry 绑定(轨道一)。这是设计取舍(注册即吞池,见 4.1),不是 bug。
|
|
175
|
-
|
|
176
|
-
### 4.3 剪贴板三选一通道表
|
|
177
|
-
|
|
178
|
-
| 你想复制的 | 通道 | 例子 |
|
|
179
|
-
|---|---|---|
|
|
180
|
-
| 可编辑元素内文本(input/textarea/Monaco) | **浏览器原生**——什么都不用写 | 输入框内 Ctrl+C/V |
|
|
181
|
-
| 任意文本 | `window.linkdesk.clipboard.writeText` | 复制选中文本到系统剪贴板 |
|
|
182
|
-
| 文件/路径列表 | `window.linkdesk.clipboard.writeFileList` | 文件树复制 → 资源管理器可粘贴(CF_HDROP) |
|
|
183
|
-
|
|
184
|
-
**注意:** 可编辑元素走浏览器原生,**不要**声明快捷键也不要拦截——Electron/Chromium 自动接系统剪贴板。
|
|
185
|
-
|
|
186
|
-
---
|
|
187
|
-
|
|
188
|
-
## 5. 颜色 → CSS 变量 `var(--xxx)`
|
|
189
|
-
|
|
190
|
-
**❌ 禁止:** 硬编码 `#0078d4` / `#1e1e1e` / `#ffffff`。
|
|
191
|
-
|
|
192
|
-
**✅ 正确:**
|
|
193
|
-
```css
|
|
194
|
-
.my-element {
|
|
195
|
-
color: var(--text-primary);
|
|
196
|
-
background: var(--bg-input);
|
|
197
|
-
border: 1px solid var(--border);
|
|
198
|
-
}
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
**理由:** 换主题后硬编码颜色不变 → 暗色主题下白字白底不可见。见 `src/index.css` 查看所有可用 CSS 变量。
|
|
202
|
-
|
|
203
|
-
---
|
|
204
|
-
|
|
205
|
-
## 6. 文字 → `t()` 国际化
|
|
206
|
-
|
|
207
|
-
**❌ 禁止:** 绕过 `t()` 硬编码显示字符串(`<button>发送</button>` / `<button>Send</button>`)。
|
|
208
|
-
|
|
209
|
-
**✅ 正确:**
|
|
210
|
-
```tsx
|
|
211
|
-
import { useTranslation } from "react-i18next";
|
|
212
|
-
const { t } = useTranslation();
|
|
213
|
-
<button>{t("发送")}</button> // i18n key = 插件 UI 原文(中文插件用中文,英文/法文插件用自己的语言)
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
---
|
|
217
|
-
|
|
218
|
-
## 7. 侧栏列表选中条目 → `onMouseDown`(不是 `onClick`)
|
|
219
|
-
|
|
220
|
-
**❌ 禁止:** 侧栏垂直列表中选中条目用 `onClick`。
|
|
221
|
-
|
|
222
|
-
**✅ 正确:**
|
|
223
|
-
```tsx
|
|
224
|
-
<div
|
|
225
|
-
className={`my-list-item${isActive ? " active" : ""}`}
|
|
226
|
-
onMouseDown={() => onSelect(item.id)}
|
|
227
|
-
>
|
|
228
|
-
<span>{item.label}</span>
|
|
229
|
-
</div>
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
**理由:** 侧栏条目垂直紧邻——快速点击时 mousedown 在条目 A、mouseup 滑到条目 B。浏览器 `click` 事件规范:mousedown 和 mouseup 落在不同元素 → click 投递到两者的共同祖先 → React 在祖先上找不到 handler → 静默丢失。`onMouseDown` 只关注按下位置,不要求释放在同一元素——消除快速点击丢事件。
|
|
233
|
-
|
|
234
|
-
**对标 VS Code:** Explorer 文件树选文件用 `onMouseDown`,不是 `onClick`。这是经过千万用户验证的模式,不要自己设计。
|
|
235
|
-
|
|
236
|
-
**适用场景:** 侧栏中任何垂直排列、条目间距小的可点击列表——会话列表、文件树、数据库连接、MQTT 主题、设备列表等。
|
|
237
|
-
|
|
238
|
-
**子元素的处理:** 条目内的操作按钮/输入框需要加 `onMouseDown={(e) => e.stopPropagation()}` 防止误触父条目的选中:
|
|
239
|
-
```tsx
|
|
240
|
-
<button
|
|
241
|
-
onMouseDown={(e) => e.stopPropagation()}
|
|
242
|
-
onClick={(e) => { e.stopPropagation(); handleDelete(); }}
|
|
243
|
-
>
|
|
244
|
-
✕
|
|
245
|
-
</button>
|
|
246
|
-
```
|
|
247
|
-
|
|
248
|
-
---
|
|
249
|
-
|
|
250
|
-
## 8. 插件自有数据模型 → `Emitter` 响应式模式
|
|
251
|
-
|
|
252
|
-
**❌ 禁止:** command handler 里改 model 后手动调 `rerender()` / `setVersion()` / 传 `treeVersion` prop。
|
|
253
|
-
|
|
254
|
-
**✅ 正确——Web 标准 `EventTarget`(零核心 import,插件自有类直接继承):**
|
|
255
|
-
```typescript
|
|
256
|
-
class MyModel extends EventTarget {
|
|
257
|
-
private _items: Item[] = [];
|
|
258
|
-
|
|
259
|
-
add(item: Item): void {
|
|
260
|
-
this._items.push(item);
|
|
261
|
-
this.dispatchEvent(new CustomEvent("change")); // ← 每个改状态的方法末尾 dispatch
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
remove(id: string): void {
|
|
265
|
-
this._items = this._items.filter(i => i.id !== id);
|
|
266
|
-
this.dispatchEvent(new CustomEvent("change"));
|
|
267
|
-
}
|
|
268
|
-
}
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
```tsx
|
|
272
|
-
// 组件 mount 时订阅,unmount 清理
|
|
273
|
-
function MyView({ model }: { model: MyModel }) {
|
|
274
|
-
const [version, setVersion] = useState(0);
|
|
275
|
-
|
|
276
|
-
useEffect(() => {
|
|
277
|
-
const onChange = () => setVersion(v => v + 1);
|
|
278
|
-
model.addEventListener("change", onChange);
|
|
279
|
-
return () => model.removeEventListener("change", onChange); // unmount 自动注销
|
|
280
|
-
}, [model]);
|
|
281
|
-
|
|
282
|
-
const items = useMemo(() => computeItems(model), [model, version]);
|
|
283
|
-
// ...
|
|
284
|
-
}
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
**理由:** 三次时序 bug(badge 0 / when 失效 / 刷新不更新树)根因都是 module 级 command handler 改了 mutable model,React 感知不到。model 自己通知变更(`EventTarget`/`CustomEvent` 是 Web 标准,不需要壳的 `Emitter`)——handler 只改 model,不碰 React。
|
|
288
|
-
|
|
289
|
-
**适用场景:** 插件有 module 级 command handler 需要改数据后触发 UI 刷新。
|
|
290
|
-
|
|
291
|
-
**⚠️ 插件禁止 `import { Emitter } from "@src/core/CoreEvents"`——那是壳内部实现(插件通信铁律 + ESLint `noCoreImportInPlugin` error 级拦截)。插件自有 model 用 Web 标准 `EventTarget`;插件与插件/壳之间的事件走 `window.linkdesk.events`(见 `07-插件间通信.md`)。**
|
|
292
|
-
|
|
293
|
-
---
|
|
294
|
-
|
|
295
|
-
## 9. 系统 UI 浮层 → linkdesk API(quickPick / notifications / dialog)
|
|
296
|
-
|
|
297
|
-
**❌ 禁止:** 手写选择器弹层 / `window.alert()` / `window.confirm()` / `import ... from "@src/core/..."`。
|
|
298
|
-
|
|
299
|
-
**✅ 正确:**
|
|
300
|
-
```tsx
|
|
301
|
-
// 选择器——window.linkdesk.quickPick.show({ items, placeholder, prefix })
|
|
302
|
-
const picked = await window.linkdesk.quickPick.show({
|
|
303
|
-
placeholder: "选择目标会话",
|
|
304
|
-
items: [
|
|
305
|
-
{ label: "会话 A", description: "/dev/ttyUSB0" },
|
|
306
|
-
{ label: "会话 B", description: "/dev/ttyUSB1" },
|
|
307
|
-
],
|
|
308
|
-
});
|
|
309
|
-
|
|
310
|
-
// 通知——window.linkdesk.notifications.show(message, { type })
|
|
311
|
-
await window.linkdesk.notifications.show("已连接", { type: "info" });
|
|
312
|
-
await window.linkdesk.notifications.show("校验失败", { type: "error" });
|
|
313
|
-
|
|
314
|
-
// 确认 / 提示 / 文件选择——window.linkdesk.dialog
|
|
315
|
-
const ok = await window.linkdesk.dialog.confirm("确定删除该会话?");
|
|
316
|
-
await window.linkdesk.dialog.alert("版本冲突,已跳过");
|
|
317
|
-
const file = await window.linkdesk.dialog.openFile({
|
|
318
|
-
filters: [{ name: "DXF 文件", extensions: ["dxf"] }],
|
|
319
|
-
});
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
**理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效。完整签名见 `contracts/linkdesk.d.ts`。
|
|
323
|
-
|
|
324
|
-
> ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
|
|
325
|
-
> 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
|
|
326
|
-
> 2. **同来源常驻有配额**——按 `options.source` 分组,每组常驻最多 5 条,超出顶掉同来源最老的。刷屏不会堆成墙,但**也别指望靠通知留长期记录**。
|
|
327
|
-
> 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板;**也别指望有第二呈现面**——通知只有铃铛这一个面(2026-10-01 用户指令重申:右下角「自动消失小卡」这类第二面长过两次、两次都被删)。
|
|
328
|
-
|
|
329
|
-
**通知主动作按钮(`notifications.show` 的 `actions`):** 失败 / 需要用户行动的通知可带 `actions` 按钮数组——点击走**命令系统**执行(对标 VS Code `showErrorMessage(msg, { title, command })` 动作)。命令 handler 由插件自注册(`commands.registerCommand`):
|
|
330
|
-
|
|
331
|
-
```tsx
|
|
332
|
-
// 失败 toast + [重试]/[查看依赖]——command = 插件自注册命令
|
|
333
|
-
await window.linkdesk.notifications.show("安装失败:无法连接源", {
|
|
334
|
-
type: "error", // error 类 toast 停留 8s(够读诊断);info/warning 停留 6s
|
|
335
|
-
actions: [
|
|
336
|
-
{ id: "retry", label: "重试", isPrimary: true, command: "myplugin.retryInstall" },
|
|
337
|
-
{ id: "deps", label: "查看依赖", command: "myplugin.openDeps" },
|
|
338
|
-
],
|
|
339
|
-
});
|
|
340
|
-
// 命令可带参——点击执行 command(...args)
|
|
341
|
-
await window.linkdesk.notifications.show("保存冲突", {
|
|
342
|
-
type: "warning",
|
|
343
|
-
actions: [{ label: "强制保存", command: "myplugin.saveForce", args: [filePath] }],
|
|
344
|
-
});
|
|
345
|
-
```
|
|
346
|
-
|
|
347
|
-
按钮文案 = 最终显示文本(壳不二次翻译);`isPrimary: true` = 主按钮(accent),不设 = 次级文本按钮。**不传 `actions` = 现状无按钮,零行为变化**。完整类型见 `contracts/linkdesk.d.ts`(`notifications.show` options 的 `actions`)。
|
|
348
|
-
|
|
349
|
-
**进度通知 + 长驻通知 + 来源身份:** `show` **一律返回句柄**(不是只有进度条才有)。三条最容易踩空的写法:
|
|
350
|
-
|
|
351
|
-
```tsx
|
|
352
|
-
// ① 进度通知——句柄驱动同一条通知(不会刷出 N 条)
|
|
353
|
-
const h = await window.linkdesk.notifications.show("正在下载…", {
|
|
354
|
-
progress: true, // 开真进度条;不传 percent = 不定态动画
|
|
355
|
-
source: "myplugin", // 见 ③
|
|
356
|
-
});
|
|
357
|
-
await h.update("正在下载…", 42); // 0-100;只传 message = 保持不定态
|
|
358
|
-
await h.finish("下载完成"); // 关闭进度条,可选补一条完成通知
|
|
359
|
-
// 或 await h.cancel(); // 直接关掉,不补完成通知
|
|
360
|
-
|
|
361
|
-
// ② 长驻通知——不自动消失,等用户点 ×(错误诊断类用)
|
|
362
|
-
await window.linkdesk.notifications.show("端口被占用,请关闭其他程序", {
|
|
363
|
-
type: "error",
|
|
364
|
-
persistent: true,
|
|
365
|
-
});
|
|
366
|
-
|
|
367
|
-
// ③ 来源身份——面板按它分组,每组常驻各 5 条配额
|
|
368
|
-
await window.linkdesk.notifications.show("同步失败", { source: "myplugin" });
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
**三个必须知道的点:**
|
|
372
|
-
|
|
373
|
-
1. **句柄是唯一钥匙**:一条通知**只能被创建它的那个句柄**更新/删除。别处 `show` 同文案 = 另一条通知,撤不掉对方。撤长驻通知(如失败的 `persistent`)就用它自己的句柄或让用户点 ×。
|
|
374
|
-
2. **`source` 必须自己报**:池是单进程共享 realm,所有插件共用同一个 `window.linkdesk`,preload **无法**知道这次 `show` 是哪个插件发的 ⇒ 只能作者显式传。**不传 → 全落「其他」组**;插件传自己的插件 id,壳自身域用 `app.<域>`。
|
|
375
|
-
3. **`persistent` 有配额**:每组(按 `source`)常驻最多 5 条,超出顶掉同来源最老的并给汇总提示。**长驻 ≠ 无限留档**——要留档写自己的文件。
|
|
376
|
-
|
|
377
|
-
> 完整的**行为契约**(不是签名,签名看 `contracts/linkdesk.d.ts`)在 [`01-插件API契约.md`](01-插件API契约.md) §3.2 的 `notifications` 行——本节只给写法,语义以那里为准。
|
|
378
|
-
|
|
379
|
-
**富内容确认框(`dialog.confirmContent`):** 要确认框里放**不止一行字**(表单 / 列表 / 截图 / 自定义排版)时用这条——**对话框是壳(居中、遮罩、Esc、焦点锁、点遮罩取消),内容由你的视图自画**(对标 VS Code「对话框是壳、内容插件定」):
|
|
380
|
-
|
|
381
|
-
```tsx
|
|
382
|
-
// 1) plugin.json 先声明这个内容的视图(contributes.views 的任意容器均可)
|
|
383
|
-
// 2) 代码里按「声明 id」寻址打开它
|
|
384
|
-
const ok = await window.linkdesk.dialog.confirmContent({
|
|
385
|
-
pluginId: "myplugin", // 内容归属插件(壳据此复合寻址)
|
|
386
|
-
viewId: "myplugin.confirmImport", // 内容视图声明 id
|
|
387
|
-
title: "导入确认", // 兜底标题——content 视图解析失败时壳回落纯文字确认
|
|
388
|
-
message: "将覆盖 3 个条目", // 兜底正文
|
|
389
|
-
payload: { files: ["a.ts", "b.ts"] }, // 不透明载荷:壳不解释,你的视图自己读
|
|
390
|
-
});
|
|
391
|
-
if (ok) { /* 用户确认 */ } // false = 取消 / 关闭
|
|
392
|
-
```
|
|
393
|
-
|
|
394
|
-
内容视图那一半(**同一份代码里的另一个视图**,读载荷 + 表态):
|
|
395
|
-
|
|
396
|
-
```tsx
|
|
397
|
-
// 你的内容视图组件里——挂载即打开,读一次够(每次开新弹窗都是全新挂载)
|
|
398
|
-
function MyConfirmContent() {
|
|
399
|
-
const data = window.linkdesk.dialogHost.current();
|
|
400
|
-
if (!data || data.open !== true) return null; // 防御:不白屏
|
|
401
|
-
const payload = data.content?.payload as MyPayload;
|
|
402
|
-
return (
|
|
403
|
-
<div>
|
|
404
|
-
{/* 正文排版、按钮全归你画 */}
|
|
405
|
-
<button onClick={() => window.linkdesk.dialogHost.cancel()}>取消</button>
|
|
406
|
-
<button onClick={() => window.linkdesk.dialogHost.confirm()}>确定</button>
|
|
407
|
-
</div>
|
|
408
|
-
);
|
|
409
|
-
}
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
**兜底是硬的**:`viewId` 解析不出来(视图没声明 / 声明插件没装)→ 壳**回落成纯文字确认框**(用 `title`/`message`),弹窗照样出、**不会静默死**。所以 `title`/`message` 别省。载荷经结构化克隆过 IPC,只能放可克隆的数据(不能放函数/React 元素)。结算只有 `dialogHost.confirm()` / `dialogHost.cancel()` 两条路——**别自己 `setState` 关弹窗**,壳不认。
|
|
413
|
-
|
|
414
|
-
---
|
|
415
|
-
|
|
416
|
-
## 10. 字号 → `--font-size-*` token + `--ui-scale`(度量体系归一化)
|
|
417
|
-
|
|
418
|
-
**❌ 禁止:** 插件文本字号写裸 `px`(`font-size: 14px`)——`check-font-scale-audit` 门禁(`npm run check`)机械拦截。
|
|
419
|
-
|
|
420
|
-
**✅ 正确:** 字号消费 `var(--font-size-*)`;行高 unitless(`1.5`)或 `calc(... * var(--ui-scale))`;固定上界(输入框/按钮/状态栏高)写 `calc(Npx * var(--ui-scale))` 随全局缩放。统一全局字号缩放(设置 `app.uiFontScale` 85–150%,恒显恒生效)。
|
|
421
|
-
|
|
422
|
-
**档位表**(100% 渲染 = `--ui-scale: 1`;引擎按缩放系数算好最终 px):
|
|
423
|
-
|
|
424
|
-
| 档 | 基准 px | 语义 |
|
|
425
|
-
|---|---|---|
|
|
426
|
-
| `--font-size-2xs` | 11 | 徽章/路径 |
|
|
427
|
-
| `--font-size-xs` | 12 | 次要文本/按钮/统计 |
|
|
428
|
-
| `--font-size-sm` | 13 | UI 主文本(对齐 VS Code 13px) |
|
|
429
|
-
| `--font-size-md` | 14 | 菜单/tab/文件树 name |
|
|
430
|
-
| `--font-size-lg` | 16 | 图标字形/内容图标(配 14px 文字) |
|
|
431
|
-
| `--font-size-xl` | 18 | 区标题 |
|
|
432
|
-
| `--font-size-2xl` | 22 | 行图标/大字 |
|
|
433
|
-
| `--font-size-3xl` | 28 | pd-name |
|
|
434
|
-
| `--font-size-4xl` | 30 | welcome-title |
|
|
435
|
-
|
|
436
|
-
**铁律 + 边界(对标档案 §五 图标裁决 / §六.2 monaco 孤岛拍板):**
|
|
437
|
-
- **独立显示图标不随字号比例**(装饰/品牌语义,与文本不直接相邻)——`.icon-btn .plugin-icon--codicon` 24 / `.plugin-icon--emoji` 24 / `.hamburger-btn` 20 / hero-icon 48 / 行图标 20 等,白名单豁免见 `scripts/check-font-scale-audit.mjs`。
|
|
438
|
-
- **内容级字号走 `contributes.configuration`**(如 `editor.fontSize`)——大文本区/编辑器内容由插件自有配置控制,不随 `--ui-scale`。
|
|
439
|
-
- **monaco 内容孤岛先例**:编辑器内容读 `editor.fontSize`,chrome(状态栏/面包屑)随全局——两轴正交,各管各的。
|
|
440
|
-
- **对齐规则**:现有 `NNpx` 迁移到档位按「+1 档」——`12→sm / 13→md / 11→xs / 10→2xs / 14→lg / 18→xl`(100% 即放大到新默认基线,对标 VS Code)。
|
|
441
|
-
|
|
442
|
-
---
|
|
443
|
-
|
|
444
|
-
## 11. token 契约——六域矩阵 + 诚实边界 + 数据纪律(.5)
|
|
445
|
-
|
|
446
|
-
> **一句话:** 写 UI 前先查 11.1 六域矩阵——用 `var(--*)` 的表单/控件/表面**自动跟随主题 + 玻璃 + 全局缩放**,零插件感知。做对靠推荐、做错靠门禁显红但 WARN、绕过靠标准 eslint-disable 知情声明(内容/品牌死色合法豁免,见 11.2)。
|
|
447
|
-
> 门禁 = `linkdesk-plugin-sdk lint`(`@linkdesk/plugin-sdk` 内置):eslint 规则腿 + 三 check 扫描腿双轨,15 项**全 WARN 永不 fail build/上传**——是建议不是封锁。作者项目根跑一次,违规即红 + 自解释修复文案。
|
|
448
|
-
|
|
449
|
-
### 11.1 token 六域矩阵——作者知道有哪些变量,才写得出「自动跟随」
|
|
450
|
-
|
|
451
|
-
| 域 | var() 键(完整清单永远以 `src/index.css` 为准) | 作者写法 | 门禁覆盖 |
|
|
452
|
-
|---|---|---|---|
|
|
453
|
-
| **颜色** | `--text-primary/--text-secondary/--text-muted`(文字色来源由 fontTone 控)+ `--bg-window/--bg-side-panel/--bg-card/--bg-input/--bg-selection` + `--accent/--accent-hover` | `color: var(--text-primary)` | `linkdesk/no-hardcoded-hex` |
|
|
454
|
-
| **表面** | `--bg-*` 表面填充 + `--surface-radius`(跟壳全局圆角滑杆) | `background: var(--bg-card)` | `linkdesk/no-hardcoded-hex` |
|
|
455
|
-
| **圆角** | `--radius-xs/sm/md/lg/xl/2xl` + `--surface-radius` | `border-radius: var(--radius-md)` | `linkdesk/no-hardcoded-radius`(border-radius 裸 px 即红) |
|
|
456
|
-
| **玻璃** | `--glass-blur/--glass-saturate/--glass-tint/--glass-morph/--glass-specular…`(`src/index.css` 全组) | `backdrop-filter: blur(var(--glass-blur)) …` | 契约引导——组合形态,逐条门禁管不住 |
|
|
457
|
-
| **字号** | `--font-size-2xs … 4xl` + `--ui-scale`(`app.uiFontScale` 缩放轴,档位表见 §10) | `font-size: var(--font-size-md)` / em/rem | `check-font-scale`(check 腿——字号裸 px 即红) |
|
|
458
|
-
| **字体族** | `--font-ui` / `--font-mono` | `font-family: var(--font-ui)` | 契约引导(作者合法自选字体) |
|
|
459
|
-
|
|
460
|
-
`var(--*)` = 换主题/玻璃/全局缩放自动跟随,零插件感知——**这正是 @linkdesk/ui 控件层「零思考跟随」的底层原因**——控件全部写在 token 上,插件 `npm i @linkdesk/ui` 消费即跟随。控件复用统一从 `@linkdesk/ui` import(见 §速查),不手写轮子。
|
|
461
|
-
|
|
462
|
-
### 11.2 诚实边界 / 知情绕行——内容与品牌色可以有自己天空
|
|
463
|
-
|
|
464
|
-
**门禁三档(07 §六):** 推荐(照抄即对)/ 警告(15 项自解释,红但 **WARN 永不 fail**)/ 知情绕行(标准 eslint-disable 声明带理由)。**任何生态都管不住作者硬写死颜色**——VS Code 也有不跟随主题的扩展。门禁做的是把「做对」变默认、「做错」变显式红但可**知情绕行**:注释带理由 = 浏览器危险站点「仍要访问」的知情确认,不是静默关灯。
|
|
465
|
-
|
|
466
|
-
**合法豁免类别:** var() 回退 hex(`color: var(--x, #fff)` = 合规形态,不拦)/ 取色器色板 / canvas 绘图 / 引擎区 / **内容画布视图级豁免**。
|
|
467
|
-
|
|
468
|
-
**内容 vs chrome 边界(愤怒的小鸟考核实证):** 游戏 / 数据可视化 / canvas 主区 = **内容世界,不是 UI chrome**——UI chrome 跟主题走(var()/t()/@linkdesk/ui),内容可以有自己天空(草地/血条红/天空蓝不必跟主题)。作者**视图级一次声明豁免**,门禁对内容区不逐条亮灯(一个游戏 5-10 处硬编码逐条 disable 太吵):
|
|
469
|
-
|
|
470
|
-
```tsx
|
|
471
|
-
/* eslint-disable linkdesk/no-hardcoded-hex, linkdesk/no-hardcoded-radius -- 内容画布:游戏主区自绘 */
|
|
472
|
-
export function GameBoard() {
|
|
473
|
-
return <canvas /* 画蓝天草地血条红——内容世界,不是 UI chrome */ />;
|
|
474
|
-
}
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
```tsx
|
|
478
|
-
// 行级知情绕行(品牌死色徽标——只豁免本行,其他行照样拦)
|
|
479
|
-
// eslint-disable-next-line linkdesk/no-hardcoded-hex -- 品牌固定色徽标
|
|
480
|
-
const PRO_BADGE = <span style={{ color: "#ff6b00" }}>PRO</span>;
|
|
481
|
-
```
|
|
482
|
-
|
|
483
|
-
```css
|
|
484
|
-
/* css 里同款格式(check 脚本认)——取色器色板固定值,本行豁免 */
|
|
485
|
-
/* eslint-disable-next-line linkdesk/no-hardcoded-hex -- 取色器色板 */
|
|
486
|
-
.swatch--brand { background: #ffd700; }
|
|
487
|
-
```
|
|
488
|
-
|
|
489
|
-
**语义:** 命中豁免的行**整体静默**不亮灯(对齐 eslint 原生 suppress——disable 声明后不逐条报);**无声明 = 未处理偏离**,`linkdesk-plugin-sdk lint` 报告正常亮 WARN。**不是新语法**——与壳现有 `no-hardcoded-hex` 报错建议格式同款。**背景不被玻璃化是机制层天然成立**——backdrop-filter 只刷壳表面元素,不套插件视图根节点,作者画的内容本就不被玻璃化。
|
|
490
|
-
|
|
491
|
-
### 11.3 非 CSS 引擎适配——翻译桥(引擎自渲染不走 CSS 变量)
|
|
492
|
-
|
|
493
|
-
monaco 式引擎自渲染(canvas / WebGL / 富文本引擎同理)不消费 CSS 变量——要跟随主题走**翻译桥**:订阅主题变更 → 翻译成引擎自己的 theme API。先例:`src/services/theme-sync.ts`(住在 **editor 插件自己的仓** `Encaron/linkdesk-plugin-editor`——起发货插件源码不在壳仓):
|
|
494
|
-
|
|
495
|
-
```ts
|
|
496
|
-
// 订阅主题变更(事件可能先于 mount → 顶层注册或 active 守卫,见 11.5)
|
|
497
|
-
const off = window.linkdesk.events.on("theme:changed", () => {
|
|
498
|
-
engine.updateTheme(translateTheme()); // 把你的 token → 引擎 theme 对象
|
|
499
|
-
});
|
|
500
|
-
```
|
|
501
|
-
|
|
502
|
-
monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开,不落死边界**——未来可能彻底适配主题。
|
|
503
|
-
|
|
504
|
-
### 11.4 插件私有数据通道——自建设置界面 / 自管存档时选通道
|
|
505
|
-
|
|
506
|
-
作者自建设置 UI / 自管存档(不走壳设置页声明)时,数据落地按语义选:
|
|
507
|
-
|
|
508
|
-
| 通道 | 适用 | 示例 |
|
|
509
|
-
|---|---|---|
|
|
510
|
-
| `window.linkdesk.pluginState`(**首选**) | 插件自管存档——集中缓存 + 文件持久化(正牌 API:`get/set/onChange(pluginId, key)`) | 游戏分数 / 关卡进度 / 高分榜 / 皮肤偏好 |
|
|
511
|
-
| `window.linkdesk.configuration.set(key)` 私有命名空间 | 跟设置语义走、可被其他插件/主题读、**要进壳设置页 UI**(声明 contributes.configuration 即进) | 插件参数(声明即 UI;不声明则纯私有键照写持久化) |
|
|
512
|
-
| `window.linkdesk.filesystem` | 大文件 / 二进制 / 跨插件共享 | 截图导出 / 存档文件 |
|
|
513
|
-
| `localStorage` | 补充——池内临时缓存(无跨机、无壳管理) | 会话内高频临时值 |
|
|
514
|
-
|
|
515
|
-
**铁律:不声明 `contributes.configuration` 的私有键不进壳设置页 UI**——`config.set` 对无 schema 键照写持久化(仅 enum 才过滤),作者要壳设置页就声明贡献、要自建界面就私有键直存,两不干扰。
|
|
516
|
-
|
|
517
|
-
### 11.5 壳纪律转移清单——非 UI 写法的纪律按落点沉对应文档
|
|
518
|
-
|
|
519
|
-
| 纪律 | 落点规范 |
|
|
520
|
-
|---|---|
|
|
521
|
-
| 插件唯一入口 `window.linkdesk.*`,**禁止 import @src/core(含 @src 任何子路径)** | `01-插件API契约.md` |
|
|
522
|
-
| 配置**订阅不读一次**(linkdesk.configuration 事件驱动) | 本文件 §3 |
|
|
523
|
-
| linkdesk.events 订阅**时序**——事件可能先于 mount(IPC 缓冲)→ 顶层注册或 active 守卫 | `02-插件生命周期.md` |
|
|
524
|
-
| **不写死其他插件 ID**(差异性行为走 plugin.json 声明字段,Registry 模式消费) | `03-插件contributes规范.md` |
|
|
525
|
-
| 配置键**必给 default** | `06-plugin.json规范.md` |
|
|
526
|
-
| **只用文档化 API 命名空间**(禁 linkdesk.xxx 未文档化随手挂) | `01-插件API契约.md` |
|
|
527
|
-
| 控件统一走 `@linkdesk/ui`(内置控件从 npm 包 import,禁止 `@src/components/shared/*`) | 本文件 §速查 |
|
|
528
|
-
|
|
529
|
-
---
|
|
530
|
-
|
|
531
|
-
## 12. CSS 类名——自己的元素用自有前缀,宿主保留名不要「借用」
|
|
532
|
-
|
|
533
|
-
**先记住一件事:插件视图的样式表不是你自己独占的。** 同一个窗口里同时加载着宿主的样式、共享组件
|
|
534
|
-
(`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
|
|
535
|
-
就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
|
|
536
|
-
|
|
537
|
-
🔴 **引用侧也有腿了(2026-09-20,SDK 0.1.46 起)**:TSX `className` **字面量**里引用的本插件前缀类名,必须能在本仓 CSS(含 scoped 规则)里找到定义——`linkdesk/no-reserved-class-name` 家族新判据机械把关。头号根因 = CSS 块注释里写 `--text-*/` 这类文本:`*/` 把注释**提前闭合**,残渣黏住下一条规则把它整条吞掉(生态首例,样式静默丢失零报错);文案列三种常见根因(拼错/漏 import/注释吞规则)。动态拼接(模板插值 / clsx / 变量)跳过并计数。
|
|
538
|
-
|
|
539
|
-
**三条纪律:**
|
|
540
|
-
|
|
541
|
-
1. **给自己的元素起的类名,必须以 `pluginId` 加连字符开头**——`settings-*`、`editor-*`、`file-tree-*`……
|
|
542
|
-
`pluginId` 就是你 `plugin.json` 里声明的那个 id(官方插件统统这么做)。**别用缩写**:`ms-`、
|
|
543
|
-
`mpd-` 这类简写写法**已经废弃**——缩写不保证唯一,两个插件各自缩写成 `ms-` 就撞在一起了;
|
|
544
|
-
而 `pluginId` 的唯一性由发布流程保证(发布后不可变),拿它当前缀是免费的防撞。
|
|
545
|
-
2. **`@keyframes` 的名字一样要带前缀**(`file-tree-fadeIn`),并且**改名字时同笔改 `animation:` 的引用**——
|
|
546
|
-
关键帧名与类名一样是全局标识符,重名时后加载的那份会把前一份的动画顶掉。
|
|
547
|
-
3. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
|
|
548
|
-
|
|
549
|
-
| 来源 | 保留名 | 说明 |
|
|
550
|
-
|---|---|---|
|
|
551
|
-
| 宿主**给你的**输入框工具类 | `.ldk-input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的)。⚠️ 它是整个 `ldk-` 家族里**唯一**鼓励你**消费**的一个(其余的 `ldk-` 名是「别碰」,它是「拿去用」) |
|
|
552
|
-
| 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle`、`ldk-hint-card`(2026-09-19 起,悬停说明卡)等(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`、`ldk-input`、`ldk-setting-group`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用**(唯一的例外是上一行的 `.ldk-input`:那个是**给你用的**) |
|
|
553
|
-
|
|
554
|
-
**`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
|
|
555
|
-
|
|
556
|
-
| 保留的关键帧名 | 说明 |
|
|
557
|
-
|---|---|
|
|
558
|
-
| `ldk-selectbox-in` | 共享组件下拉框的入场动画 |
|
|
559
|
-
| `ldk-drop-zone-in` | 拖放区的入场动画(宿主的自有动画一律带 `ldk-` 前缀) |
|
|
560
|
-
| `ldk-dropdown-card-in` | 下拉卡片的入场动画 |
|
|
561
|
-
| `ldk-floating-panel-in` | 浮动面板的入场动画 |
|
|
562
|
-
| `ldk-notif-icon-spin` | 通知图标的旋转 |
|
|
563
|
-
| `ldk-notif-progress-scan` | 通知的进度扫描 |
|
|
564
|
-
| `ldk-rn-spin` | 发行说明页刷新图标的旋转 |
|
|
565
|
-
| `ldk-boot-mark-breath` | 池首帧品牌过场的呼吸 |
|
|
566
|
-
| `ldk-view-skeleton-breath` | 内容加载骨架的呼吸 |
|
|
567
|
-
| `ldk-welcome-skeleton-breath` | 欢迎页最近列表加载骨架的呼吸 |
|
|
568
|
-
| `ldk-welcome-in` | 欢迎页入场 fade-up(全页唯一一处入场) |
|
|
569
|
-
|
|
570
|
-
**引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
|
|
571
|
-
你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
|
|
572
|
-
**上面那张保留表里的**(引用宿主的动画是**合法消费**,不会判你)。引一个**谁都没定义**的名字,
|
|
573
|
-
动画**不报错、不警告,只是不动**——症状是「我的动画怎么没生效」,而控制台一片安静(同一个窗口里
|
|
574
|
-
还有别的插件和宿主在跑,你很难一眼看出是这一条)。`@linkdesk/plugin-sdk` **≥ 0.1.37** 起,插件的
|
|
575
|
-
lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 + 名字**);确需引用一个门禁看不见的名字
|
|
576
|
-
(例如动画由运行时注入),用标准 `eslint-disable` 注释写明理由。
|
|
577
|
-
|
|
578
|
-
> 🔧 **维护者注(作者可跳过)**:上面两张表的「**保留名**」「**保留的关键帧名**」两列都是**机器读的**——`npm run check` 里的门禁
|
|
579
|
-
> (`scripts/check-reserved-names-doc-sync.mjs`)把它们与登记表
|
|
580
|
-
> `packages/plugin-sdk/schemas/reserved-class-names.json` **双向核对**:登记表里的名字必须在这里出现,
|
|
581
|
-
> 这里出现的名字必须在登记表里登记(裸名)、或在宿主源码里真实存在(`ldk-` 名);关键帧表与登记表的
|
|
582
|
-
> `keyframes` 段同样**双向**。
|
|
583
|
-
> ⇒ **改这两列 = 改公共面**:加/删一个名字要**同笔改三处**——登记表 + 中英两棵树的这两张表。
|
|
584
|
-
> 两列**只放名字**,解释写「说明」列。
|
|
585
|
-
|
|
586
|
-
**还有一条跟命名空间有关的**:你的 `pluginId` **不得以 `ldk-` 开头**——整个 `ldk-` 命名空间是宿主的,
|
|
587
|
-
一个叫 `ldk-tools` 的插件用纪律 1 派生出来的前缀(`ldk-tools-*`)会**由构造落进宿主空间**,纪律 1
|
|
588
|
-
也就跟着失效了。这条约束写在 `plugin.json` 的 schema 里,编辑器会当场提示。
|
|
589
|
-
|
|
590
|
-
**要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
|
|
591
|
-
(手写等于绕过组件,组件升级你就掉队)。
|
|
592
|
-
|
|
593
|
-
**状态类一律复合使用**:`.你的类.active`、`.你的类.on`(不要裸写 `.active {}`、`.on {}`——那会把
|
|
594
|
-
宿主和其他插件里带同名状态类的元素一起改掉)。
|
|
595
|
-
|
|
596
|
-
**反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
|
|
597
|
-
同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
|
|
598
|
-
|
|
599
|
-
**删组件时,同笔删它的 CSS 规则**——被壳的共享组件(`SidePanel` / `SidebarSection`)接管了的节点,
|
|
600
|
-
插件侧**不要留孤儿规则**:规则还在、节点没了,它就成了一个**静默吃掉样式**的挂载点——谁哪天往那个
|
|
601
|
-
类上挂样式(比如一个本地 token),都会**静默失效**(1.24 真实事故:官方 `serial-monitor` 的侧栏状态点
|
|
602
|
-
颜色被静默丢掉,v1.0.17 当场修正)。拿不准有没有孤儿规则,跑壳仓的
|
|
603
|
-
`npm run audit:plugin-dead-css`——它把「定义了、源码没人用」的自有前缀类逐条列出来(只报不拦)。
|
|
604
|
-
|
|
605
|
-
### 12.1 从旧版 `@linkdesk/ui` 升上来——一件要你自己改的事
|
|
606
|
-
|
|
607
|
-
共享组件的类名带上了 `ldk-` 前缀(`@linkdesk/ui` **0.2.0** 起)。这件事**只影响一种写法**:
|
|
608
|
-
你写在**插件自己 CSS 里**、用后代选择器去微调共享组件外观的那些规则。**升级前不用动,升级时改一处前缀即可。**
|
|
609
|
-
|
|
610
|
-
- **什么时候受影响**:把 `@linkdesk/ui` 升到 **0.2.0 之后**——**不是立刻**。旧版本里这些组件的类名是
|
|
611
|
-
`.badge` 这样的裸名,包里带的 CSS 与组件自洽,**你不升级就不会坏**。(依赖写 `^0.1.x` 时不会自动
|
|
612
|
-
跨到 `0.2.0`,所以只有你主动升级的那一下才需要动。)
|
|
613
|
-
- **什么会受影响**:你**插件自己 CSS** 里的这类后代选择器——
|
|
614
|
-
`.control-bar .combobox { … }`、`.settings-slider-control .slider { … }`、`.changelog .mdv { … }`
|
|
615
|
-
等等。**组件自己的样式不受影响,你自己的类名也不用改。**
|
|
616
|
-
- **怎么改**:把选择器里**指向共享组件的那一段**加上 `ldk-` 前缀——`.combobox` → `.ldk-combobox`、
|
|
617
|
-
`.slider` → `.ldk-slider`、`.mdv` → `.ldk-mdv`、`.badge` → `.ldk-badge`、`.selectbox-trigger` →
|
|
618
|
-
`.ldk-selectbox-trigger`、`.combobox-field` → `.ldk-combobox-field`——**族里的名字(`-trigger` / `-field` /
|
|
619
|
-
`-input` 这类后缀)一样带前缀**。你自己的前缀(`.control-bar`、`.settings-*`)照旧。
|
|
620
|
-
**升级后拿这八个旧基名 `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle`
|
|
621
|
-
grep 一遍自己的 CSS**:在调共享组件的就加上前缀,其余别动。
|
|
622
|
-
- **为什么不自动兼容**:这类失配**不报错**——选择器匹配不上,只是那几条规则悄悄不再生效,界面看着
|
|
623
|
-
「大致还对、就是不太对」。正因为它是静默的,我们才把名字收进 `ldk-` 前缀,并把这段写进文档。
|
|
624
|
-
|
|
625
|
-
### 12.2 前缀规则(§12 纪律 1/2)上线——既有代码要不要动
|
|
626
|
-
|
|
627
|
-
**一句话:不改也照常跑,但下次动那个文件就是该改的时候。**
|
|
628
|
-
|
|
629
|
-
- **官方插件已经按新规则清过账**——本次改名涉及四只:`file-tree`(v1.0.9)、`settings`(v1.0.11)、
|
|
630
|
-
`serial-monitor`(v1.0.12)、`marketplace`(v1.0.33),裸类名与关键帧名都补上了 `<pluginId>-` 前缀;
|
|
631
|
-
其余官方插件仓本来就没有裸定义(它们的类名不是自带前缀,就是根本没定义类名)。以官方插件清单为口径
|
|
632
|
-
的审计读数是 **18/18 合规**。
|
|
633
|
-
- **第三方作者没有仓要改**:这条规则只管**你自己写的类名与关键帧名**——不动仓库结构、不动 `pluginId`、
|
|
634
|
-
也不影响别人的代码。你既有插件**不用为它单独发版**。
|
|
635
|
-
- **旧的无前缀类名不会报错、也不会失效**——今天照常工作。代价是**撞名的风险仍然在**:另一个插件写了
|
|
636
|
-
同名类名,两边样式就会落到同一个元素上(不报错,只是长得不对,很难查)。
|
|
637
|
-
- **合规由工程自带的检查判**:脚手架建出来的工程带着一条严格检查腿(`npm run verify`),它扫你自己 CSS
|
|
638
|
-
里**给自有元素裸定义**的类名和 `@keyframes` 名,不带 `<pluginId>-` 前缀就判红。所以真正的动作是
|
|
639
|
-
**下一次动那个文件时顺手把名字改掉**:`.panel {}` → `.myplugin-panel {}`,CSS 与用到它的 JSX 两侧一起改
|
|
640
|
-
(只改标识符,不动样式值)。
|
|
641
|
-
|
|
642
|
-
> 现在就想看看自己的工程有没有裸名?在工程根跑 `npm run verify`。
|
|
643
|
-
|
|
644
|
-
### 12.3 宿主的输入框工具类改名了:`.input` → `.ldk-input`(2026-09-16)
|
|
645
|
-
|
|
646
|
-
**一句话:如果你的插件写过 `className="input"`,改成 `className="ldk-input"` 就行——样式一模一样,只是名字换了。**
|
|
647
|
-
|
|
648
|
-
- **改了什么**:宿主原来把一个输入框工具类叫 **`.input`**(不带前缀,是唯一一个不带 `ldk-` 的宿主公共名)。它和本条纪律 1「跨方的名字都带命名空间」冲突 ⇒ 现在统一叫 **`.ldk-input`**。同时宿主的**设置分组卡片** `.setting-group` 也改名为 **`.ldk-setting-group`**。
|
|
649
|
-
- **谁受影响**:**在你自己插件的 JSX/TSX 里写过 `className="input"` 的插件**——官方插件里 `settings` 与 `serial-monitor` 两家用过,已在同一批发版改好。**改法就一处**:`className="input"` → `className="ldk-input"`;拼接写法同理(`"input my-input"` → `"ldk-input my-input"`)。**样式零变化**——同一条规则、同一批 CSS 变量,只换了名字。
|
|
650
|
-
- **不改会怎样**:输入框**不报错**,只是**失去宿主给的外观**(底色 / 边框 / 圆角 / 内边距),看起来像浏览器原生输入框。
|
|
651
|
-
- **什么时候必须改**:在**新壳**上跑就要改。新壳的版本号是 **`0.2.0`**,官方两只插件都已在 `plugin.json` 里声明 `minAppVersion: "0.2.0"`——你也给自己的插件声明同一个值,旧壳上的用户就会收到一句清楚的「需要应用版本 ≥0.2.0」提示,而不是看到一个没样式的输入框(`minAppVersion` 的语义见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
|
|
652
|
-
|
|
653
|
-
### 12.4 共享组件剩下的类名也带 `ldk-` 了(2026-09-16)
|
|
654
|
-
|
|
655
|
-
**一句话:和 12.1 同一件事,只是把当时没覆盖到的组件补上——你若在自己 CSS 里用后代选择器微调过这些组件,升级时加一个 `ldk-` 前缀即可。**
|
|
656
|
-
|
|
657
|
-
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes` 名——现在也带上了前缀(**2026-09-16 那轮起**;版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)):
|
|
658
|
-
|
|
659
|
-
| 旧族 | 新族 |
|
|
660
|
-
|---|---|
|
|
661
|
-
| `.colorpicker-*` | `.ldk-colorpicker-*` |
|
|
662
|
-
| `.ctx-*` | `.ldk-ctx-*` |
|
|
663
|
-
| `.form-row` | `.ldk-form-row` |
|
|
664
|
-
| `.inline-input`、`.inline-input--compact/--normal` | `.ldk-inline-input`、`.ldk-inline-input--compact/--normal` |
|
|
665
|
-
| `.number-input*` | `.ldk-number-input*` |
|
|
666
|
-
| `.segmented-radio`、`.segmented-radio__option/__label` | `.ldk-segmented-radio`、`.ldk-segmented-radio__option/__label` |
|
|
667
|
-
| `.sidebar-section*`、`.sidebar-pane-view`、`.sidebar-pane-sash` | `.ldk-sidebar-section*`、`.ldk-sidebar-section-pane-view`、`.ldk-sidebar-section-pane-sash` |
|
|
668
|
-
| `.theme-picker*`、`.theme-card`、`.theme-preview` | `.ldk-theme-picker*`、`.ldk-theme-picker-card`、`.ldk-theme-picker-preview` |
|
|
669
|
-
| `.tbadge` / `.tname` / `.pv-bar` / `.pv-dot`(主题卡片内部) | `.ldk-theme-picker-badge` / `.ldk-theme-picker-name` / `.ldk-theme-picker-preview-bar` / `.ldk-theme-picker-preview-dot` |
|
|
670
|
-
| `@keyframes selectbox-in` | `@keyframes ldk-selectbox-in` |
|
|
671
|
-
|
|
672
|
-
- **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
|
|
673
|
-
- **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
|
|
674
|
-
- 🔴 **宿主以后改共享名 / 改样式,你这边不必改代码、也不必改 CSS**——组件与样式**由壳池统一供给**(壳池集中供给,见 [19-组件速查 §二](19-组件速查.md)):壳升级后同一份实现跟着壳走,界面自然一致。你唯一要维持的是 `@linkdesk/ui` 依赖**别掉出当前版本线**(它决定你本地 dev 与类型解析到的那一份)。
|
|
675
|
-
- ⛔ **组件样式同样不从你的源码里来**:源码里出现 `import "@linkdesk/ui/index.css"`(或其 dist / `@import` 形态)会被 SDK 的 lint 腿 `linkdesk/no-ui-css-import` 判红——**没有豁免出口**。把样式烤进插件,等于「壳改样式、全生态跟随」对你失效。
|
|
676
|
-
- **什么时候必须改**:当你要支持的壳升到含这次改名的版本时(版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)——ui 版本 = 壳版本,一条线)。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
|
|
677
|
-
- **这把尺子你也有**(`@linkdesk/plugin-sdk` 0.1.40 起):你仓里的 lint 自带「悬空名」判据——宿主改了共享名、你没跟上时,**你自己的 CI 会替你喊**(用法与修法见 [16-命名规范 §7.6](16-命名规范.md))。
|
|
678
|
-
|
|
679
|
-
### 12.5 自定义属性的**作用域**——`--x:` 写在 `:root` 里就等于写给整个软件
|
|
680
|
-
|
|
681
|
-
类名那三条纪律管的是**名字**,这一节管**地盘**。自定义属性(`--xxx`)的规矩只有一句:
|
|
682
|
-
|
|
683
|
-
> **作用域才是命名空间。** 名字随你起,**它住在哪棵子树里**才是它属于谁。
|
|
684
|
-
|
|
685
|
-
**① 文档级的作用域只有宿主能用。** `:root` / `html` / `body` / `[data-theme="…"]` / `*` 上的定义
|
|
686
|
-
**对整个文档可见**——那不是你的地盘:
|
|
687
|
-
|
|
688
|
-
```css
|
|
689
|
-
/* ❌ 这条定义全文档可见 */
|
|
690
|
-
:root { --my-panel-gap: 8px; }
|
|
691
|
-
|
|
692
|
-
/* ✅ 挂在你自己的根类之下,作用域 = 你的子树 */
|
|
693
|
-
.my-plugin-root { --my-panel-gap: 8px; }
|
|
694
|
-
```
|
|
695
|
-
|
|
696
|
-
**② 其余定义一律挂在自己的类之下。** 写 `.你的类 { --xxx: … }` 就好——**这里的名字不需要任何前缀**:
|
|
697
|
-
`:root` 上的 `--gap` 会跟别人撞,`.my-plugin-root` 下的 `--gap` 不会(作用域已经把地盘划开了)。
|
|
698
|
-
|
|
699
|
-
**③ `--ldk-*` 自定义属性谁都不许定义**(和类名、关键帧同一条规矩——整个 `ldk-` 命名空间是宿主的)。
|
|
700
|
-
|
|
701
|
-
**为什么这条比类名还凶**:宿主大部分颜色 / 圆角 / 层级**不是由程序写上去的、而是靠样式表提供的**。
|
|
702
|
-
你在 `:root` 里写一个宿主的契约名(比如 `--bg-card`),**你会赢**——整个软件的卡片底色跟着变;
|
|
703
|
-
而且**换个主题可能又变回来**(主题会覆盖其中一部分名字)⇒ 症状是「**时好时坏**」,最难查的一类。
|
|
704
|
-
|
|
705
|
-
**一条自检**(写完 CSS 顺手看一眼):**「我的 `--x:` 是不是写在 `:root` 里?」** 是 ⇒ 搬进你自己的根类。
|
|
706
|
-
|
|
707
|
-
**迁移**——已经在 `:root` 里写过自定义属性的插件:
|
|
708
|
-
|
|
709
|
-
| 情形 | 判级 | 怎么办 |
|
|
710
|
-
|---|---|---|
|
|
711
|
-
| 名字**带**你自己的前缀(`--my-plugin-gap`) | 🟡 建议改 | 搬进自己的根类。名字是你的、没人跟你抢,但「写在 `:root`」本身没有理由——改完作用域从整个文档缩回你自己的子树 |
|
|
712
|
-
| 名字**不带**前缀(`--gap`、`--bg-card`…) | 🔴 必须改 | 它此刻在全文档生效、可能正覆盖着宿主或别的插件的值 ⇒ 把它搬进自己的根类(名字可以照旧保留,**换的是作用域**) |
|
|
713
|
-
| 名字以 `ldk-` 开头 | 🔴 必须改 | 换成你自己的名字——`ldk-` 是宿主命名空间 |
|
|
714
|
-
| 写在**自己的根类**之下 | ✅ 合规 | 不用动。`.你的根类 .ldk-x { --y: … }` 这类**微调**同样合规(选择器里有你自己的类就行) |
|
|
715
|
-
|
|
716
|
-
**它怎么被机械守住**:在插件工程根跑 `npm run lint`(或 CI 里的 `npm run verify`)会逐条报出来
|
|
717
|
-
——🔴 会让 CI 红,🟡 只提示不拦。「我的插件本地好好的、CI 却红」时先看这一段。
|
|
718
|
-
|
|
719
|
-
> 🔧 **维护者注(作者可跳过)**:规则正文(含宿主契约块的登记方式、浮层宿主根那个例外)在
|
|
720
|
-
> `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
|
|
721
|
-
> `scripts/check-css-namespace.mjs` 守着,插件侧由 SDK 的 `check-css-namespace` 腿守着
|
|
722
|
-
> (token 作用域是那条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
|
|
723
|
-
|
|
724
|
-
### 12.6 选择器本身也要有「落点」——**禁写无锚选择器**(2026-09-16)
|
|
725
|
-
|
|
726
|
-
前五节管的是**名字**(类名 / 关键帧 / 自定义属性)。这一节管**选择器的形态**——一条更容易忽略的规矩:
|
|
727
|
-
|
|
728
|
-
> **类名和 id 是「名字锚」;元素 / 通配 / 属性 / 伪类 / 伪元素不是。**
|
|
729
|
-
> 后者**不需要与任何人同名**就能命中别人的元素。
|
|
730
|
-
|
|
731
|
-
```css
|
|
732
|
-
/* ❌ 一条规则改掉「这个文档里所有」的按钮——宿主和其他插件的按钮全在内 */
|
|
733
|
-
button { border: none; }
|
|
734
|
-
* { box-sizing: border-box; }
|
|
735
|
-
#some-id { display: none; } /* id 也是全局的、可猜的,优先级还高于类 */
|
|
736
|
-
:root { outline: none; } /* `:root` 同样是无锚选择器 */
|
|
737
|
-
|
|
738
|
-
/* ✅ 挂在自己的根类之下——同一个意图,落点只有你自己的子树 */
|
|
739
|
-
.my-plugin-root button { border: none; }
|
|
740
|
-
```
|
|
741
|
-
|
|
742
|
-
**两条规则**(都在插件工程根 `npm run lint` / CI `npm run verify` 里**机械判红**):
|
|
743
|
-
|
|
744
|
-
| 规则 | 判定 | 为什么 |
|
|
745
|
-
|---|---|---|
|
|
746
|
-
| **禁无锚选择器** | 选择器**没有**任何 `.类` 或 `#id` 主体(元素 / 通配 / 属性 / 伪类 / 伪元素;**顶层或限定一律禁,`@media` 内也算**)⇒ 🔴 | 它命中「该文档里所有那一类元素」,与谁渲染无关 |
|
|
747
|
-
| **跨方命中必须自带自有锚** | 选择器里出现 `ldk-*` 类(**含 `:has(…)` 内的提及**)却**不带** `.<你的 pluginId>-*` 类 ⇒ 🔴 | `ldk-` 是宿主命名空间;**调优必须发生在自己的地盘里** |
|
|
748
|
-
|
|
749
|
-
⚠️ **第二条不影响「改共享组件外观」这件事本身**——那是**合法特性**(scoped 调优)。它只要求你**带着自家前缀作锚**:
|
|
750
|
-
|
|
751
|
-
```css
|
|
752
|
-
/* ❌ 改的是宿主/共享组件的元素,自己却一点落点都没有 ⇒ 判红 */
|
|
753
|
-
.ldk-toggle { transform: scale(1.1); }
|
|
754
|
-
|
|
755
|
-
/* ✅ 同一个意图,写在自己的地盘里 ⇒ 合规 */
|
|
756
|
-
.my-plugin-root .ldk-toggle { transform: scale(1.1); }
|
|
757
|
-
```
|
|
758
|
-
|
|
759
|
-
**为什么值得专门记住**:宿主自己就有 **17 处**这样的「无锚选择器」(`*` 重置 / `html`·`body` /
|
|
760
|
-
`[data-theme]` / `*:focus-visible` / 滚动条一族 / `input[type="number"]`·`select`)——它们**是有意的
|
|
761
|
-
共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
|
|
762
|
-
你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
|
|
763
|
-
|
|
764
|
-
**迁移**:**今天 0 存量**——官方插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
|
|
765
|
-
的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
|
|
766
|
-
|
|
767
|
-
> 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
|
|
768
|
-
> `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`;
|
|
769
|
-
> 宿主侧由 `scripts/check-css-namespace.mjs` 的判据⑩⑪(+ 探针轴 ④ 的运行时镜像)守着,
|
|
770
|
-
> 插件侧由 SDK 的 `check-css-namespace` 腿的**第四、第五条判据**守着(`checks/selector-form.ts` 的 S2/S3,
|
|
771
|
-
> 与 `checks/keyframe-refs.ts` 的关键帧引用悬空 —— 后者 **2026-09-18 起**在位,SDK `≥ 0.1.37`)。
|
|
772
|
-
|
|
773
|
-
---
|
|
774
|
-
|
|
775
|
-
## 13. 悬停提示 → `data-hint` 属性(或 `<HintTip>`)
|
|
776
|
-
|
|
777
|
-
**鼠标停在你的按钮/图标上时,那个小条不是浏览器画的。**
|
|
778
|
-
|
|
779
|
-
宿主有一套统一的轻提示(`HintTip`):深浅主题、字号缩放、贴边翻面、快捷键键帽都由壳一处决定。
|
|
780
|
-
**你不需要 import 任何东西**就能用——写属性即可:
|
|
781
|
-
|
|
782
|
-
```tsx
|
|
783
|
-
// ❌ 原生 title:浏览器画,主题/缩放/键帽都不跟壳走(SDK ≥ 0.1.49 起这条腿判红)
|
|
784
|
-
<button title={t("刷新")}>
|
|
785
|
-
|
|
786
|
-
// ✅ 属性式:把 title= 换成 data-hint=(DOM 结构零变化)
|
|
787
|
-
<button data-hint={t("刷新")} aria-label={t("刷新")}>
|
|
788
|
-
|
|
789
|
-
// ✅ 带快捷键:给命令 id,壳去查命令表(文案与快捷键都来自那一份 ⇒ 提示条/右键菜单/命令面板永远一个说法)
|
|
790
|
-
<button data-hint-command="fileTree.refresh" aria-label={t("刷新")}>
|
|
791
|
-
|
|
792
|
-
// ✅ 揭示类("看全被截断的字"):该立刻出现,别让它等
|
|
793
|
-
<div data-hint={fullPath} data-hint-delay="0">{truncated}</div>
|
|
794
|
-
|
|
795
|
-
// ✅ 复合场景(要自己控制包裹):组件式
|
|
796
|
-
import { HintTip } from "@linkdesk/ui";
|
|
797
|
-
<HintTip label={t("刷新")} command="fileTree.refresh"><button …>…</button></HintTip>
|
|
798
|
-
```
|
|
799
|
-
|
|
800
|
-
四个属性,都写在你自己的 DOM 元素上:
|
|
801
|
-
|
|
802
|
-
| 属性 | 作用 |
|
|
803
|
-
|---|---|
|
|
804
|
-
| `data-hint` | 提示主文案(说明类与揭示类通用——**文案永远由你给**,壳不下发任何句子) |
|
|
805
|
-
| `data-hint-command` | 命令 id——壳查命令表取名字与快捷键。与右键菜单/命令面板**同源**(改一处全跟走) |
|
|
806
|
-
| `data-hint-delay` | 意图延时(毫秒)。说明类**留默认**(120ms——防划过闪一下);揭示类传 `"0"` |
|
|
807
|
-
| `data-hint-placement` | 首选方位 `top`/`bottom`/`left`/`right`(缺省 `top`,贴不下自动翻面) |
|
|
808
|
-
|
|
809
|
-
**⚠️ 三条纪律**
|
|
810
|
-
|
|
811
|
-
1. **说明类慢、揭示类近 0**——「看全被截断的字」要立刻;反过来给图标加命令说明才该等那一等。
|
|
812
|
-
2. **别再用原生 `title=`**:SDK 腿 `linkdesk/no-native-title`(SDK ≥ 0.1.49)判红——`lint` 输出红行、
|
|
813
|
-
`ci-verify` 判红。确需原生 title 的形态(提示渲染器够不到的)走
|
|
814
|
-
`// eslint-disable-next-line linkdesk/no-native-title -- 理由`(**理由必填**)。
|
|
815
|
-
3. **条内不放按钮**:提示是提示不是菜单(要交互用 `<ContextMenu>`);要**长文案/标题/注脚**或多行说明,
|
|
816
|
-
用 `HintCard`——那一件本来就是管"有注脚的长说明"的。
|
|
817
|
-
|
|
818
|
-
> 🔧 **维护者注(作者可跳过)**:渲染器 = `src/components/shared/hint-tip/HintTipRenderer.tsx`(池内单例挂载:
|
|
819
|
-
> 委托 `pointerover`/`pointerout`/`focusin`/`focusout` + 意图延时状态机);属性字面量的单一真相源 =
|
|
820
|
-
> `hintAttrs.ts`(⛔ 别处不许再写 `"data-hint"` 字面量);总开关 = 壳配置 `app.hint.enabled`(缺省开,设置页可见);
|
|
821
|
-
> 门禁三腿 = 壳侧 `scripts/check-native-title.mjs`(存量白名单账、只判新增)+ SDK 腿
|
|
822
|
-
> `checks/no-native-title.ts`(同 id、锚⑪ 3 句锚词互钉)。
|
|
823
|
-
|
|
824
|
-
---
|
|
825
|
-
|
|
826
|
-
## 速查
|
|
827
|
-
|
|
828
|
-
| 你要做的 | 核心设施 | 引入方式 |
|
|
829
|
-
|---|---|---|
|
|
830
|
-
| 右键菜单 | `<ContextMenu>`(open-string menuId) | `@linkdesk/ui`(ContextMenu)+ `plugin.json contributes.menus` 声明(或 `window.linkdesk.menu.registerItems`,见 §1) |
|
|
831
|
-
| 浮层/弹窗 | `createPortal` | `react-dom`(渲染到 `document.body`,见 §2) |
|
|
832
|
-
| 持久化 | `window.linkdesk.configuration.get/set/onChange` | 插件通信铁律——只走 window.linkdesk.*(见 §3) |
|
|
833
|
-
| 系统选择器 | `window.linkdesk.quickPick.show` | 池内 QuickPickHost 统一渲染(见 §9) |
|
|
834
|
-
| 通知 | `window.linkdesk.notifications.show` | 池内**铃铛宽通知面板**统一渲染(见 §9;语义见 `01-插件API契约.md` §3.2) |
|
|
835
|
-
| 确认/提示/文件选择 | `window.linkdesk.dialog.confirm/alert/open/openFile` | 池内 DialogHost 统一渲染(见 §9) |
|
|
836
|
-
| 富内容确认框 | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | 池内 DialogHost 渲染壳,**内容 = 插件自绘视图**(见 §9) |
|
|
837
|
-
| 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
|
|
838
|
-
| 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
|
|
839
|
-
| 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
|
|
840
|
-
| 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
|
|
841
|
-
| 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
|
|
842
|
-
| 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
|
|
843
|
-
| 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
|
|
844
|
-
| UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
|
|
845
|
-
| 文字 | `t()` | `useTranslation()` from `react-i18next` |
|
|
846
|
-
| CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
|
|
847
|
-
| 元素 / id 选择器 | 必须挂在自己的根类之下 | 见 §12.6(无锚选择器不需要同名就能命中所有人的元素) |
|
|
848
|
-
| 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
|
|
849
|
-
|
|
850
|
-
**写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
|
|
1
|
+
# 插件 UI 写法规约
|
|
2
|
+
|
|
3
|
+
> **一句话:核心已提供标准组件和注册表——不要手写轮子。手写 = 风格不一致 + 以后归一化时要拆。**
|
|
4
|
+
> 写插件前扫一眼,避免同类返工。
|
|
5
|
+
> **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. 右键菜单 → `<ContextMenu>` + MenuRegistry
|
|
10
|
+
|
|
11
|
+
**❌ 禁止:** 手写 `<div className="my-menu">` + `useState` + click-outside listener。
|
|
12
|
+
|
|
13
|
+
**✅ 正确:**
|
|
14
|
+
```json
|
|
15
|
+
// ① 声明菜单项——plugin.json contributes.menus(首选,声明式)
|
|
16
|
+
{
|
|
17
|
+
"contributes": {
|
|
18
|
+
"menus": {
|
|
19
|
+
"editorContext": [
|
|
20
|
+
{ "command": "myPlugin.copy", "group": "navigation" },
|
|
21
|
+
{ "command": "myPlugin.clear", "group": "edit" }
|
|
22
|
+
]
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
// 运行时动态注册(等价)——window.linkdesk.menu.registerItems(menuId, pluginId, items)
|
|
30
|
+
window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
|
|
31
|
+
{ command: "myPlugin.copy", group: "navigation" },
|
|
32
|
+
{ command: "myPlugin.clear", group: "edit" },
|
|
33
|
+
]);
|
|
34
|
+
|
|
35
|
+
// ② 使用统一组件——MenuId 是开放 string,直接写字符串字面量
|
|
36
|
+
<ContextMenu menuId="editorContext" />
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
**理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when 条件过滤。手写做不到这四种失焦。
|
|
40
|
+
|
|
41
|
+
**MenuId 是开放 string(`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)——插件声明任意字符串即契约,无需壳加代码。** 壳内置注册点(MENU_SLOTS 常量表):
|
|
42
|
+
|
|
43
|
+
| MenuId(字符串字面量) | 场景 |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `commandPalette` | Ctrl+Shift+P 命令面板 |
|
|
46
|
+
| `tabContext` | 标签栏标签右键 |
|
|
47
|
+
| `panelViewContext` | 面板标签栏右键(位置/对齐子菜单 + 视图显隐列表) |
|
|
48
|
+
| `editorContext` | 标签页主内容区右键 |
|
|
49
|
+
| `extensionGear` | 底部齿轮菜单(设置/命令面板/主题选择器) |
|
|
50
|
+
| `marketplaceItemGear` | 插件市场条目齿轮(启用/禁用/卸载) |
|
|
51
|
+
| `menuBar` | ☰ 汉堡菜单栏 |
|
|
52
|
+
| `panel` | 菜单栏「面板」菜单 |
|
|
53
|
+
| `fileContext` | 文件树右键 |
|
|
54
|
+
| `cardContext` | 卡片右键 |
|
|
55
|
+
| `quickSendContext` | 快捷发送药丸右键 |
|
|
56
|
+
| `iconBar` | 图标栏右键 |
|
|
57
|
+
| `settingItemGear` | 设置项齿轮(Settings Editor 行 hover) |
|
|
58
|
+
| `viewTitleContext` | 侧栏视图 title 右键(折叠/重置位置/视图同组) |
|
|
59
|
+
|
|
60
|
+
新增右键场景 → MenuId 开放 string 直接声明即可(如 `"myMenu"`):`contributes.menus.myMenu` 声明 + `<ContextMenu menuId="myMenu" />` 消费——**零壳改动**(插件独立铁律)。壳若要在此场景提供统一渲染点才需在 MENU_SLOTS 加条目。
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## 2. 浮层 / 弹窗 → `createPortal`
|
|
65
|
+
|
|
66
|
+
**❌ 禁止:** 弹窗嵌在组件树的深层 div 里。
|
|
67
|
+
|
|
68
|
+
**✅ 正确:**
|
|
69
|
+
```tsx
|
|
70
|
+
import { createPortal } from "react-dom";
|
|
71
|
+
|
|
72
|
+
return createPortal(
|
|
73
|
+
<div className="my-dialog">{/* ... */}</div>,
|
|
74
|
+
document.body // ← 关键:渲染到 body
|
|
75
|
+
);
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed` 也看不见。render 到 `document.body` 才能突破组件树限制。
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 3. 持久化 → `window.linkdesk.configuration`(plugin.json contributes.configuration 声明)
|
|
83
|
+
|
|
84
|
+
**❌ 禁止:** `localStorage.setItem()` / `PreferenceService.loadPrefs()` / 手写文件读写 / `import ... from "@src/core/..."`。
|
|
85
|
+
|
|
86
|
+
**✅ 正确——走 `window.linkdesk.configuration`(插件通信铁律:只走 window.linkdesk.*,禁止 import @src/core):**
|
|
87
|
+
```tsx
|
|
88
|
+
// 读配置(Promise——值运行时动态)
|
|
89
|
+
useEffect(() => {
|
|
90
|
+
window.linkdesk.configuration.get<boolean>("myPlugin.showLineNumbers").then((v) => {
|
|
91
|
+
setShowLineNumbers(v);
|
|
92
|
+
});
|
|
93
|
+
}, []);
|
|
94
|
+
|
|
95
|
+
// 写配置
|
|
96
|
+
await window.linkdesk.configuration.set("myPlugin.showLineNumbers", true);
|
|
97
|
+
|
|
98
|
+
// 订阅变更——返回 unsubscribe,unmount 调用
|
|
99
|
+
useEffect(() => {
|
|
100
|
+
return window.linkdesk.configuration.onChange<boolean>("myPlugin.showLineNumbers", (v) => {
|
|
101
|
+
setShowLineNumbers(v);
|
|
102
|
+
});
|
|
103
|
+
}, []);
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**plugin.json 声明配置项:**
|
|
107
|
+
```json
|
|
108
|
+
{
|
|
109
|
+
"contributes": {
|
|
110
|
+
"configuration": {
|
|
111
|
+
"title": "My Plugin",
|
|
112
|
+
"properties": {
|
|
113
|
+
"myPlugin.showLineNumbers": {
|
|
114
|
+
"type": "boolean",
|
|
115
|
+
"default": true,
|
|
116
|
+
"description": "显示行号"
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**理由:** 壳自动持久化 + 重启恢复 + Settings Editor 自动渲染。手写 localStorage → 丢掉 Settings Editor 集成 + 下一个持久化 bug。
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## 4. 快捷键 → 两轨道:声明式(非文本键)+ 池侧自处理(文本键/焦点绑定键)
|
|
129
|
+
|
|
130
|
+
快捷键有**两条轨道**,选哪条取决于键的性质。**选错轨道 = 键死或劫持全池**(教训)。
|
|
131
|
+
|
|
132
|
+
### 4.1 轨道一:`contributes.keybindings`(设置面板可见)——**仅限非文本键**
|
|
133
|
+
|
|
134
|
+
**❌ 禁止:** 把 `ctrl+c` / `ctrl+v` / `ctrl+x` / `ctrl+a` / `f2` 等**文本编辑键**写进 `contributes.keybindings`。
|
|
135
|
+
|
|
136
|
+
**✅ 正确:**(非文本键——如 `ctrl+k` / `ctrl+shift+e` / `f5`)
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"contributes": {
|
|
140
|
+
"keybindings": [
|
|
141
|
+
{
|
|
142
|
+
"key": "ctrl+k",
|
|
143
|
+
"command": "myPlugin.clear",
|
|
144
|
+
"when": "activeEditor == 'myPlugin'"
|
|
145
|
+
}
|
|
146
|
+
]
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
**理由(为什么文本键是雷):** 声明/注册的键会同步进主进程 keyCache → `before-input-event` 命中即**无条件吞键**(不认 when、不认可编辑状态、不认 handler 是否存在)。壳注册一个 `ctrl+c` 就吞掉全池所有输入框/Monaco 的原生 `ctrl+c`。文本键正解 = 轨道二。
|
|
152
|
+
|
|
153
|
+
### 4.2 轨道二:池侧自处理(容器 onKeyDown)——文本键 + 焦点绑定键正解
|
|
154
|
+
|
|
155
|
+
**✅ 正确:** 组件自己的键盘交互在自己的**容器 `onKeyDown`** 里处理:
|
|
156
|
+
|
|
157
|
+
```tsx
|
|
158
|
+
<div
|
|
159
|
+
tabIndex={0} // 让容器可聚焦——点击子项时浏览器把焦点给最近可聚焦祖先
|
|
160
|
+
onKeyDown={(e) => {
|
|
161
|
+
if (e.key === "F2") { e.preventDefault(); startRename(); }
|
|
162
|
+
}}
|
|
163
|
+
>
|
|
164
|
+
{items}
|
|
165
|
+
</div>
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
**为什么是正解:** 池内所有插件共用一个 document——**DOM 焦点天然分区**。容器聚焦才收键,Monaco 聚焦收不到,多插件各干各的 `ctrl+c` 互不打扰。不需要 when、不需要冲突检测。文件树剪贴板键 = 共享 `useClipboardKeys` hook + 命令链同款。剪贴板相关键可复用 `src/pool/hooks/useClipboardKeys`(`onCopy`/`onCut`/`onPaste` 声明式回调,机制一处实现一处修)。
|
|
169
|
+
|
|
170
|
+
**❌ 反模式(红字):** `document.addEventListener("keydown", ...)` / `window.addEventListener("keydown", ...)` = **全局劫持**——绕过分区前提,插件有活动会话时劫持全池同键(串口 F2 曾劫持文件树 F2)。**`tabIndex` + 容器 `onKeyDown` 才是焦点分区正解**;非焦点元素不触发,可加 `tabIndex={0}` 承接。
|
|
171
|
+
|
|
172
|
+
🔴 **这条反模式有腿了(2026-09-20,SDK 0.1.46 起)**:`linkdesk-plugin-sdk lint` 的 `linkdesk/no-global-key-listener` 腿机械拦截 window/document 的 keydown/keyup **字面量**监听,报错文案直接给正解与豁免写法。确需全局抓键的正当形态(如快捷键录制器要 capture 抓原始键)走标准 disable 注释+理由——判据本身无白名单。
|
|
173
|
+
|
|
174
|
+
**注意:** 轨道二键**不进快捷键设置面板**——面板只显示 KeybindingRegistry 绑定(轨道一)。这是设计取舍(注册即吞池,见 4.1),不是 bug。
|
|
175
|
+
|
|
176
|
+
### 4.3 剪贴板三选一通道表
|
|
177
|
+
|
|
178
|
+
| 你想复制的 | 通道 | 例子 |
|
|
179
|
+
|---|---|---|
|
|
180
|
+
| 可编辑元素内文本(input/textarea/Monaco) | **浏览器原生**——什么都不用写 | 输入框内 Ctrl+C/V |
|
|
181
|
+
| 任意文本 | `window.linkdesk.clipboard.writeText` | 复制选中文本到系统剪贴板 |
|
|
182
|
+
| 文件/路径列表 | `window.linkdesk.clipboard.writeFileList` | 文件树复制 → 资源管理器可粘贴(CF_HDROP) |
|
|
183
|
+
|
|
184
|
+
**注意:** 可编辑元素走浏览器原生,**不要**声明快捷键也不要拦截——Electron/Chromium 自动接系统剪贴板。
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 5. 颜色 → CSS 变量 `var(--xxx)`
|
|
189
|
+
|
|
190
|
+
**❌ 禁止:** 硬编码 `#0078d4` / `#1e1e1e` / `#ffffff`。
|
|
191
|
+
|
|
192
|
+
**✅ 正确:**
|
|
193
|
+
```css
|
|
194
|
+
.my-element {
|
|
195
|
+
color: var(--text-primary);
|
|
196
|
+
background: var(--bg-input);
|
|
197
|
+
border: 1px solid var(--border);
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
**理由:** 换主题后硬编码颜色不变 → 暗色主题下白字白底不可见。见 `src/index.css` 查看所有可用 CSS 变量。
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 6. 文字 → `t()` 国际化
|
|
206
|
+
|
|
207
|
+
**❌ 禁止:** 绕过 `t()` 硬编码显示字符串(`<button>发送</button>` / `<button>Send</button>`)。
|
|
208
|
+
|
|
209
|
+
**✅ 正确:**
|
|
210
|
+
```tsx
|
|
211
|
+
import { useTranslation } from "react-i18next";
|
|
212
|
+
const { t } = useTranslation();
|
|
213
|
+
<button>{t("发送")}</button> // i18n key = 插件 UI 原文(中文插件用中文,英文/法文插件用自己的语言)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
---
|
|
217
|
+
|
|
218
|
+
## 7. 侧栏列表选中条目 → `onMouseDown`(不是 `onClick`)
|
|
219
|
+
|
|
220
|
+
**❌ 禁止:** 侧栏垂直列表中选中条目用 `onClick`。
|
|
221
|
+
|
|
222
|
+
**✅ 正确:**
|
|
223
|
+
```tsx
|
|
224
|
+
<div
|
|
225
|
+
className={`my-list-item${isActive ? " active" : ""}`}
|
|
226
|
+
onMouseDown={() => onSelect(item.id)}
|
|
227
|
+
>
|
|
228
|
+
<span>{item.label}</span>
|
|
229
|
+
</div>
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
**理由:** 侧栏条目垂直紧邻——快速点击时 mousedown 在条目 A、mouseup 滑到条目 B。浏览器 `click` 事件规范:mousedown 和 mouseup 落在不同元素 → click 投递到两者的共同祖先 → React 在祖先上找不到 handler → 静默丢失。`onMouseDown` 只关注按下位置,不要求释放在同一元素——消除快速点击丢事件。
|
|
233
|
+
|
|
234
|
+
**对标 VS Code:** Explorer 文件树选文件用 `onMouseDown`,不是 `onClick`。这是经过千万用户验证的模式,不要自己设计。
|
|
235
|
+
|
|
236
|
+
**适用场景:** 侧栏中任何垂直排列、条目间距小的可点击列表——会话列表、文件树、数据库连接、MQTT 主题、设备列表等。
|
|
237
|
+
|
|
238
|
+
**子元素的处理:** 条目内的操作按钮/输入框需要加 `onMouseDown={(e) => e.stopPropagation()}` 防止误触父条目的选中:
|
|
239
|
+
```tsx
|
|
240
|
+
<button
|
|
241
|
+
onMouseDown={(e) => e.stopPropagation()}
|
|
242
|
+
onClick={(e) => { e.stopPropagation(); handleDelete(); }}
|
|
243
|
+
>
|
|
244
|
+
✕
|
|
245
|
+
</button>
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## 8. 插件自有数据模型 → `Emitter` 响应式模式
|
|
251
|
+
|
|
252
|
+
**❌ 禁止:** command handler 里改 model 后手动调 `rerender()` / `setVersion()` / 传 `treeVersion` prop。
|
|
253
|
+
|
|
254
|
+
**✅ 正确——Web 标准 `EventTarget`(零核心 import,插件自有类直接继承):**
|
|
255
|
+
```typescript
|
|
256
|
+
class MyModel extends EventTarget {
|
|
257
|
+
private _items: Item[] = [];
|
|
258
|
+
|
|
259
|
+
add(item: Item): void {
|
|
260
|
+
this._items.push(item);
|
|
261
|
+
this.dispatchEvent(new CustomEvent("change")); // ← 每个改状态的方法末尾 dispatch
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
remove(id: string): void {
|
|
265
|
+
this._items = this._items.filter(i => i.id !== id);
|
|
266
|
+
this.dispatchEvent(new CustomEvent("change"));
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
```tsx
|
|
272
|
+
// 组件 mount 时订阅,unmount 清理
|
|
273
|
+
function MyView({ model }: { model: MyModel }) {
|
|
274
|
+
const [version, setVersion] = useState(0);
|
|
275
|
+
|
|
276
|
+
useEffect(() => {
|
|
277
|
+
const onChange = () => setVersion(v => v + 1);
|
|
278
|
+
model.addEventListener("change", onChange);
|
|
279
|
+
return () => model.removeEventListener("change", onChange); // unmount 自动注销
|
|
280
|
+
}, [model]);
|
|
281
|
+
|
|
282
|
+
const items = useMemo(() => computeItems(model), [model, version]);
|
|
283
|
+
// ...
|
|
284
|
+
}
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
**理由:** 三次时序 bug(badge 0 / when 失效 / 刷新不更新树)根因都是 module 级 command handler 改了 mutable model,React 感知不到。model 自己通知变更(`EventTarget`/`CustomEvent` 是 Web 标准,不需要壳的 `Emitter`)——handler 只改 model,不碰 React。
|
|
288
|
+
|
|
289
|
+
**适用场景:** 插件有 module 级 command handler 需要改数据后触发 UI 刷新。
|
|
290
|
+
|
|
291
|
+
**⚠️ 插件禁止 `import { Emitter } from "@src/core/CoreEvents"`——那是壳内部实现(插件通信铁律 + ESLint `noCoreImportInPlugin` error 级拦截)。插件自有 model 用 Web 标准 `EventTarget`;插件与插件/壳之间的事件走 `window.linkdesk.events`(见 `07-插件间通信.md`)。**
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## 9. 系统 UI 浮层 → linkdesk API(quickPick / notifications / dialog)
|
|
296
|
+
|
|
297
|
+
**❌ 禁止:** 手写选择器弹层 / `window.alert()` / `window.confirm()` / `import ... from "@src/core/..."`。
|
|
298
|
+
|
|
299
|
+
**✅ 正确:**
|
|
300
|
+
```tsx
|
|
301
|
+
// 选择器——window.linkdesk.quickPick.show({ items, placeholder, prefix })
|
|
302
|
+
const picked = await window.linkdesk.quickPick.show({
|
|
303
|
+
placeholder: "选择目标会话",
|
|
304
|
+
items: [
|
|
305
|
+
{ label: "会话 A", description: "/dev/ttyUSB0" },
|
|
306
|
+
{ label: "会话 B", description: "/dev/ttyUSB1" },
|
|
307
|
+
],
|
|
308
|
+
});
|
|
309
|
+
|
|
310
|
+
// 通知——window.linkdesk.notifications.show(message, { type })
|
|
311
|
+
await window.linkdesk.notifications.show("已连接", { type: "info" });
|
|
312
|
+
await window.linkdesk.notifications.show("校验失败", { type: "error" });
|
|
313
|
+
|
|
314
|
+
// 确认 / 提示 / 文件选择——window.linkdesk.dialog
|
|
315
|
+
const ok = await window.linkdesk.dialog.confirm("确定删除该会话?");
|
|
316
|
+
await window.linkdesk.dialog.alert("版本冲突,已跳过");
|
|
317
|
+
const file = await window.linkdesk.dialog.openFile({
|
|
318
|
+
filters: [{ name: "DXF 文件", extensions: ["dxf"] }],
|
|
319
|
+
});
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
**理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效。完整签名见 `contracts/linkdesk.d.ts`。
|
|
323
|
+
|
|
324
|
+
> ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
|
|
325
|
+
> 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
|
|
326
|
+
> 2. **同来源常驻有配额**——按 `options.source` 分组,每组常驻最多 5 条,超出顶掉同来源最老的。刷屏不会堆成墙,但**也别指望靠通知留长期记录**。
|
|
327
|
+
> 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板;**也别指望有第二呈现面**——通知只有铃铛这一个面(2026-10-01 用户指令重申:右下角「自动消失小卡」这类第二面长过两次、两次都被删)。
|
|
328
|
+
|
|
329
|
+
**通知主动作按钮(`notifications.show` 的 `actions`):** 失败 / 需要用户行动的通知可带 `actions` 按钮数组——点击走**命令系统**执行(对标 VS Code `showErrorMessage(msg, { title, command })` 动作)。命令 handler 由插件自注册(`commands.registerCommand`):
|
|
330
|
+
|
|
331
|
+
```tsx
|
|
332
|
+
// 失败 toast + [重试]/[查看依赖]——command = 插件自注册命令
|
|
333
|
+
await window.linkdesk.notifications.show("安装失败:无法连接源", {
|
|
334
|
+
type: "error", // error 类 toast 停留 8s(够读诊断);info/warning 停留 6s
|
|
335
|
+
actions: [
|
|
336
|
+
{ id: "retry", label: "重试", isPrimary: true, command: "myplugin.retryInstall" },
|
|
337
|
+
{ id: "deps", label: "查看依赖", command: "myplugin.openDeps" },
|
|
338
|
+
],
|
|
339
|
+
});
|
|
340
|
+
// 命令可带参——点击执行 command(...args)
|
|
341
|
+
await window.linkdesk.notifications.show("保存冲突", {
|
|
342
|
+
type: "warning",
|
|
343
|
+
actions: [{ label: "强制保存", command: "myplugin.saveForce", args: [filePath] }],
|
|
344
|
+
});
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
按钮文案 = 最终显示文本(壳不二次翻译);`isPrimary: true` = 主按钮(accent),不设 = 次级文本按钮。**不传 `actions` = 现状无按钮,零行为变化**。完整类型见 `contracts/linkdesk.d.ts`(`notifications.show` options 的 `actions`)。
|
|
348
|
+
|
|
349
|
+
**进度通知 + 长驻通知 + 来源身份:** `show` **一律返回句柄**(不是只有进度条才有)。三条最容易踩空的写法:
|
|
350
|
+
|
|
351
|
+
```tsx
|
|
352
|
+
// ① 进度通知——句柄驱动同一条通知(不会刷出 N 条)
|
|
353
|
+
const h = await window.linkdesk.notifications.show("正在下载…", {
|
|
354
|
+
progress: true, // 开真进度条;不传 percent = 不定态动画
|
|
355
|
+
source: "myplugin", // 见 ③
|
|
356
|
+
});
|
|
357
|
+
await h.update("正在下载…", 42); // 0-100;只传 message = 保持不定态
|
|
358
|
+
await h.finish("下载完成"); // 关闭进度条,可选补一条完成通知
|
|
359
|
+
// 或 await h.cancel(); // 直接关掉,不补完成通知
|
|
360
|
+
|
|
361
|
+
// ② 长驻通知——不自动消失,等用户点 ×(错误诊断类用)
|
|
362
|
+
await window.linkdesk.notifications.show("端口被占用,请关闭其他程序", {
|
|
363
|
+
type: "error",
|
|
364
|
+
persistent: true,
|
|
365
|
+
});
|
|
366
|
+
|
|
367
|
+
// ③ 来源身份——面板按它分组,每组常驻各 5 条配额
|
|
368
|
+
await window.linkdesk.notifications.show("同步失败", { source: "myplugin" });
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
**三个必须知道的点:**
|
|
372
|
+
|
|
373
|
+
1. **句柄是唯一钥匙**:一条通知**只能被创建它的那个句柄**更新/删除。别处 `show` 同文案 = 另一条通知,撤不掉对方。撤长驻通知(如失败的 `persistent`)就用它自己的句柄或让用户点 ×。
|
|
374
|
+
2. **`source` 必须自己报**:池是单进程共享 realm,所有插件共用同一个 `window.linkdesk`,preload **无法**知道这次 `show` 是哪个插件发的 ⇒ 只能作者显式传。**不传 → 全落「其他」组**;插件传自己的插件 id,壳自身域用 `app.<域>`。
|
|
375
|
+
3. **`persistent` 有配额**:每组(按 `source`)常驻最多 5 条,超出顶掉同来源最老的并给汇总提示。**长驻 ≠ 无限留档**——要留档写自己的文件。
|
|
376
|
+
|
|
377
|
+
> 完整的**行为契约**(不是签名,签名看 `contracts/linkdesk.d.ts`)在 [`01-插件API契约.md`](01-插件API契约.md) §3.2 的 `notifications` 行——本节只给写法,语义以那里为准。
|
|
378
|
+
|
|
379
|
+
**富内容确认框(`dialog.confirmContent`):** 要确认框里放**不止一行字**(表单 / 列表 / 截图 / 自定义排版)时用这条——**对话框是壳(居中、遮罩、Esc、焦点锁、点遮罩取消),内容由你的视图自画**(对标 VS Code「对话框是壳、内容插件定」):
|
|
380
|
+
|
|
381
|
+
```tsx
|
|
382
|
+
// 1) plugin.json 先声明这个内容的视图(contributes.views 的任意容器均可)
|
|
383
|
+
// 2) 代码里按「声明 id」寻址打开它
|
|
384
|
+
const ok = await window.linkdesk.dialog.confirmContent({
|
|
385
|
+
pluginId: "myplugin", // 内容归属插件(壳据此复合寻址)
|
|
386
|
+
viewId: "myplugin.confirmImport", // 内容视图声明 id
|
|
387
|
+
title: "导入确认", // 兜底标题——content 视图解析失败时壳回落纯文字确认
|
|
388
|
+
message: "将覆盖 3 个条目", // 兜底正文
|
|
389
|
+
payload: { files: ["a.ts", "b.ts"] }, // 不透明载荷:壳不解释,你的视图自己读
|
|
390
|
+
});
|
|
391
|
+
if (ok) { /* 用户确认 */ } // false = 取消 / 关闭
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
内容视图那一半(**同一份代码里的另一个视图**,读载荷 + 表态):
|
|
395
|
+
|
|
396
|
+
```tsx
|
|
397
|
+
// 你的内容视图组件里——挂载即打开,读一次够(每次开新弹窗都是全新挂载)
|
|
398
|
+
function MyConfirmContent() {
|
|
399
|
+
const data = window.linkdesk.dialogHost.current();
|
|
400
|
+
if (!data || data.open !== true) return null; // 防御:不白屏
|
|
401
|
+
const payload = data.content?.payload as MyPayload;
|
|
402
|
+
return (
|
|
403
|
+
<div>
|
|
404
|
+
{/* 正文排版、按钮全归你画 */}
|
|
405
|
+
<button onClick={() => window.linkdesk.dialogHost.cancel()}>取消</button>
|
|
406
|
+
<button onClick={() => window.linkdesk.dialogHost.confirm()}>确定</button>
|
|
407
|
+
</div>
|
|
408
|
+
);
|
|
409
|
+
}
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
**兜底是硬的**:`viewId` 解析不出来(视图没声明 / 声明插件没装)→ 壳**回落成纯文字确认框**(用 `title`/`message`),弹窗照样出、**不会静默死**。所以 `title`/`message` 别省。载荷经结构化克隆过 IPC,只能放可克隆的数据(不能放函数/React 元素)。结算只有 `dialogHost.confirm()` / `dialogHost.cancel()` 两条路——**别自己 `setState` 关弹窗**,壳不认。
|
|
413
|
+
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## 10. 字号 → `--font-size-*` token + `--ui-scale`(度量体系归一化)
|
|
417
|
+
|
|
418
|
+
**❌ 禁止:** 插件文本字号写裸 `px`(`font-size: 14px`)——`check-font-scale-audit` 门禁(`npm run check`)机械拦截。
|
|
419
|
+
|
|
420
|
+
**✅ 正确:** 字号消费 `var(--font-size-*)`;行高 unitless(`1.5`)或 `calc(... * var(--ui-scale))`;固定上界(输入框/按钮/状态栏高)写 `calc(Npx * var(--ui-scale))` 随全局缩放。统一全局字号缩放(设置 `app.uiFontScale` 85–150%,恒显恒生效)。
|
|
421
|
+
|
|
422
|
+
**档位表**(100% 渲染 = `--ui-scale: 1`;引擎按缩放系数算好最终 px):
|
|
423
|
+
|
|
424
|
+
| 档 | 基准 px | 语义 |
|
|
425
|
+
|---|---|---|
|
|
426
|
+
| `--font-size-2xs` | 11 | 徽章/路径 |
|
|
427
|
+
| `--font-size-xs` | 12 | 次要文本/按钮/统计 |
|
|
428
|
+
| `--font-size-sm` | 13 | UI 主文本(对齐 VS Code 13px) |
|
|
429
|
+
| `--font-size-md` | 14 | 菜单/tab/文件树 name |
|
|
430
|
+
| `--font-size-lg` | 16 | 图标字形/内容图标(配 14px 文字) |
|
|
431
|
+
| `--font-size-xl` | 18 | 区标题 |
|
|
432
|
+
| `--font-size-2xl` | 22 | 行图标/大字 |
|
|
433
|
+
| `--font-size-3xl` | 28 | pd-name |
|
|
434
|
+
| `--font-size-4xl` | 30 | welcome-title |
|
|
435
|
+
|
|
436
|
+
**铁律 + 边界(对标档案 §五 图标裁决 / §六.2 monaco 孤岛拍板):**
|
|
437
|
+
- **独立显示图标不随字号比例**(装饰/品牌语义,与文本不直接相邻)——`.icon-btn .plugin-icon--codicon` 24 / `.plugin-icon--emoji` 24 / `.hamburger-btn` 20 / hero-icon 48 / 行图标 20 等,白名单豁免见 `scripts/check-font-scale-audit.mjs`。
|
|
438
|
+
- **内容级字号走 `contributes.configuration`**(如 `editor.fontSize`)——大文本区/编辑器内容由插件自有配置控制,不随 `--ui-scale`。
|
|
439
|
+
- **monaco 内容孤岛先例**:编辑器内容读 `editor.fontSize`,chrome(状态栏/面包屑)随全局——两轴正交,各管各的。
|
|
440
|
+
- **对齐规则**:现有 `NNpx` 迁移到档位按「+1 档」——`12→sm / 13→md / 11→xs / 10→2xs / 14→lg / 18→xl`(100% 即放大到新默认基线,对标 VS Code)。
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
444
|
+
## 11. token 契约——六域矩阵 + 诚实边界 + 数据纪律(.5)
|
|
445
|
+
|
|
446
|
+
> **一句话:** 写 UI 前先查 11.1 六域矩阵——用 `var(--*)` 的表单/控件/表面**自动跟随主题 + 玻璃 + 全局缩放**,零插件感知。做对靠推荐、做错靠门禁显红但 WARN、绕过靠标准 eslint-disable 知情声明(内容/品牌死色合法豁免,见 11.2)。
|
|
447
|
+
> 门禁 = `linkdesk-plugin-sdk lint`(`@linkdesk/plugin-sdk` 内置):eslint 规则腿 + 三 check 扫描腿双轨,15 项**全 WARN 永不 fail build/上传**——是建议不是封锁。作者项目根跑一次,违规即红 + 自解释修复文案。
|
|
448
|
+
|
|
449
|
+
### 11.1 token 六域矩阵——作者知道有哪些变量,才写得出「自动跟随」
|
|
450
|
+
|
|
451
|
+
| 域 | var() 键(完整清单永远以 `src/index.css` 为准) | 作者写法 | 门禁覆盖 |
|
|
452
|
+
|---|---|---|---|
|
|
453
|
+
| **颜色** | `--text-primary/--text-secondary/--text-muted`(文字色来源由 fontTone 控)+ `--bg-window/--bg-side-panel/--bg-card/--bg-input/--bg-selection` + `--accent/--accent-hover` | `color: var(--text-primary)` | `linkdesk/no-hardcoded-hex` |
|
|
454
|
+
| **表面** | `--bg-*` 表面填充 + `--surface-radius`(跟壳全局圆角滑杆) | `background: var(--bg-card)` | `linkdesk/no-hardcoded-hex` |
|
|
455
|
+
| **圆角** | `--radius-xs/sm/md/lg/xl/2xl` + `--surface-radius` | `border-radius: var(--radius-md)` | `linkdesk/no-hardcoded-radius`(border-radius 裸 px 即红) |
|
|
456
|
+
| **玻璃** | `--glass-blur/--glass-saturate/--glass-tint/--glass-morph/--glass-specular…`(`src/index.css` 全组) | `backdrop-filter: blur(var(--glass-blur)) …` | 契约引导——组合形态,逐条门禁管不住 |
|
|
457
|
+
| **字号** | `--font-size-2xs … 4xl` + `--ui-scale`(`app.uiFontScale` 缩放轴,档位表见 §10) | `font-size: var(--font-size-md)` / em/rem | `check-font-scale`(check 腿——字号裸 px 即红) |
|
|
458
|
+
| **字体族** | `--font-ui` / `--font-mono` | `font-family: var(--font-ui)` | 契约引导(作者合法自选字体) |
|
|
459
|
+
|
|
460
|
+
`var(--*)` = 换主题/玻璃/全局缩放自动跟随,零插件感知——**这正是 @linkdesk/ui 控件层「零思考跟随」的底层原因**——控件全部写在 token 上,插件 `npm i @linkdesk/ui` 消费即跟随。控件复用统一从 `@linkdesk/ui` import(见 §速查),不手写轮子。
|
|
461
|
+
|
|
462
|
+
### 11.2 诚实边界 / 知情绕行——内容与品牌色可以有自己天空
|
|
463
|
+
|
|
464
|
+
**门禁三档(07 §六):** 推荐(照抄即对)/ 警告(15 项自解释,红但 **WARN 永不 fail**)/ 知情绕行(标准 eslint-disable 声明带理由)。**任何生态都管不住作者硬写死颜色**——VS Code 也有不跟随主题的扩展。门禁做的是把「做对」变默认、「做错」变显式红但可**知情绕行**:注释带理由 = 浏览器危险站点「仍要访问」的知情确认,不是静默关灯。
|
|
465
|
+
|
|
466
|
+
**合法豁免类别:** var() 回退 hex(`color: var(--x, #fff)` = 合规形态,不拦)/ 取色器色板 / canvas 绘图 / 引擎区 / **内容画布视图级豁免**。
|
|
467
|
+
|
|
468
|
+
**内容 vs chrome 边界(愤怒的小鸟考核实证):** 游戏 / 数据可视化 / canvas 主区 = **内容世界,不是 UI chrome**——UI chrome 跟主题走(var()/t()/@linkdesk/ui),内容可以有自己天空(草地/血条红/天空蓝不必跟主题)。作者**视图级一次声明豁免**,门禁对内容区不逐条亮灯(一个游戏 5-10 处硬编码逐条 disable 太吵):
|
|
469
|
+
|
|
470
|
+
```tsx
|
|
471
|
+
/* eslint-disable linkdesk/no-hardcoded-hex, linkdesk/no-hardcoded-radius -- 内容画布:游戏主区自绘 */
|
|
472
|
+
export function GameBoard() {
|
|
473
|
+
return <canvas /* 画蓝天草地血条红——内容世界,不是 UI chrome */ />;
|
|
474
|
+
}
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
```tsx
|
|
478
|
+
// 行级知情绕行(品牌死色徽标——只豁免本行,其他行照样拦)
|
|
479
|
+
// eslint-disable-next-line linkdesk/no-hardcoded-hex -- 品牌固定色徽标
|
|
480
|
+
const PRO_BADGE = <span style={{ color: "#ff6b00" }}>PRO</span>;
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
```css
|
|
484
|
+
/* css 里同款格式(check 脚本认)——取色器色板固定值,本行豁免 */
|
|
485
|
+
/* eslint-disable-next-line linkdesk/no-hardcoded-hex -- 取色器色板 */
|
|
486
|
+
.swatch--brand { background: #ffd700; }
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
**语义:** 命中豁免的行**整体静默**不亮灯(对齐 eslint 原生 suppress——disable 声明后不逐条报);**无声明 = 未处理偏离**,`linkdesk-plugin-sdk lint` 报告正常亮 WARN。**不是新语法**——与壳现有 `no-hardcoded-hex` 报错建议格式同款。**背景不被玻璃化是机制层天然成立**——backdrop-filter 只刷壳表面元素,不套插件视图根节点,作者画的内容本就不被玻璃化。
|
|
490
|
+
|
|
491
|
+
### 11.3 非 CSS 引擎适配——翻译桥(引擎自渲染不走 CSS 变量)
|
|
492
|
+
|
|
493
|
+
monaco 式引擎自渲染(canvas / WebGL / 富文本引擎同理)不消费 CSS 变量——要跟随主题走**翻译桥**:订阅主题变更 → 翻译成引擎自己的 theme API。先例:`src/services/theme-sync.ts`(住在 **editor 插件自己的仓** `Encaron/linkdesk-plugin-editor`——起发货插件源码不在壳仓):
|
|
494
|
+
|
|
495
|
+
```ts
|
|
496
|
+
// 订阅主题变更(事件可能先于 mount → 顶层注册或 active 守卫,见 11.5)
|
|
497
|
+
const off = window.linkdesk.events.on("theme:changed", () => {
|
|
498
|
+
engine.updateTheme(translateTheme()); // 把你的 token → 引擎 theme 对象
|
|
499
|
+
});
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开,不落死边界**——未来可能彻底适配主题。
|
|
503
|
+
|
|
504
|
+
### 11.4 插件私有数据通道——自建设置界面 / 自管存档时选通道
|
|
505
|
+
|
|
506
|
+
作者自建设置 UI / 自管存档(不走壳设置页声明)时,数据落地按语义选:
|
|
507
|
+
|
|
508
|
+
| 通道 | 适用 | 示例 |
|
|
509
|
+
|---|---|---|
|
|
510
|
+
| `window.linkdesk.pluginState`(**首选**) | 插件自管存档——集中缓存 + 文件持久化(正牌 API:`get/set/onChange(pluginId, key)`) | 游戏分数 / 关卡进度 / 高分榜 / 皮肤偏好 |
|
|
511
|
+
| `window.linkdesk.configuration.set(key)` 私有命名空间 | 跟设置语义走、可被其他插件/主题读、**要进壳设置页 UI**(声明 contributes.configuration 即进) | 插件参数(声明即 UI;不声明则纯私有键照写持久化) |
|
|
512
|
+
| `window.linkdesk.filesystem` | 大文件 / 二进制 / 跨插件共享 | 截图导出 / 存档文件 |
|
|
513
|
+
| `localStorage` | 补充——池内临时缓存(无跨机、无壳管理) | 会话内高频临时值 |
|
|
514
|
+
|
|
515
|
+
**铁律:不声明 `contributes.configuration` 的私有键不进壳设置页 UI**——`config.set` 对无 schema 键照写持久化(仅 enum 才过滤),作者要壳设置页就声明贡献、要自建界面就私有键直存,两不干扰。
|
|
516
|
+
|
|
517
|
+
### 11.5 壳纪律转移清单——非 UI 写法的纪律按落点沉对应文档
|
|
518
|
+
|
|
519
|
+
| 纪律 | 落点规范 |
|
|
520
|
+
|---|---|
|
|
521
|
+
| 插件唯一入口 `window.linkdesk.*`,**禁止 import @src/core(含 @src 任何子路径)** | `01-插件API契约.md` |
|
|
522
|
+
| 配置**订阅不读一次**(linkdesk.configuration 事件驱动) | 本文件 §3 |
|
|
523
|
+
| linkdesk.events 订阅**时序**——事件可能先于 mount(IPC 缓冲)→ 顶层注册或 active 守卫 | `02-插件生命周期.md` |
|
|
524
|
+
| **不写死其他插件 ID**(差异性行为走 plugin.json 声明字段,Registry 模式消费) | `03-插件contributes规范.md` |
|
|
525
|
+
| 配置键**必给 default** | `06-plugin.json规范.md` |
|
|
526
|
+
| **只用文档化 API 命名空间**(禁 linkdesk.xxx 未文档化随手挂) | `01-插件API契约.md` |
|
|
527
|
+
| 控件统一走 `@linkdesk/ui`(内置控件从 npm 包 import,禁止 `@src/components/shared/*`) | 本文件 §速查 |
|
|
528
|
+
|
|
529
|
+
---
|
|
530
|
+
|
|
531
|
+
## 12. CSS 类名——自己的元素用自有前缀,宿主保留名不要「借用」
|
|
532
|
+
|
|
533
|
+
**先记住一件事:插件视图的样式表不是你自己独占的。** 同一个窗口里同时加载着宿主的样式、共享组件
|
|
534
|
+
(`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
|
|
535
|
+
就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
|
|
536
|
+
|
|
537
|
+
🔴 **引用侧也有腿了(2026-09-20,SDK 0.1.46 起)**:TSX `className` **字面量**里引用的本插件前缀类名,必须能在本仓 CSS(含 scoped 规则)里找到定义——`linkdesk/no-reserved-class-name` 家族新判据机械把关。头号根因 = CSS 块注释里写 `--text-*/` 这类文本:`*/` 把注释**提前闭合**,残渣黏住下一条规则把它整条吞掉(生态首例,样式静默丢失零报错);文案列三种常见根因(拼错/漏 import/注释吞规则)。动态拼接(模板插值 / clsx / 变量)跳过并计数。
|
|
538
|
+
|
|
539
|
+
**三条纪律:**
|
|
540
|
+
|
|
541
|
+
1. **给自己的元素起的类名,必须以 `pluginId` 加连字符开头**——`settings-*`、`editor-*`、`file-tree-*`……
|
|
542
|
+
`pluginId` 就是你 `plugin.json` 里声明的那个 id(官方插件统统这么做)。**别用缩写**:`ms-`、
|
|
543
|
+
`mpd-` 这类简写写法**已经废弃**——缩写不保证唯一,两个插件各自缩写成 `ms-` 就撞在一起了;
|
|
544
|
+
而 `pluginId` 的唯一性由发布流程保证(发布后不可变),拿它当前缀是免费的防撞。
|
|
545
|
+
2. **`@keyframes` 的名字一样要带前缀**(`file-tree-fadeIn`),并且**改名字时同笔改 `animation:` 的引用**——
|
|
546
|
+
关键帧名与类名一样是全局标识符,重名时后加载的那份会把前一份的动画顶掉。
|
|
547
|
+
3. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
|
|
548
|
+
|
|
549
|
+
| 来源 | 保留名 | 说明 |
|
|
550
|
+
|---|---|---|
|
|
551
|
+
| 宿主**给你的**输入框工具类 | `.ldk-input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的)。⚠️ 它是整个 `ldk-` 家族里**唯一**鼓励你**消费**的一个(其余的 `ldk-` 名是「别碰」,它是「拿去用」) |
|
|
552
|
+
| 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle`、`ldk-hint-card`(2026-09-19 起,悬停说明卡)等(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`、`ldk-input`、`ldk-setting-group`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用**(唯一的例外是上一行的 `.ldk-input`:那个是**给你用的**) |
|
|
553
|
+
|
|
554
|
+
**`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
|
|
555
|
+
|
|
556
|
+
| 保留的关键帧名 | 说明 |
|
|
557
|
+
|---|---|
|
|
558
|
+
| `ldk-selectbox-in` | 共享组件下拉框的入场动画 |
|
|
559
|
+
| `ldk-drop-zone-in` | 拖放区的入场动画(宿主的自有动画一律带 `ldk-` 前缀) |
|
|
560
|
+
| `ldk-dropdown-card-in` | 下拉卡片的入场动画 |
|
|
561
|
+
| `ldk-floating-panel-in` | 浮动面板的入场动画 |
|
|
562
|
+
| `ldk-notif-icon-spin` | 通知图标的旋转 |
|
|
563
|
+
| `ldk-notif-progress-scan` | 通知的进度扫描 |
|
|
564
|
+
| `ldk-rn-spin` | 发行说明页刷新图标的旋转 |
|
|
565
|
+
| `ldk-boot-mark-breath` | 池首帧品牌过场的呼吸 |
|
|
566
|
+
| `ldk-view-skeleton-breath` | 内容加载骨架的呼吸 |
|
|
567
|
+
| `ldk-welcome-skeleton-breath` | 欢迎页最近列表加载骨架的呼吸 |
|
|
568
|
+
| `ldk-welcome-in` | 欢迎页入场 fade-up(全页唯一一处入场) |
|
|
569
|
+
|
|
570
|
+
**引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
|
|
571
|
+
你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
|
|
572
|
+
**上面那张保留表里的**(引用宿主的动画是**合法消费**,不会判你)。引一个**谁都没定义**的名字,
|
|
573
|
+
动画**不报错、不警告,只是不动**——症状是「我的动画怎么没生效」,而控制台一片安静(同一个窗口里
|
|
574
|
+
还有别的插件和宿主在跑,你很难一眼看出是这一条)。`@linkdesk/plugin-sdk` **≥ 0.1.37** 起,插件的
|
|
575
|
+
lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 + 名字**);确需引用一个门禁看不见的名字
|
|
576
|
+
(例如动画由运行时注入),用标准 `eslint-disable` 注释写明理由。
|
|
577
|
+
|
|
578
|
+
> 🔧 **维护者注(作者可跳过)**:上面两张表的「**保留名**」「**保留的关键帧名**」两列都是**机器读的**——`npm run check` 里的门禁
|
|
579
|
+
> (`scripts/check-reserved-names-doc-sync.mjs`)把它们与登记表
|
|
580
|
+
> `packages/plugin-sdk/schemas/reserved-class-names.json` **双向核对**:登记表里的名字必须在这里出现,
|
|
581
|
+
> 这里出现的名字必须在登记表里登记(裸名)、或在宿主源码里真实存在(`ldk-` 名);关键帧表与登记表的
|
|
582
|
+
> `keyframes` 段同样**双向**。
|
|
583
|
+
> ⇒ **改这两列 = 改公共面**:加/删一个名字要**同笔改三处**——登记表 + 中英两棵树的这两张表。
|
|
584
|
+
> 两列**只放名字**,解释写「说明」列。
|
|
585
|
+
|
|
586
|
+
**还有一条跟命名空间有关的**:你的 `pluginId` **不得以 `ldk-` 开头**——整个 `ldk-` 命名空间是宿主的,
|
|
587
|
+
一个叫 `ldk-tools` 的插件用纪律 1 派生出来的前缀(`ldk-tools-*`)会**由构造落进宿主空间**,纪律 1
|
|
588
|
+
也就跟着失效了。这条约束写在 `plugin.json` 的 schema 里,编辑器会当场提示。
|
|
589
|
+
|
|
590
|
+
**要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
|
|
591
|
+
(手写等于绕过组件,组件升级你就掉队)。
|
|
592
|
+
|
|
593
|
+
**状态类一律复合使用**:`.你的类.active`、`.你的类.on`(不要裸写 `.active {}`、`.on {}`——那会把
|
|
594
|
+
宿主和其他插件里带同名状态类的元素一起改掉)。
|
|
595
|
+
|
|
596
|
+
**反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
|
|
597
|
+
同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
|
|
598
|
+
|
|
599
|
+
**删组件时,同笔删它的 CSS 规则**——被壳的共享组件(`SidePanel` / `SidebarSection`)接管了的节点,
|
|
600
|
+
插件侧**不要留孤儿规则**:规则还在、节点没了,它就成了一个**静默吃掉样式**的挂载点——谁哪天往那个
|
|
601
|
+
类上挂样式(比如一个本地 token),都会**静默失效**(1.24 真实事故:官方 `serial-monitor` 的侧栏状态点
|
|
602
|
+
颜色被静默丢掉,v1.0.17 当场修正)。拿不准有没有孤儿规则,跑壳仓的
|
|
603
|
+
`npm run audit:plugin-dead-css`——它把「定义了、源码没人用」的自有前缀类逐条列出来(只报不拦)。
|
|
604
|
+
|
|
605
|
+
### 12.1 从旧版 `@linkdesk/ui` 升上来——一件要你自己改的事
|
|
606
|
+
|
|
607
|
+
共享组件的类名带上了 `ldk-` 前缀(`@linkdesk/ui` **0.2.0** 起)。这件事**只影响一种写法**:
|
|
608
|
+
你写在**插件自己 CSS 里**、用后代选择器去微调共享组件外观的那些规则。**升级前不用动,升级时改一处前缀即可。**
|
|
609
|
+
|
|
610
|
+
- **什么时候受影响**:把 `@linkdesk/ui` 升到 **0.2.0 之后**——**不是立刻**。旧版本里这些组件的类名是
|
|
611
|
+
`.badge` 这样的裸名,包里带的 CSS 与组件自洽,**你不升级就不会坏**。(依赖写 `^0.1.x` 时不会自动
|
|
612
|
+
跨到 `0.2.0`,所以只有你主动升级的那一下才需要动。)
|
|
613
|
+
- **什么会受影响**:你**插件自己 CSS** 里的这类后代选择器——
|
|
614
|
+
`.control-bar .combobox { … }`、`.settings-slider-control .slider { … }`、`.changelog .mdv { … }`
|
|
615
|
+
等等。**组件自己的样式不受影响,你自己的类名也不用改。**
|
|
616
|
+
- **怎么改**:把选择器里**指向共享组件的那一段**加上 `ldk-` 前缀——`.combobox` → `.ldk-combobox`、
|
|
617
|
+
`.slider` → `.ldk-slider`、`.mdv` → `.ldk-mdv`、`.badge` → `.ldk-badge`、`.selectbox-trigger` →
|
|
618
|
+
`.ldk-selectbox-trigger`、`.combobox-field` → `.ldk-combobox-field`——**族里的名字(`-trigger` / `-field` /
|
|
619
|
+
`-input` 这类后缀)一样带前缀**。你自己的前缀(`.control-bar`、`.settings-*`)照旧。
|
|
620
|
+
**升级后拿这八个旧基名 `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle`
|
|
621
|
+
grep 一遍自己的 CSS**:在调共享组件的就加上前缀,其余别动。
|
|
622
|
+
- **为什么不自动兼容**:这类失配**不报错**——选择器匹配不上,只是那几条规则悄悄不再生效,界面看着
|
|
623
|
+
「大致还对、就是不太对」。正因为它是静默的,我们才把名字收进 `ldk-` 前缀,并把这段写进文档。
|
|
624
|
+
|
|
625
|
+
### 12.2 前缀规则(§12 纪律 1/2)上线——既有代码要不要动
|
|
626
|
+
|
|
627
|
+
**一句话:不改也照常跑,但下次动那个文件就是该改的时候。**
|
|
628
|
+
|
|
629
|
+
- **官方插件已经按新规则清过账**——本次改名涉及四只:`file-tree`(v1.0.9)、`settings`(v1.0.11)、
|
|
630
|
+
`serial-monitor`(v1.0.12)、`marketplace`(v1.0.33),裸类名与关键帧名都补上了 `<pluginId>-` 前缀;
|
|
631
|
+
其余官方插件仓本来就没有裸定义(它们的类名不是自带前缀,就是根本没定义类名)。以官方插件清单为口径
|
|
632
|
+
的审计读数是 **18/18 合规**。
|
|
633
|
+
- **第三方作者没有仓要改**:这条规则只管**你自己写的类名与关键帧名**——不动仓库结构、不动 `pluginId`、
|
|
634
|
+
也不影响别人的代码。你既有插件**不用为它单独发版**。
|
|
635
|
+
- **旧的无前缀类名不会报错、也不会失效**——今天照常工作。代价是**撞名的风险仍然在**:另一个插件写了
|
|
636
|
+
同名类名,两边样式就会落到同一个元素上(不报错,只是长得不对,很难查)。
|
|
637
|
+
- **合规由工程自带的检查判**:脚手架建出来的工程带着一条严格检查腿(`npm run verify`),它扫你自己 CSS
|
|
638
|
+
里**给自有元素裸定义**的类名和 `@keyframes` 名,不带 `<pluginId>-` 前缀就判红。所以真正的动作是
|
|
639
|
+
**下一次动那个文件时顺手把名字改掉**:`.panel {}` → `.myplugin-panel {}`,CSS 与用到它的 JSX 两侧一起改
|
|
640
|
+
(只改标识符,不动样式值)。
|
|
641
|
+
|
|
642
|
+
> 现在就想看看自己的工程有没有裸名?在工程根跑 `npm run verify`。
|
|
643
|
+
|
|
644
|
+
### 12.3 宿主的输入框工具类改名了:`.input` → `.ldk-input`(2026-09-16)
|
|
645
|
+
|
|
646
|
+
**一句话:如果你的插件写过 `className="input"`,改成 `className="ldk-input"` 就行——样式一模一样,只是名字换了。**
|
|
647
|
+
|
|
648
|
+
- **改了什么**:宿主原来把一个输入框工具类叫 **`.input`**(不带前缀,是唯一一个不带 `ldk-` 的宿主公共名)。它和本条纪律 1「跨方的名字都带命名空间」冲突 ⇒ 现在统一叫 **`.ldk-input`**。同时宿主的**设置分组卡片** `.setting-group` 也改名为 **`.ldk-setting-group`**。
|
|
649
|
+
- **谁受影响**:**在你自己插件的 JSX/TSX 里写过 `className="input"` 的插件**——官方插件里 `settings` 与 `serial-monitor` 两家用过,已在同一批发版改好。**改法就一处**:`className="input"` → `className="ldk-input"`;拼接写法同理(`"input my-input"` → `"ldk-input my-input"`)。**样式零变化**——同一条规则、同一批 CSS 变量,只换了名字。
|
|
650
|
+
- **不改会怎样**:输入框**不报错**,只是**失去宿主给的外观**(底色 / 边框 / 圆角 / 内边距),看起来像浏览器原生输入框。
|
|
651
|
+
- **什么时候必须改**:在**新壳**上跑就要改。新壳的版本号是 **`0.2.0`**,官方两只插件都已在 `plugin.json` 里声明 `minAppVersion: "0.2.0"`——你也给自己的插件声明同一个值,旧壳上的用户就会收到一句清楚的「需要应用版本 ≥0.2.0」提示,而不是看到一个没样式的输入框(`minAppVersion` 的语义见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
|
|
652
|
+
|
|
653
|
+
### 12.4 共享组件剩下的类名也带 `ldk-` 了(2026-09-16)
|
|
654
|
+
|
|
655
|
+
**一句话:和 12.1 同一件事,只是把当时没覆盖到的组件补上——你若在自己 CSS 里用后代选择器微调过这些组件,升级时加一个 `ldk-` 前缀即可。**
|
|
656
|
+
|
|
657
|
+
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes` 名——现在也带上了前缀(**2026-09-16 那轮起**;版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)):
|
|
658
|
+
|
|
659
|
+
| 旧族 | 新族 |
|
|
660
|
+
|---|---|
|
|
661
|
+
| `.colorpicker-*` | `.ldk-colorpicker-*` |
|
|
662
|
+
| `.ctx-*` | `.ldk-ctx-*` |
|
|
663
|
+
| `.form-row` | `.ldk-form-row` |
|
|
664
|
+
| `.inline-input`、`.inline-input--compact/--normal` | `.ldk-inline-input`、`.ldk-inline-input--compact/--normal` |
|
|
665
|
+
| `.number-input*` | `.ldk-number-input*` |
|
|
666
|
+
| `.segmented-radio`、`.segmented-radio__option/__label` | `.ldk-segmented-radio`、`.ldk-segmented-radio__option/__label` |
|
|
667
|
+
| `.sidebar-section*`、`.sidebar-pane-view`、`.sidebar-pane-sash` | `.ldk-sidebar-section*`、`.ldk-sidebar-section-pane-view`、`.ldk-sidebar-section-pane-sash` |
|
|
668
|
+
| `.theme-picker*`、`.theme-card`、`.theme-preview` | `.ldk-theme-picker*`、`.ldk-theme-picker-card`、`.ldk-theme-picker-preview` |
|
|
669
|
+
| `.tbadge` / `.tname` / `.pv-bar` / `.pv-dot`(主题卡片内部) | `.ldk-theme-picker-badge` / `.ldk-theme-picker-name` / `.ldk-theme-picker-preview-bar` / `.ldk-theme-picker-preview-dot` |
|
|
670
|
+
| `@keyframes selectbox-in` | `@keyframes ldk-selectbox-in` |
|
|
671
|
+
|
|
672
|
+
- **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
|
|
673
|
+
- **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
|
|
674
|
+
- 🔴 **宿主以后改共享名 / 改样式,你这边不必改代码、也不必改 CSS**——组件与样式**由壳池统一供给**(壳池集中供给,见 [19-组件速查 §二](19-组件速查.md)):壳升级后同一份实现跟着壳走,界面自然一致。你唯一要维持的是 `@linkdesk/ui` 依赖**别掉出当前版本线**(它决定你本地 dev 与类型解析到的那一份)。
|
|
675
|
+
- ⛔ **组件样式同样不从你的源码里来**:源码里出现 `import "@linkdesk/ui/index.css"`(或其 dist / `@import` 形态)会被 SDK 的 lint 腿 `linkdesk/no-ui-css-import` 判红——**没有豁免出口**。把样式烤进插件,等于「壳改样式、全生态跟随」对你失效。
|
|
676
|
+
- **什么时候必须改**:当你要支持的壳升到含这次改名的版本时(版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)——ui 版本 = 壳版本,一条线)。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
|
|
677
|
+
- **这把尺子你也有**(`@linkdesk/plugin-sdk` 0.1.40 起):你仓里的 lint 自带「悬空名」判据——宿主改了共享名、你没跟上时,**你自己的 CI 会替你喊**(用法与修法见 [16-命名规范 §7.6](16-命名规范.md))。
|
|
678
|
+
|
|
679
|
+
### 12.5 自定义属性的**作用域**——`--x:` 写在 `:root` 里就等于写给整个软件
|
|
680
|
+
|
|
681
|
+
类名那三条纪律管的是**名字**,这一节管**地盘**。自定义属性(`--xxx`)的规矩只有一句:
|
|
682
|
+
|
|
683
|
+
> **作用域才是命名空间。** 名字随你起,**它住在哪棵子树里**才是它属于谁。
|
|
684
|
+
|
|
685
|
+
**① 文档级的作用域只有宿主能用。** `:root` / `html` / `body` / `[data-theme="…"]` / `*` 上的定义
|
|
686
|
+
**对整个文档可见**——那不是你的地盘:
|
|
687
|
+
|
|
688
|
+
```css
|
|
689
|
+
/* ❌ 这条定义全文档可见 */
|
|
690
|
+
:root { --my-panel-gap: 8px; }
|
|
691
|
+
|
|
692
|
+
/* ✅ 挂在你自己的根类之下,作用域 = 你的子树 */
|
|
693
|
+
.my-plugin-root { --my-panel-gap: 8px; }
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
**② 其余定义一律挂在自己的类之下。** 写 `.你的类 { --xxx: … }` 就好——**这里的名字不需要任何前缀**:
|
|
697
|
+
`:root` 上的 `--gap` 会跟别人撞,`.my-plugin-root` 下的 `--gap` 不会(作用域已经把地盘划开了)。
|
|
698
|
+
|
|
699
|
+
**③ `--ldk-*` 自定义属性谁都不许定义**(和类名、关键帧同一条规矩——整个 `ldk-` 命名空间是宿主的)。
|
|
700
|
+
|
|
701
|
+
**为什么这条比类名还凶**:宿主大部分颜色 / 圆角 / 层级**不是由程序写上去的、而是靠样式表提供的**。
|
|
702
|
+
你在 `:root` 里写一个宿主的契约名(比如 `--bg-card`),**你会赢**——整个软件的卡片底色跟着变;
|
|
703
|
+
而且**换个主题可能又变回来**(主题会覆盖其中一部分名字)⇒ 症状是「**时好时坏**」,最难查的一类。
|
|
704
|
+
|
|
705
|
+
**一条自检**(写完 CSS 顺手看一眼):**「我的 `--x:` 是不是写在 `:root` 里?」** 是 ⇒ 搬进你自己的根类。
|
|
706
|
+
|
|
707
|
+
**迁移**——已经在 `:root` 里写过自定义属性的插件:
|
|
708
|
+
|
|
709
|
+
| 情形 | 判级 | 怎么办 |
|
|
710
|
+
|---|---|---|
|
|
711
|
+
| 名字**带**你自己的前缀(`--my-plugin-gap`) | 🟡 建议改 | 搬进自己的根类。名字是你的、没人跟你抢,但「写在 `:root`」本身没有理由——改完作用域从整个文档缩回你自己的子树 |
|
|
712
|
+
| 名字**不带**前缀(`--gap`、`--bg-card`…) | 🔴 必须改 | 它此刻在全文档生效、可能正覆盖着宿主或别的插件的值 ⇒ 把它搬进自己的根类(名字可以照旧保留,**换的是作用域**) |
|
|
713
|
+
| 名字以 `ldk-` 开头 | 🔴 必须改 | 换成你自己的名字——`ldk-` 是宿主命名空间 |
|
|
714
|
+
| 写在**自己的根类**之下 | ✅ 合规 | 不用动。`.你的根类 .ldk-x { --y: … }` 这类**微调**同样合规(选择器里有你自己的类就行) |
|
|
715
|
+
|
|
716
|
+
**它怎么被机械守住**:在插件工程根跑 `npm run lint`(或 CI 里的 `npm run verify`)会逐条报出来
|
|
717
|
+
——🔴 会让 CI 红,🟡 只提示不拦。「我的插件本地好好的、CI 却红」时先看这一段。
|
|
718
|
+
|
|
719
|
+
> 🔧 **维护者注(作者可跳过)**:规则正文(含宿主契约块的登记方式、浮层宿主根那个例外)在
|
|
720
|
+
> `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
|
|
721
|
+
> `scripts/check-css-namespace.mjs` 守着,插件侧由 SDK 的 `check-css-namespace` 腿守着
|
|
722
|
+
> (token 作用域是那条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
|
|
723
|
+
|
|
724
|
+
### 12.6 选择器本身也要有「落点」——**禁写无锚选择器**(2026-09-16)
|
|
725
|
+
|
|
726
|
+
前五节管的是**名字**(类名 / 关键帧 / 自定义属性)。这一节管**选择器的形态**——一条更容易忽略的规矩:
|
|
727
|
+
|
|
728
|
+
> **类名和 id 是「名字锚」;元素 / 通配 / 属性 / 伪类 / 伪元素不是。**
|
|
729
|
+
> 后者**不需要与任何人同名**就能命中别人的元素。
|
|
730
|
+
|
|
731
|
+
```css
|
|
732
|
+
/* ❌ 一条规则改掉「这个文档里所有」的按钮——宿主和其他插件的按钮全在内 */
|
|
733
|
+
button { border: none; }
|
|
734
|
+
* { box-sizing: border-box; }
|
|
735
|
+
#some-id { display: none; } /* id 也是全局的、可猜的,优先级还高于类 */
|
|
736
|
+
:root { outline: none; } /* `:root` 同样是无锚选择器 */
|
|
737
|
+
|
|
738
|
+
/* ✅ 挂在自己的根类之下——同一个意图,落点只有你自己的子树 */
|
|
739
|
+
.my-plugin-root button { border: none; }
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
**两条规则**(都在插件工程根 `npm run lint` / CI `npm run verify` 里**机械判红**):
|
|
743
|
+
|
|
744
|
+
| 规则 | 判定 | 为什么 |
|
|
745
|
+
|---|---|---|
|
|
746
|
+
| **禁无锚选择器** | 选择器**没有**任何 `.类` 或 `#id` 主体(元素 / 通配 / 属性 / 伪类 / 伪元素;**顶层或限定一律禁,`@media` 内也算**)⇒ 🔴 | 它命中「该文档里所有那一类元素」,与谁渲染无关 |
|
|
747
|
+
| **跨方命中必须自带自有锚** | 选择器里出现 `ldk-*` 类(**含 `:has(…)` 内的提及**)却**不带** `.<你的 pluginId>-*` 类 ⇒ 🔴 | `ldk-` 是宿主命名空间;**调优必须发生在自己的地盘里** |
|
|
748
|
+
|
|
749
|
+
⚠️ **第二条不影响「改共享组件外观」这件事本身**——那是**合法特性**(scoped 调优)。它只要求你**带着自家前缀作锚**:
|
|
750
|
+
|
|
751
|
+
```css
|
|
752
|
+
/* ❌ 改的是宿主/共享组件的元素,自己却一点落点都没有 ⇒ 判红 */
|
|
753
|
+
.ldk-toggle { transform: scale(1.1); }
|
|
754
|
+
|
|
755
|
+
/* ✅ 同一个意图,写在自己的地盘里 ⇒ 合规 */
|
|
756
|
+
.my-plugin-root .ldk-toggle { transform: scale(1.1); }
|
|
757
|
+
```
|
|
758
|
+
|
|
759
|
+
**为什么值得专门记住**:宿主自己就有 **17 处**这样的「无锚选择器」(`*` 重置 / `html`·`body` /
|
|
760
|
+
`[data-theme]` / `*:focus-visible` / 滚动条一族 / `input[type="number"]`·`select`)——它们**是有意的
|
|
761
|
+
共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
|
|
762
|
+
你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
|
|
763
|
+
|
|
764
|
+
**迁移**:**今天 0 存量**——官方插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
|
|
765
|
+
的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
|
|
766
|
+
|
|
767
|
+
> 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
|
|
768
|
+
> `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`;
|
|
769
|
+
> 宿主侧由 `scripts/check-css-namespace.mjs` 的判据⑩⑪(+ 探针轴 ④ 的运行时镜像)守着,
|
|
770
|
+
> 插件侧由 SDK 的 `check-css-namespace` 腿的**第四、第五条判据**守着(`checks/selector-form.ts` 的 S2/S3,
|
|
771
|
+
> 与 `checks/keyframe-refs.ts` 的关键帧引用悬空 —— 后者 **2026-09-18 起**在位,SDK `≥ 0.1.37`)。
|
|
772
|
+
|
|
773
|
+
---
|
|
774
|
+
|
|
775
|
+
## 13. 悬停提示 → `data-hint` 属性(或 `<HintTip>`)
|
|
776
|
+
|
|
777
|
+
**鼠标停在你的按钮/图标上时,那个小条不是浏览器画的。**
|
|
778
|
+
|
|
779
|
+
宿主有一套统一的轻提示(`HintTip`):深浅主题、字号缩放、贴边翻面、快捷键键帽都由壳一处决定。
|
|
780
|
+
**你不需要 import 任何东西**就能用——写属性即可:
|
|
781
|
+
|
|
782
|
+
```tsx
|
|
783
|
+
// ❌ 原生 title:浏览器画,主题/缩放/键帽都不跟壳走(SDK ≥ 0.1.49 起这条腿判红)
|
|
784
|
+
<button title={t("刷新")}>
|
|
785
|
+
|
|
786
|
+
// ✅ 属性式:把 title= 换成 data-hint=(DOM 结构零变化)
|
|
787
|
+
<button data-hint={t("刷新")} aria-label={t("刷新")}>
|
|
788
|
+
|
|
789
|
+
// ✅ 带快捷键:给命令 id,壳去查命令表(文案与快捷键都来自那一份 ⇒ 提示条/右键菜单/命令面板永远一个说法)
|
|
790
|
+
<button data-hint-command="fileTree.refresh" aria-label={t("刷新")}>
|
|
791
|
+
|
|
792
|
+
// ✅ 揭示类("看全被截断的字"):该立刻出现,别让它等
|
|
793
|
+
<div data-hint={fullPath} data-hint-delay="0">{truncated}</div>
|
|
794
|
+
|
|
795
|
+
// ✅ 复合场景(要自己控制包裹):组件式
|
|
796
|
+
import { HintTip } from "@linkdesk/ui";
|
|
797
|
+
<HintTip label={t("刷新")} command="fileTree.refresh"><button …>…</button></HintTip>
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
四个属性,都写在你自己的 DOM 元素上:
|
|
801
|
+
|
|
802
|
+
| 属性 | 作用 |
|
|
803
|
+
|---|---|
|
|
804
|
+
| `data-hint` | 提示主文案(说明类与揭示类通用——**文案永远由你给**,壳不下发任何句子) |
|
|
805
|
+
| `data-hint-command` | 命令 id——壳查命令表取名字与快捷键。与右键菜单/命令面板**同源**(改一处全跟走) |
|
|
806
|
+
| `data-hint-delay` | 意图延时(毫秒)。说明类**留默认**(120ms——防划过闪一下);揭示类传 `"0"` |
|
|
807
|
+
| `data-hint-placement` | 首选方位 `top`/`bottom`/`left`/`right`(缺省 `top`,贴不下自动翻面) |
|
|
808
|
+
|
|
809
|
+
**⚠️ 三条纪律**
|
|
810
|
+
|
|
811
|
+
1. **说明类慢、揭示类近 0**——「看全被截断的字」要立刻;反过来给图标加命令说明才该等那一等。
|
|
812
|
+
2. **别再用原生 `title=`**:SDK 腿 `linkdesk/no-native-title`(SDK ≥ 0.1.49)判红——`lint` 输出红行、
|
|
813
|
+
`ci-verify` 判红。确需原生 title 的形态(提示渲染器够不到的)走
|
|
814
|
+
`// eslint-disable-next-line linkdesk/no-native-title -- 理由`(**理由必填**)。
|
|
815
|
+
3. **条内不放按钮**:提示是提示不是菜单(要交互用 `<ContextMenu>`);要**长文案/标题/注脚**或多行说明,
|
|
816
|
+
用 `HintCard`——那一件本来就是管"有注脚的长说明"的。
|
|
817
|
+
|
|
818
|
+
> 🔧 **维护者注(作者可跳过)**:渲染器 = `src/components/shared/hint-tip/HintTipRenderer.tsx`(池内单例挂载:
|
|
819
|
+
> 委托 `pointerover`/`pointerout`/`focusin`/`focusout` + 意图延时状态机);属性字面量的单一真相源 =
|
|
820
|
+
> `hintAttrs.ts`(⛔ 别处不许再写 `"data-hint"` 字面量);总开关 = 壳配置 `app.hint.enabled`(缺省开,设置页可见);
|
|
821
|
+
> 门禁三腿 = 壳侧 `scripts/check-native-title.mjs`(存量白名单账、只判新增)+ SDK 腿
|
|
822
|
+
> `checks/no-native-title.ts`(同 id、锚⑪ 3 句锚词互钉)。
|
|
823
|
+
|
|
824
|
+
---
|
|
825
|
+
|
|
826
|
+
## 速查
|
|
827
|
+
|
|
828
|
+
| 你要做的 | 核心设施 | 引入方式 |
|
|
829
|
+
|---|---|---|
|
|
830
|
+
| 右键菜单 | `<ContextMenu>`(open-string menuId) | `@linkdesk/ui`(ContextMenu)+ `plugin.json contributes.menus` 声明(或 `window.linkdesk.menu.registerItems`,见 §1) |
|
|
831
|
+
| 浮层/弹窗 | `createPortal` | `react-dom`(渲染到 `document.body`,见 §2) |
|
|
832
|
+
| 持久化 | `window.linkdesk.configuration.get/set/onChange` | 插件通信铁律——只走 window.linkdesk.*(见 §3) |
|
|
833
|
+
| 系统选择器 | `window.linkdesk.quickPick.show` | 池内 QuickPickHost 统一渲染(见 §9) |
|
|
834
|
+
| 通知 | `window.linkdesk.notifications.show` | 池内**铃铛宽通知面板**统一渲染(见 §9;语义见 `01-插件API契约.md` §3.2) |
|
|
835
|
+
| 确认/提示/文件选择 | `window.linkdesk.dialog.confirm/alert/open/openFile` | 池内 DialogHost 统一渲染(见 §9) |
|
|
836
|
+
| 富内容确认框 | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | 池内 DialogHost 渲染壳,**内容 = 插件自绘视图**(见 §9) |
|
|
837
|
+
| 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
|
|
838
|
+
| 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
|
|
839
|
+
| 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
|
|
840
|
+
| 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
|
|
841
|
+
| 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
|
|
842
|
+
| 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
|
|
843
|
+
| 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
|
|
844
|
+
| UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
|
|
845
|
+
| 文字 | `t()` | `useTranslation()` from `react-i18next` |
|
|
846
|
+
| CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
|
|
847
|
+
| 元素 / id 选择器 | 必须挂在自己的根类之下 | 见 §12.6(无锚选择器不需要同名就能命中所有人的元素) |
|
|
848
|
+
| 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
|
|
849
|
+
|
|
850
|
+
**写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
|