@linkdesk/plugin-docs 0.1.32 → 0.1.34
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 +40 -2
- package/docs/05-ui-conventions.md +62 -2
- package/docs/06-plugin-json-spec.md +2 -2
- package/docs/10-building-a-settings-plugin.md +17 -1
- package/docs/16-naming-conventions.md +2 -2
- package/docs/19-component-cheatsheet.md +1 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +40 -2
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +56 -2
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +2 -2
- 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 +17 -1
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +2 -2
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +1 -0
- package/docs/zh/plugin.schema.json +5 -2
- package/package.json +1 -1
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
| `titleBar` | ✅ | top bar left/right slot buttons | MenuRegistry |
|
|
34
34
|
| `viewsContainers` | ✅ | declare sidebar/panel containers | ViewContainerService |
|
|
35
35
|
| `views` | ✅ | register views in a container — any plugin can register in any container | ViewContainerService |
|
|
36
|
-
| `floatingPanel` | ✅ | declare that a view can be shown in a shell-internal floating panel (type B) — `viewId` references an already-registered view; without the declaration there is no "Open in Floating Panel" context menu item | declaration addressing → FloatingPanelService |
|
|
36
|
+
| `floatingPanel` | ✅ | declare that a view can be shown in a shell-internal floating panel (type B) — `viewId` references an already-registered view; without the declaration there is no "Open in Floating Panel" context menu item; optional `defaultForm`/`formKey` fix or offer the **first-open form** (§3.15) | declaration addressing → FloatingPanelService |
|
|
37
37
|
| `i18n` | ✅ | plugin-bundled translation files | i18nResources (i18next namespace) |
|
|
38
38
|
|
|
39
39
|
### Main-process consumers (2)
|
|
@@ -733,6 +733,8 @@ useEffect(() => {
|
|
|
733
733
|
| Field | Required | Description |
|
|
734
734
|
|------|:--:|------|
|
|
735
735
|
| `viewId` | ✅ | **a view ID already registered in contributes.views** — declaration addressing resolves the plugin/renderPath/title |
|
|
736
|
+
| `defaultForm` | ❌ | the form used the **first time** the view is opened, fixed by the author (the user gets no entry point): `"floatingPanel"` (floating panel) \| `"tab"` (tab) |
|
|
737
|
+
| `formKey` | ❌ | the **first-open** form is **left to the user**: a configuration key name (you declare that key in `contributes.configuration`; its `default` is your default form) |
|
|
736
738
|
|
|
737
739
|
**Declaring is consuming — four things appear automatically:**
|
|
738
740
|
|
|
@@ -743,7 +745,43 @@ useEffect(() => {
|
|
|
743
745
|
| `linkdesk.panel.revealFloating(viewId)` opens the panel programmatically | panel identity toggle semantics — no panel → open; same view → close; another panel → replace |
|
|
744
746
|
| Uninstalling the declaring plugin → the menu item disappears + revealFloating no-ops without crashing | the declaration unloads with the plugin lifecycle |
|
|
745
747
|
|
|
746
|
-
|
|
748
|
+
#### Configurable first-open form (`defaultForm` / `formKey`) — authors who just want the panel to pop out add nothing
|
|
749
|
+
|
|
750
|
+
**Division of labour: the plugin only declares which form it wants; the shell decides and executes** — the plugin has zero execution power and the shell has zero plugin knowledge (the shell hard-codes no plugin ID, so any future declarer works without shell changes).
|
|
751
|
+
|
|
752
|
+
| What the author wants | How to write it | What the user sees in the Settings editor |
|
|
753
|
+
|:--|:--|:--|
|
|
754
|
+
| Fix the form, no user override | `"defaultForm": "tab"` | Nothing (no Settings item appears at all) |
|
|
755
|
+
| Let the user choose | `"formKey": "<plugin-id>.openForm"` plus declaring that key yourself in `contributes.configuration` | The control for that key (toggle/dropdown, rendered from your `type`) |
|
|
756
|
+
|
|
757
|
+
```json
|
|
758
|
+
{
|
|
759
|
+
"contributes": {
|
|
760
|
+
"floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" },
|
|
761
|
+
"configuration": {
|
|
762
|
+
"title": "Settings plugin",
|
|
763
|
+
"properties": {
|
|
764
|
+
"settings.openForm": {
|
|
765
|
+
"type": "string",
|
|
766
|
+
"enum": ["floatingPanel", "tab"],
|
|
767
|
+
"default": "floatingPanel",
|
|
768
|
+
"description": "Form when opening Settings — floatingPanel / tab"
|
|
769
|
+
}
|
|
770
|
+
}
|
|
771
|
+
}
|
|
772
|
+
}
|
|
773
|
+
}
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
**The shell's decision chain** (first match wins; executed by "first open" entry points — today that is `core.openSettings`):
|
|
777
|
+
|
|
778
|
+
1. `formKey` is present and that key **is registered** → read its value: `"floatingPanel"` / `"tab"` is used as-is (**the value *is* the form — no mapping layer**);
|
|
779
|
+
2. otherwise `defaultForm` (only legal values are accepted);
|
|
780
|
+
3. neither → **previous behaviour** (a declaring plugin opens as a floating panel — today's settings default).
|
|
781
|
+
|
|
782
|
+
**Four boundaries**: ① it only governs the **first open** — an existing tab is still focused and an already-open panel still toggles shut; changing the form afterwards keeps using the two old paths ("Open in main window" / "Open in Floating Panel"); ② `formKey` and `defaultForm` are **mutually exclusive** (both declared ⇒ schema validation fails — one form from two sources); ③ a typo'd `formKey` / a key that was never registered ⇒ falls back to `defaultForm` (neither = previous behaviour) plus one warning — it **never fails silently**; ④ declaring `"defaultForm": "tab"` on a plugin with no tab form (`appearsIn.tabBar` + `entry`) falls back to the floating panel rather than silently doing nothing.
|
|
783
|
+
|
|
784
|
+
**The first declarer = settings** (`core.openSettings`, Ctrl+, opens the panel, and `settings.openForm` lets the user change it inside the "Settings plugin" group); **the second declarer, used as a validation vehicle = the `floating-panel-demo` test plugin** (a tab-style view; end-to-end validation of replacement + the right-click return path + unload no-op).
|
|
747
785
|
|
|
748
786
|
---
|
|
749
787
|
|
|
@@ -560,10 +560,11 @@ both stylesheets land on the same element.
|
|
|
560
560
|
| `ldk-drop-zone-in` | the drop zone's entrance animation |
|
|
561
561
|
| `ldk-dropdown-card-in` | the dropdown card's entrance animation |
|
|
562
562
|
| `ldk-floating-panel-in` | the floating panel's entrance animation |
|
|
563
|
-
| `ldk-group-tab-enter` | the group tab's entrance animation |
|
|
564
|
-
| `ldk-group-tab-exit` | the group tab's exit animation |
|
|
565
563
|
| `ldk-notif-icon-spin` | the notification icon's spin |
|
|
566
564
|
| `ldk-notif-progress-scan` | the notification progress scan |
|
|
565
|
+
| `ldk-rn-spin` | the release-notes page's refresh icon spin |
|
|
566
|
+
| `ldk-boot-mark-breath` | the boot brand screen's breathing |
|
|
567
|
+
| `ldk-view-skeleton-breath` | the content loading skeleton's breathing |
|
|
567
568
|
|
|
568
569
|
**The name you reference has to exist somewhere**—rule 2 above says "when you rename, change the reference in
|
|
569
570
|
the same commit"; this is the other half, and **the machine checks it**: the name you write in
|
|
@@ -762,6 +763,64 @@ button { border: none; }
|
|
|
762
763
|
|
|
763
764
|
---
|
|
764
765
|
|
|
766
|
+
## 13. Hover Hints → the `data-hint` attributes (or `<HintTip>`)
|
|
767
|
+
|
|
768
|
+
**That little bar that appears when the pointer rests on your button/icon is not drawn by the browser.**
|
|
769
|
+
|
|
770
|
+
The host ships one unified light hint (`HintTip`): light/dark theme, UI scaling, edge flipping, and the
|
|
771
|
+
keycap look for shortcuts are all decided in one place by the shell. **You do not import anything** to use
|
|
772
|
+
it—write attributes:
|
|
773
|
+
|
|
774
|
+
```tsx
|
|
775
|
+
// ❌ native title: drawn by the browser; theme/scaling/keycaps never follow the shell (red since SDK >= 0.1.49)
|
|
776
|
+
<button title={t("Refresh")}>
|
|
777
|
+
|
|
778
|
+
// ✅ attribute form: swap title= for data-hint= (zero DOM structure change)
|
|
779
|
+
<button data-hint={t("Refresh")} aria-label={t("Refresh")}>
|
|
780
|
+
|
|
781
|
+
// ✅ with a shortcut: give the command id and the shell looks it up (name + keys come from that one table,
|
|
782
|
+
// so the hint bar / context menu / command palette always say the same thing)
|
|
783
|
+
<button data-hint-command="fileTree.refresh" aria-label={t("Refresh")}>
|
|
784
|
+
|
|
785
|
+
// ✅ reveal kind ("see the whole truncated text"): it must appear at once, don't make it wait
|
|
786
|
+
<div data-hint={fullPath} data-hint-delay="0">{truncated}</div>
|
|
787
|
+
|
|
788
|
+
// ✅ composite cases (you want to control the wrapper): the component form
|
|
789
|
+
import { HintTip } from "@linkdesk/ui";
|
|
790
|
+
<HintTip label={t("Refresh")} command="fileTree.refresh"><button …>…</button></HintTip>
|
|
791
|
+
```
|
|
792
|
+
|
|
793
|
+
Four attributes, all written on your own DOM elements:
|
|
794
|
+
|
|
795
|
+
| Attribute | What it does |
|
|
796
|
+
|---|---|
|
|
797
|
+
| `data-hint` | The hint text (explain and reveal kinds share it—**the text is always yours**; the shell never ships sentences) |
|
|
798
|
+
| `data-hint-command` | Command id—the shell reads name and shortcut from the command table. **Same source** as the context menu / command palette (change it once, everything follows) |
|
|
799
|
+
| `data-hint-delay` | Intent delay in ms. Explain kind: **leave the default** (120 ms—prevents a flash while sweeping past); reveal kind: pass `"0"` |
|
|
800
|
+
| `data-hint-placement` | Preferred side: `top`/`bottom`/`left`/`right` (default `top`; flips automatically when it does not fit) |
|
|
801
|
+
|
|
802
|
+
**⚠️ Three rules**
|
|
803
|
+
|
|
804
|
+
1. **Explain kind waits, reveal kind does not**—"see the whole truncated text" must be immediate; a command
|
|
805
|
+
explanation for an icon is exactly the case that should pause a moment.
|
|
806
|
+
2. **No more native `title=`**: the SDK leg `linkdesk/no-native-title` (SDK >= 0.1.49) marks it red—`lint`
|
|
807
|
+
prints a red row and `ci-verify` fails. For the rare form where the hint renderer cannot reach (the
|
|
808
|
+
legitimate exception), write `// eslint-disable-next-line linkdesk/no-native-title -- reason` (a **reason
|
|
809
|
+
is mandatory**).
|
|
810
|
+
3. **No buttons inside the bar**: a hint is a hint, not a menu (use `<ContextMenu>` for interaction); for a
|
|
811
|
+
**long text / title / footnote** or multi-line explanation use `HintCard`—that component is the one that
|
|
812
|
+
owns "long explanations with a footnote".
|
|
813
|
+
|
|
814
|
+
> 🔧 **Maintainer note (authors may skip)**: renderer = `src/components/shared/hint-tip/HintTipRenderer.tsx`
|
|
815
|
+
> (a single mount in the pool: delegated `pointerover`/`pointerout`/`focusin`/`focusout` plus an intent-delay
|
|
816
|
+
> state machine); the single source of truth for the attribute literals is `hintAttrs.ts` (⛔ never write a
|
|
817
|
+
> `"data-hint"` literal anywhere else); the master switch is the shell config `app.hint.enabled` (default on,
|
|
818
|
+
> visible in settings); the gates are three legs — shell-side `scripts/check-native-title.mjs` (legacy
|
|
819
|
+
> white-list ledger, new sites only) and the SDK leg `checks/no-native-title.ts` (same id, pinned to each
|
|
820
|
+
> other by the three 锚⑪ anchor sentences).
|
|
821
|
+
|
|
822
|
+
---
|
|
823
|
+
|
|
765
824
|
## Quick Reference
|
|
766
825
|
|
|
767
826
|
| What you want to do | Core facility | How to bring it in |
|
|
@@ -775,6 +834,7 @@ button { border: none; }
|
|
|
775
834
|
| Rich-content confirm | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | the in-pool DialogHost renders the shell, **the content = a plugin-drawn view** (see §9) |
|
|
776
835
|
| Shortcuts (non-text keys) | `plugin.json contributes.keybindings` | — (putting text keys here = swallowing the whole pool, see §4.1) |
|
|
777
836
|
| Shortcuts (text keys / focus-bound keys) | container `onKeyDown` + `tabIndex` | pool-side self-handling, see §4.2 (document/window keydown is forbidden) |
|
|
837
|
+
| Hover hints | `data-hint` / `data-hint-command` / `data-hint-delay` attributes (or `<HintTip>`) | just write them on your own DOM elements — **no import needed** (see §13; a native `title=` is red) |
|
|
778
838
|
| Colors | CSS variables | `var(--xxx)`, list in `src/index.css` |
|
|
779
839
|
| Font sizes | CSS variables | `var(--font-size-*)` + `--ui-scale`, bare px forbidden (gate, see §10) |
|
|
780
840
|
| Six-domain token overview | see the §11.1 matrix | color/surface/radius/glass/font size/font family—`var(--*)` follows theme+glass+scaling automatically; full list in `src/index.css` |
|
|
@@ -114,7 +114,7 @@ The `entry` field → the loader automatically recognizes this as a view plugin.
|
|
|
114
114
|
| `contributes.themes` | theme | registered into ThemeRegistry → theme browser |
|
|
115
115
|
| `contributes.languages` | language | registered into LanguageRegistry |
|
|
116
116
|
| `contributes.fileAssociations` | — | registered into FileAssociationService → double-clicking a file opens it automatically |
|
|
117
|
-
| `contributes.floatingPanel` | — | Declares that the view can be displayed in a floating panel inside the shell — viewId references an already-registered view; without the declaration there is no "Open in Floating Panel" context-menu item |
|
|
117
|
+
| `contributes.floatingPanel` | — | Declares that the view can be displayed in a floating panel inside the shell — viewId references an already-registered view; without the declaration there is no "Open in Floating Panel" context-menu item; optional `defaultForm`/`formKey` fix or offer the **first-open form** |
|
|
118
118
|
|
|
119
119
|
**A plugin can declare several contributions at once.** A view plugin, for example, can have `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands` — each is registered independently and does not affect the others.
|
|
120
120
|
|
|
@@ -329,7 +329,7 @@ Plugin-level activation ordering — declares which plugins must be activated be
|
|
|
329
329
|
|
|
330
330
|
- **③ Switch entry point = a role group on the settings page (appearing dynamically)**: when the settings UI opens it enumerates `listRoles()` → for every **non-settings-plugin role** it calls `list(role)` → **a group is created only when there are ≥2 candidates** (a single candidate makes switching meaningless). Group shape = the switch button on top (listing every candidate for that role, the active one highlighted) + the active set's own configuration below; it reuses a group of the same name where possible (finding the active candidate's own configuration group by pluginId), and only creates a new one otherwise; if the active set has no settings, it shows an empty state. Switching = `setActive` → refetch data → the configuration follows the active set. Switching your settings plugin's **own role** (settings) = the button in the generic area at the top (see `10-building-a-settings-plugin.md`).
|
|
331
331
|
- **④ Icon bar slot occupancy**: for plugins that declare `factoryRole` (form 2), the icon bar **renders only the active set's icon** and hides inactive ones — "swap the official one out for yours"; form 1 plugins that do not declare it still all show up side by side as before.
|
|
332
|
-
- **⑤ Routing seam**: opening settings (`Ctrl+,` / the gear) = `factorySlots.getActive("settings")` → if a tab is already open, focus it /
|
|
332
|
+
- **⑤ Routing seam**: opening settings (`Ctrl+,` / the gear) = `factorySlots.getActive("settings")` → if a tab is already open, focus it / **the first-open form comes from the declaration** (`formKey` value → `defaultForm` → previous behaviour): `tab` → open a tab; `floatingPanel` → the floating panel (the payload carries pluginId for composite addressing); with no `floatingPanel` declaration this entry point does nothing (previous behaviour). After switching the active set, all subsequent opens go through the new set, consistently on both ends. **The first-open form only governs the first open** — converting between the panel and a tab afterwards keeps using the old paths (criteria and boundaries → `03-contributes-spec.md` §3.15).
|
|
333
333
|
- **⑥ Switching sets on the plugin side** (the switch button's click, zero shell changes): `setActive` → tab form = close this set's tab → open the target set (singleton dedupe focuses it if it already exists); floating panel form = `panel.revealFloating(viewId, pluginId?)` **replacing the panel content in place with composite addressing** (no leftover tab popping up behind; if the target set declares no floatingPanel → fall back to opening a tab). Deleting any set → `onPluginLifecycleChange` → refetch → the button disappears on its own.
|
|
334
334
|
|
|
335
335
|
**Two-scenario example (official + third-party plugin marketplace):**
|
|
@@ -36,13 +36,29 @@ Follow the official settings plugin (= the `plugin.json` in **the settings plugi
|
|
|
36
36
|
{ "id": "settings", "title": "Settings", "render": "src/views/SettingsView.tsx", "order": 0 }
|
|
37
37
|
]
|
|
38
38
|
},
|
|
39
|
-
"floatingPanel": { "viewId": "settings" } // ③ floating panel form (optional)
|
|
39
|
+
"floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" } // ③ floating panel form (optional) — formKey hands the first-open form to the user
|
|
40
40
|
}
|
|
41
41
|
}
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
All three key declarations are required: **`factoryRole: "settings"`** (puts you in the shared-area candidate list) + **`contributes.views`** (the actual render component) + **`floatingPanel`** (the `Ctrl+,` fallback form).
|
|
45
45
|
|
|
46
|
+
**The first-open form is configurable (optional; write nothing and it opens as a floating panel)**: to let the user choose (floating panel / tab), add `"formKey": "<plugin-id>.openForm"` to `floatingPanel` and declare that key yourself — the key's `default` is your default form:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
"configuration": {
|
|
50
|
+
"title": "Settings plugin",
|
|
51
|
+
"properties": {
|
|
52
|
+
"settings.openForm": {
|
|
53
|
+
"type": "string", "enum": ["floatingPanel", "tab"], "default": "floatingPanel",
|
|
54
|
+
"description": "Form when opening Settings — floatingPanel / tab"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
To fix the form with no user override, write `"defaultForm": "tab"` instead (no configuration key ⇒ no Settings item appears at all). The two are **mutually exclusive** (declaring both fails schema validation); the decision chain, the boundaries and the "the shell decides, the plugin only declares" split → [`03-contributes-spec.md` §3.15](03-contributes-spec.md).
|
|
61
|
+
|
|
46
62
|
## Data API shape — everything goes through `window.linkdesk.*`
|
|
47
63
|
|
|
48
64
|
Settings plugins are **forbidden from `import @src/core/...`** (the plugin communication iron rule + ESLint `noCoreImportInPlugin`). All data is in the public API:
|
|
@@ -99,10 +99,10 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
|
|
|
99
99
|
|:--|:--|:--|
|
|
100
100
|
| Host command prefix | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | Your command id lands in the host's own segment — in the command palette and the keybindings page it looks like a host feature |
|
|
101
101
|
| Host protocol id | `bracket` | Same name as the host's bracket-matching protocol handler ⇒ one of the two never runs, with no error |
|
|
102
|
-
| Host pseudo plugin id | `app`、`appearance
|
|
102
|
+
| Host pseudo plugin id | `app`、`appearance` | The host registers as a "plugin" too (shell core / appearance; the former "update" group merged into General on 2026-09-26 — `update` is retired & logged) ⇒ these ids read as the host itself |
|
|
103
103
|
| Host config key | `app.schemaVersion` | The config **internal version marker** (invisible in the settings UI, never registered) — taking it derails migration bookkeeping and the user's data looks lost |
|
|
104
104
|
| Host config key | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | Theme and colours — taking it overwrites the theme the user is currently using |
|
|
105
|
-
| Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle` | Light/dark mode, accent colour, menu style |
|
|
105
|
+
| Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | Light/dark mode, accent colour, menu style, hover hints |
|
|
106
106
|
| Host config key | `app.backgroundImage`、`app.backgroundMask`、`app.backgroundOpacity`、`app.zoneBackgroundImage` | Background and per-zone backgrounds |
|
|
107
107
|
| Host config key | `app.glassBlur`、`app.glassOpacity`、`app.glassSaturate`、`app.glassTint` | The four glass parameters |
|
|
108
108
|
| Host config key | `app.surfaceRadius`、`app.zoneRadius`、`app.zoneRadiusScale` | Corner radii |
|
|
@@ -84,6 +84,7 @@ The version of `@linkdesk/ui` **equals the version of the LinkDesk shell you ins
|
|
|
84
84
|
| `ContextMenu` | Context menu component | Works with `contributes.menus` — see [05-UI Conventions](05-ui-conventions.md) |
|
|
85
85
|
| `InlineInput` | Inline input (imperative handle) | Renaming in place in a tree/list (grab the `ref` and call `InlineInputHandle`) |
|
|
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
|
+
| `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) |
|
|
87
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 |
|
|
88
89
|
|
|
89
90
|
> 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**.
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
| `titleBar` | ✅ | 顶栏左右槽位按钮 | MenuRegistry |
|
|
34
34
|
| `viewsContainers` | ✅ | 声明侧栏/面板容器 | ViewContainerService |
|
|
35
35
|
| `views` | ✅ | 往容器注册视图——任何插件可往任意容器注册 | ViewContainerService |
|
|
36
|
-
| `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId
|
|
36
|
+
| `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键;可选 `defaultForm`/`formKey` 定/选**首开形态**(§3.15) | 声明寻址 → FloatingPanelService |
|
|
37
37
|
| `i18n` | ✅ | 插件自带翻译文件 | i18nResources(i18next 命名空间) |
|
|
38
38
|
|
|
39
39
|
### 主进程消费(2 个)
|
|
@@ -733,6 +733,8 @@ useEffect(() => {
|
|
|
733
733
|
| 字段 | 必需 | 说明 |
|
|
734
734
|
|------|:--:|------|
|
|
735
735
|
| `viewId` | ✅ | **contributes.views 中已注册的视图 ID**——声明寻址解析出插件/renderPath/title |
|
|
736
|
+
| `defaultForm` | ❌ | **首次打开**用哪种形态,作者定死(用户没入口):`"floatingPanel"`(悬浮面板)\| `"tab"`(标签页) |
|
|
737
|
+
| `formKey` | ❌ | **首次打开**形态**交给用户选**:填一个配置键名(键由你在 `contributes.configuration` 里声明,键的 `default` 即作者默认形态) |
|
|
736
738
|
|
|
737
739
|
**声明即消费,四件事自动出现:**
|
|
738
740
|
|
|
@@ -743,7 +745,43 @@ useEffect(() => {
|
|
|
743
745
|
| `linkdesk.panel.revealFloating(viewId)` 可编程弹面板 | 面板身份开关键——无面板→开;同视图→关;他面板→替换 |
|
|
744
746
|
| 卸载声明插件 → 右键条目消失 + revealFloating no-op 不崩 | 声明随插件生命周期卸载 |
|
|
745
747
|
|
|
746
|
-
|
|
748
|
+
#### 首开形态可配(`defaultForm` / `formKey`)——只想要面板能弹出来的作者一个字都不用加
|
|
749
|
+
|
|
750
|
+
**分工:插件只声明想要哪种,壳决定并执行**——插件零执行权、壳零插件知识(壳侧不认任何插件 ID,换一只声明者自动生效,不必改壳)。
|
|
751
|
+
|
|
752
|
+
| 作者想要 | 写法 | 用户在设置页的入口 |
|
|
753
|
+
|:--|:--|:--|
|
|
754
|
+
| 定死形态,不给用户改 | `"defaultForm": "tab"` | 无(设置页不出现任何项) |
|
|
755
|
+
| 让用户自己选 | `"formKey": "<插件id>.openForm"` + 自己在 `contributes.configuration` 里声明这个键 | 该键的控件(布尔/下拉按你的 `type` 渲染) |
|
|
756
|
+
|
|
757
|
+
```json
|
|
758
|
+
{
|
|
759
|
+
"contributes": {
|
|
760
|
+
"floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" },
|
|
761
|
+
"configuration": {
|
|
762
|
+
"title": "设置插件",
|
|
763
|
+
"properties": {
|
|
764
|
+
"settings.openForm": {
|
|
765
|
+
"type": "string",
|
|
766
|
+
"enum": ["floatingPanel", "tab"],
|
|
767
|
+
"default": "floatingPanel",
|
|
768
|
+
"description": "打开设置时的形态——floatingPanel 悬浮面板 / tab 标签页"
|
|
769
|
+
}
|
|
770
|
+
}
|
|
771
|
+
}
|
|
772
|
+
}
|
|
773
|
+
}
|
|
774
|
+
```
|
|
775
|
+
|
|
776
|
+
**壳的判定链**(第一命中即定;由「第一次打开」这一类入口执行——今天 = `core.openSettings`):
|
|
777
|
+
|
|
778
|
+
1. `formKey` 有、且那个键**已注册** → 读它的值:`"floatingPanel"` / `"tab"` 直接用(**值即形态,无映射层**);
|
|
779
|
+
2. 否则看 `defaultForm`(合法值才认);
|
|
780
|
+
3. 都没有 → **原行为**(声明了面板即面板——今天设置插件的默认)。
|
|
781
|
+
|
|
782
|
+
**四条边界**:① 只管**第一次打开**——已有标签页仍聚焦、面板开着再点仍按开关键关掉,打开之后想换形态照旧走「在主窗口中打开」/「在悬浮面板中打开」两条老路;② `formKey` 与 `defaultForm` **互斥**(同时写 ⇒ schema 校验红:一个形态两个来源);③ `formKey` 写错字 / 没注册那个键 ⇒ 降级 `defaultForm`(都没有 = 原行为)+ 出声一条 warn——**不静默失效**;④ 声明 `"defaultForm": "tab"` 但插件没有标签页形态(`appearsIn.tabBar` + `entry`)⇒ 落回悬浮面板,不静默无动作。
|
|
783
|
+
|
|
784
|
+
**首批声明者 = settings**(`core.openSettings` Ctrl+, 弹面板,`settings.openForm` 在「设置插件」组里让用户改);**第二声明者验证载体 = `floating-panel-demo`** 测试插件(标签页型视图,端到端验证替换 + 右键回程 + 卸载 no-op)。
|
|
747
785
|
|
|
748
786
|
---
|
|
749
787
|
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -559,10 +559,11 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
|
|
|
559
559
|
| `ldk-drop-zone-in` | 拖放区的入场动画(宿主的自有动画一律带 `ldk-` 前缀) |
|
|
560
560
|
| `ldk-dropdown-card-in` | 下拉卡片的入场动画 |
|
|
561
561
|
| `ldk-floating-panel-in` | 浮动面板的入场动画 |
|
|
562
|
-
| `ldk-group-tab-enter` | 分组标签的入场动画 |
|
|
563
|
-
| `ldk-group-tab-exit` | 分组标签的退场动画 |
|
|
564
562
|
| `ldk-notif-icon-spin` | 通知图标的旋转 |
|
|
565
563
|
| `ldk-notif-progress-scan` | 通知的进度扫描 |
|
|
564
|
+
| `ldk-rn-spin` | 发行说明页刷新图标的旋转 |
|
|
565
|
+
| `ldk-boot-mark-breath` | 池首帧品牌过场的呼吸 |
|
|
566
|
+
| `ldk-view-skeleton-breath` | 内容加载骨架的呼吸 |
|
|
566
567
|
|
|
567
568
|
**引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
|
|
568
569
|
你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
|
|
@@ -769,6 +770,57 @@ button { border: none; }
|
|
|
769
770
|
|
|
770
771
|
---
|
|
771
772
|
|
|
773
|
+
## 13. 悬停提示 → `data-hint` 属性(或 `<HintTip>`)
|
|
774
|
+
|
|
775
|
+
**鼠标停在你的按钮/图标上时,那个小条不是浏览器画的。**
|
|
776
|
+
|
|
777
|
+
宿主有一套统一的轻提示(`HintTip`):深浅主题、字号缩放、贴边翻面、快捷键键帽都由壳一处决定。
|
|
778
|
+
**你不需要 import 任何东西**就能用——写属性即可:
|
|
779
|
+
|
|
780
|
+
```tsx
|
|
781
|
+
// ❌ 原生 title:浏览器画,主题/缩放/键帽都不跟壳走(SDK ≥ 0.1.49 起这条腿判红)
|
|
782
|
+
<button title={t("刷新")}>
|
|
783
|
+
|
|
784
|
+
// ✅ 属性式:把 title= 换成 data-hint=(DOM 结构零变化)
|
|
785
|
+
<button data-hint={t("刷新")} aria-label={t("刷新")}>
|
|
786
|
+
|
|
787
|
+
// ✅ 带快捷键:给命令 id,壳去查命令表(文案与快捷键都来自那一份 ⇒ 提示条/右键菜单/命令面板永远一个说法)
|
|
788
|
+
<button data-hint-command="fileTree.refresh" aria-label={t("刷新")}>
|
|
789
|
+
|
|
790
|
+
// ✅ 揭示类("看全被截断的字"):该立刻出现,别让它等
|
|
791
|
+
<div data-hint={fullPath} data-hint-delay="0">{truncated}</div>
|
|
792
|
+
|
|
793
|
+
// ✅ 复合场景(要自己控制包裹):组件式
|
|
794
|
+
import { HintTip } from "@linkdesk/ui";
|
|
795
|
+
<HintTip label={t("刷新")} command="fileTree.refresh"><button …>…</button></HintTip>
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
四个属性,都写在你自己的 DOM 元素上:
|
|
799
|
+
|
|
800
|
+
| 属性 | 作用 |
|
|
801
|
+
|---|---|
|
|
802
|
+
| `data-hint` | 提示主文案(说明类与揭示类通用——**文案永远由你给**,壳不下发任何句子) |
|
|
803
|
+
| `data-hint-command` | 命令 id——壳查命令表取名字与快捷键。与右键菜单/命令面板**同源**(改一处全跟走) |
|
|
804
|
+
| `data-hint-delay` | 意图延时(毫秒)。说明类**留默认**(120ms——防划过闪一下);揭示类传 `"0"` |
|
|
805
|
+
| `data-hint-placement` | 首选方位 `top`/`bottom`/`left`/`right`(缺省 `top`,贴不下自动翻面) |
|
|
806
|
+
|
|
807
|
+
**⚠️ 三条纪律**
|
|
808
|
+
|
|
809
|
+
1. **说明类慢、揭示类近 0**——「看全被截断的字」要立刻;反过来给图标加命令说明才该等那一等。
|
|
810
|
+
2. **别再用原生 `title=`**:SDK 腿 `linkdesk/no-native-title`(SDK ≥ 0.1.49)判红——`lint` 输出红行、
|
|
811
|
+
`ci-verify` 判红。确需原生 title 的形态(提示渲染器够不到的)走
|
|
812
|
+
`// eslint-disable-next-line linkdesk/no-native-title -- 理由`(**理由必填**)。
|
|
813
|
+
3. **条内不放按钮**:提示是提示不是菜单(要交互用 `<ContextMenu>`);要**长文案/标题/注脚**或多行说明,
|
|
814
|
+
用 `HintCard`——那一件本来就是管"有注脚的长说明"的。
|
|
815
|
+
|
|
816
|
+
> 🔧 **维护者注(作者可跳过)**:渲染器 = `src/components/shared/hint-tip/HintTipRenderer.tsx`(池内单例挂载:
|
|
817
|
+
> 委托 `pointerover`/`pointerout`/`focusin`/`focusout` + 意图延时状态机);属性字面量的单一真相源 =
|
|
818
|
+
> `hintAttrs.ts`(⛔ 别处不许再写 `"data-hint"` 字面量);总开关 = 壳配置 `app.hint.enabled`(缺省开,设置页可见);
|
|
819
|
+
> 门禁三腿 = 壳侧 `scripts/check-native-title.mjs`(存量白名单账、只判新增)+ SDK 腿
|
|
820
|
+
> `checks/no-native-title.ts`(同 id、锚⑪ 3 句锚词互钉)。
|
|
821
|
+
|
|
822
|
+
---
|
|
823
|
+
|
|
772
824
|
## 速查
|
|
773
825
|
|
|
774
826
|
| 你要做的 | 核心设施 | 引入方式 |
|
|
@@ -782,6 +834,8 @@ button { border: none; }
|
|
|
782
834
|
| 富内容确认框 | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | 池内 DialogHost 渲染壳,**内容 = 插件自绘视图**(见 §9) |
|
|
783
835
|
| 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
|
|
784
836
|
| 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
|
|
837
|
+
| 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
|
|
838
|
+
| 悬停提示 | `data-hint` / `data-hint-command` / `data-hint-delay` 属性(或 `<HintTip>`) | 写在你的 DOM 元素上即可,**不需要 import**(见 §13;原生 `title=` 判红) |
|
|
785
839
|
| 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
|
|
786
840
|
| 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
|
|
787
841
|
| 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
|
|
@@ -114,7 +114,7 @@ my-plugin/
|
|
|
114
114
|
| `contributes.themes` | theme | 注册到 ThemeRegistry → 主题浏览器 |
|
|
115
115
|
| `contributes.languages` | language | 注册到 LanguageRegistry |
|
|
116
116
|
| `contributes.fileAssociations` | — | 注册到 FileAssociationService → 双击文件自动打开 |
|
|
117
|
-
| `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId
|
|
117
|
+
| `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键;可选 `defaultForm`/`formKey` 定/选**首开形态** |
|
|
118
118
|
|
|
119
119
|
**插件可同时声明多种贡献。** 比如一个视图插件可以有 `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands`——全部独立注册,互不影响。
|
|
120
120
|
|
|
@@ -329,7 +329,7 @@ my-plugin/
|
|
|
329
329
|
|
|
330
330
|
- **③ 切换入口 = 设置页角色分组(动态出现)**:设置 UI 打开时枚举 `listRoles()` → 对每个**非设置插件角色** `list(role)` → **候选 ≥2 才建组**(单候选无切换意义)。组形态 = 切换按钮在顶(列出该角色全部候选,激活高亮)+ 激活套自己的配置在下方;复用同名组优先(按 pluginId 找激活候选自己的配置组)、没有才新建;激活套无配置项 → 空状态。切换 = `setActive` → 重拉数据 → 配置随激活套换。你的设置插件**自身角色**(settings)的切换 = 顶部通用区按钮(见 `10-如何造一个设置插件.md`)。
|
|
331
331
|
- **④ 图标栏占槽**:声明 `factoryRole` 的插件(形态二),图标栏**只渲染激活套图标**、非激活套隐藏——"把官方的剔除换成你的";不声明的形态一照旧全出并排。
|
|
332
|
-
- **⑤ 路由接缝**:打开设置(`Ctrl+,` / 齿轮)= `factorySlots.getActive("settings")` → 已开标签页聚焦 /
|
|
332
|
+
- **⑤ 路由接缝**:打开设置(`Ctrl+,` / 齿轮)= `factorySlots.getActive("settings")` → 已开标签页聚焦 / **按声明定首开形态**(`formKey` 键值 → `defaultForm` → 原行为):`tab` → 开标签页;`floatingPanel` → 悬浮面板(载荷带 pluginId 复合寻址);无 `floatingPanel` 声明 → 本入口不动(原行为)。切换激活套后,后续打开全走新套,两端一致。**首开形态只管「第一次打开」**——打开之后的面板↔标签页互转仍各走原路(判据与边界 → `03-插件contributes规范.md` §3.15)。
|
|
333
333
|
- **⑥ 全插件侧换套**(切换按钮点击,零壳改动):`setActive` → 标签页形态 = 关本套 tab → 开目标套(singleton 去重已存在则聚焦);悬浮面板形态 = `panel.revealFloating(viewId, pluginId?)` **原地复合替换**面板内容(不背后弹残留 tab;目标套无 floatingPanel 声明 → 退回开标签页)。删任意套 → `onPluginLifecycleChange` → 重拉 → 按钮自动消失。
|
|
334
334
|
|
|
335
335
|
**双场景示例(官方 + 第三方 插件市场):**
|
|
@@ -36,13 +36,29 @@
|
|
|
36
36
|
{ "id": "settings", "title": "设置", "render": "src/views/SettingsView.tsx", "order": 0 }
|
|
37
37
|
]
|
|
38
38
|
},
|
|
39
|
-
"floatingPanel": { "viewId": "settings" } // ③
|
|
39
|
+
"floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" } // ③ 悬浮面板形态(可选)——formKey 把首开形态交给用户
|
|
40
40
|
}
|
|
41
41
|
}
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
三个关键声明缺一不可:**`factoryRole: "settings"`**(进通用区候选列表)+ **`contributes.views`**(真实渲染组件)+ **`floatingPanel`**(`Ctrl+,` 兜底形态)。
|
|
45
45
|
|
|
46
|
+
**首开形态可配(可选,一个字不写 = 打开即悬浮面板)**:想让用户自己选(悬浮面板 / 标签页),就给 `floatingPanel` 加 `"formKey": "<插件id>.openForm"` 并自己声明那个键——键的 `default` 即你的默认形态:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
"configuration": {
|
|
50
|
+
"title": "设置插件",
|
|
51
|
+
"properties": {
|
|
52
|
+
"settings.openForm": {
|
|
53
|
+
"type": "string", "enum": ["floatingPanel", "tab"], "default": "floatingPanel",
|
|
54
|
+
"description": "打开设置时的形态——floatingPanel 悬浮面板 / tab 标签页"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
定死不让用户改则写 `"defaultForm": "tab"`(不给配置项,设置页就不出现任何项)。两者**互斥**(同时写 = schema 校验红);判定链、边界与「壳决定并执行、插件只声明」的分工 → [`03-插件contributes规范.md` §3.15](03-插件contributes规范.md)。
|
|
61
|
+
|
|
46
62
|
## 数据 API 形状——全走 `window.linkdesk.*`
|
|
47
63
|
|
|
48
64
|
设置插件**禁止 `import @src/core/...`**(插件通信铁律 + ESLint `noCoreImportInPlugin`)。数据全在公开 API:
|
|
@@ -101,10 +101,10 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
101
101
|
|:--|:--|:--|
|
|
102
102
|
| 宿主命令前缀 | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | 你的命令 id 落进宿主自己的段——命令面板、快捷键设置页里它看起来像宿主的功能 |
|
|
103
103
|
| 宿主协议 id | `bracket` | 与宿主的括号匹配协议处理器同名 ⇒ 有一方不生效(不报错) |
|
|
104
|
-
| 宿主伪 pluginId | `app`、`appearance
|
|
104
|
+
| 宿主伪 pluginId | `app`、`appearance` | 宿主自己也以「插件」身份注册(壳通用 / 外观;原「更新」组 2026-09-26 并入「通用」,`update` 已退役登记)⇒ 用这些 id 会被当成宿主自己 |
|
|
105
105
|
| 宿主配置键 | `app.schemaVersion` | 配置的**内部版本标志**(设置界面里看不到、也没有注册过)——占它会让迁移记账错乱,用户数据看着丢 |
|
|
106
106
|
| 宿主配置键 | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | 主题与配色——占它 = 直接顶掉用户当前选的主题 |
|
|
107
|
-
| 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle` |
|
|
107
|
+
| 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | 亮暗模式、强调色、菜单样式、悬停提示 |
|
|
108
108
|
| 宿主配置键 | `app.backgroundImage`、`app.backgroundMask`、`app.backgroundOpacity`、`app.zoneBackgroundImage` | 背景与区域背景 |
|
|
109
109
|
| 宿主配置键 | `app.glassBlur`、`app.glassOpacity`、`app.glassSaturate`、`app.glassTint` | 玻璃材质四参 |
|
|
110
110
|
| 宿主配置键 | `app.surfaceRadius`、`app.zoneRadius`、`app.zoneRadiusScale` | 圆角 |
|
|
@@ -85,6 +85,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
85
85
|
| `ContextMenu` | 右键菜单组件 | 配合 `contributes.menus` —— 见 [05-插件UI写法规约](05-插件UI写法规约.md) |
|
|
86
86
|
| `InlineInput` | 行内输入(命令式句柄) | 树/列表里就地改名(拿 `ref` 调 `InlineInputHandle`) |
|
|
87
87
|
| `OverlayPortal` | 弹层 portal 宿主 | 自绘弹窗要 portal 到 body 时用它,别裸写 `createPortal` 到处飘 |
|
|
88
|
+
| `HintTip` | 轻量悬停提示(组件式) | 「给它一个子元素、一句话」——**多数场景直接写 `data-hint` 属性即可,不必 import**;要自己控制包裹时用这个组件(见 [05-插件UI写法规约](05-插件UI写法规约.md) §13;原生 `title=` 判红) |
|
|
88
89
|
| `HintCard` | 贴锚的悬停说明卡(非交互) | 「停在某个小标上出一张说明卡」——给 `lines`(1–3 句)与锚元素,触发/定位/玻璃全归壳;⛔ 卡内不放链接按钮 |
|
|
89
90
|
|
|
90
91
|
> 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
|
|
@@ -620,9 +620,12 @@
|
|
|
620
620
|
"description": "Floating Panel declaration — declares that a view in contributes.views can be shown in a Floating Panel inside the shell. viewId must reference an already registered view: the declaration is resolved into pluginId/renderPath/title. Without it there is no 'Open in Floating Panel' context menu entry. The first declarer is settings (Ctrl+, opens the panel).",
|
|
621
621
|
"required": ["viewId"],
|
|
622
622
|
"properties": {
|
|
623
|
-
"viewId": { "type": "string", "description": "View ID — a view registered in contributes.views" }
|
|
623
|
+
"viewId": { "type": "string", "description": "View ID — a view registered in contributes.views" },
|
|
624
|
+
"defaultForm": { "enum": ["floatingPanel", "tab"], "description": "Form used the FIRST time this view is opened — 'floatingPanel' (Floating Panel inside the shell) or 'tab'. Author-fixed: the user gets no Settings entry. Omit to keep the previous behaviour (a declaring plugin opens as a Floating Panel). Mutually exclusive with formKey." },
|
|
625
|
+
"formKey": { "type": "string", "description": "Configuration key that lets the USER choose the first-open form. Must be declared in this same plugin's contributes.configuration: its default is the author's default form, and its value must be 'floatingPanel' or 'tab' (any other value falls back to the author-fixed form). Declaring it makes the item appear in the Settings editor. Mutually exclusive with defaultForm." }
|
|
624
626
|
},
|
|
625
|
-
"additionalProperties": false
|
|
627
|
+
"additionalProperties": false,
|
|
628
|
+
"not": { "required": ["defaultForm", "formKey"] }
|
|
626
629
|
},
|
|
627
630
|
"i18n": {
|
|
628
631
|
"type": "object",
|