@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
|
@@ -452,6 +452,33 @@ my-plugin/
|
|
|
452
452
|
|
|
453
453
|
视图由 ViewContainerService 按 `contributes.views[].render` 加载,图标走壳的 component-less 注册路径。**侧栏专用插件要图标 = `appearsIn.iconBar` + sidebar `viewsContainers`,不需要 `entry`、不需要 `src/index.tsx`**;**有标签页需求的插件才需要 `entry`**。
|
|
454
454
|
|
|
455
|
+
### 「开始」卡与 [+] 菜单准入(appearsIn.standaloneOpenable)
|
|
456
|
+
|
|
457
|
+
> 🔴 **opt-IN 白名单制(2026-10-02 起,缺省 `false`)——只声明 `appearsIn.tabBar: true` 不再自动进欢迎页「开始」卡与标签栏 [+] 创建菜单;要进就得再声明一行 `standaloneOpenable: true`。**
|
|
458
|
+
|
|
459
|
+
**为什么拆出这个字段**:`tabBar` 回答的是「这插件**能不能**开成标签页」(能力),而欢迎页「开始」卡与 [+] 菜单回答的是另一个问题——「**此刻直接开它,有没有东西可看**」。二者长期被当成一回事,于是长出「编辑器进了开始卡、点开却是一个空的文件编辑器标签(ENOENT)」这类病:它有 tab 形态,但那是**按资源打开**的编辑器——没有文件就没有内容。`standaloneOpenable` 把后一个问题变成可声明的字段。
|
|
460
|
+
|
|
461
|
+
| 你声明 | 「开始」卡 / [+] 菜单 | 命令面板 / 最近打开 / 会话恢复 / 悬浮面板「在主窗口中打开」 |
|
|
462
|
+
|---|---|---|
|
|
463
|
+
| `tabBar: true`(不声明本字段) | ❌ 不出现 | ✅ 照常能开 |
|
|
464
|
+
| `tabBar: true` + `standaloneOpenable: true` | ✅ 出现 | ✅ 照常能开 |
|
|
465
|
+
| `tabBar: true` + `standaloneOpenable: false` | ❌ 不出现(显式拒绝) | ✅ 照常能开 |
|
|
466
|
+
|
|
467
|
+
> ⚠️ **本字段只管这两张菜单「列不列出来」,不判能力、不判权限。** 不声明它只是让插件从这两张菜单消失——用户 / 命令 / 脚本仍能打开它,最近记录与会话恢复照常工作。**声明 true = 多给一张入口;不写它 ≠ 禁用插件。**
|
|
468
|
+
|
|
469
|
+
**什么时候该声明 `true`**:插件有一个**属于自己**的、打开即有内容的界面——串口监视器、Git 面板、文件树、设置页这类。
|
|
470
|
+
**什么时候不该声明**(保持缺省):插件的标签页形态是**按资源打开**的编辑器(要用户先选文件 / 对象),或它本身只是给别人提供数据 / 视图容器的底座。
|
|
471
|
+
|
|
472
|
+
```json
|
|
473
|
+
// 有独立内容的插件——进「开始」卡与 [+] 菜单
|
|
474
|
+
{ "entry": "src/index.tsx", "appearsIn": { "iconBar": "top", "tabBar": true, "standaloneOpenable": true } }
|
|
475
|
+
|
|
476
|
+
// 按资源打开的编辑器——有 tab 形态,但不占这两张菜单
|
|
477
|
+
{ "entry": "src/index.tsx", "appearsIn": { "tabBar": true } }
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
> 🔴 **breaking 公告(对既有作者)**:本字段缺省为 `false`,故**此前只声明 `tabBar: true` 的插件,升级后会从「开始」卡与 [+] 菜单消失**(其余打开路径一律不受影响)。若你的插件打开即有内容,加一行 `standaloneOpenable: true`、bump 版本、重新 `publish` 即可恢复。
|
|
481
|
+
|
|
455
482
|
### `contributes` 字段(Phase 5+)——对标 VS Code
|
|
456
483
|
|
|
457
484
|
> **插件一旦声明 `contributes`,系统自动接线——不需要改任何核心代码。**
|
|
@@ -41,13 +41,14 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
41
41
|
> 包是**单源码防漂移**的编译产物:壳改组件 → 包跟着变,所以"内置同款"是字面意义上的同一份实现。
|
|
42
42
|
> 它也**不进**你的 `.linkdesk-plugin` bundle(构建时 external),**运行时由壳池供给同一份实例**——不必担心体积,也不必担心装了两份。
|
|
43
43
|
|
|
44
|
-
### 2.1
|
|
44
|
+
### 2.1 版本自走(没有对照表)
|
|
45
45
|
|
|
46
|
-
`@linkdesk/ui`
|
|
46
|
+
`@linkdesk/ui` 的版本号**自己走**(每次发布 patch +1),与壳版本号无关(🟢 2026-10-01 起)。
|
|
47
47
|
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
48
|
+
- **该装哪个**:`npm i @linkdesk/ui@latest` 拿到的就是最新——壳发版时只有共享组件**真变了**才发新包,所以「最新包 = 最新壳里的那套组件」由发布门禁保证,你不用对照任何表。
|
|
49
|
+
- **不用追着升**:样式与行为**运行时由壳池统一供给**——壳升级,你的插件界面自动跟着新,装哪版包都不影响长相。
|
|
50
|
+
- **什么时候必须动**:只有当你**要用的新组件 / 新 prop** 出现在更高版本时——那是你主动升,不是被迫跟。
|
|
51
|
+
- **想知道手里的包剪自哪个壳**:看包里 `dist/shell-provenance.json`(壳版号 + 短 hash + 日期)。
|
|
51
52
|
|
|
52
53
|
### 2.2 壳对作者的三条承诺(都有机械兜底)
|
|
53
54
|
|
|
@@ -40,6 +40,7 @@
|
|
|
40
40
|
"iconBar": { "type": "string", "enum": ["top", "bottom"], "description": "Icon Bar position; omitted = no icon shown" },
|
|
41
41
|
"sidePanel": { "type": "boolean", "description": "Has a Sidebar view container. Default false." },
|
|
42
42
|
"tabBar": { "type": "boolean", "description": "Can be opened as a tab. Default false." },
|
|
43
|
+
"standaloneOpenable": { "type": "boolean", "default": false, "description": "Has a standalone surface worth opening on its own — declaring true is what admits the plugin to the Welcome page's Start card and the [+] create menu (both render the same filtered list). ⚠️ This gates those two menus ONLY: absent or false hides the plugin from them, but it does not make the plugin unopenable — commands, recents, session restore, and a floating panel's open-in action all still key off appearsIn.tabBar. Declare it when the plugin has content of its own to show; leave it off for plugins whose tab form is a per-resource editor (opening one with no resource has nothing to display). Default false." },
|
|
43
44
|
"statusBar": { "type": "string", "description": "File path of a self-drawn (code) Status Bar component, relative to the plugin root, .tsx, e.g. \"src/components/statusBar.tsx\" — the pool renders it from the declared URL, replacing static statusBar contributions; omit it when you only contribute static entries." }
|
|
44
45
|
}
|
|
45
46
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.54",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|