原生 JavaScript 集成

@tinyflow-ai/ui 是最直接、能力最完整的浏览器接入方式。React、Vue 和 Svelte 包内部也都创建这个 Tinyflow 类。

安装与挂载

npm install @tinyflow-ai/ui

import { Tinyflow } from '@tinyflow-ai/ui';
import '@tinyflow-ai/ui/dist/index.css';

const editor = new Tinyflow({
  element: '#editor',
  data: { nodes: [], edges: [] },
  defaultTheme: 'system',
  provider: {
    llm: async () => [{ value: 'main', label: '主模型' }],
    knowledge: async () => [],
    searchEngine: async () => []
  },
  hiddenNodes: ['codeNode'],
  onDataChange(data) {
    markDraftDirty(data);
  }
});

#editor { width: 100%; height: 640px; }

element 可以是 CSS selector 或 Element。selector 找不到元素、传入类型错误，构造函数会抛错。

数据操作

const snapshot = editor.getData();
editor.setData(await loadDefinition('flow-1'));
editor.setTheme('dark');
editor.destroy();

getData() 返回 XYFlow 的 nodes、edges、viewport。setData() 和 setTheme() 当前都会销毁并重建内部自定义元素；调用期间不要依赖旧 DOM 引用或旧 flow instance。

Provider

Provider 为编辑器的选择控件提供 { value, label } 列表。value 应是稳定的逻辑 ID，不能把 API key 放进 label、value 或工作流 JSON。

provider: {
  llm: () => fetch('/api/editor-options/llms').then(r => r.json()),
  knowledge: () => fetch('/api/editor-options/knowledge').then(r => r.json()),
  searchEngine: () => fetch('/api/editor-options/search-engines').then(r => r.json())
}

生命周期注意事项

• 该包依赖 DOM，SSR 时只在客户端 mount 后创建。
• 路由卸载或页面销毁时调用 destroy()。
• 组件使用 shadow: 'none'，宿主全局 CSS 可能影响内部控件。
• 当前核心 store 是模块级状态；同页多个编辑器实例可能共享或覆盖状态，正式支持前不要在一个页面并行挂载多个实例。
• onDataChange 可能频繁调用，远程自动保存应 debounce。

完整配置见配置项与 API，数据行为见数据与生命周期。