feat: rebuild plugin UI with host rendering and standard settings (#4053)

* feat: rebuild plugin pages with host rendering and native settings

* fix(plugins): contain host-view errors, isolate editing, and migrate fixtures

* fix(plugins): migrate remaining permission fixture hosts
This commit is contained in:
陈大猫 authored and GitHub committed 2026-10-28 23:08:31 -07:00
1 parent 7cd57adcea
commit d5a03606b7
227 files changed
+8298 -4172

No files matched your search

+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Netcatty example contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
@@ -0,0 +1,22 @@
# Hello React: host-rendered plugin UI
This example uses ordinary React and custom CSS. Netcatty draws its visible UI;
the script runs in the isolated runtime and requests `views` and `settings.read` (its own settings only).
Build: `npm run build --workspace @netcatty/example-hello-react-host`.
Package this folder with the plugin CLI and install the `.ncpkg` from Settings.
No development environment flag is needed for this browser example.
It declares Vault, terminal sidebar, tab, aside, panel and modal views.
Its Settings entry is a standard Netcatty form with greeting, appearance and
content groups. Name, greeting enabled, accent color and default note are saved
by the host and applied to new pages and already-open pages. Demo edits inside
a page remain local; use Settings to change persistent defaults.
Try text/Chinese input, reset, checkbox, select, a package image and the custom
menu. Close and reopen a sidebar: its registered tool remains available. Hidden
views retain their own state within the host's five-minute/16-instance cache.
The view permission grants no host data. User-entered text is handled by the
plugin. Unsafe elements, external resources and escaping styles are rejected;
ordinary React support does not guarantee every third-party browser library.
See `docs/plugin-platform/host-rendered-ui.md` for the supported contract.
@@ -0,0 +1,5 @@
import { build } from 'esbuild';
import { fileURLToPath, URL } from 'node:url';
await build({ entryPoints: [fileURLToPath(new URL('./src/index.tsx', import.meta.url))], outfile: fileURLToPath(new URL('./dist/index.js', import.meta.url)), bundle: true, platform: 'browser', format: 'esm',
plugins: [{ name: 'host-sdk', setup(buildApi) { buildApi.onResolve({ filter: /^@netcatty\/plugin-sdk$/ }, (args) => ({ path: args.path, external: true })); } }],
define: { 'process.env.NODE_ENV': '"production"' }, minify: true });
@@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#258afa"/><path d="M9 23V9h4l6 9V9h4v14h-4l-6-9v9z" fill="#fff"/></svg>

After

Width:  |  Height:  |  Size: 197 B

@@ -0,0 +1,173 @@
{
"manifestVersion": 1,
"id": "com.netcatty.hello-react-host",
"name": "hello-react-host",
"displayName": {
"en": "Hello React",
"zh-CN": "你好,React"
},
"description": "Freely styled pages with standard, persistent Netcatty settings. No host data access.",
"version": "0.2.0",
"publisher": "netcatty",
"license": "MIT",
"engines": {
"netcatty": ">=0.0.0",
"api": ">=0.1.0-internal.1 <0.2.0"
},
"features": {
"required": [
"views.vault-pages",
"views.terminal-sidebar",
"views.host-drawn"
]
},
"main": {
"browser": "dist/index.js"
},
"activationEvents": [
"onView:com.netcatty.hello-react-host.vault",
"onView:com.netcatty.hello-react-host.sidebar",
"onView:com.netcatty.hello-react-host.tab",
"onView:com.netcatty.hello-react-host.aside",
"onView:com.netcatty.hello-react-host.panel",
"onView:com.netcatty.hello-react-host.modal"
],
"permissions": {
"required": [
"views",
"settings.read"
]
},
"contributes": {
"views": [
{
"id": "com.netcatty.hello-react-host.vault",
"title": {
"en": "Hello · Vault",
"zh-CN": "你好 · Vault 页面"
},
"location": "vault-page"
},
{
"id": "com.netcatty.hello-react-host.sidebar",
"title": {
"en": "Hello · Sidebar",
"zh-CN": "你好 · 终端侧栏"
},
"location": "terminal-sidebar"
},
{
"id": "com.netcatty.hello-react-host.tab",
"title": {
"en": "Hello · Tab",
"zh-CN": "你好 · 独立标签页"
},
"location": "tab"
},
{
"id": "com.netcatty.hello-react-host.aside",
"title": {
"en": "Hello · Aside",
"zh-CN": "你好 · 侧边面板"
},
"location": "aside"
},
{
"id": "com.netcatty.hello-react-host.panel",
"title": {
"en": "Hello · Panel",
"zh-CN": "你好 · 底部面板"
},
"location": "panel"
},
{
"id": "com.netcatty.hello-react-host.modal",
"title": {
"en": "Hello · Modal",
"zh-CN": "你好 · 弹窗"
},
"location": "modal"
}
],
"settings": [
{
"id": "com.netcatty.hello-react-host.name",
"label": {
"en": "Default name",
"zh-CN": "默认称呼"
},
"group": {
"en": "Greeting",
"zh-CN": "问候"
},
"description": {
"en": "Used when opening a new plugin page.",
"zh-CN": "用于新打开的插件页面。"
},
"control": "text",
"scope": "application",
"default": "",
"pattern": "^.{0,40}$"
},
{
"id": "com.netcatty.hello-react-host.enabled",
"label": {
"en": "Enable greeting",
"zh-CN": "启用问候"
},
"group": {
"en": "Greeting",
"zh-CN": "问候"
},
"control": "switch",
"scope": "application",
"default": true
},
{
"id": "com.netcatty.hello-react-host.color",
"label": {
"en": "Accent color",
"zh-CN": "强调颜色"
},
"group": {
"en": "Appearance",
"zh-CN": "外观"
},
"control": "select",
"scope": "application",
"default": "blue",
"options": [
{
"value": "blue",
"label": {
"en": "Blue",
"zh-CN": "蓝色"
}
},
{
"value": "green",
"label": {
"en": "Green",
"zh-CN": "绿色"
}
}
]
},
{
"id": "com.netcatty.hello-react-host.note",
"label": {
"en": "Default note",
"zh-CN": "默认便签"
},
"group": {
"en": "Content",
"zh-CN": "内容"
},
"control": "textarea",
"scope": "application",
"default": "",
"pattern": "^[\\s\\S]{0,500}$"
}
]
}
}
@@ -0,0 +1,8 @@
{
"name": "@netcatty/example-hello-react-host",
"version": "0.2.0",
"private": true,
"type": "module",
"scripts": { "build": "node build.mjs" },
"dependencies": { "@netcatty/plugin-sdk": "0.1.0-internal.1", "react": "^19.2.1", "react-dom": "^19.2.1" }
}
@@ -0,0 +1,67 @@
import React, { useEffect, useState } from 'react';
import { definePlugin, type PluginContext } from '@netcatty/plugin-sdk';
import { registerHostReactView, PluginPopover } from '@netcatty/plugin-sdk/host-react';
const css = `
.page { max-width: 760px; padding: 24px; margin: 0 auto; color: hsl(var(--foreground)); font: 14px/1.5 system-ui, sans-serif; }
.badge { color: hsl(var(--primary)); font-size: 11px; font-weight: 700; letter-spacing: .12em; }
h1 { font-size: 26px; margin: 8px 0; } p { color: hsl(var(--muted-foreground)); }
.card { display: grid; grid-template-columns: 1fr auto; gap: 12px; align-items: end; margin-top: 24px; padding: 20px; border: 1px solid hsl(var(--border)); border-radius: 12px; background: hsl(var(--muted)); }
textarea, select { padding: 9px; background: hsl(var(--background)); color: inherit; border: 1px solid hsl(var(--border)); border-radius: 6px; }
.check { display: flex; align-items: center; gap: 8px; } .check input { width: 16px; height: 16px; padding: 0; }
label { display: grid; gap: 8px; } input { padding: 9px; border: 1px solid hsl(var(--border)); border-radius: 6px; background: hsl(var(--background)); color: inherit; }
button { border: 0; border-radius: 6px; padding: 10px 16px; background: hsl(var(--primary)); color: hsl(var(--primary-foreground)); cursor: pointer; }
button:hover { opacity: .85; } button:disabled { opacity: .45; cursor: default; }
.page[data-color="green"] { --plugin-accent: 145 65% 36%; }
.page[data-color="green"] button { background: hsl(var(--plugin-accent)); } .result { grid-column: 1 / -1; margin: 0; }
@container (max-width: 420px) { .card { grid-template-columns: 1fr; } }
`;
function Hello({ settings }: { settings: PluginContext['settings'] }) {
const [name, setName] = useState(''); const [greeting, setGreeting] = useState('');
const [enabled, setEnabled] = useState(true); const [color, setColor] = useState('blue'); const [note, setNote] = useState(''); const [menu, setMenu] = useState(false);
const [settingsError, setSettingsError] = useState('');
const [settingsReady, setSettingsReady] = useState(false);
useEffect(() => {
let disposed = false;
const revisions = new Map<string, number>();
const apply = async (key: string) => {
const revision = (revisions.get(key) ?? 0) + 1;
revisions.set(key, revision);
try {
const value = await settings.get(`com.netcatty.hello-react-host.${key}`);
if (disposed || revisions.get(key) !== revision) return;
if (key === 'name') setName(typeof value === 'string' ? value : '');
if (key === 'enabled') setEnabled(value !== false);
if (key === 'color') setColor(value === 'green' ? 'green' : 'blue');
if (key === 'note') setNote(typeof value === 'string' ? value : '');
} catch {
if (!disposed) setSettingsError('无法读取插件设置,请检查该插件的设置读取权限。');
}
};
const subscription = settings.onDidChange(({ settingId }) => {
const key = settingId.slice('com.netcatty.hello-react-host.'.length);
if (['name', 'enabled', 'color', 'note'].includes(key)) void apply(key);
});
void Promise.all(['name', 'enabled', 'color', 'note'].map(apply)).then(() => {
if (!disposed) setSettingsReady(true);
});
return () => { disposed = true; subscription.dispose(); };
}, [settings]);
if (!settingsReady) return <main className="page"><p role="status">正在读取插件设置…</p></main>;
return <main className="page" data-color={color}><img src="asset:mark.svg" alt="Example mark" width="32" height="32" /><span className="badge">NETCATTY · HELLO</span><h1>你好,世界!</h1><p>一个融入 Netcatty 的小工作台。试试问候、便签和菜单。</p>
{settingsError && <p role="alert">{settingsError}</p>}
<div className="card"><label>你的称呼<input type="text" value={name} onChange={(event) => setName(event.currentTarget.value)} placeholder="输入称呼" /></label>
<button type="button" disabled={!enabled} onClick={() => setGreeting(`你好,${name || '朋友'}!`)}>打个招呼</button><p className="result">{greeting}</p></div>
<div className="card"><label className="check"><input aria-label="Enable greeting" type="checkbox" checked={enabled} onChange={(event) => setEnabled(event.currentTarget.checked)} />启用问候</label>
<label>颜色<select aria-label="Color" value={color} onChange={(event) => setColor(event.currentTarget.value)}><option value="blue">蓝色</option><option value="green">绿色</option></select></label>
<label>便签<textarea aria-label="Note" value={note} onChange={(event) => setNote(event.currentTarget.value)} placeholder="试试中文输入" /></label>
<button type="button" onClick={() => { setName('朋友'); setEnabled(true); setColor('green'); setNote('你好,Netcatty'); }}>填入示例</button>
<p className="result" data-testid="controls">{enabled ? '已启用' : '已停用'} · {color} · {note}</p>
<button id="menu-trigger" type="button" onClick={() => setMenu((value) => !value)}>自定义菜单</button><PluginPopover anchor="menu-trigger" open={menu} onClose={() => setMenu(false)}><section style={{ padding: 16 }}><h2>插件自定义内容</h2><p>选择一个操作,或按 Esc 返回。</p><button type="button" onClick={() => { setGreeting('你好,来自菜单的问候!'); setMenu(false); }}>从菜单打招呼</button></section></PluginPopover>
</div></main>;
}
export default definePlugin({ activate(context) {
for (const id of ['vault', 'sidebar', 'tab', 'aside', 'panel', 'modal']) {
context.subscriptions.add(registerHostReactView(context.views, `com.netcatty.hello-react-host.${id}`, () => <Hello settings={context.settings} />, css));
}
} });