@linkdesk/plugin-docs 0.1.23 → 0.1.24
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/00-readme.md +1 -1
- package/docs/01-plugin-api-contract.md +1 -1
- package/docs/05-ui-conventions.md +4 -3
- package/docs/10-building-a-settings-plugin.md +1 -1
- package/docs/13-development-guide.md +1 -1
- package/docs/19-component-cheatsheet.md +21 -1
- package/docs/zh/00-README.md +1 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +1 -1
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +4 -5
- package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +1 -1
- package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +1 -1
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +22 -1
- package/package.json +1 -1
package/docs/00-readme.md
CHANGED
|
@@ -97,7 +97,7 @@ System-level capabilities (serial ports, filesystem, configuration, dialogs) are
|
|
|
97
97
|
| `create-linkdesk-plugin` | Generates a plugin project skeleton in one line (the yo code equivalent) — **and it creates the git repo for you** | `npm create` when starting a new plugin; one-off, not part of the project |
|
|
98
98
|
| `@linkdesk/plugin-sdk` | The four author-toolchain commands: `dev` (dev host + HMR) / `build` (→ `.linkdesk-plugin`) / `validate` / `lint`; ships `plugin.schema.json` + `theme.schema.json` + the dev host page | devDependencies of every plugin project |
|
|
99
99
|
| `@linkdesk/contracts` | Full TS types for `window.linkdesk.*` (generated contract artifacts — the single source of truth) | **No need to install it yourself** — the SDK depends on it and forwards everything |
|
|
100
|
-
| `@linkdesk/ui` | Shared UI parts (buttons/selects/toggles/color picker/context menu…) | **Optional** — install it when you want your UI to look built-in (automatic theme/glass following) → [19-component-cheatsheet](19-component-cheatsheet.md) |
|
|
100
|
+
| `@linkdesk/ui` | Shared UI parts (buttons/selects/toggles/color picker/context menu…) — **the shell pool serves one instance at runtime**; installing it is for types and local dev | **Optional** — install it when you want your UI to look built-in (automatic theme/glass following); **its version matches the shell's** (one line → [19-component-cheatsheet §2.1](19-component-cheatsheet.md)) |
|
|
101
101
|
|
|
102
102
|
**In one sentence:** `create` generates the project → the project installs `sdk` → `sdk` brings `contracts` (types come along) → `ui` is standalone, installed on demand.
|
|
103
103
|
> Version numbers are not pinned on this page — **just install without a version to get the latest**.
|
|
@@ -137,7 +137,7 @@ The old §3.x per-namespace method list has been deleted (= a hand-written secon
|
|
|
137
137
|
|
|
138
138
|
**Allowed imports (shared controls come from the `@linkdesk/ui` npm package; the full `@src/core` exception allowlist lives in `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
|
|
139
139
|
- `@linkdesk/contracts` **types** (`import type`, zero runtime coupling) — the real registry package (see §3.1)
|
|
140
|
-
- `@linkdesk/ui` **shared controls / shared hooks** (ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker, etc., consolidated) — **declare it explicitly in your own project's `dependencies
|
|
140
|
+
- `@linkdesk/ui` **shared controls / shared hooks** (ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker, etc., consolidated) — **declare it explicitly in your own project's `dependencies`**, with the same version number as the shell you support (shell `0.2.13` ⇒ `"@linkdesk/ui": "^0.2.13"`; see [19-Component Cheatsheet §2.1](19-component-cheatsheet.md) for the version line) and build against the published package. ⛔ **Do not import its css** (styles are supplied by the shell pool; an SDK lint leg fails it — see [05-UI Conventions §12.4](05-ui-conventions.md)). 🔴 After that, **official plugins and third-party plugins share one project shape** (the six official ones already have the explicit declaration added); the only exception is those two **dev fixtures** inside the shell repo (still hoisted via the root workspaces). **Never import from `@src/components/shared/*`** (the second entry point for shared controls has been deleted)
|
|
141
141
|
- **Pure-utility allowlist (`@src/core` exceptions)**: `@src/core/pipeline/*` (DataConverter / DataDispatch / RingBuffer / ProtocolParser) + `@src/core/utils/CancellationToken` + `@src/core/registry/commands/MenuRegistry` (the MenuId type/enum only) and so on — treat `eslint-local-rules.js` as the only authority for the full table; don't copy a second one here
|
|
142
142
|
- 🔴 **Review conclusion**: this allowlist **is in practice used only by shell-repo fixtures** — after the official plugins moved out of the shell repo, their source has zero `@src` hits (at runtime everything goes through `window.linkdesk.*`; measured). The allowlist **stays** (the fixtures are still inside `plugins/` and still guarded by that same eslint rule), but **third-party authors should pretend it doesn't exist**: the only three things you can use are `@linkdesk/contracts` / `@linkdesk/ui` / `window.linkdesk.*`
|
|
143
143
|
- **Exception registry**: imports outside the allowlist must be registered before they are permitted (an audit item of the plugin-independence iron rule)
|
|
@@ -660,7 +660,7 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
|
|
|
660
660
|
|
|
661
661
|
**In one line: same story as 12.1, just for the components that 12.1 didn't cover—if your own CSS tunes those components with descendant selectors, add the `ldk-` prefix when you upgrade.**
|
|
662
662
|
|
|
663
|
-
- **What changed**: §12.1 covered the eight base names of `@linkdesk/ui` (`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`) at **0.2.0**. The remaining components' class names—plus one `@keyframes` name—now carry the prefix too
|
|
663
|
+
- **What changed**: §12.1 covered the eight base names of `@linkdesk/ui` (`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`) at **0.2.0**. The remaining components' class names—plus one `@keyframes` name—now carry the prefix too (**since the 2026-09-16 round**; for how to read the version line see [19-Component Cheatsheet §2.1](19-component-cheatsheet.md)):
|
|
664
664
|
|
|
665
665
|
| Old family | New family |
|
|
666
666
|
|---|---|
|
|
@@ -677,8 +677,9 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
|
|
|
677
677
|
|
|
678
678
|
- **Who is affected**: again **only your own CSS**'s descendant selectors that point at those components (e.g. `.settings-row:has(.theme-picker)`). **The components' own styling does not change, and your own class names stay as they are.** The whole point is that the shared components' names now all live in the `ldk-` namespace, whose rule you already know: **anything starting with `ldk-` belongs to the host—don't put it on your own elements** (the one exception is `.ldk-input`, the utility that is **for you**).
|
|
679
679
|
- **What happens if you don't**: exactly the silent failure described in 12.1—the selector just stops matching and those few rules quietly stop applying. **No error.**
|
|
680
|
-
- 🔴 **
|
|
681
|
-
- **
|
|
680
|
+
- 🔴 **When the host renames a shared name or restyles a component, there is no code and no CSS for you to change** — components and styles are supplied by the shell pool (L9 centralized supply, see [19-Component Cheatsheet §2](19-component-cheatsheet.md)): the same implementation follows the shell upgrade, so your UI stays consistent. The one thing to maintain is that your `@linkdesk/ui` dependency **stays on the current version line** (it decides what your local dev and types resolve to).
|
|
681
|
+
- ⛔ **Component styles never come from your source either**: a line like `import "@linkdesk/ui/index.css"` (or its dist / `@import` form) is failed by the SDK lint leg `linkdesk/no-ui-css-import`, with **no exemption exit** — baking the styles into your plugin means "the shell restyles once, the whole ecosystem follows" stops being true for you.
|
|
682
|
+
- **When you must change it**: when the shell you support moves to a version that contains this rename (how to read the version line: [19-Component Cheatsheet §2.1](19-component-cheatsheet.md) — ui version = shell version, one line). After upgrading, **grep your own CSS for the old families** in the table above: an official plugin (`settings`) had exactly one such spot and it was fixed in the same release batch.
|
|
682
683
|
- **You get the same ruler** (`@linkdesk/plugin-sdk` 0.1.40 onward): your repo's lint ships with a dangling-name check—when the host renames a shared name and you didn't follow, **your own CI calls it out** (usage and fixes in [16-naming-conventions §7.6](16-naming-conventions.md)).
|
|
683
684
|
|
|
684
685
|
### 12.5 The **scope** of custom properties—`--x:` written under `:root` is written for the whole application
|
|
@@ -71,7 +71,7 @@ The filename is simply `settings.json`, with no shell-side map — copy it as-is
|
|
|
71
71
|
|
|
72
72
|
## Shared controls — `@linkdesk/ui`
|
|
73
73
|
|
|
74
|
-
A settings UI's shared controls live in the **`@linkdesk/ui`** package (consolidated there — third parties `npm i @linkdesk/ui` and import directly; **`import @src/core/...` is forbidden, and so is `@src/components/...`**):
|
|
74
|
+
A settings UI's shared controls live in the **`@linkdesk/ui`** package (consolidated there — third parties `npm i @linkdesk/ui` and import directly; **`import @src/core/...` is forbidden, and so is `@src/components/...`**); install the version line that **matches the shell** (see [19-component-cheatsheet §2.1](19-component-cheatsheet.md): ui version = shell version) — components and styles are supplied by the shell pool at runtime, so ⛔ **do not import its css from your source**:
|
|
75
75
|
|
|
76
76
|
`ContextMenu` · `InlineInput` · `SelectBox` · `Toggle` · `ColorPicker` · `FontFamilySelect` · `FilePathInput` · `NumberInput` · `Slider` · `Combobox` · `FormRow` · `SegmentedRadio` · `ThemePicker` · `PluginIcon` · shared hooks (`useDebouncedInput` / `useClipboardKeys`, etc.)
|
|
77
77
|
|
|
@@ -145,7 +145,7 @@ No errors in the output means it passes. Declared a command → press `Ctrl+Shif
|
|
|
145
145
|
npm i @linkdesk/ui
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
-
Controls like context menus, selects, and toggles come from the shared package — **glass/theme follow automatically**, no styling of your own.
|
|
148
|
+
Controls like context menus, selects, and toggles come from the shared package — **glass/theme follow automatically**, no styling of your own; components and styles are supplied by the shell pool at runtime (install the line that **matches the shell**, see [19-component-cheatsheet §2.1](19-component-cheatsheet.md)), and ⛔ you must not import its css.
|
|
149
149
|
|
|
150
150
|
**How to know you did it right**
|
|
151
151
|
Switch themes and your context menu's appearance follows (hand-made implementations usually don't). Repo hard constraint 3 is explicit: a hand-written context menu is a violation.
|
|
@@ -35,9 +35,28 @@ npm i @linkdesk/ui # Optional — install it when you want your UI to match
|
|
|
35
35
|
|
|
36
36
|
```tsx
|
|
37
37
|
import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
38
|
+
// ⛔ Do not import "@linkdesk/ui/index.css" — the shell pool supplies the styles; that line has no business in your source
|
|
38
39
|
```
|
|
39
40
|
|
|
40
|
-
> The package is the build artifact of a **single-source, anti-drift** setup: the shell changes a component → the package changes with it, so "same as the built-ins" is literally the same implementation. It also **does not go into** your `.linkdesk-plugin` bundle (externalized at build time) —
|
|
41
|
+
> The package is the build artifact of a **single-source, anti-drift** setup: the shell changes a component → the package changes with it, so "same as the built-ins" is literally the same implementation. It also **does not go into** your `.linkdesk-plugin` bundle (externalized at build time), and at **runtime the shell pool supplies that one instance** — nothing to worry about in terms of size or duplicate copies.
|
|
42
|
+
|
|
43
|
+
### 2.1 One version line (no lookup table)
|
|
44
|
+
|
|
45
|
+
The version of `@linkdesk/ui` **equals the version of the LinkDesk shell you installed**. Shell 0.2.13 → package 0.2.13.
|
|
46
|
+
|
|
47
|
+
- **Which one to install**: look at the **oldest shell** you intend to support and install the matching ui version; `npm i @linkdesk/ui@latest` gets you the newest line. This page keeps no lookup table — the shell maintains that line, and it isn't something you have to track.
|
|
48
|
+
- **No need to chase upgrades**: a range like `^0.2.13` picks up later patches on the same line by itself; a shell upgrade won't suddenly break your plugin.
|
|
49
|
+
- **When you do have to move**: only when a **new component you want** appears in a higher version — that's a deliberate upgrade on your side, not something you're forced into.
|
|
50
|
+
|
|
51
|
+
### 2.2 Three promises the shell makes to authors (each backed by a mechanical gate)
|
|
52
|
+
|
|
53
|
+
| Promise | What it means | Backstop |
|
|
54
|
+
|:--|:--|:--|
|
|
55
|
+
| **Add-only** | Published component/export names are lifelong commitments: new ones get added, existing ones are never renamed or removed | The shell repo's export-surface snapshot gate (removing one fails the gate) |
|
|
56
|
+
| **Behavior changes arrive as new names** | To change behavior, a new prop or a new component name is added; the old name keeps its meaning | Same gate — changing the meaning of an old name counts as a removal |
|
|
57
|
+
| **Styles follow the shell** | What a component looks like is the shell's call; upgrades bring the styling along | Styles are supplied by the shell pool (above); your bundle carries no copy that can drift |
|
|
58
|
+
|
|
59
|
+
> Conversely: **to change appearance, switch components or variant props — don't override `ldk-` class names** (those belong to the host; see [05-UI Conventions](05-ui-conventions.md) §12).
|
|
41
60
|
|
|
42
61
|
---
|
|
43
62
|
|
|
@@ -95,6 +114,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
95
114
|
| The Title Bar eats half the clicks on my dialog | The overlay sits at `top: 0` and collides with the window drag region | Use the shared overlay component (it already avoids the drag region) |
|
|
96
115
|
| User settings don't stick | You used `localStorage` | `window.linkdesk.configuration.set` |
|
|
97
116
|
| Two UI libraries installed, styles bleed into each other | You pulled in a third-party component library | Use the shared parts where you can; if you truly need a third party, watch out for style isolation |
|
|
117
|
+
| The shell restyled a component but my plugin didn't follow | Your source `import`s `@linkdesk/ui`'s css (baking the styles into your own package) | Delete that line — the shell pool supplies the styles (the SDK's lint leg fails it; see §2) |
|
|
98
118
|
|
|
99
119
|
---
|
|
100
120
|
|
package/docs/zh/00-README.md
CHANGED
|
@@ -97,7 +97,7 @@
|
|
|
97
97
|
| `create-linkdesk-plugin` | 一行生成插件工程骨架(对标 yo code)——**还会替你建好 git 仓** | 建新插件时 `npm create`,一次性、不进项目 |
|
|
98
98
|
| `@linkdesk/plugin-sdk` | 作者工具链四命令:`dev`(dev 宿主+HMR)/ `build`(→ `.linkdesk-plugin`)/ `validate` / `lint`;随包 `plugin.schema.json` + `theme.schema.json` + dev 宿主页 | 每个插件工程 devDependencies |
|
|
99
99
|
| `@linkdesk/contracts` | `window.linkdesk.*` 全量 TS 类型(契约生成产物——单一真相源) | **不用主动装**——SDK 依赖它并全量转发 |
|
|
100
|
-
| `@linkdesk/ui` | 共享 UI
|
|
100
|
+
| `@linkdesk/ui` | 共享 UI 零件(按钮/下拉/开关/取色器/右键菜单…)——**运行时由壳池供给同一份实例**,装它是为了类型与本地 dev | **可选**——想让界面跟内置同款(自动跟随主题/玻璃)时装;**版本与壳同号**(一条线 → [19-组件速查 §2.1](19-组件速查.md)) |
|
|
101
101
|
|
|
102
102
|
**关系一句话**:`create` 生成工程 → 工程装 `sdk` → `sdk` 带 `contracts`(类型随来)→ `ui` 独立、按需装。
|
|
103
103
|
> 版本号不写死在本页——**装的时候不带版本号即可拿到最新**。
|
|
@@ -137,7 +137,7 @@ async function list(): Promise<FileEntry[]> {
|
|
|
137
137
|
|
|
138
138
|
**允许的 import(共享控件走 `@linkdesk/ui` npm 包;`@src/core` 例外白名单全表见 `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
|
|
139
139
|
- `@linkdesk/contracts` **类型**(`import type`,零运行时耦合)——registry 真包(见 §三 3.1)
|
|
140
|
-
- `@linkdesk/ui` **共享控件 / 共享 hooks**(ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker 等,收归)——**在你自己工程的 `dependencies`
|
|
140
|
+
- `@linkdesk/ui` **共享控件 / 共享 hooks**(ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker 等,收归)——**在你自己工程的 `dependencies` 里显式声明**,版本与你要支持的壳同号(壳 `0.2.13` ⇒ `"@linkdesk/ui": "^0.2.13"`;版本线见 [19-组件速查 §2.1](19-组件速查.md)),构建走货架。⛔ **不要 import 它的 css**(样式由壳池统一供给,SDK 的 lint 腿判红——见 [05-插件UI写法规约 §12.4](05-插件UI写法规约.md))。🔴后**官方插件与第三方是同一款工程形态**(官方 6 只在已补上显式声明);唯一例外是壳仓内那两只**开发夹具**(仍靠根 workspaces 提升)。**一律不从 `@src/components/shared/*` import**(后共享控件第二入口已删)
|
|
141
141
|
- **纯工具白名单(`@src/core` 例外)**:`@src/core/pipeline/*`(DataConverter / DataDispatch / RingBuffer / ProtocolParser)+ `@src/core/utils/CancellationToken` + `@src/core/registry/commands/MenuRegistry`(仅 MenuId 类型/枚举)等——全表只以 eslint-local-rules.js 为准,不在此抄第二份
|
|
142
142
|
- 🔴 **复核结论**:这条白名单**实际只剩壳仓夹具在用**——官方插件搬出壳仓后,它们的源码里 `@src` 早已零命中(运行时全走 `window.linkdesk.*`,已实测)。白名单**保留**(夹具仍在 `plugins/` 内、仍由同一条 eslint 规则守着),但**第三方作者请当作它不存在**:你能用的只有 `@linkdesk/contracts` / `@linkdesk/ui` / `window.linkdesk.*` 三样
|
|
143
143
|
- **例外登记**:白名单外的 import 必须登记在案再放行(插件独立铁律审计项)
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -641,7 +641,7 @@ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 +
|
|
|
641
641
|
|
|
642
642
|
**一句话:和 12.1 同一件事,只是把当时没覆盖到的组件补上——你若在自己 CSS 里用后代选择器微调过这些组件,升级时加一个 `ldk-` 前缀即可。**
|
|
643
643
|
|
|
644
|
-
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes`
|
|
644
|
+
- **改了什么**:§12.1 覆盖的是 `@linkdesk/ui` 的八个基名(`badge` / `button` / `combobox` / `mdv` / `selectbox` / `sle` / `slider` / `toggle`,**0.2.0** 起)。其余组件的类名——外加一个 `@keyframes` 名——现在也带上了前缀(**2026-09-16 那轮起**;版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)):
|
|
645
645
|
|
|
646
646
|
| 旧族 | 新族 |
|
|
647
647
|
|---|---|
|
|
@@ -658,10 +658,9 @@ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 +
|
|
|
658
658
|
|
|
659
659
|
- **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
|
|
660
660
|
- **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
|
|
661
|
-
- 🔴
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
- **什么时候必须改**:升到 **`@linkdesk/ui` 0.3.0** 时。`^0.2.0` 不会解析到 `0.3.0`(0.x 的范围就是这么算的),所以你不主动升级就不会坏。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
|
|
661
|
+
- 🔴 **宿主以后改共享名 / 改样式,你这边不必改代码、也不必改 CSS**——组件与样式**由壳池统一供给**(L9 集中供给,见 [19-组件速查 §二](19-组件速查.md)):壳升级后同一份实现跟着壳走,界面自然一致。你唯一要维持的是 `@linkdesk/ui` 依赖**别掉出当前版本线**(它决定你本地 dev 与类型解析到的那一份)。
|
|
662
|
+
- ⛔ **组件样式同样不从你的源码里来**:源码里出现 `import "@linkdesk/ui/index.css"`(或其 dist / `@import` 形态)会被 SDK 的 lint 腿 `linkdesk/no-ui-css-import` 判红——**没有豁免出口**。把样式烤进插件,等于「壳改样式、全生态跟随」对你失效。
|
|
663
|
+
- **什么时候必须改**:当你要支持的壳升到含这次改名的版本时(版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)——ui 版本 = 壳版本,一条线)。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
|
|
665
664
|
- **这把尺子你也有**(`@linkdesk/plugin-sdk` 0.1.40 起):你仓里的 lint 自带「悬空名」判据——宿主改了共享名、你没跟上时,**你自己的 CI 会替你喊**(用法与修法见 [16-命名规范 §7.6](16-命名规范.md))。
|
|
666
665
|
|
|
667
666
|
### 12.5 自定义属性的**作用域**——`--x:` 写在 `:root` 里就等于写给整个软件
|
|
@@ -71,7 +71,7 @@ const filePath = dir ? window.linkdesk.path.join(dir, "settings.json") : "";
|
|
|
71
71
|
|
|
72
72
|
## 共享控件——`@linkdesk/ui`
|
|
73
73
|
|
|
74
|
-
设置 UI 的共享控件在 **`@linkdesk/ui`** 包(收归——第三方 `npm i @linkdesk/ui` 后直接 import,**禁 `import @src/core/...` 也禁 `@src/components
|
|
74
|
+
设置 UI 的共享控件在 **`@linkdesk/ui`** 包(收归——第三方 `npm i @linkdesk/ui` 后直接 import,**禁 `import @src/core/...` 也禁 `@src/components/...`**);装**与壳同号**的那条线(见 [19-组件速查 §2.1](19-组件速查.md):ui 版本 = 壳版本),组件与样式运行时由壳池供给,⛔ **源码里不要 import 它的 css**:
|
|
75
75
|
|
|
76
76
|
`ContextMenu` · `InlineInput` · `SelectBox` · `Toggle` · `ColorPicker` · `FontFamilySelect` · `FilePathInput` · `NumberInput` · `Slider`· `Combobox` · `FormRow` · `SegmentedRadio` · `ThemePicker` · `PluginIcon` · 共享 hooks(`useDebouncedInput` / `useClipboardKeys` 等)
|
|
77
77
|
|
package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md
CHANGED
|
@@ -145,7 +145,7 @@ npm run validate # 校验 plugin.json:$schema / 字段合法性 / i18n 文
|
|
|
145
145
|
npm i @linkdesk/ui
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
-
|
|
148
|
+
右键菜单、下拉、开关这类控件走共享包——**玻璃/主题自动跟随**,不用自己调样式;组件与样式由壳池运行时供给(装与壳**同号**的那条线,见 [19-组件速查 §2.1](19-组件速查.md)),⛔ 不要 import 它的 css。
|
|
149
149
|
|
|
150
150
|
**怎么知道做对了**
|
|
151
151
|
切换主题时你的右键菜单外观跟着变(自造的实现通常不会)。仓库硬约束 3 明确:手写右键菜单是违规的。
|
|
@@ -35,9 +35,29 @@ npm i @linkdesk/ui # 可选——想让界面跟内置同款时装
|
|
|
35
35
|
|
|
36
36
|
```tsx
|
|
37
37
|
import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
38
|
+
// ⛔ 不要 import "@linkdesk/ui/index.css"——样式由壳池统一供给,源码里不该有这行
|
|
38
39
|
```
|
|
39
40
|
|
|
40
|
-
> 包是**单源码防漂移**的编译产物:壳改组件 → 包跟着变,所以"内置同款"
|
|
41
|
+
> 包是**单源码防漂移**的编译产物:壳改组件 → 包跟着变,所以"内置同款"是字面意义上的同一份实现。
|
|
42
|
+
> 它也**不进**你的 `.linkdesk-plugin` bundle(构建时 external),**运行时由壳池供给同一份实例**——不必担心体积,也不必担心装了两份。
|
|
43
|
+
|
|
44
|
+
### 2.1 版本一条线(没有对照表)
|
|
45
|
+
|
|
46
|
+
`@linkdesk/ui` 的版本号 **= 你装的那个 LinkDesk 壳的版本号**。壳 0.2.13,包就是 0.2.13。
|
|
47
|
+
|
|
48
|
+
- **该装哪个**:看你**最低要支持**的那个壳版本,装同号的 ui;`npm i @linkdesk/ui@latest` 拿到的就是最新那条线。本页不设对照表——这条线由壳自己维护,不是你要记的东西。
|
|
49
|
+
- **不用追着升**:`^0.2.13` 这样的范围会自动吃到同一线上的后续修订版;壳升级不会让你的插件突然坏掉。
|
|
50
|
+
- **什么时候必须动**:只有当你**要用的新组件**出现在更高版本时——那是你主动升,不是被迫跟。
|
|
51
|
+
|
|
52
|
+
### 2.2 壳对作者的三条承诺(都有机械兜底)
|
|
53
|
+
|
|
54
|
+
| 承诺 | 意思 | 兜底 |
|
|
55
|
+
|:--|:--|:--|
|
|
56
|
+
| **只加不删** | 已发布的组件名 / 导出名是终身承诺——只会新增,不会改名或删除 | 壳仓的导出面快照门禁(删一个就判红) |
|
|
57
|
+
| **行为改走新名字** | 要改行为就**新加 prop / 新加组件名**,不动老名字的语义 | 同上——老名字的语义变更按"删"处理 |
|
|
58
|
+
| **样式跟着壳走** | 组件长什么样由壳决定,升级后样式自然同步 | 样式由壳池供给(见上),你的包里没有会漂移的副本 |
|
|
59
|
+
|
|
60
|
+
> 反过来说:**要换外观就换组件 / 换变体 prop,别覆写 `ldk-` 类名**——那是宿主的(见 [05-插件UI写法规约](05-插件UI写法规约.md) §12)。
|
|
41
61
|
|
|
42
62
|
---
|
|
43
63
|
|
|
@@ -95,6 +115,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
95
115
|
| 弹窗被标题栏吃掉一半点击 | 弹层放到 `top: 0`,撞上窗口拖拽区 | 用共享弹层组件(它已避开拖拽区) |
|
|
96
116
|
| 用户设置没保存住 | 用了 `localStorage` | `window.linkdesk.configuration.set` |
|
|
97
117
|
| 装了两个 UI 库,样式互相污染 | 自己引了第三方组件库 | 能用共享件就用;确需第三方时注意样式隔离 |
|
|
118
|
+
| 壳改过组件样式,我的插件没跟着变 | 源码里 `import` 了 `@linkdesk/ui` 的 css(样式被烤进自己的包) | 删掉那行——样式由壳池供给(SDK 的 lint 腿判红,见 §二) |
|
|
98
119
|
|
|
99
120
|
---
|
|
100
121
|
|