Qiufeng
84e9e7bff5
GitHub Pages / build (push) Canceled after 0s
GitHub Pages / deploy (push) Canceled after 0s
Docker image / meta (push) Successful in 24s
Docs Docker image / meta (push) Successful in 7s
Docker image / build (amd64, linux/amd64, ubuntu-latest) (push) Failing after 59s
Docs Docker image / build (amd64, linux/amd64, ubuntu-latest) (push) Failing after 30s
Docker image / merge (push) Canceled after 0s
Docs Docker image / merge (push) Canceled after 0s
Docker image / build (arm64, linux/arm64, ubuntu-24.04-arm) (push) Canceled after 0s
Docs Docker image / build (arm64, linux/arm64, ubuntu-24.04-arm) (push) Canceled after 0s
78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# @miragenflow/plugin-sdk
|
|
|
|
MiragenFlow 画布节点内部扩展的 **TypeScript SDK**。扩展作者只写节点 UI 与逻辑,类型、JSX、运行时桥接和构建由 SDK 提供。当前产品不提供远程加载或安装入口,扩展需要随应用源码集成。
|
|
|
|
## 提供什么
|
|
|
|
| 能力 | 说明 |
|
|
| --- | --- |
|
|
| **完整类型** | `CanvasPlugin` / `CanvasNodeDefinition` / `CanvasNodeContext` / `CanvasOp` / `CanvasTheme` / `CanvasNodeData` … 全部有提示 |
|
|
| `definePlugin(...)` | 给插件对象(或工厂)补全类型;对象形式无需再 `const { React } = runtime` |
|
|
| automatic JSX | `jsxImportSource` 指向本包,TSX 自动转发到宿主 React,**不打包第二份 React** |
|
|
| 类型化 hooks | `import { useState, useEffect, useMemo, useRef, ... }`,运行时转发宿主 React |
|
|
| `buildPlugin(...)` | 统一 esbuild 构建,插件 `build.mjs` 只需一行 |
|
|
|
|
## 最小插件
|
|
|
|
```tsx
|
|
// src/index.tsx
|
|
import { definePlugin, useState } from "@miragenflow/plugin-sdk";
|
|
import type { CanvasNodeContentProps } from "@miragenflow/plugin-sdk";
|
|
|
|
function Content({ ctx }: CanvasNodeContentProps) {
|
|
const [n, setN] = useState(0);
|
|
return (
|
|
<button onMouseDown={(e) => e.stopPropagation()} onClick={() => setN((v) => v + 1)} style={{ color: ctx.theme.node.text }}>
|
|
{ctx.node.title}: {n}
|
|
</button>
|
|
);
|
|
}
|
|
|
|
export default definePlugin({
|
|
id: "my-plugin",
|
|
name: "我的插件",
|
|
version: "1.0.0",
|
|
nodes: [
|
|
{
|
|
type: "my-plugin:node",
|
|
title: "示例",
|
|
icon: "✨",
|
|
defaultSize: { width: 240, height: 160 },
|
|
Content,
|
|
},
|
|
],
|
|
});
|
|
```
|
|
|
|
```js
|
|
// build.mjs
|
|
import { buildPlugin } from "@miragenflow/plugin-sdk/build";
|
|
await buildPlugin(import.meta.url);
|
|
```
|
|
|
|
`npm run build` 只产出 `dist/<目录名>.js`,不会写入应用公共目录或远程清单。
|
|
|
|
## 依赖接入
|
|
|
|
插件 `package.json`:
|
|
|
|
```json
|
|
{
|
|
"type": "module",
|
|
"scripts": { "build": "node build.mjs", "dev": "node build.mjs --watch", "typecheck": "tsc --noEmit" },
|
|
"devDependencies": {
|
|
"@miragenflow/plugin-sdk": "file:../sdk",
|
|
"@types/react": "19.1.12",
|
|
"typescript": "^5"
|
|
}
|
|
}
|
|
```
|
|
|
|
插件 `tsconfig.json` 关键项:`"jsx": "react-jsx"`、`"jsxImportSource": "@miragenflow/plugin-sdk"`、`"moduleResolution": "bundler"`。
|
|
|
|
## 设计约束
|
|
|
|
- **React 单例**:JSX 与 hooks 惰性读取 `globalThis.MiragenFlowRuntime.React`(由源码集成层注入),react 全程 external,绝不打包第二份。
|
|
- **重依赖**:three、marked 等在源码里 `await import("https://esm.sh/...")` 动态加载,esbuild 自动 external,不进 bundle。
|
|
- **类型真源**:`src/types.ts` 是宿主 `web/src/types/canvas-plugin.ts` 公开契约的镜像;宿主契约变更时同步此处。
|