MolEditor 组件 API

MolEditor 是 package 根入口导出的 Vue 3 组件。

import { MolEditor, type EditorOptions } from '@shangchien/molio'

Props

Prop	类型	默认值	用法
mols	RDKitJSON[]	[]	非受控初始化分子列表。适合从 SMILES/SDF 解析后直接加载。
options	EditorOptions	{ width: 400, height: 300 }	控制尺寸、只读、网格、交互、视口和默认工具。
fullscreen	boolean	undefined	受控全屏状态，配合 v-model:fullscreen。
defaultFullscreen	boolean	false	非受控全屏初始值。
documentSnapshot	DocumentSnapshot | null	null	受控文档快照，配合 v-model:document-snapshot。
plugins	AnyPlugin[]	默认 builtin	覆盖 builtin plugin 层；高级宿主才需要。
optionalPlugins	AnyPlugin[]	[]	推荐的宿主扩展入口，追加 object/ui/workflow 插件。
uiComponents	Record<string, Component>	{}	解析 leftDock.panelComponent 与 slots.component。
uploadService	UploadService	undefined	便捷上传服务入口；完整场景推荐使用 WorkflowServicePlugin.upload。

Events

Event	Payload	触发时机
update:documentSnapshot	DocumentSnapshot	文档变化后 emit，用于 v-model:document-snapshot。
document-change	{ affectedMoleculeIds: string[], label?: string, source?: 'molecule' | 'document' | 'load' }	分子、文本、图片、连接线或加载动作改变文档时触发。
update:fullscreen	boolean	全屏状态变化，用于 v-model:fullscreen。
fullscreen-change	boolean	全屏状态变化通知。
select	{ atomIndices: number[], bondIndices: number[], moleculeId: string }	分子级选区变化兼容事件。
update	{ moleculeId: string, rdkitJson: RDKitJSON }	分子更新兼容事件。
action	{ key: string, value?: unknown }	shell 内部动作透传，宿主通常不需要依赖。

EditorOptions

const options: EditorOptions = {
  width: 960,
  height: 640,
  readonly: false,
  defaultTool: PRESET_TOOLS.select,
  grid: { show: true, spacing: 40 },
  viewport: {
    initial: { x: 0, y: 0, scale: 1 },
    autoFitOnInit: false,
    autoFitOnLoad: true,
  },
  interaction: {
    zoomMin: 0.05,
    zoomMax: 20,
    zoomInFactor: 1.15,
    zoomOutFactor: 0.87,
  },
}

常用字段

字段	说明
width / height	非全屏画布尺寸，单位 px。
readonly	只读模式会限制编辑类交互。
defaultTool	初始化工具，通常使用 PRESET_TOOLS.select。
grid.show / grid.spacing	控制背景网格显示和间距。
viewport.initial	初始化视口 patch，可只传 x、y 或 scale。
viewport.autoFitOnInit	初始化后是否自动适配画布。
viewport.autoFitOnLoad	重新加载文档或分子后是否自动适配画布。
interaction.zoomMin / zoomMax	视口缩放边界。
interaction.zoomInFactor / zoomOutFactor	toolbar 缩放步长。

受控模式

<MolEditor
  v-model:document-snapshot="snapshot"
  v-model:fullscreen="fullscreen"
  :options="options"
/>

受控快照适合保存草稿、生成分享链接、接入表单或在父组件中实现保存按钮。全屏受控适合把编辑器嵌入 modal、布局面板或产品工作台。

插件入口

普通宿主优先使用 optionalPlugins：

<MolEditor
  :optional-plugins="[hostUiPlugin, hostWorkflowPlugin]"
  :ui-components="uiComponents"
/>

只有当宿主想完全替换默认 builtin 层时，才使用 plugins 覆盖。