@linkdesk/plugin-docs 0.1.0

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.
Files changed (49) hide show
  1. package/README.md +58 -0
  2. package/docs/00-readme.md +189 -0
  3. package/docs/01-plugin-api-contract.md +171 -0
  4. package/docs/02-plugin-lifecycle.md +348 -0
  5. package/docs/03-contributes-spec.md +800 -0
  6. package/docs/04-distribution-format.md +172 -0
  7. package/docs/05-ui-conventions.md +549 -0
  8. package/docs/06-plugin-json-spec.md +640 -0
  9. package/docs/07-plugin-to-plugin-communication.md +299 -0
  10. package/docs/08-view-container-api.md +405 -0
  11. package/docs/09-plugin-directory-layout.md +301 -0
  12. package/docs/10-building-a-settings-plugin.md +164 -0
  13. package/docs/11-authoring-themes.md +173 -0
  14. package/docs/12-readme-media-contract.md +74 -0
  15. package/docs/13-development-guide.md +259 -0
  16. package/docs/14-data-pipeline-command-conventions.md +173 -0
  17. package/docs/15-multi-repo-and-local-workspace.md +86 -0
  18. package/docs/16-naming-conventions.md +77 -0
  19. package/docs/17-region-map.md +225 -0
  20. package/docs/18-cross-region-wiring.md +192 -0
  21. package/docs/19-component-cheatsheet.md +108 -0
  22. package/docs/20-adding-a-setting.md +159 -0
  23. package/docs/themes/01-build-a-theme-plugin.md +150 -0
  24. package/docs/themes/02-theme-field-index.md +145 -0
  25. package/docs/zh/00-README.md +189 -0
  26. package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
  27. package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
  28. package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
  29. package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
  30. package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
  31. package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
  32. package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
  33. package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
  34. package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
  35. 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 +164 -0
  36. package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
  37. package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
  38. package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
  39. package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
  40. package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
  41. package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
  42. package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
  43. package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
  44. package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
  45. 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 +159 -0
  46. package/docs/zh/plugin.schema.json +687 -0
  47. package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
  48. package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
  49. package/package.json +20 -0
@@ -0,0 +1,403 @@
1
+ # 08 — ViewContainer 视图容器 API
2
+
3
+ > 2026-07-30 · 2026-08-21 全量更新。**插件如何注册侧栏/面板视图。** 对标 VS Code `contributes.viewsContainers` + `contributes.views`。
4
+ > 所有有侧栏的插件(file-tree/marketplace/serial-monitor)都走此 API。面板视图(`location: "panel"`)同此机制。
5
+ > **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
6
+
7
+ ---
8
+
9
+ ## 一、概念
10
+
11
+ ```
12
+ ┌──────────────────────────────────────┐
13
+ │ 侧栏 (SidebarZone) │
14
+ │ ┌──────────────────────────────────┐ │
15
+ │ │ 资源管理器 [◀折叠][+][🔄] │ │ ← 容器 header(ViewContainer.title)+ titleActions
16
+ │ ├──────────────────────────────────┤ │
17
+ │ │ ▶ FOLDERS │ │ ← view(SidebarSection——可独立折叠)
18
+ │ │ src/ │ │
19
+ │ │ docs/ │ │
20
+ │ │ │ │
21
+ │ │ ▶ OUTLINE (语言插件) │ │ ← 另一个插件注册的 view——文件树不知道它的存在
22
+ │ │ functionA() │ │
23
+ │ │ │ │
24
+ │ │ ▶ TIMELINE (Git 插件) │ │ ← 又一个插件注册的 view
25
+ │ │ M modified.ts │ │
26
+ │ └──────────────────────────────────┘ │
27
+ └──────────────────────────────────────┘
28
+
29
+ ┌──────────────────────────────────────┐
30
+ │ 底部面板 (PanelZone) ← location: "panel" 的容器渲染在这里 │
31
+ │ ┌─────────┬─────────┐ │
32
+ │ │ 输出 │ 待办 │ ← 面板标签栏(切换器)+ 活动视图 titleActions │
33
+ │ └─────────┴─────────┘ │
34
+ └──────────────────────────────────────┘
35
+ ```
36
+
37
+ - **ViewContainer** = 侧栏/面板的一个"频道"。点图标栏切换。如 `explorer` / `marketplace` / `serial-monitor` / `panel-demo`。
38
+ - **View** = 容器里的一个可折叠 section。如 `folders` / `sessions` / `settings`。
39
+ - **任何插件** 都可以往别人的容器里注册 view。容器的主人不知道、不关心。
40
+ - **渲染位置由 `location` 决定**:`"sidebar"` → 左侧栏 SidebarZone;`"panel"` → 底部面板 PanelZone(标签栏切换视图);`"auxiliarybar"` → 右侧辅助侧栏 RightSidebarZone——⚠ **壳当前未接线(不渲染,区域 dormant)**:声明 auxiliarybar 容器/视图 = 无表面不可见。第三方侧栏/面板需求请用 `"sidebar"`/`"panel"`。所有区都用同一个 `PoolSectionStack` 渲染 view(SidebarSection 自动包裹)。
41
+
42
+ ---
43
+
44
+ ## 二、声明式注册——plugin.json(正路)
45
+
46
+ **🔥 所有 view 必须在 plugin.json 声明。** `render` 是组件模块路径字符串——loader 加载组件后注册进壳。**`render` 字段是函数/组件,过不了 IPC**——运行时 `registerView`(§四)传的 render 会被池侧白名单剥掉。所以:**组件永远靠 plugin.json 声明,运行时调用只更新元数据。**
47
+
48
+ ```json
49
+ {
50
+ "contributes": {
51
+ "viewsContainers": {
52
+ "explorer": {
53
+ "title": "资源管理器",
54
+ "location": "sidebar",
55
+ "hideIfEmpty": false,
56
+ "order": 100
57
+ }
58
+ },
59
+ "views": {
60
+ "explorer": [
61
+ {
62
+ "id": "folders",
63
+ "title": "",
64
+ "render": "src/views/FoldersView.tsx",
65
+ "order": 0,
66
+ "collapsed": false,
67
+ "titleActions": []
68
+ }
69
+ ]
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ ### viewsContainers 字段
76
+
77
+ | 字段 | 必需 | 类型 | 说明 |
78
+ |------|:--:|------|------|
79
+ | `title` | ✅ | string | 侧栏 header 显示的名称。如 "资源管理器" |
80
+ | `location` | ❌ | `"sidebar"` \| `"panel"` \| `"auxiliarybar"` \| `"main"` | 容器位置。默认 `"sidebar"`(见 §一渲染区)。`"main"`=主区标签页渲染面——仅活跃 factoryRole 插件(市场)声明,壳 ShellViewRenderer 消费 |
81
+ | `hideIfEmpty` | ❌ | boolean | 无活跃 view 时自动隐藏。默认 `false` |
82
+ | `order` | ❌ | number | 同位置容器排序。小值靠前 |
83
+ | `icon` | ❌ | string | 容器图标——覆盖插件自身图标 |
84
+ | `mergeHeaderWhenSingle` | ❌ | boolean | 容器内只有一个 view 时,隐藏 view 折叠头——标题合并到容器 header。对标 VS Code `mergeViewWithContainerWhenSingleView`(`panel-demo` 侧栏容器即用此模式) |
85
+
86
+ ### views 字段(全表)
87
+
88
+ | 字段 | 必需 | 类型 | 说明 |
89
+ |------|:--:|------|------|
90
+ | `id` | ✅ | string | View 唯一 ID。命名建议:`<功能名>` 如 `folders` / `sessions` |
91
+ | `render` | ✅ | string | 组件模块路径。**相对于插件目录**。如 `"src/views/FoldersView.tsx"` |
92
+ | `title` | ❌ | string | SidebarSection 折叠头标题。空字符串 = 无折叠头,直接渲染内容 |
93
+ | `role` | ❌ | `"toolbar"` \| `"section"` | 容器角色。默认 `"section"`(有折叠头);`"toolbar"` = 粘顶、不被 section 覆盖。替代 title 空串 hack |
94
+ | `order` | ❌ | number | 容器内排序。小值在上 |
95
+ | `collapsed` | ❌ | boolean | 初始折叠。默认 `false` |
96
+ | `when` | ❌ | string | Context key 条件——满足时才显示此 view。如 `"explorerFocus"` |
97
+ | `canToggleVisibility` | ❌ | boolean | ✅ 已实现——用户可在面板切换器/侧栏「视图」子菜单切换可见性 |
98
+ | `canMoveView` | ❌ | boolean | ✅ 已实现——用户可拖放此 view 到其他容器 |
99
+ | `hideByDefault` | ❌ | boolean | ✅ 已实现——默认隐藏,用户需手动从视图菜单开启 |
100
+ | `titleDescription` | ❌ | string | 标题旁的副文字。对标 VS Code `ViewPane.titleDescription` |
101
+ | `singleViewPaneContainerTitle` | ❌ | string | 单 view 且 `mergeHeaderWhenSingle` 时,容器 header 显示此标题替代容器 title |
102
+ | `minHeight` | ❌ | number | 拖拽 resize 最小高度(px)。不声明默认 100 |
103
+ | `showActions` | ❌ | `"always"` \| `"whenExpanded"` \| `"default"` | 控制动作区显隐时机。对标 VS Code `ViewPaneShowActions` |
104
+ | `titleTooltip` | ❌ | string | 标题 hover tooltip——标题截断时显示完整文字 |
105
+ | `badge` | ❌ | string \| number | 标题右侧标记——数字/短文字(如已安装数量 "15") |
106
+ | `titleActions` | ❌ | `TitleActionWidget[]` | **视图动作区声明制**——见 §三 |
107
+
108
+ ---
109
+
110
+ ## 三、titleActions 声明制——视图 header 右侧的动作区
111
+
112
+ **对标 VS Code 视图 header 右侧的 `[+][🔄][⊟]` / 终端 `[+][▾]`。** 声明在 `contributes.views[].titleActions`,壳统一渲染器 `ViewTitleActions.tsx` 消费——**随视图走、随视图迁移**(视图在面板/侧栏之间移动,动作区跟着走)。
113
+
114
+ ### 三 widget 形态
115
+
116
+ | 类型 | 形态 | 点击行为 |
117
+ |------|------|------|
118
+ | `icon` | 单图标按钮 | 执行 `command` |
119
+ | `dropdown` | 纯下拉(chevron) | 展开 `items` 列表,点条目执行对应 `command` |
120
+ | `split` | 主按钮 + 下拉复合 | 主按钮执行 `command`(默认动作),右侧 chevron 展开 `items` 备选 |
121
+
122
+ **widget 字段:** `id`(唯一)、`command`(点击执行的命令 ID)、`args`(可选——`executeCommand(command, args)` 单个位置参数透传)、`icon`(codicon 类名,如 `"codicon-add"`)、`title`(tooltip/aria-label/无 icon 时的文本)、`items`(dropdown/split 的备选条目 `{ label, command, args }`)。
123
+
124
+ ### 真实示例——panel-demo(官方验证插件)
125
+
126
+ ```json
127
+ {
128
+ "id": "demo-output",
129
+ "title": "输出",
130
+ "render": "src/views/DemoOutputView.tsx",
131
+ "order": 0,
132
+ "titleActions": [
133
+ {
134
+ "type": "split",
135
+ "id": "add-log",
136
+ "command": "panel-demo.addLog",
137
+ "icon": "codicon-add",
138
+ "title": "添加演示日志",
139
+ "args": { "level": "info", "text": "主按钮——添加信息日志" },
140
+ "items": [
141
+ { "label": "添加信息", "command": "panel-demo.addLog", "args": { "level": "info" } },
142
+ { "label": "添加警告", "command": "panel-demo.addLog", "args": { "level": "warn" } },
143
+ { "label": "添加错误", "command": "panel-demo.addLog", "args": { "level": "error" } }
144
+ ]
145
+ },
146
+ {
147
+ "type": "icon",
148
+ "id": "clear-log",
149
+ "command": "panel-demo.clearLog",
150
+ "icon": "codicon-clear-all",
151
+ "title": "清空输出"
152
+ }
153
+ ]
154
+ }
155
+ ```
156
+
157
+ ### titleActions 命令的注册
158
+
159
+ `titleActions` 声明的 `command` 执行真相源 = **池侧命令注册表**(`executeCommand` 池侧优先、壳 IPC fallback)。命令 handler 在 view 组件里注册:
160
+
161
+ ```tsx
162
+ // DemoOutputView.tsx(panel-demo 真实写法)
163
+ useEffect(() => {
164
+ const api = window.linkdesk?.commands;
165
+ api?.registerCommand?.(
166
+ "panel-demo.addLog",
167
+ (args?: { level?: LogLevel; text?: string }) => {
168
+ addLine(args?.level ?? "info", args?.text ?? "");
169
+ },
170
+ // 池侧 registerCommand 注册——when 交给声明制;when:"false" = 纯程序化命令不进命令面板(titleActions 专属)
171
+ );
172
+ api?.registerCommand?.("panel-demo.clearLog", () => clearLines());
173
+ }, []);
174
+ ```
175
+
176
+ > **`when: "false"` = 纯程序化命令不进命令面板**——titleActions 专属命令都这样声明,防止在 Ctrl+Shift+P 里刷屏。
177
+
178
+ ### 渲染位置(一个渲染器,两处消费)
179
+
180
+ - **面板容器(PanelZone)**:标签栏右侧动作区——按**活动视图**的 titleActions 渲染(`PanelZone.tsx`)
181
+ - **侧栏容器(SidebarZone/RightSidebarZone)**:section 折叠头右侧——每视图各渲染各的(`PoolSectionStack` 注入 SidebarSection actions 槽);`mergeHeaderWhenSingle` 单视图时容器 header 即视图 header,同样消费
182
+
183
+ **零声明(`titleActions: []`)→ 渲染 null(右侧空白,现状保持)。** widget 是通用件不是给终端造的——谁声明谁用(插件独立铁律:第三方声明即用,零壳改动)。
184
+
185
+ ---
186
+
187
+ ## 四、运行时更新与查询——`window.linkdesk.viewContainer`
188
+
189
+ **声明式(§二)管"有什么 view";运行时 API 管"元数据更新 + 查询"。** 视图的元数据真相源在壳 `ViewContainerService`(池通过真 IPC 访问)。
190
+
191
+ ```typescript
192
+ // 查询——返回 DTO(可序列化公开字段,render/actions 已剥)
193
+ const views = await window.linkdesk.viewContainer.getViews("explorer"); // ViewDto[]
194
+ const view = await window.linkdesk.viewContainer.getView("folders"); // ViewDto | undefined
195
+ const container = await window.linkdesk.viewContainer.getViewContainer("explorer");
196
+
197
+ // 更新元数据——标题随数据变化(对标 VS Code registerViews 更新)
198
+ // 同一 (pluginId, viewId) 重复调用 = 更新已有,render 保留(render 过不了 IPC,池侧白名单剥掉)
199
+ await window.linkdesk.viewContainer.registerView("file-tree", "explorer", {
200
+ id: "folders",
201
+ title: newFolderName, // 只更新标题——其他字段可选
202
+ minHeight: 180,
203
+ });
204
+ ```
205
+
206
+ **规则:**
207
+ - 同一个 `(pluginId, viewId)` 组合多次调用 `registerView` = **更新已有 view**。不指定某字段则保留原值。
208
+ - **`render` 是函数——过不了 IPC**(invoke 结构化克隆抛 `DataCloneError`,池侧白名单 `toViewMetaDto` 剥掉)。**永远不要靠运行时注册传组件**——组件必须 plugin.json 声明(§二),运行时只更新元数据。
209
+ - 查询不存在的容器/视图 → `undefined` / `[]`。
210
+
211
+ ### 视图变更广播
212
+
213
+ 壳注册表变化会 `events.emit("viewContainer:changed", { containerId, views: DTO[] })`——插件可订阅(marketplace 用它在视图注册后刷新 UI):
214
+
215
+ ```typescript
216
+ const unsub = window.linkdesk.events.on<{ containerId: string }>(
217
+ "viewContainer:changed",
218
+ ({ containerId }) => { refresh(containerId); }
219
+ );
220
+ ```
221
+
222
+ ### 壳侧写操作 API(插件不直接调——跨插件交互走 UI/桥)
223
+
224
+ 以下方法在壳 `ViewContainerService`(`src/core/services/layout/ViewContainerService.ts`)——插件侧**禁止 import 该模块**(ESLint `noCoreImportInPlugin` error 级,见 `01 §五`)。显隐/迁移/排序的**用户操作**由池侧 UI 经 IPC 桥自动落到壳:
225
+
226
+ | 壳方法 | 语义 | 插件怎么触发 |
227
+ |--------|------|------|
228
+ | `setVisible(containerId, viewId, visible)` / `isVisible` / `toggleViewVisibility` | 视图显隐(+ 持久化) | 面板切换器勾选 `panel:toggleViewVisibility` 桥 |
229
+ | `moveView(viewId, from, to, newIndex?)` | 跨容器迁移 | 拖放(`viewDragProtocol` MIME) |
230
+ | `reorderView(containerId, viewId, newIndex)` | 容器内重排(+ 持久化) | 拖 header 排序 |
231
+ | `registerViewEmptyContent(containerId, viewId, content, when?)` | View 空状态占位(无数据时显示) | — |
232
+
233
+ > 插件想"程序化"显隐/迁移 = 走 `executeCommand`(壳/插件注册的命令 handler 内调壳侧服务),或 `panel.reveal`(见 §五)。
234
+
235
+ ---
236
+
237
+ ## 五、面板视图——`location: "panel"` + `panel.reveal`
238
+
239
+ 面板容器(`location: "panel"`)渲染在底部 PanelZone,标签栏切换视图。**聚焦底部面板视图 = `window.linkdesk.panel.reveal(viewId)`**(对标 VS Code 视图提升语义):
240
+
241
+ ```typescript
242
+ await window.linkdesk.panel.reveal("demo-output"); // 聚焦底部面板的 demo-output 视图
243
+ ```
244
+
245
+ - 面板隐藏 → 展开并切到该视图(Ctrl+J 同机制)
246
+ - 面板已显示 → 切换聚焦
247
+ - `viewId` 不在 panel 容器 → **no-op**(不报错)
248
+
249
+ **完整面板容器示例——panel-demo:**
250
+
251
+ ```json
252
+ {
253
+ "contributes": {
254
+ "viewsContainers": {
255
+ "panel-demo": { "title": "面板演示", "location": "panel" },
256
+ "panel-demo-sidebar": { "title": "面板演示", "location": "sidebar" }
257
+ },
258
+ "views": {
259
+ "panel-demo": [
260
+ { "id": "demo-output", "title": "输出", "render": "src/views/DemoOutputView.tsx", "order": 0, "titleActions": [/* §三 */] },
261
+ { "id": "demo-todo", "title": "待办", "render": "src/views/DemoTodoView.tsx", "order": 1 }
262
+ ],
263
+ "panel-demo-sidebar": [
264
+ { "id": "demo-sidebar", "title": "侧栏演示", "render": "src/views/DemoSidebarView.tsx", "order": 0, "titleActions": [/* §三 */] }
265
+ ]
266
+ }
267
+ }
268
+ }
269
+ ```
270
+
271
+ > 同一个插件可以同时声明 panel 容器 + sidebar 容器(各归各的 zone)。**`panel.moveToEditor` 已移除**——zone 位置移动是布局命令的事。
272
+
273
+ ---
274
+
275
+ ## 六、View 组件写法规约
276
+
277
+ ### 组件签名
278
+
279
+ ```typescript
280
+ // src/views/MyView.tsx
281
+ export default function MyView() {
282
+ // 标准 React 组件——和写普通组件完全一样
283
+ return <div>...</div>;
284
+ }
285
+ ```
286
+
287
+ ### 不要自己包 SidebarSection
288
+
289
+ **❌ 错误:**
290
+ ```tsx
291
+ export default function MyView() {
292
+ return (
293
+ <SidebarSection title="我的视图">
294
+ <div>内容</div>
295
+ </SidebarSection>
296
+ );
297
+ }
298
+ ```
299
+
300
+ **✅ 正确:**
301
+ ```tsx
302
+ export default function MyView() {
303
+ // PoolSectionStack 会自动用 SidebarSection 包裹——不需要自己包
304
+ return <div>内容</div>;
305
+ }
306
+ ```
307
+
308
+ 渲染循环(壳 `usePoolSync` → 池 `PoolSectionStack`):
309
+ ```tsx
310
+ views.map(view => (
311
+ <SidebarSection key={view.id} title={view.title} defaultOpen={!view.collapsed}>
312
+ <PluginComponent renderPath={view._renderPath} />
313
+ </SidebarSection>
314
+ ))
315
+ ```
316
+
317
+ view 组件只负责**内容区域**。折叠/展开/标题由 SidebarSection 统一管理。
318
+
319
+ ### title 为空字符串
320
+
321
+ `"title": ""` → SidebarSection 不渲染折叠头——内容直接显示。适合"唯一的 view,不需要折叠"的场景。如 file-tree 的 `folders` view。多 section 场景用 `role` 而非 title hack。
322
+
323
+ ### 工具栏按钮
324
+
325
+ view 内容顶部可以自由放置工具栏按钮——不是 SidebarSection 的 header actions(那个走 titleActions 声明制,§三)。内容区域完全自由:
326
+
327
+ ```tsx
328
+ export default function MyView() {
329
+ return (
330
+ <>
331
+ <div className="my-toolbar">
332
+ <button onClick={...}>+ 新建</button>
333
+ </div>
334
+ <div className="my-content">...</div>
335
+ </>
336
+ );
337
+ }
338
+ ```
339
+
340
+ ---
341
+
342
+ ## 七、完整示例——Git 插件往 Explorer 注册 TIMELINE
343
+
344
+ ```json
345
+ // git/plugin.json
346
+ {
347
+ "contributes": {
348
+ "views": {
349
+ "explorer": [
350
+ {
351
+ "id": "timeline",
352
+ "title": "TIMELINE",
353
+ "render": "src/views/TimelineView.tsx",
354
+ "order": 100,
355
+ "when": "gitOpen"
356
+ }
357
+ ]
358
+ }
359
+ }
360
+ }
361
+ ```
362
+
363
+ ```typescript
364
+ // git/src/views/TimelineView.tsx
365
+ export default function TimelineView() {
366
+ // ... 读 git log → 渲染列表 ...
367
+ return <div className="git-timeline">...</div>;
368
+ }
369
+ ```
370
+
371
+ 文件树插件零改动。TimelineView 自动出现在 FOLDERS 下面。
372
+
373
+ ---
374
+
375
+ ## 八、生命周期
376
+
377
+ ```
378
+ 插件加载
379
+ → loader parseContributions → 声明式注册 viewsContainers + views(加载 render 组件)
380
+ → 组件 mount → 运行时 registerView 更新元数据(标题/排序/minHeight)
381
+ → 壳 usePoolSync → 池 PoolSectionStack 渲染 getActiveViews(containerId)
382
+
383
+ 插件卸载
384
+ → ViewContainerService.unregisterAll(pluginId)(可逆注册 tracker 逆序回滚)
385
+ → 该插件的全部容器 + 全部 view 移除
386
+ → events.emit("viewContainer:changed") 广播
387
+ → 池重渲染——其他插件的 view 不受影响
388
+ ```
389
+
390
+ ## 九、何时用声明式、何时用运行时
391
+
392
+ | 场景 | 方式 |
393
+ |------|------|
394
+ | view 标题固定不变 | plugin.json 声明式(§二) |
395
+ | view 标题随数据变化(如"收发设置 — COM3") | plugin.json 声明 + 运行时 `registerView({ title: 新标题 })` 更新元数据(§四) |
396
+ | view 数量固定 | plugin.json 声明式 |
397
+ | view 需要动作区(header 右侧按钮/下拉) | plugin.json `titleActions` 声明制(§三) |
398
+ | 需要聚焦底部面板视图 | `window.linkdesk.panel.reveal(viewId)`(§五) |
399
+
400
+ ---
401
+
402
+ > **← 概览:** `00-README.md`
403
+ > **→ 相关:** `01-插件API契约.md` `03-插件contributes规范.md` `07-插件间通信.md`