Ref 方法 API

父组件通过 ref 调用 MolEditor 暴露的方法和状态。

const editorRef = ref<InstanceType<typeof MolEditor> | null>(null)

editorRef.value?.undo()
editorRef.value?.setScale(1.25)

命令总线

API	签名	用法
`executeCommand`	`(id: string, args?: unknown) => Promise<boolean> \| boolean`	执行内置或插件注册的命令。
`registerCommand`	`(id: string, handler: EditorCommandHandler) => () => void`	注册宿主命令，返回 unregister。
`hasCommand`	`(id: string) => boolean`	检查命令是否存在。

import { EDITOR_COMMANDS } from '@shangchien/molio'

await editorRef.value?.executeCommand(EDITOR_COMMANDS.selectionCopySvg)
const unregister = editorRef.value?.registerCommand('host:save', async () => saveDraft())
unregister?.()

历史与文档

API	用法
`undo()` / `redo()`	执行历史栈撤销和重做。
`reset()`	清空当前文档。
`getDocumentSnapshot()`	返回当前 normalized 文档快照。
`restoreDocumentSnapshot(snapshot)`	恢复文档快照，并按加载视口策略处理。
`importMolecules(rdkitJsons)`	追加导入一组分子。
`reload(rdkitJsons?)`	用新的分子列表重载画布；不传则清空。
`getStoreEntries()`	获取当前分子 store 条目，适合宿主调试或导出前查询。

const snapshot = editorRef.value?.getDocumentSnapshot()
if (snapshot)
  localStorage.setItem('molio:draft', JSON.stringify(snapshot))

分子编辑 primitives

这些方法面向需要程序化编辑分子的高级宿主。常规业务优先通过工具、命令或 workflow 完成。

API	用法
`addMolecule(rdkitJson)`	添加分子，返回分子 ID。
`removeMolecule(moleculeId)`	删除分子。
`placeMoleculeAt(moleculeId, point)`	移动分子的世界坐标位置。
`addAtomToMolecule(moleculeId, params)`	添加原子。
`updateAtomInMolecule(moleculeId, atomIndex, params)`	更新原子元素、电荷等属性。
`removeAtomFromMolecule(moleculeId, atomIndex)`	删除原子。
`addBondToMolecule(moleculeId, params)`	添加键。
`updateBondInMolecule(moleculeId, bondIndex, params)`	更新键级或键样式。
`removeBondFromMolecule(moleculeId, bondIndex)`	删除键。
`getAtomNeighbors(moleculeId, atomIndex)`	查询邻接原子。
`getAtomBonds(moleculeId, atomIndex)`	查询原子相关键。

选区与剪贴板

API	用法
`selectAll()`	选中所有可选对象。
`clearSelection()`	清空选区。
`deleteSelected()`	删除当前选区。
`getSelectedMols()`	返回选中的分子数据。
`getSelectionContext()`	返回统一 selection context，覆盖 molecule/text/image/connector。
`copy()` / `paste()` / `pasteAt(point)`	复用编辑器剪贴板能力。
`hasSelection`	只读状态 ref，指示当前是否有选区。
`selectedAtoms` / `selectedBonds`	当前选中的分子原子/键集合。
`selectionBounds`	当前选区 bounds。

视口、尺寸与全屏

API	用法
`resize(width, height)`	改变非全屏画布尺寸。
`setViewport({ x, y, scale })`	设置视口 patch，未传字段保持当前值。
`setScale(scale, anchor?)`	以可选屏幕锚点设置缩放。
`zoomIn()` / `zoomOut()`	使用 `interaction.zoomInFactor` / `zoomOutFactor` 缩放。
`zoomBy(factor, anchor?)`	按比例缩放。
`applyZoom(scale, anchor?)`	设置绝对缩放值。
`autofit()`	自动居中并适配当前内容。
`setFullscreen(value)`	设置窗口全屏状态。
`toggleFullscreen()`	切换全屏状态。
`isFullscreen`	当前全屏状态 ref。
`viewport`	当前 `{ x, y, scale }` ref。

网格和工具

API	用法
`setGridVisible(visible)`	显示或隐藏背景网格。
`setGridSpacing(spacing)`	修改网格间距。
`setTool(tool)`	设置完整工具对象。
`setAtomTool(atomicNumber, symbol)`	快速切到原子工具。
`setBondTool(bondOrder, wedge?, label?)`	快速切到键工具。
`setTemplateTool(template)`	设置模板工具。
`resetTool()`	回到默认工具。
`activeTool`	当前工具 ref。
`mode`	当前底层交互模式。

导出、保存与分享

API	返回值	用法
`exportStagePng(filename?)`	`void`	下载当前画布 PNG。
`exportStageSvg(filename?)`	`void`	下载当前画布 SVG。
`exportMoleculePng(moleculeId, filename?)`	`void`	下载单个分子 PNG。
`exportMoleculeSvg(moleculeId, filename?)`	`void`	下载单个分子 SVG。
`saveDocumentWithWorkflow()`	`Promise<Blob \| null>`	通过 persistence workflow 保存 `.mpz`。
`loadDocumentWithWorkflow(file)`	`Promise<DocumentSnapshot \| null>`	通过 persistence workflow 读取文件。
`shareDocumentWithWorkflow(nodeIds?)`	`Promise<{ url?: string, blob?: Blob } \| null>`	通过 share workflow 生成分享结果。
`runWorkflowLayout(nodeIds?)`	`Promise<boolean>`	执行 layout workflow。

显式氢

API	用法
`toggleExplicitHydrogens(addHydrogens)`	`true` 添加显式氢，`false` 移除显式氢。
`addExplicitHydrogens()`	添加显式氢。
`removeExplicitHydrogens()`	移除显式氢。

有选区时只作用于选中的分子；没有选区时作用于当前文档内全部分子。

事件订阅

API	用法
`onMoleculeChange(handler)`	订阅分子变化。
`onDocumentChange(handler)`	订阅文档变化。
`onSelectionChange(handler)`	订阅选区变化。

这些方法适合非 Vue 事件场景，例如外部服务或嵌入式宿主需要运行时订阅。

Ref 方法 API ​

命令总线 ​

历史与文档 ​

分子编辑 primitives ​

选区与剪贴板 ​

视口、尺寸与全屏 ​

网格和工具 ​

导出、保存与分享 ​

显式氢 ​

事件订阅 ​

Ref 方法 API

命令总线

历史与文档

分子编辑 primitives

选区与剪贴板

视口、尺寸与全屏

网格和工具

导出、保存与分享

显式氢

事件订阅