@linkdesk/plugin-docs 0.1.36 → 0.1.37
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 +6 -0
- package/docs/19-component-cheatsheet.md +2 -0
- package/docs/20-adding-a-setting.md +63 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +6 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +2 -0
- package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +63 -0
- package/docs/zh/plugin.schema.json +6 -0
- package/package.json +1 -1
|
@@ -265,6 +265,12 @@ useEffect(() => {
|
|
|
265
265
|
| `enumDescriptions` | ❌ | option descriptions — one-to-one with enum |
|
|
266
266
|
| `uiHint` | ❌ | rendering hint — SettingsView picks the control from the hint (known values include `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"`; it is an open string — an unknown hint degrades to the default rendering for the type). `"segmented"` = a segmented single-select (the ghost dual-track scheme, declared together with `enum` + `enumDescriptions`; the short label = the part of the enumDescription before `—`, the tooltip = the whole line) |
|
|
267
267
|
| `group` | ❌ | **a second-level heading inside the group** — keys sharing the same `group` value are rendered under a subheading on the settings page; keys without a `group` stay flat. Declaring a Chinese section name is enough for it to display; heading text goes through i18n (the plugin's `contributes.i18n` provides the translation). Zero shell changes — the shell mechanism works exactly the same for plugin keys |
|
|
268
|
+
| `renderHint` | ❌ | rendering hint for special rows (an open string — an unknown value degrades to the default rendering for the `type`). `"action"` renders a **button** (button text = `description`, clicking runs `actionCommand`); `"readonly"` renders a **read-only status line** (the value is the return value of `statusCommand`, re-fetched every 3 seconds; it does not read configuration storage). Both are general capabilities — any plugin gets them by declaring them; usage and examples in [20-adding-a-setting](20-adding-a-setting.md) |
|
|
269
|
+
| `actionCommand` | ❌ | command executed when a `renderHint: "action"` row is clicked — one of your own commands, or a shell command |
|
|
270
|
+
| `actionDisabledAll` | ❌ | disable condition for a `renderHint: "action"` button — disabled while **every** listed entry matches the current configuration value, shaped as `[{ "key": "…", "value": … }]` |
|
|
271
|
+
| `statusCommand` | ❌ | data-source command id for `renderHint: "readonly"` — its return value (a string) is the text shown on that row; the value comes from the command, not from configuration storage |
|
|
272
|
+
|
|
273
|
+
**Two optional fields on the group level** (written on the `configuration` level, not on a key): `subtitle` = one subtitle line under the group name; `groupDescriptions` = **per-section notes**, key = the exact `group` text (it only displays when it matches character for character). Declaring neither = nothing is rendered (zero intrusion).
|
|
268
274
|
|
|
269
275
|
**Effect after installation:** the Settings Editor's left navigation tree automatically gains a "CAD Viewer" group → the form is rendered automatically on the right — no hand-written settings UI needed.
|
|
270
276
|
|
|
@@ -86,6 +86,8 @@ The version of `@linkdesk/ui` **equals the version of the LinkDesk shell you ins
|
|
|
86
86
|
| `OverlayPortal` | Overlay portal host | Use it when a custom-drawn dialog needs to portal to body; don't scatter bare `createPortal` calls everywhere |
|
|
87
87
|
| `HintTip` | Lightweight hover hint (component form) | For "give it a child element and one sentence" — **most cases just write the `data-hint` attribute, no import needed**; use this component when you want to control the wrapper yourself (see [05-UI Conventions](05-ui-conventions.md) §13; a native `title=` is red) |
|
|
88
88
|
| `HintCard` | Anchored hover hint card (non-interactive) | For "hover a small badge, see a short explanation card": give `lines` (1–3 sentences) and the anchor element; triggering/positioning/glass are all handled by the shell; ⛔ no links or buttons inside the card |
|
|
89
|
+
| `ReadOnlyText` | Read-only text (single-line or multi-line, not editable) | Showing a **read-only value**: paths, addresses, live status lines (this is what the settings page's read-only status rows use — declare `renderHint: "readonly"` + `statusCommand`, see [20-adding-a-setting](20-adding-a-setting.md)) |
|
|
90
|
+
| `SectionSubtitle` | Section subtitle (one small line under a heading) | A one-line note under a group/section — the settings page renders `subtitle` / `groupDescriptions` with it, and you can use it directly when assembling your own explanatory block |
|
|
89
91
|
|
|
90
92
|
> The list follows the package's actual export surface (`packages/linkdesk-ui/src/index.ts` is the single source of truth) — if this page disagrees with the package, **the package wins**.
|
|
91
93
|
|
|
@@ -65,6 +65,9 @@ Once installed into LinkDesk, a "My Plugin" group appears on the left of the set
|
|
|
65
65
|
| **A more fitting widget** (color picker / slider / file picker…) | `uiHint` — see the table below |
|
|
66
66
|
| Subheadings inside the same group | `group` — entries sharing a `group` value collect under one second-level heading |
|
|
67
67
|
| Dropdown options that **show a short label**, with the full sentence on hover | `enum` + `enumDescriptions`, together with `uiHint: "segmented"` |
|
|
68
|
+
| The entry is not user-editable but **shows a live status** | `renderHint: "readonly"` + `statusCommand` — see 2.2 below |
|
|
69
|
+
| The entry is a **button** (click to do something) | `renderHint: "action"` + `actionCommand` — see 2.3 below |
|
|
70
|
+
| A one-line note under the group name / under each section | `subtitle` / `groupDescriptions` (written on the `configuration` level, not on a key) |
|
|
68
71
|
|
|
69
72
|
**Known `uiHint` values** (an unknown value falls back to the default rendering for its `type`, without error):
|
|
70
73
|
|
|
@@ -90,6 +93,66 @@ Once installed into LinkDesk, a "My Plugin" group appears on the left of the set
|
|
|
90
93
|
|
|
91
94
|
> ⚠️ **There is no `"integer"`** — integers use `"number"` too (with `step: 1`).
|
|
92
95
|
|
|
96
|
+
### 2.1 Notes for the Group and Its Sections
|
|
97
|
+
|
|
98
|
+
Besides the group name (`title`) you can add one subtitle line under it, and one line under each section (`group`) — **written on the `configuration` level**:
|
|
99
|
+
|
|
100
|
+
```jsonc
|
|
101
|
+
"configuration": {
|
|
102
|
+
"title": "My Plugin",
|
|
103
|
+
"subtitle": "What this whole group is about, in one line",
|
|
104
|
+
"groupDescriptions": { "Sampling": "The settings here affect the sampling stage" },
|
|
105
|
+
"properties": { /* … */ }
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Both are optional. The key in `groupDescriptions` **must match the `group` text on the entry character for character** (otherwise that line does not appear); sections you don't describe stay exactly as they were — no empty rows.
|
|
110
|
+
|
|
111
|
+
### 2.2 Read-Only Status Row: Show **Live State**, Not a Configuration Value
|
|
112
|
+
|
|
113
|
+
Some rows are not meant to be edited; they let the user (and an AI) **see what is happening right now** — for example "Channel status: running · 127.0.0.1:47001". Use `renderHint: "readonly"` for those: the value comes from the **return value of a command**, and it is re-fetched **every 3 seconds**, so what you see is a live reading.
|
|
114
|
+
|
|
115
|
+
```jsonc
|
|
116
|
+
"my-plugin.engine.status": {
|
|
117
|
+
"type": "string", "default": "",
|
|
118
|
+
"description": "Engine status",
|
|
119
|
+
"renderHint": "readonly",
|
|
120
|
+
"statusCommand": "my-plugin.engineStatus" // ← a command you registered (returns one line of text)
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
// Register that command in your plugin — its return value is the text shown on the row (\n allowed)
|
|
126
|
+
window.linkdesk?.commands?.registerCommand?.("my-plugin.engineStatus", async () => {
|
|
127
|
+
return connected ? `running · ${endpoint}` : "not connected";
|
|
128
|
+
});
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
| Point | Explanation |
|
|
132
|
+
|:--|:--|
|
|
133
|
+
| Where the value comes from | **The command**, not `configuration` — that is why it can show runtime state; `default` only exists to satisfy validation and is never displayed |
|
|
134
|
+
| What the command returns | A string (use `\n` for multiple lines; rendered as multiple lines) |
|
|
135
|
+
| Whose command goes in `statusCommand` | **One of your own**; a shell command id works too, as long as you know what it returns |
|
|
136
|
+
| Can the user edit it? | No — it is a read-only row with no input control |
|
|
137
|
+
| What if the command does not exist yet | The row stays **blank** (no error, no placeholder) — so don't expect text before the command is registered |
|
|
138
|
+
|
|
139
|
+
### 2.3 Button Row: Click to Do Something
|
|
140
|
+
|
|
141
|
+
```jsonc
|
|
142
|
+
"my-plugin.openDashboard": {
|
|
143
|
+
"type": "string", "default": "",
|
|
144
|
+
"description": "Open dashboard", // ← this line is the button text
|
|
145
|
+
"renderHint": "action",
|
|
146
|
+
"actionCommand": "my-plugin.showDashboard" // ← executed when clicked
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- **The button text is `description`** (there is no other string on an action row, so phrase it as an action, not as a noun explanation).
|
|
151
|
+
- Clicking runs `actionCommand`; the command can be **one of your own** or **a shell command** (such as `app.openAiManual`).
|
|
152
|
+
- To grey the button out while some condition holds, add `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]` — the button is disabled while **every** listed entry matches the current configuration value.
|
|
153
|
+
|
|
154
|
+
> All three are **general capabilities**: any plugin gets them by declaring them, and the host has no privilege here (a different settings plugin renders them just the same — the contract lives in `plugin.schema.json`).
|
|
155
|
+
|
|
93
156
|
---
|
|
94
157
|
|
|
95
158
|
## 3. Step 3: Read It in Code
|
|
@@ -265,6 +265,12 @@ useEffect(() => {
|
|
|
265
265
|
| `enumDescriptions` | ❌ | 选项说明——和 enum 一一对应 |
|
|
266
266
|
| `uiHint` | ❌ | 渲染提示——SettingsView 按 hint 选择控件(已知值 `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"` 等,开放 string——未知 hint 降级回 type 默认渲染)。`"segmented"` = 分段单选(ghost 双轨制,配合 `enum` + `enumDescriptions` 声明,短标签 = enumDescription `—` 前段、tooltip = 全句) |
|
|
267
267
|
| `group` | ❌ | **组内二级标题**——同 `group` 值的 key 在设置页归到子标题下渲染;无 `group` 的 key 保持平铺。声明中文节名即显示;节名标题走 i18n(插件 `contributes.i18n` 提供翻译)。零壳改动——壳机制对插件键同样生效。 |
|
|
268
|
+
| `renderHint` | ❌ | 特殊行的渲染提示(开放 string,未知值降级回 `type` 默认渲染)。`"action"` = 渲染成**按钮**(按钮文字 = `description`,点击执行 `actionCommand`);`"readonly"` = 渲染成**只读状态行**(值 = 执行 `statusCommand` 的返回值,每 3 秒重取;不读配置存储)。两个值都是通用能力——任何插件声明即生效,用法与示例见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md) |
|
|
269
|
+
| `actionCommand` | ❌ | `renderHint: "action"` 的行点击时执行的命令 id——可以是插件自己的命令,也可以是壳命令 |
|
|
270
|
+
| `actionDisabledAll` | ❌ | `renderHint: "action"` 的按钮禁用条件——**列出的每一项都匹配当前配置值**时禁用,形如 `[{ "key": "…", "value": … }]` |
|
|
271
|
+
| `statusCommand` | ❌ | `renderHint: "readonly"` 的数据源命令 id——返回值(字符串)就是那一行显示的文字;值来自命令而非配置存储 |
|
|
272
|
+
|
|
273
|
+
**分组层的两个可选字段**(写在 `configuration` 这层,不在键上):`subtitle` = 分组名下面的一行副标题;`groupDescriptions` = **分节说明**,键 = 该 `group` 的原文(逐字相同才会显示)。两条都不声明 = 不渲染(零侵入)。
|
|
268
274
|
|
|
269
275
|
**安装后效果:** Settings Editor 左侧导航树自动出现 "CAD 查看器" 分组 → 右侧自动渲染表单——不需要手写设置界面。
|
|
270
276
|
|
|
@@ -87,6 +87,8 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
87
87
|
| `OverlayPortal` | 弹层 portal 宿主 | 自绘弹窗要 portal 到 body 时用它,别裸写 `createPortal` 到处飘 |
|
|
88
88
|
| `HintTip` | 轻量悬停提示(组件式) | 「给它一个子元素、一句话」——**多数场景直接写 `data-hint` 属性即可,不必 import**;要自己控制包裹时用这个组件(见 [05-插件UI写法规约](05-插件UI写法规约.md) §13;原生 `title=` 判红) |
|
|
89
89
|
| `HintCard` | 贴锚的悬停说明卡(非交互) | 「停在某个小标上出一张说明卡」——给 `lines`(1–3 句)与锚元素,触发/定位/玻璃全归壳;⛔ 卡内不放链接按钮 |
|
|
90
|
+
| `ReadOnlyText` | 只读文字(单行/多行,不可编辑) | 显示**只读值**:路径、地址、实时状态行(设置页的只读状态行使的就是它——声明 `renderHint: "readonly"` + `statusCommand` 即可,见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md)) |
|
|
91
|
+
| `SectionSubtitle` | 分节副标题(标题下的一行小字) | 分组/分节下面的一行说明——设置页用它渲染 `subtitle` / `groupDescriptions`,自己拼说明区时也可以直接用它 |
|
|
90
92
|
|
|
91
93
|
> 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
|
|
92
94
|
|
|
@@ -65,6 +65,9 @@ npm run validate # 校验 plugin.json 合法
|
|
|
65
65
|
| **换一个更合适的控件**(取色器 / 滑杆 / 文件选择…) | `uiHint`——见下表 |
|
|
66
66
|
| 同一分组里再分小标题 | `group`——同 `group` 值的几条会归到一个二级标题下 |
|
|
67
67
|
| 下拉选项**显示短标签**、鼠标悬停看全句 | `enum` + `enumDescriptions`,并配 `uiHint: "segmented"` |
|
|
68
|
+
| 这一项不是给用户改的,而是**显示一个实时状态** | `renderHint: "readonly"` + `statusCommand`——见 §二·2 |
|
|
69
|
+
| 这一项是个**按钮**(点一下去做某件事) | `renderHint: "action"` + `actionCommand`——见 §二·3 |
|
|
70
|
+
| 分组名下面加一行说明 / 每个小分节加一行说明 | `subtitle` / `groupDescriptions`(写在 `configuration` 这一层,不是键上) |
|
|
68
71
|
|
|
69
72
|
**`uiHint` 已知值**(未知值会降级回按 `type` 默认渲染,不会报错):
|
|
70
73
|
|
|
@@ -90,6 +93,66 @@ npm run validate # 校验 plugin.json 合法
|
|
|
90
93
|
|
|
91
94
|
> ⚠️ **没有 `"integer"`**——整数也用 `"number"`(配 `step: 1`)。
|
|
92
95
|
|
|
96
|
+
### 二·1 分组与小分节的说明文字
|
|
97
|
+
|
|
98
|
+
分组名(`title`)下面可以加一行副标题,每个小分节(`group`)也可以各加一行——**写在 `configuration` 这一层**:
|
|
99
|
+
|
|
100
|
+
```jsonc
|
|
101
|
+
"configuration": {
|
|
102
|
+
"title": "我的插件",
|
|
103
|
+
"subtitle": "这个分组整体是干什么的,一行话",
|
|
104
|
+
"groupDescriptions": { "采样": "这一节里的设置影响采样阶段" },
|
|
105
|
+
"properties": { /* … */ }
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
两条都可选。`groupDescriptions` 的键**必须与键上写的 `group` 逐字相同**(否则那一行不会出现);没有声明的分节保持原样,不会留空行。
|
|
110
|
+
|
|
111
|
+
### 二·2 只读状态行:显示**实时状态**,不是配置值
|
|
112
|
+
|
|
113
|
+
有些行不是让用户改的,而是让他(和 AI)**看见正在发生什么**——比如「通道状态:运行中 · 127.0.0.1:47001」。这类行用 `renderHint: "readonly"`:它的值来自**一条命令的返回值**,每次渲染后还会**每 3 秒重取一次**,所以显示的是活读数。
|
|
114
|
+
|
|
115
|
+
```jsonc
|
|
116
|
+
"my-plugin.engine.status": {
|
|
117
|
+
"type": "string", "default": "",
|
|
118
|
+
"description": "引擎当前状态",
|
|
119
|
+
"renderHint": "readonly",
|
|
120
|
+
"statusCommand": "my-plugin.engineStatus" // ← 你自己注册的命令(返回一句话)
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
// 插件代码里注册这条命令——返回值就是那一行要显示的文字(可含 \n 换行)
|
|
126
|
+
window.linkdesk?.commands?.registerCommand?.("my-plugin.engineStatus", async () => {
|
|
127
|
+
return connected ? `运行中 · ${endpoint}` : "未连接";
|
|
128
|
+
});
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
| 要点 | 说明 |
|
|
132
|
+
|:--|:--|
|
|
133
|
+
| 值从哪来 | **命令行**,不读 `configuration`——所以它能显示运行时状态;`default` 只为通过校验,不会显示 |
|
|
134
|
+
| 命令返回什么 | 一个字符串(多行用 `\n`,渲染成多行) |
|
|
135
|
+
| `statusCommand` 写谁的 | **你自己注册的命令**;写壳命令 id 也行(只要你清楚它返回什么) |
|
|
136
|
+
| 用户能改吗 | 不能——这是只读行,没有输入控件 |
|
|
137
|
+
| 命令还不存在会怎样 | 那一行**空着**(不报错、不占位)——所以别在命令注册前就指望它有字 |
|
|
138
|
+
|
|
139
|
+
### 二·3 按钮行:点一下去做某件事
|
|
140
|
+
|
|
141
|
+
```jsonc
|
|
142
|
+
"my-plugin.openDashboard": {
|
|
143
|
+
"type": "string", "default": "",
|
|
144
|
+
"description": "打开仪表盘", // ← 这一行就是按钮上的文字
|
|
145
|
+
"renderHint": "action",
|
|
146
|
+
"actionCommand": "my-plugin.showDashboard" // ← 点击时执行这条命令
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
- **按钮文字 = `description`**(这行没有别的字符串可用,所以 `description` 要写成动作短语,别写成名词解释)。
|
|
151
|
+
- 点击时执行 `actionCommand`;命令可以是**你自己注册的**,也可以是**壳命令**(如 `app.openAiManual`)。
|
|
152
|
+
- 想「条件不满足时置灰」:加 `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]`——**列出的每一项都匹配当前配置值**时按钮禁用。
|
|
153
|
+
|
|
154
|
+
> 三样都是**通用能力**:任何插件声明就生效,宿主没有特权(设置页的渲染方换一只插件也照渲染——契约就写在 `plugin.schema.json` 里)。
|
|
155
|
+
|
|
93
156
|
---
|
|
94
157
|
|
|
95
158
|
## 三、第 3 步:在代码里读它
|
|
@@ -356,6 +356,8 @@
|
|
|
356
356
|
"required": ["title", "properties"],
|
|
357
357
|
"properties": {
|
|
358
358
|
"title": { "type": "string", "description": "Settings group name" },
|
|
359
|
+
"subtitle": { "type": "string", "description": "One-line subtitle under the group title (optional — omitted = nothing is rendered)" },
|
|
360
|
+
"groupDescriptions": { "type": "object", "description": "Per-section one-line description — key = the group's exact text, value = the line shown under that section heading (optional)", "additionalProperties": { "type": "string" } },
|
|
359
361
|
"properties": {
|
|
360
362
|
"type": "object",
|
|
361
363
|
"description": "Configuration mapping — key → { type, default, enum?, description }",
|
|
@@ -369,6 +371,10 @@
|
|
|
369
371
|
"enumDescriptions": { "type": "object", "description": "enum value → display name mapping" },
|
|
370
372
|
"description": { "type": "string" },
|
|
371
373
|
"uiHint": { "type": "string", "description": "Settings editor rendering hint. SettingsView picks the control from the hint. An unknown hint falls back to the default rendering for its type — no error is thrown. The value is an open string, so third parties may declare new hint names." },
|
|
374
|
+
"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. Open string — an unknown hint falls back to the default rendering for the type." },
|
|
375
|
+
"actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked)" },
|
|
376
|
+
"actionDisabledAll": { "type": "array", "description": "Disable the \"action\" button while every entry matches the current configuration value", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string" }, "value": {} }, "additionalProperties": false } },
|
|
377
|
+
"statusCommand": { "type": "string", "description": "Command whose return value (a string) is shown by a \"readonly\" status line — the value comes from the command, not from configuration storage, so a status row can show live runtime state. Shell command id or one of your own." },
|
|
372
378
|
"monoOnly": { "type": "boolean", "description": "Monospace only — meaningful only with uiHint \"fontFamily\". true/omitted = list monospace families only (editor fonts); false = all families (UI fonts)." },
|
|
373
379
|
"minimum": { "type": "number", "description": "Numeric lower bound — applies when type is number (range of the slider/numeric control)" },
|
|
374
380
|
"maximum": { "type": "number", "description": "Numeric upper bound — applies when type is number (range of the slider/numeric control)" },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.37",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|