@linkdesk/plugin-docs 0.1.52 → 0.1.54
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/01-plugin-api-contract.md +1 -1
- package/docs/05-ui-conventions.md +851 -847
- package/docs/06-plugin-json-spec.md +27 -0
- package/docs/19-component-cheatsheet.md +6 -5
- 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 +852 -848
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +27 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +6 -5
- package/docs/zh/plugin.schema.json +1 -0
- package/package.json +1 -1
|
@@ -455,6 +455,33 @@ do not need it (`icon` *is* the identity image).
|
|
|
455
455
|
|
|
456
456
|
Views are loaded by ViewContainerService from `contributes.views[].render`, and the icon goes through the shell's component-less registration path. **For a sidebar-only plugin to get an icon = `appearsIn.iconBar` + a sidebar `viewsContainers`, with no `entry` and no `src/index.tsx` needed**; **only plugins that need tabs need `entry`**.
|
|
457
457
|
|
|
458
|
+
### Admission to the Start card and the [+] menu (appearsIn.standaloneOpenable)
|
|
459
|
+
|
|
460
|
+
> 🔴 **opt-IN, allow-list, default `false` (since 2026-10-02) — declaring `appearsIn.tabBar: true` alone no longer puts you in the welcome page's Start card or the tab bar's [+] create menu; add one more line, `standaloneOpenable: true`, to be admitted.**
|
|
461
|
+
|
|
462
|
+
**Why this field exists**: `tabBar` answers "**can** this plugin be opened as a tab" (capability), while the Start card and the [+] menu answer a different question — "**if I open it right now, is there anything to look at**". The two were long treated as one thing, which produced cases like "the editor shows up in the Start card, but clicking it opens an empty file-editor tab that errors with ENOENT": it has a tab form, but that form is a **per-resource** editor — with no file there is no content. `standaloneOpenable` turns the second question into a declarable field.
|
|
463
|
+
|
|
464
|
+
| What you declare | Start card / [+] menu | Command palette / recent / session restore / floating panel "open in main window" |
|
|
465
|
+
|---|---|---|
|
|
466
|
+
| `tabBar: true` (field omitted) | ❌ not listed | ✅ still opens |
|
|
467
|
+
| `tabBar: true` + `standaloneOpenable: true` | ✅ listed | ✅ still opens |
|
|
468
|
+
| `tabBar: true` + `standaloneOpenable: false` | ❌ not listed (explicit refusal) | ✅ still opens |
|
|
469
|
+
|
|
470
|
+
> ⚠️ **This field only governs whether those two menus list you. It is not a capability gate and not a permission gate.** Omitting it only removes the plugin from those two menus — users, commands and scripts can still open it, and recents and session restore keep working. **Turning it on = releasing one more entry point; leaving it off ≠ disabling the plugin.**
|
|
471
|
+
|
|
472
|
+
**When to declare `true`**: the plugin has an interface of **its own** that shows content the moment it opens — a serial monitor, a Git panel, a file tree, a settings page.
|
|
473
|
+
**When not to** (keep the default): the plugin's tab form is a **per-resource** editor (the user picks a file/object first), or the plugin is merely a base that provides data or view containers to others.
|
|
474
|
+
|
|
475
|
+
```json
|
|
476
|
+
// A plugin with content of its own — admitted to the Start card and the [+] menu
|
|
477
|
+
{ "entry": "src/index.tsx", "appearsIn": { "iconBar": "top", "tabBar": true, "standaloneOpenable": true } }
|
|
478
|
+
|
|
479
|
+
// A per-resource editor — has a tab form but stays out of those two menus
|
|
480
|
+
{ "entry": "src/index.tsx", "appearsIn": { "tabBar": true } }
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
> 🔴 **Breaking-change notice (for existing authors)**: this field defaults to `false`, so **plugins that previously declared only `tabBar: true` will disappear from the Start card and the [+] menu after upgrading** (every other open path is unaffected). If your plugin shows content the moment it opens, add one line `standaloneOpenable: true`, bump the version and `publish` again to restore it.
|
|
484
|
+
|
|
458
485
|
### The `contributes` field (Phase 5+) — aligned with VS Code
|
|
459
486
|
|
|
460
487
|
> **Once a plugin declares `contributes`, the system wires it up automatically — no core code changes needed.**
|
|
@@ -40,13 +40,14 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
40
40
|
|
|
41
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
42
|
|
|
43
|
-
### 2.1
|
|
43
|
+
### 2.1 Self-driven versioning (no lookup table)
|
|
44
44
|
|
|
45
|
-
The version of `@linkdesk/ui` **
|
|
45
|
+
The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is unrelated to the shell version (🟢 since 2026-10-01).
|
|
46
46
|
|
|
47
|
-
- **Which one to install**:
|
|
48
|
-
- **No need to chase upgrades**:
|
|
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.
|
|
47
|
+
- **Which one to install**: `npm i @linkdesk/ui@latest` gets you the newest. A new package is published only when the shared components actually change (checked at every shell release by the publish gate), so "latest package = the components inside the latest shell" holds by construction — nothing to look up.
|
|
48
|
+
- **No need to chase upgrades**: styles and behavior are **served at runtime by the shell pool** — a shell upgrade refreshes your plugin's UI automatically, no matter which package version you installed.
|
|
49
|
+
- **When you do have to move**: only when a **new component / new prop you want** appears in a higher version — that's a deliberate upgrade on your side, not something you're forced into.
|
|
50
|
+
- **Curious which shell a package was cut from**: check `dist/shell-provenance.json` inside the package (shell version + short commit + date).
|
|
50
51
|
|
|
51
52
|
### 2.2 Three promises the shell makes to authors (each backed by a mechanical gate)
|
|
52
53
|
|
|
@@ -91,7 +91,7 @@ async function list(): Promise<FileEntry[]> {
|
|
|
91
91
|
| **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
|
|
92
92
|
| **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion 与更新检查都消费它)。壳内另有 `getProductInfo` 私有扩展(关于页 8 字段数据源,不在契约——池插件不可调) |
|
|
93
93
|
| **tabs** | **跨窗资源事件联动:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **全窗广播语义**——资源持有者在主窗与全部脱出窗的标签页同步更新/关闭;`sourceId` 为全局唯一资源身份(文件路径/会话 id),变更即全局事实(联动**不依赖调用方与标签页同窗**——脱出窗标签随侧栏改名/删除即时联动,对标 VS Code)。`focusBySourceId(sourceId)` = **按来源窗路由**(视图动作,聚焦到具体某窗,非全局事实)。**无新 API**——复用既有面,此行为契约由全窗广播保证 |
|
|
94
|
-
| **notifications** |
|
|
94
|
+
| **notifications** | **默认通知面 = 状态栏铃铛宽面板**(右下**常驻**窄 toast 链路已整删)——不弹卡、不抢焦点、不挡操作;未读计数 +1,用户点开才看见。**别把它当「必须被看见」的通道**:要用户当场决定 → `dialog.confirm`。**`show` 一律返回句柄**(`{ update, finish, cancel }`,——**不是只有 `progress:true` 才有**);**一条通知只能被创建它的那个句柄更新/删除**,别处同文案 `show` = 另一条。`progress:true` 开真进度条:`update(msg, percent?)` 给 0-100 确定条、不传 percent = 不定态动画;`finish(msg?)` 关掉并可选补完成通知;`cancel` 直接关掉不补。`persistent:true` = 长驻不自动消失(错误诊断类),等用户点 ×。**常驻配额按 `source` 分桶各 5 条**,超出顶掉同来源最老的并给汇总提示(长驻 ≠ 留档,要留档写自己的文件)。`source` = **机器读的归属键、不含人类文案**(人类可读名壳解析)——⚠️ **做不到自动注入**:池是单进程共享 realm,所有插件共用一个 `window.linkdesk`,preload 无从知道这次 `show` 是哪个插件的树发的 ⇒ **只能作者显式报自己的插件 id**(壳自身域用 `app.<域>`);**不传 → 全落「其他」组**。`actions` 点击走壳 `executeCommand(command, args)`,handler 插件自注册。**`toast:true`(W3a)** = **轻提示**——进去的不是面板而是右下角一张**自动消失的小卡**(≈4s、悬停暂停)、**不计未读**;它是**「一次操作的回执」**,⚠️ **不是留档通道**(用户可能根本来不及看)——要回看用 `persistent:true` 或写自己的文件 |
|
|
95
95
|
| **dialog** | `confirm`/`alert`/`open`/`openFile` = 壳渲染的模态框(抢焦点、有焦点锁)。**`confirmContent(options)`** = **富内容确认**——对话框仍是壳(居中/遮罩/Esc/焦点锁/点遮罩取消),**内容 = 插件自绘视图**(`pluginId` + `viewId` 声明寻址 + 不透明 `payload`,对标 VS Code「对话框是壳、内容插件定」)。**内容侧读法**:视图挂载后经 `dialogHost.current?.content?.payload` 取数(`open !== true` → `null`,防御不白屏);**结算只有 `dialogHost.confirm` / `dialogHost.cancel` 两条路**(别自己关弹窗,壳不认)。**兜底是硬的**:`viewId` 解析不出(未声明/声明插件没装)→ 壳**回落纯文字确认框**(用 `title`/`message`),弹窗照出、不静默死 ⇒ `title`/`message` 别省。`payload` 过 IPC 结构化克隆 ⇒ 只能放可克隆数据 |
|
|
96
96
|
| **search** | 全文搜索/替换——`searchFiles(opts)` 一发一收,经 IPC 由壳/主进程执行(插件侧零本地扫描);请求/结果形状以契约 `SearchWireOptions`/`SearchWireResult` 为准 |
|
|
97
97
|
| **encoding** | 编码检测/转换三件套(主进程 EncodingService 代办):`detect(buffer)` 猜编码名 / `decode(buffer, encoding)` 字节→文本 / `encode(text, encoding)` 文本→字节——`Uint8Array` 进出 |
|