web-doc-editor

基于原生 TypeScript / JavaScript 与 DOM 的文档模板编辑器 SDK：挂载 HTML 模板、填空、签名/印章、浮动图层与分页视图，支持草稿持久化、缩放与打印/导出流程。详细设计说明见仓库内 WebDocEditorSDK.md。

安装

npm install web-doc-editor
# 或
pnpm add web-doc-editor

快速开始

import { WebDocEditor, type DocumentTemplate } from 'web-doc-editor';

const container = document.getElementById('editor-container');
if (!container) throw new Error('缺少挂载容器');

const template: DocumentTemplate = {
  id: 'tpl_001',
  version: '1.0',
  meta: { author: 'Admin' },
  content: `
    <div>
      <h1>商业合同</h1>
      <p>甲方：{_{party_a}}</p>
      <p>乙方：{_{party_b}}</p>
      <div style="margin-top: 50px;">
        <p>甲方签字：{_{sign:party_a_sign}}</p>
      </div>
    </div>
  `,
};

const sdk = new WebDocEditor({
  container,
  template,
  draftKey: 'contract-draft-001', // 相同 draftKey 可恢复未完成草稿
});

说明：产品文档中常写作「WebDocEditorSDK」；从本包导入的主类名为 WebDocEditor。

初始化参数（Config）

| 参数名 | 类型 | 必填 | 说明 | | ------ | ---- | ---- | ---- | | container | HTMLElement | 是 | 挂载父节点；内部会生成带命名空间隔离的样式与结构。 | | template | DocumentTemplate | 是 | 模板对象，见下表。 | | namespace | string | 否 | 附加在根包装器上的 CSS 类名，便于与宿主样式隔离。 | | draftKey | string | 否 | localStorage 草稿键；相同键名会恢复字段与浮动元素。默认 wd-sdk-draft。 | | showToolbar | boolean | 否 | 是否显示内置顶部工具栏；false 时用下方 API 自建 UI。默认 true。 |

DocumentTemplate

| 参数名 | 类型 | 必填 | 说明 | | ------ | ---- | ---- | ---- | | id | string | 是 | 模板唯一标识。 | | version | string | 是 | 模板版本号。 | | meta | Record<string, any> | 是 | 业务扩展元信息。 | | content | string | 是 | HTML 字符串，内嵌占位符规则见 WebDocEditorSDK.md「模板占位符规则」。 |

实例 API

适合在 showToolbar: false 时深度集成：

• sdk.addSignature(onComplete?: (dataUrl: string) => void) — 打开签名面板，完成后加入画布或走回调。
• sdk.addImage(file?: File) — 无参则打开文件选择；传入 File 直接贴图。
• sdk.deleteActiveElement() — 删除当前选中的浮动元素。
• sdk.setZoom(zoom: number \| 'fit') — 缩放；'fit' 按容器宽度适配。
• sdk.setMode(mode: 'edit' \| 'preview' \| 'print-preview') — 编辑 / 预览 / 打印预览。
• sdk.print() — 校验必填项后触发打印流程。
• sdk.getFieldsData() — 当前字段键值对（含占位与签名等）。
• sdk.clearDraft() — 清除当前 draftKey 相关草稿。
• sdk.onFieldClick(handler) — 处理 {_{click:xxx}} 占位；在回调里通过 updateValue(val) 回填。

占位符规则（摘要）

完整语法与示例见 WebDocEditorSDK.md。

• 单行文本：{_{field}} 或 {_{align:left|center|right:field}}
• 固定宽度与字数：{_{fixed:120px:10:right:company_reg_number}}
• 自动换行长文本：{_{wrap:[align:]field}}
• 仅点击、外部填值：{_{click:field}} + onFieldClick
• 签名热区：{_{sign:field}} 或字段名含 signature 的 {_{signature_field}}

本仓库开发

环境： Node.js（建议 18+）

pnpm install
pnpm run dev          # 示例应用，默认端口见 package.json scripts
pnpm run build:lib    # 构建 lib，发布前执行

构建产物入口：lib/web-doc-editor.es.js（ESM）、lib/web-doc-editor.umd.js（UMD），类型定义见 lib/index.d.ts。