@linkdesk/plugin-docs 0.1.61 → 0.1.63
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/03-contributes-spec.md +2 -0
- package/docs/22-menu-contribution-points.md +25 -1
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +2 -0
- package/docs/zh/22-/350/217/234/345/215/225/350/264/241/347/214/256/347/202/271.md +22 -1
- package/docs/zh/plugin.schema.json +1 -1
- package/package.json +1 -1
|
@@ -217,6 +217,8 @@ useEffect(() => {
|
|
|
217
217
|
|
|
218
218
|
**⚠️ Track selection (`05 §4`):** only put **non-text keys** in `contributes.keybindings`. Writing text-editing keys such as `ctrl+c` / `ctrl+v` / `f2` here makes the main process's `before-input-event` unconditionally swallow input in every pool text field. The right way to bind text keys / focus-bound keys is a pool-side container `onKeyDown` (DOM focus partitions naturally).
|
|
219
219
|
|
|
220
|
+
**⚠️ A user's "Clear" overrides your declaration.** Two items in the shortcut page's gear menu look alike but are not: **"Reset to Default"** only removes the user's override (your `key` comes back), while **"Clear" means this command should have no key** — once a user clears it, your `contributes.keybindings` entry for that command is **no longer registered** (the host keeps a suppression list at the registration entry point), and it **stays that way across restarts**. That is the user's explicit intent: ⛔ it is not a bug and your declaration is not wrong, so don't go hunting for "why is my shortcut not registering". Re-binding the command in the page, or choosing "Reset to Default", lifts the suppression and your declaration takes effect again. On disk it is a single `{ "command": "…", "key": "" }` entry (empty `key` = the clear marker) in the user's `keybindings.json`. To clear from plugin code: `window.linkdesk.keybindings.clearKeybindingForCommand` (LinkDesk **0.2.46+**; older shells lack the method — probe before calling).
|
|
221
|
+
|
|
220
222
|
### 3.4 `contributes.configuration` — settings
|
|
221
223
|
|
|
222
224
|
```json
|
|
@@ -160,7 +160,7 @@ Posting into the `menuBar` or `panel` slot with `group: "panel"` merges the item
|
|
|
160
160
|
| `&&` / `\|\|` / `!` / `( )` | `resourceIsFile && !file-tree.inputFocus` | Boolean combination (`!` binds tightest, then `&&`, then `\|\|`) |
|
|
161
161
|
| `true` / `false` | `when: "false"` | Constants (`false` = never show; useful as a placeholder) |
|
|
162
162
|
|
|
163
|
-
### 🔴
|
|
163
|
+
### 🔴 Three pitfalls you must know
|
|
164
164
|
|
|
165
165
|
**Pitfall 1 — literals need (single) quotes.**
|
|
166
166
|
The parser only accepts `'…'` (and numbers) as literals. Writing `resourceExtname == .md` without quotes **fails to parse**,
|
|
@@ -184,6 +184,29 @@ use the boolean key:
|
|
|
184
184
|
"when": "resourceExtname != ''" // ❌ false when undefined; reads fine but is ambiguous
|
|
185
185
|
```
|
|
186
186
|
|
|
187
|
+
**Pitfall 3 — an identifier in `when` is a plain property lookup on the object you hand in (watch this in plugin-authored slots).**
|
|
188
|
+
The host reads `when` with a **bare property lookup** (`key in overrides ? overrides[key] : global value`) — the identifier in the
|
|
189
|
+
expression is used **verbatim as the property name**. So when you render one of **your own slots** with the shared `ContextMenu`
|
|
190
|
+
and pass the row data down through its `context` prop, the name in `when` must match that object's field name
|
|
191
|
+
**character for character, case included**. A mismatch — or renaming one side only — makes the expression **permanently false and
|
|
192
|
+
the item silently disappears**: no error, no warning, **not even the console line from Pitfall 1**.
|
|
193
|
+
|
|
194
|
+
```jsonc
|
|
195
|
+
// menu declaration: reads the per-row "this row has a binding" flag
|
|
196
|
+
{ "command": "my-plugin.copyKey", "when": "rowHasKey" }
|
|
197
|
+
```
|
|
198
|
+
```tsx
|
|
199
|
+
// the object handed down at render time — the field name must match "rowHasKey" exactly
|
|
200
|
+
<ContextMenu context={{ command, key, rowHasKey: key !== "" }} … />
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
> 🔴 Real case, 2026-10-05: the official `settings` plugin 1.0.32 shipped a keybinding-row gear menu whose three gated items
|
|
204
|
+
> (copy keybinding / copy as JSON / reset to default) **never appeared at all** — the declaration said `keybindingHasKey` /
|
|
205
|
+
> `keybindingIsUser`, while the fields were `hasKey` and there was no `isUser` at all. All nine gate legs and every unit test
|
|
206
|
+
> were green, because **none of them evaluates `when`**. The fix pairs two things: derive the field names with
|
|
207
|
+
> **computed property names** from a single constant (so a rename becomes a TypeScript compile error), plus a **contract
|
|
208
|
+
> regression test** that reconciles the menu declaration in `plugin.json` against the runtime row object. Worth copying.
|
|
209
|
+
|
|
187
210
|
### Which keys you may use
|
|
188
211
|
|
|
189
212
|
| Key | Value | Written by | Notes |
|
|
@@ -230,6 +253,7 @@ A menu item **only references a command id**, so rule number one is always:
|
|
|
230
253
|
|:--|:--|:--|
|
|
231
254
|
| Not a single item of mine in the slot | The slot key was written as the member name (`FileContext`) | The `check-menu-slot-case` gate (inside `npm run lint` / `verify`); or look at your `plugin.json` and check the key is lower camelCase |
|
|
232
255
|
| Appears sometimes, not others | The `when` is false | Re-run the `when` in the debug entry, or look for `when 表达式解析失败` in the console |
|
|
256
|
+
| My item **never appears** (not intermittently), and the console is clean | The identifier in `when` does not match the field name of the object you hand into the menu (spelling/case) — the host does a bare property lookup, so a miss is simply false | Derive the field name with a **computed property name** from one constant, or write a declaration↔runtime contract test (see §5, Pitfall 3) |
|
|
233
257
|
| Appears but does nothing when clicked | The command was never registered (declared in `contributes.commands` but no pool-side `registerCommand`) | See [21-command-ification-spec](21-command-ification-spec.md) §2 "two legs" |
|
|
234
258
|
| My item sorts first/last and loses to others | `order` defaults to `100` and other groups are smaller | Adjust `order` or rename the group (group order = first appearance) |
|
|
235
259
|
| A "missing your repo's prefix" report | A command id / config key / appearance id / context key lacks the `<pluginId>.` prefix | `npm run verify` reports the site and suggests a name (see [16-naming-conventions](16-naming-conventions.md) §7) |
|
|
@@ -215,6 +215,8 @@ useEffect(() => {
|
|
|
215
215
|
|
|
216
216
|
**⚠️ 轨道选择(`05 §4`):** 只把**非文本键**写进 `contributes.keybindings`。`ctrl+c` / `ctrl+v` / `f2` 等文本编辑键写这里 = 主进程 `before-input-event` 无条件吞全池输入框。文本键/焦点绑定键正解 = 池侧容器 `onKeyDown`(DOM 焦点天然分区)。
|
|
217
217
|
|
|
218
|
+
**⚠️ 用户的「清空」会压掉你的声明。** 快捷键页齿轮菜单里两项看着像、其实不同:**「恢复为默认」**只删用户的覆盖(你的 `key` 顶回来);**「清空」=这条命令不要键**——用户清空后,你的 `contributes.keybindings` 对那条命令**不再注册**(壳侧抑制名册拦在注册入口),且**重启后依然如此**。那是用户的显式意愿:⛔ 不是 bug,也不是你的声明写错了,别去猜「为什么我的快捷键没生效」。用户在快捷键页重新绑定、或点「恢复为默认」,都会解除抑制,你的声明随之恢复。落盘形状 = 用户 `keybindings.json` 里一条 `{ "command": "…", "key": "" }`(空 `key` = 清空标记)。需要插件侧主动清空时用 `window.linkdesk.keybindings.clearKeybindingForCommand`(LinkDesk **0.2.46+**;旧壳没有此方法,调用前先探测)。
|
|
219
|
+
|
|
218
220
|
### 3.4 `contributes.configuration`——设置项
|
|
219
221
|
|
|
220
222
|
```json
|
|
@@ -156,7 +156,7 @@
|
|
|
156
156
|
| `&&` / `||` / `!` / `( )` | `resourceIsFile && !file-tree.inputFocus` | 布尔组合(`!` 优先级最高,`&&` 高于 `\|\|`) |
|
|
157
157
|
| `true` / `false` | `when: "false"` | 常量(`false` = 恒隐藏,留占位用) |
|
|
158
158
|
|
|
159
|
-
### 🔴
|
|
159
|
+
### 🔴 三个必须知道的坑
|
|
160
160
|
|
|
161
161
|
**坑 1 —— 字面量要加引号(单引号)。**
|
|
162
162
|
解析器只认 `'…'`(和数字)当字面量。写成 `resourceExtname == .md`(不加引号)**解析失败** ⇒
|
|
@@ -178,6 +178,26 @@
|
|
|
178
178
|
"when": "resourceExtname != ''" // ❌ 未定义时 != 不成立,看着对但语义含糊
|
|
179
179
|
```
|
|
180
180
|
|
|
181
|
+
**坑 3 —— `when` 里的标识符 = **你递进去那个对象上的属性名**(**插件自有槽位**尤其要盯)。**
|
|
182
|
+
宿主读 `when` 是**裸属性查表**(`key in overrides ? overrides[key] : 全局值`):表达式里的标识符**原样当属性名**用。
|
|
183
|
+
所以当你在**自己的槽位**上用共享 `ContextMenu` 渲染、并把「本行数据」通过它的 `context` prop 递下去时,
|
|
184
|
+
`when` 里写的名字必须与那个对象的字段名**逐字相同(含大小写)**;写错、或改名只改了一边 ⇒ **恒为假、项静默消失**——
|
|
185
|
+
不报错、不警告,**连坑 1 那行控制台都没有**。
|
|
186
|
+
|
|
187
|
+
```jsonc
|
|
188
|
+
// 菜单声明:读「本行有绑定」这个行局部旗子
|
|
189
|
+
{ "command": "my-plugin.copyKey", "when": "rowHasKey" }
|
|
190
|
+
```
|
|
191
|
+
```tsx
|
|
192
|
+
// 渲染时递下去的对象——字段名必须与 "rowHasKey" 逐字对上
|
|
193
|
+
<ContextMenu context={{ command, key, rowHasKey: key !== "" }} … />
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
> 🔴 2026-10-05 实况:官方 `settings` 1.0.32 的快捷键行齿轮菜单,三条门控项(复制快捷键/复制为 JSON/重置为默认)
|
|
197
|
+
> **一条都没出现**——声明写 `keybindingHasKey`/`keybindingIsUser`,而字段叫 `hasKey`、`isUser` 压根不存在。
|
|
198
|
+
> 九段门禁 + 全部单测皆绿,因为**没有一条求值 `when`**。修法两条一起上:字段名用**计算属性名**从同一个常量取
|
|
199
|
+
> (改名即 TypeScript 编译错)+ 一条**契约回归测试**(拿 `plugin.json` 的菜单声明与运行时行对象对账)。可作同类项的范式。
|
|
200
|
+
|
|
181
201
|
### 能用哪些键
|
|
182
202
|
|
|
183
203
|
| 键 | 取值 | 谁写 | 说明 |
|
|
@@ -220,6 +240,7 @@ await window.linkdesk.contextKey.set("my-plugin.previewOpen", true);
|
|
|
220
240
|
|:--|:--|:--|
|
|
221
241
|
| 整个槽位一条我的项都没有 | 槽位键写成了成员名(`FileContext`) | 门禁 `check-menu-slot-case`(`npm run lint` / `verify` 里);或搜你的 `plugin.json` 看键是不是小驼峰 |
|
|
222
242
|
| 有时出现有时不出现 | `when` 为假 | 复制 `when` 到命令面板的调试入口 / 看控制台有没有「when 表达式解析失败」 |
|
|
243
|
+
| 我的项**恒不出现**(不是时隐时现),控制台也没有报错 | `when` 里的标识符与**你递进菜单的那个对象**的字段名对不上(拼写/大小写)——宿主是裸属性查表,查不到即为假 | 字段名用**计算属性名**从同一常量取;或写一条「声明 ↔ 运行时对象」的契约测试(见 §五 坑 3) |
|
|
223
244
|
| 出现了但点了没反应 | 命令没注册(只声明了 `contributes.commands`,池侧没 `registerCommand`) | 见 [21-插件命令化规范](21-插件命令化规范.md) §二「两条腿」 |
|
|
224
245
|
| 我的项排在最后/最前,压不过别人 | `order` 缺省 `100`,别人的组更小 | 调 `order` 或换组名(组序 = 首现顺序) |
|
|
225
246
|
| 报「不带本仓归属」 | 命令 id / 配置键 / 外观 id / context key 少了 `<pluginId>.` 前缀 | `npm run verify` 会报点并给出建议名(见 [16-命名规范](16-命名规范.md) §七) |
|
|
@@ -372,7 +372,7 @@
|
|
|
372
372
|
"enumDescriptions": { "type": "object", "description": "enum value → display name mapping" },
|
|
373
373
|
"description": { "type": "string" },
|
|
374
374
|
"title": { "type": "string", "description": "Row display name — the short human-readable label shown as the settings row name and on the marketplace features tab (optional — omitted = the settings row falls back to showing the configuration key). Value convention matches description: the Chinese source text IS the i18n key; English translations go in your plugin's i18n/en.json. Keep it a noun phrase (≤12 characters, drop the plugin-name prefix); rows with renderHint \"action\" take a verb-phrase name instead (it reads as a button label)." },
|
|
375
|
-
"uiHint": { "type": "string", "description": "Settings editor rendering hint — SettingsView picks the control from the hint. Known hints: slider, fontSize, color, fontFamily, file, directory, image, segmented, fontTone, accentSource, themePicker, select, stringList. A hint the installed renderer does not know is shown read-only — the current value plus a tooltip saying the declared control is unsupported (no editable fallback control, no error thrown). The value is an open string, so third parties may declare new hint names." },
|
|
375
|
+
"uiHint": { "type": "string", "description": "Settings editor rendering hint — SettingsView picks the control from the hint. Known hints: slider, fontSize, color, fontFamily, file, directory, image, segmented, fontTone, accentSource, themePicker, select, stringList, fileAssociationsManager. A hint the installed renderer does not know is shown read-only — the current value plus a tooltip saying the declared control is unsupported (no editable fallback control, no error thrown). The value is an open string, so third parties may declare new hint names." },
|
|
376
376
|
"renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand; \"color\" renders a read-only color row (swatch + value). \"readonly\"/\"action\" are shorthands meaning the row's primary control IS the status line/button: statusCommand and actionCommand may also be declared alongside any primary control, rendering as companions to its right ([primary control][companion button][companion readonly]). Known hints: readonly, action, color. An unknown hint is shown read-only (current value + explanatory tooltip). Open string." },
|
|
377
377
|
"actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked). May be declared alongside any primary control: it then renders as a companion button to the right of that control, with its text taken from description." },
|
|
378
378
|
"actionDisabledAll": { "type": "array", "description": "Disable the \"action\" button while every entry matches the current configuration value (omit the field entirely — or pass an empty list — to keep the button always enabled)", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string" }, "value": {} }, "additionalProperties": false } },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.63",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|