HTML 生命周期、样式与迁移

宿主尺寸

relation-graph 使用宿主的实际尺寸。宿主没有高度时，图谱也没有可见高度：

html, body {height: 100%; margin: 0;}
#graph {width: 100%; height: 100%; min-height: 360px;}

宿主尺寸变化由 ResizeObserver 处理。隐藏标签页、折叠面板或弹窗首次显示后，如果布局系统没有触发 ResizeObserver，可调用 graph.refresh()、moveToCenter() 或 zoomToFit()。

多实例

const leftGraph = await createRelationGraph('#left-graph', leftConfig);
const rightGraph = await createRelationGraph('#right-graph', rightConfig);

每个实例拥有独立 DOM、事件、状态和插件。不要把一个实例的节点对象传给另一个实例；跨图复制时使用 JSON 数据。

销毁

const stop = graph.subscribe('selection', updateBusinessPanel);
const unregisterPort = registerConnectTarget(graph, port, portOptions);

function unmount() {
  stop();
  unregisterPort();
  graph.destroy();
}

插件和官方 helper 会被实例销毁流程统一处理，但业务代码自己创建的全局监听、计时器、网络请求仍应自行释放。

样式

HTML 平台使用普通 DOM，业务样式可以直接覆盖：

#graph .relation-graph {
  --rg-node-color: #ffffff;
  --rg-node-border-color: #64748b;
  --rg-line-color: #94a3b8;
  --rg-toolbar-hover-bg-color: rgba(15, 23, 42, 0.08);
}

#graph .rg-node-peel[data-id="critical"] > .rg-node {
  border-color: #dc2626;
}

优先使用节点/连线数据、renderer class 和 CSS Variables；不要依赖没有公开承诺的深层 DOM 顺序。

从旧项目迁移

旧包、Shadow Root 主组件和多个自定义子元素已经停止提供。迁移步骤：

卸载旧包，安装 @relation-graph/html@3.1.2。
删除自动注册的旧脚本和所有 rg-* 子组件标签。
用普通容器和 createRelationGraph() 创建实例。
将 options 和数据放入 config.options、config.data。
将 onReady 获取实例改为等待工厂 Promise。
将事件监听改为 config.events；外围只读观察可用 rg:* DOM 事件。
将节点、线和展开按钮插槽改成 renderers。
将 background/canvas/view 插槽改成 layers。
将工具栏、MiniView、编辑器改成 ui 或官方插件。
将连接目标改成 registerConnectTarget()。

旧能力	HTML 对应能力
主标签	`createRelationGraph(host, config)`；可选单一 light-DOM 标签
`onReady` detail	`await createRelationGraph()`
节点/连线插槽	`renderers.node`、`renderers.line`、`renderers.lineLabel`
展开按钮插槽	`renderers.nodeExpandButton`
background/canvas/view 插槽	`layers`
工具栏与 MiniView 子组件	`ui.toolbar`、`ui.miniView`
编辑子组件	`ui.editing`
连接目标子组件	`registerConnectTarget()`
store-change 事件	`subscribe(domain, listener)`

旧示例 URL 会重定向到 /examples/<id>/html，但应用代码应尽快改用 html 平台名。旧 npm 包不会获得新版本或安全修复。

排错

空白画面：检查宿主高度和 style.css。
404 或 CORS：固定使用发行文件 URL，并通过 HTTP 服务器打开页面。
自定义 HTML 被显示为文本：返回 DOM Node，或仅对可信静态内容使用 trustedHTML()。
工具栏/MiniView 不显示：同时检查 ui 是否安装、核心 show* 是否开启。
重复挂载错误：先销毁旧实例。

返回：HTML Startup。