工具函数 API

@shangchien/molio/utils 提供浏览器优先的分子解析、校验、序列化和渲染函数。

import {
  validateSmiles,
  smilesToRdkitJson,
  smilesToSvg,
  smilesToPngBlob,
} from '@shangchien/molio/utils'

Result 模型

所有异步工具函数都返回统一结果：

type MoleculeUtilityResult<T> =
  | { ok: true, data: T, warnings?: string[] }
  | { ok: false, error: MoleculeUtilityError, warnings?: string[] }

错误码包括：

code	含义
`EMPTY_INPUT`	输入为空。
`RDKIT_INIT_FAILED`	RDKit wasm 初始化失败。
`PARSE_ERROR`	输入格式无法解析。
`VALIDATION_ERROR`	RDKit 认为分子无效。
`SERIALIZE_ERROR`	序列化失败。
`RENDER_ERROR`	SVG/PNG 渲染失败。
`ENV_NOT_SUPPORTED`	当前环境不支持 PNG 栅格化。

RDKit runtime

API	用法
`configureRDKit(options)`	全局配置 RDKit wasm URL 或 locateFile。
`configureMoleculeUtilities(options)`	工具 facade 的别名配置入口。
`initRDKit(options?)`	主动初始化 RDKit。
`setRDKit(instance)`	测试或高级宿主注入 RDKit 实例。

configureRDKit({ wasmUrl: '/assets/RDKit_minimal.wasm' })
await initRDKit()

校验与解析

API	返回	用法
`validateSmiles(smiles, rdkitOptions?)`	`MoleculeUtilityResult<{ valid: boolean }>`	校验 SMILES。
`validateMolBlock(molBlock, rdkitOptions?)`	`MoleculeUtilityResult<{ valid: boolean }>`	校验 MOL block。
`smilesToRdkitJson(smiles, rdkitOptions?)`	`MoleculeUtilityResult<RDKitJSON>`	SMILES 转 RDKitJSON。
`molBlockToRdkitJson(molBlock, rdkitOptions?)`	`MoleculeUtilityResult<RDKitJSON>`	MOL block 转 RDKitJSON。
`molOrSdfToRdkitJsons(content, rdkitOptions?)`	`MoleculeUtilityResult<RDKitJSON[]>`	MOL/SDF 文本转分子列表。

const parsed = await smilesToRdkitJson('CCO')
if (parsed.ok)
  editorRef.value?.importMolecules([parsed.data])
else
  console.warn(parsed.error.message)

序列化

API	返回	用法
`rdkitJsonToSmiles(rdkitJson, rdkitOptions?)`	`MoleculeUtilityResult<string>`	RDKitJSON 转 SMILES。
`rdkitJsonToMolBlock(rdkitJson, rdkitOptions?)`	`MoleculeUtilityResult<string>`	RDKitJSON 转 MOL block。
`serializeToSmiles(entries)`	`string`	批量分子条目序列化为 SMILES。
`serializeToSdf(entries)`	`string`	批量分子条目序列化为 SDF。

SVG 渲染

API	返回	用法
`rdkitJsonToSvg(rdkitJson, options?)`	`MoleculeUtilityResult<string>`	RDKitJSON 转 SVG 字符串。
`smilesToSvg(smiles, options?)`	`Promise<MoleculeUtilityResult<string>>`	SMILES 转 SVG。
`molBlockToSvg(molBlock, options?)`	`Promise<MoleculeUtilityResult<string>>`	MOL block 转 SVG。

const svg = await smilesToSvg('CCO', {
  padding: 24,
  optimize: { multipass: true },
})
if (svg.ok)
  previewSvg.value = svg.data

PNG 渲染

API	返回	用法
`rdkitJsonToPngBlob(rdkitJson, options?)`	`Promise<MoleculeUtilityResult<Blob>>`	RDKitJSON 转 PNG Blob。
`smilesToPngBlob(smiles, options?)`	`Promise<MoleculeUtilityResult<Blob>>`	SMILES 转 PNG Blob。
`molBlockToPngBlob(molBlock, options?)`	`Promise<MoleculeUtilityResult<Blob>>`	MOL block 转 PNG Blob。

PNG 生成依赖浏览器栅格化能力。Node/SSR 环境通常会返回 ENV_NOT_SUPPORTED。

const png = await smilesToPngBlob('CCO', { scale: 2, colors: 128 })
if (png.ok)
  uploadBlob(png.data)

渲染 options

字段	说明
`id`	分子导出 ID。
`padding`	SVG/PNG 周围留白。
`worldTransform`	分子世界变换；用于与画布布局保持一致。
`optimize`	SVG 优化选项。
`scale`	PNG 缩放倍率。
`colors`	PNG 调色板压缩颜色数。
`rdkit`	仅 `smilesToSvg`、`molBlockToSvg`、`smilesToPngBlob`、`molBlockToPngBlob` 支持，用于传入 RDKit 初始化选项。

工具函数 API ​

Result 模型 ​

RDKit runtime ​

校验与解析 ​

序列化 ​

SVG 渲染 ​

PNG 渲染 ​

渲染 options ​

工具函数 API

Result 模型

RDKit runtime

校验与解析

序列化

SVG 渲染

PNG 渲染

渲染 options