@aeriz/wysiwygDOCS
为韩文文档打造的所见即所得编辑器。支持合并单元格表格、清理来自 Word、HWP、Excel 的粘贴内容、pt 字号与韩文字体、查找替换和打印,并在 React、Vue、Svelte、Angular、jQuery 和 Web Components 中使用同一套选项。
v2.0.1 · 核心 80 KB(gzip)· 代码高亮器另计 4 KB · 零依赖
简介
@aeriz/wysiwyg 是一款为韩文文档打造的所见即所得(WYSIWYG)编辑器。只需传入一个元素,工具栏、表格、粘贴清理和撤销就能直接使用。
- 像文字处理软件一样的表格 即使有合并单元格,插入、删除、合并、拆分之后列依然对齐。
- 干净的粘贴 保留 Word、HWP(韩文)、Excel 的格式,去掉
mso-*、class 和注释。
- 韩文文档格式 以 pt 为单位的字号,맑은 고딕、바탕 等系统字体,百分比行距、字间距、查找替换、打印。
- 安全且快速 粘贴、
setHTML、查看器和服务端使用同一套净化规则。65 页文档每次按键约 18 ms。
- 一种用法 原生 JS、React、Vue、Svelte、Angular、jQuery 和 Web Components 使用相同的选项。
- 不加载 Web 字体 运行时不下载任何字体,只连接你需要的字体。
示例
以下示例还原了编辑器嵌入真实产品时的样子。它们都在本页实时运行,JS、HTML、CSS 标签页中就是每个示例的全部代码。同一个编辑器只需修改选项,就能变成论坛发帖、办公文档或评论框。
块展示
@aeriz/wysiwyg · JS 79 行
把编辑器支持的 16 种块放在同一个文档里。点击左侧列表即可跳到对应的块,下方会显示该块保存后的 HTML 和 Markdown。切换到查看器,只用保存的 JSON 就能绘制出相同的页面;切换到深色可查看深色主题。
深色模式上线.doc一个文档包含 16 种块
深色模式上线
设计、开发和测试共用的文档,目标是 11 月 24 日正式发布。一个段落里可以混用斜体、下划线、删除线、文字颜色、高亮、CO2、1st 和链接。
示意图 v3 · 左为浅色,右为深色。图片说明也是块的一部分。
1. 日程
| 阶段 | 负责 | 时间 | 状态 |
| 颜色变量 | 设计 | 11/3 – 11/7 | 已完成 |
| 应用到界面 | Web | 11/10 – 11/19 | 进行中 80% |
| App | 进行中 55% |
| 测试 · 无障碍 | QA | 11/20 – 11/21 | 计划中 |
2. 待办
- 定义背景、表面和文字的 12 个变量
- 跟随系统设置(
prefers-color-scheme)
- 记住用户选择的主题
- 修复图表和图片的白色背景
设计原则
- 用深海军蓝代替纯黑(
#000)。
- 层级越高的表面越亮。
- 强调色降低一档饱和度。
发布步骤
- 内部测试(11/20)
- 向 10% 的用户灰度发布
- 全量发布(11/24)
3. 实现
:root { --bg: #ffffff; --text: #111827; }
@media (prefers-color-scheme: dark) {
:root { --bg: #0b1020; --text: #e5e7eb; }
}
body { background: var(--bg); color: var(--text); }
以前晚上一打开应用就得眯着眼,用了测试版之后再也不会了。
— 测试用户
跟随系统,还是在应用里选择?
都可以。默认跟随系统,用户在应用中选择主题后会记住该选择。
真的能省电吗?(折叠的折叠块)
4. 参考资料
prefers-color-scheme: Hello darkness, my old friend如何在网页上支持深色模式,包括让用户自行选择的切换开关
在空行输入 #、-、1.、[ ] 或 > 再加一个空格,或者输入 ```、---,块会立即转换。
论坛发帖
@aeriz/wysiwyg · JS 25 行
填写分类、标题和正文后点击发布,AerizViewer 会绘制出帖子页面。工具栏只保留了这个表单需要的按钮。
aeriz 社区 › 登山 › 发新帖
trail_dev · 刚刚 · 浏览 1
上周六从牛耳站出发,一路登上了白云台。天气晴朗,在山顶能看到整个首尔。

路线与用时
| 路段 | 距离 | 用时 |
| 牛耳站 → 哈鲁岭 | 2.1 km | 50 分钟 |
| 哈鲁岭 → 白云台 | 1.6 km | 1 小时 10 分钟 |
| 合计(上山) | 2 小时 |
装备
- 手套 — 山顶下方的铁链路段很滑
- 1 升水和一些零食
拖入或粘贴图片即可添加。点击表格内部可以添加一行。
粘贴实验室
@aeriz/wysiwyg · JS 45 行
试着粘贴 Excel、Word、HWP(韩文)放进剪贴板的杂乱 HTML(模拟样本),以及含有恶意代码的网页内容。格式会保留,mso-*、事件属性和 javascript: 会被去掉。右侧即时显示将要保存的 HTML、JSON 和 Markdown。
粘贴:
每个按钮都会粘贴与 Office 放进剪贴板的格式相同的 HTML。也可以复制你自己的文档粘贴进来。
工作报告
@aeriz/wysiwyg · JS 15 行
带审批栏和合并单元格表格的公司内部文档模板。模板直接以 HTML 导入,提交审批后用 setReadOnly(true) 锁定。
每周工作报告
| 部门 | 平台组 | 周期 | 2026/11/9 – 11/13 |
| 填写人 | 王明(高级工程师) | 日期 | 2026/11/13 |
1. 本周进展
| 项目 | 进度 | 备注 |
| 计划 | 实际 |
| 支付系统重构 | 80% | 85% | 提前完成 |
| 后台表格编辑 | 60% | 55% | 测试延后一天 |
| 文档站示例 | 100% | 100% | 已上线 |
2. 下周计划
- 支付压力测试(11/16)
- 完成后台测试
- 落实安全评审意见
3. 需协调事项
安装
选择你使用的包管理器。如果不使用构建工具,请查看 CDN 标签页。
bash
npm install @aeriz/wysiwyg
bash
pnpm add @aeriz/wysiwyg
bash
yarn add @aeriz/wysiwyg
html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@aeriz/wysiwyg@2.0.1/dist/aeriz-wysiwyg.min.css">
<!-- 全局变量 AerizWysiwyg -->
<script src="https://cdn.jsdelivr.net/npm/@aeriz/wysiwyg@2.0.1/dist/aeriz-wysiwyg.min.js"></script>
<!-- 需要代码高亮时(全局变量 AerizWysiwygHighlight) -->
<script src="https://cdn.jsdelivr.net/npm/@aeriz/wysiwyg@2.0.1/dist/aeriz-wysiwyg-highlight.min.js"></script>
无论用哪种方式安装,样式表都只需加载一次。使用打包工具时,写 import '@aeriz/wysiwyg/style.css' 即可。
提示 在 CDN 地址中写上确切的版本号,例如 @2.0.1。地址不会变,因此可以长期缓存。
快速开始
传入一个元素即可。设置 height 后,正文在该高度内滚动;不设置时,编辑器会填满父元素(最小 320px)。
js
import { AerizEditor } from '@aeriz/wysiwyg';
import '@aeriz/wysiwyg/style.css';
const editor = new AerizEditor({
element: document.querySelector('#editor'),
initialHTML: '<p>Hello</p>',
height: 480,
upload: { url: '/api/upload' },
onChange: (html) => save(html),
});
editor.getHTML(); // 粘贴到任何地方都保持相同外观的 HTML
editor.getBlocks(); // 用于存储的 JSON 快照
点击表格内部,用工具栏的表格菜单添加行和列,或拖选多个单元格后合并。Ctrl+H 打开查找替换,Alt+F10 跳到工具栏。
上传图片和文件
一个 upload 选项同时处理图片和文件。不设置时,对话框中的“上传”标签页不可用,粘贴的图片会以 data URL 的形式保存在文档中。
js
new AerizEditor({
element,
upload: {
url: '/api/upload', // 以 multipart 方式 POST:file, kind ('image' | 'file')
headers: () => ({ Authorization: `Bearer ${token()}` }), // 每次上传都会调用,令牌始终是最新的
maxSize: 10 * 1024 * 1024, // 超过此大小的文件不会发送,并调用 onError
},
onError: (error, { code }) => toast(code === 'upload' ? '上传失败' : error.message),
});
服务器返回 { "url": "https://…" }。如果要自己处理上传,请用 handler: (file, kind) => Promise<url> 代替 url。两者都设置时,以 handler 为准。
代码高亮(可选)
代码块高亮器不在核心包中。只在需要时 import,并传给 highlighter。它支持 15 种语言,gzip 后约 4 KB。
js
import { AerizEditor } from '@aeriz/wysiwyg';
import { highlighter } from '@aeriz/wysiwyg/highlight';
new AerizEditor({ element, highlighter });
不设置时,代码块显示为纯文本,并隐藏语言选择。只要符合 { languages: [{ id, label }], highlight(code, id) } 的结构,也可以使用其他高亮器。高亮器返回的 HTML 只保留文本和 <span class> 后才会插入。
- 可以用工具栏按钮选择语言,也可以交给自动识别。
- 从 GitHub、VS Code 或博客复制的代码(
language-py、lang-js、highlight-source-shell、data-lang)和 Markdown 代码围栏(```ts)会保留原来的语言。
py → Python、sh → Bash 这样的别名也能识别。
- 在输入法组字过程中(如中文输入)切换语言,也不会出现重复字符。
原生 JS
不使用框架时,直接使用类即可。如果加载的是 CDN 脚本,相同的导出位于全局变量 AerizWysiwyg 上。
html
<div id="editor"></div>
<script>
const editor = new AerizWysiwyg.AerizEditor({
element: document.getElementById('editor'),
highlighter: AerizWysiwygHighlight.highlighter, // 加载了高亮器时
});
</script>
React
@aeriz/wysiwyg/react 组件以 props 的形式接收与 new AerizEditor() 相同的选项,支持 React 16.8 及以上版本。
jsx
import { useState } from 'react';
import { AerizEditor } from '@aeriz/wysiwyg/react';
import '@aeriz/wysiwyg/style.css';
export function Compose() {
const [html, setHtml] = useState('<p>Hello</p>');
return <AerizEditor value={html} onChange={setHtml} height={480} upload={{ url: '/api/upload' }} />;
}
- 把
value 原样传回不会移动光标。如果传入的值与编辑器当前的输出相同,就不会替换正文。
readOnly 会就地切换。locale、height、fonts 等会改变布局的选项会重建编辑器,并保留正文内容。
Vue
Vue 3 使用 @aeriz/wysiwyg/vue,Vue 2.6 和 2.7 使用 @aeriz/wysiwyg/vue2。用 v-model 绑定 HTML。
vue
<script setup>
import { ref } from 'vue';
import { AerizEditor } from '@aeriz/wysiwyg/vue';
import '@aeriz/wysiwyg/style.css';
const html = ref('<p>Hello</p>');
</script>
<template>
<AerizEditor v-model="html" :height="480" :read-only="locked" @error="onError" />
</template>
Svelte
它是一个 action 而不是组件,因此同一个文件可以在 Svelte 3、4、5 中使用。
html
<script>
import { aerizEditor } from '@aeriz/wysiwyg/svelte';
let html = '<p>Hello</p>';
</script>
<div use:aerizEditor={{ value: html, onChange: (v) => (html = v), height: 480 }}></div>
Angular
面向 Angular 14+ 的指令以 TypeScript 源码形式发布。请在 tsconfig.app.json 的 include 中加入 node_modules/@aeriz/wysiwyg/angular/*.ts。
ts
import { AerizEditorDirective } from '@aeriz/wysiwyg/angular';
@Component({
standalone: true,
imports: [FormsModule, AerizEditorDirective],
template: `<div aerizEditor [(ngModel)]="html" [height]="480" (error)="onError($event)"></div>`,
})
export class ComposeComponent { html = '<p>Hello</p>'; }
对表单控件调用 disable() 后,编辑器会变为只读。
Web 组件
html
<script type="module">import '@aeriz/wysiwyg/wc';</script>
<form method="post">
<aeriz-editor name="body" height="480" upload-url="/api/upload"></aeriz-editor>
</form>
属性:value · placeholder · theme · locale · toolbar · read-only · height · status-bar · upload-url · aria-label。无法用字符串表示的选项通过 property 传入(upload、fonts、fontSizes、highlighter、favicon)。事件:input · change · error · aeriz-ready。
jQuery
js
import '@aeriz/wysiwyg/jquery'; // 存在全局 jQuery 时会自动注册
$('#editor').aerizEditor({ value: '<p>Hello</p>', height: 480 });
$('#editor').aerizEditor('getHTML');
$('#editor').aerizEditor('destroy');
服务端与边缘
@aeriz/wysiwyg/server 不导入 CSS,也不使用 document,因此可以直接在 Node、Deno、Bun 和 Cloudflare Workers 中运行。
js
import { renderBlocksToHTML, blocksToMarkdown, blocksToPlainText } from '@aeriz/wysiwyg/server';
const html = renderBlocksToHTML(post.blocks, { wrapper: 'content' }); // 输入相同,输出就相同
const text = blocksToPlainText(post.blocks); // 用于搜索索引
表格
光标位于表格中时,工具栏会显示表格菜单和单元格背景色。拖动鼠标可以选中多个单元格。
| 操作 | 存在合并单元格时 |
| 插入列 | 在合并的表头内部插入时,表头会变宽。在纵向合并单元格旁边插入时,新单元格的高度与之相同。 |
| 插入行 | 跨越新行的纵向合并单元格会增加一行。 |
| 删除行或列 | 删除合并单元格起始的那一行时,该单元格会下移。合并的表头会少一列。 |
| 合并 | 如果选区只覆盖了另一个合并单元格的一部分,会扩展到包含整个单元格。文本以换行连接。 |
| 拆分 | 恢复为单个单元格,并补上空单元格,使表格保持矩形。 |
Tab | 按网格顺序移到下一个单元格。在最后一个单元格按下时会添加一行。 |
粘贴
| 来源 | 保留 | 去除 |
| Excel | 合并单元格、粗体、背景色、边框、对齐、文字颜色 | mso-number-format、class、<col>、工作表的默认字体 |
| Word | 粗体和斜体、缩进、项目符号列表和编号列表(含嵌套) | mso-list 段落、Wingdings 项目符号、<o:p>、lang |
| HWP(韩文) | 缩进、字间距、字体(<font> 转为 <span style>)、单元格宽度和背景色 | HStyle class、style-name、单元格内包裹的段落、默认字号(size="3") |
| Google 文档 | 段落、标题、列表、粗体 | 包住全部内容的 <b id="docs-internal-guid-…">、列表项中的 <p> |
| 网页 | 段落、标题、列表、表格、链接 | 脚本、事件属性、块 id |
| 本编辑器 | 文档中的内容(格式、链接、列表和表格结构) | 浏览器添加的计算样式(如 font-size: 15px)、对齐按钮和调整大小的手柄 |
- 包住多个块的链接或粗体(
<a><p>…</p></a>)会先拆开,再分别套回每个块的文本上,因此不会出现段落套段落的情况。
- 在列表项、表格单元格、图片说明等不能放置块的位置,引用和标注框也会以换行连接的文本形式插入。
- 粘贴到这类位置的链接卡片、文件和视频,会变成指向其地址的一行链接(文字为卡片标题或文件名)。粘贴到引用或标注框中时,会先填好内容,再移到框外。
- 选区跨越同一表格的多个单元格时粘贴,会保留所有单元格,只删除选中的文本,并插入到第一个单元格中,表格结构不会被破坏。
- 光标位于图片或链接卡片上时,会粘贴到它后面的段落中。选区跨越多个块时粘贴,会先删除选区。
- 在链接文字中粘贴 URL 时,只插入地址本身,不会出现链接套链接。
以 pt 为单位的长度会转换为 px,字号仍保留为 pt。Ctrl+Shift+V 以纯文本粘贴。粘贴或拖入图片文件时,会通过 upload 上传。
js
import { AerizEditor, DEFAULT_FONTS } from '@aeriz/wysiwyg';
new AerizEditor({
element,
fontSizes: [9, 10, 10.5, 11, 12, 14, 16, 20], // pt
fonts: [
...DEFAULT_FONTS,
{ label: 'Pretendard', stack: 'Pretendard, sans-serif', cssUrl: 'https://…/pretendard.css' },
],
});
- 默认字体为 맑은 고딕、굴림、돋움、바탕、궁서、나눔고딕、나눔명조、Apple SD 산돌고딕 Neo、Arial、Times New Roman 和 Courier New。设备上没有的字体不会出现在列表中。
- 只有带
cssUrl 的字体才会加载 CSS,而且只在打开字体列表时加载,不会产生其他请求。
- 行距范围为 100%~300%,字间距以 em 为单位。特殊字符分为符号、箭头、圈码、单位、括号和数学几组。
免费字体(SIL OFL 1.1)
FREE_FONTS 列出了 15 款可以放心免费使用的韩文字体。包中不含字体文件,也没有默认的 CDN 地址。把你自己托管的 CSS 传给 freeFonts({ cssUrl }),打开字体列表时只会加载这些字体。
js
import { AerizEditor, freeFonts } from '@aeriz/wysiwyg';
new AerizEditor({
element,
// 追加在 DEFAULT_FONTS 之后;나눔고딕 和 나눔명조 已经在列表中,只会补上 URL
fonts: freeFonts({
only: ['pretendard', 'noto-serif-kr', 'd2coding'], // 省略则为全部
cssUrl: (font) => `/fonts/${font.id}/font.css`, // 你自己托管的 CSS
}),
});
- 没有
cssUrl 的字体,只有在设备上已安装时才会显示。freeFonts() 本身不会发出任何请求。
- 如果自行托管字体文件,请把每款字体的
OFL.txt 放在旁边。OFL 允许商用和网页嵌入,但禁止单独出售字体文件。
- 默认列表中的 맑은 고딕、굴림、바탕 等系统字体直接使用设备上的字体,不分发任何文件。
块边界与链接
在段落、列表、引用、代码、表格和嵌入内容之间输入时的行为。
换行
| 操作 | 结果 |
| 在列表或引用的空行按 Enter | 跳出该块,新的一行为正文(<p>)。 |
| 在块内按 Shift+Enter | 不拆分块,只换行(<br>)。所有块都一样。 |
| 在表格单元格中按 Enter | 在单元格内换行。 |
| 在代码块中按 Enter | 换行并保持缩进。在空的最后一行按 Enter,或按 Ctrl+Enter 跳出。 |
| 引用、标注框中的列表或代码 | Enter 添加列表项或新行。在空项或空的最后一行按下时,变成框内的段落。 |
| 标注框 | 与引用相同。在空的最后一行按 Enter 跳出框,在第一行开头按 Backspace 把这一行作为正文移出。 |
| 折叠块 | 在标题中按 Enter 会在正文顶部新开一行(折叠时在折叠块之后)。在正文空的最后一行按 Enter 跳出折叠块。在标题开头按 Backspace 解除折叠块,变回正文段落。 |
删除
| 操作 | 结果 |
| 在空块中按 Backspace | 先变成正文段落,再按一次接到上一个块的末尾。空的第二个列表项移到上一项末尾。空文档保持不变。 |
| 在段落开头按 Backspace,或在末尾按 Delete | 与前后段落合并,不会留下 <span style>。表格和代码块不合并,光标移入其中。 |
| 在代码块末尾按 Delete | 只移动光标,不会把下一段拉进代码。 |
| 在分隔线、图片、视频、链接卡片旁 | 第一次只用红框标出,第二次才删除。 |
选中后输入
| 操作 | 结果 |
| 选中多个块后输入 | 只替换选区。三击选中的段落不会带上下一段。 |
| 从表格单元格选到表格外、从折叠块标题选到正文后输入 | 文字(包括中文)按顺序插入到选区起点。 |
| Ctrl+A | 即使文档以表格开头、以卡片或视频结尾,也能全选。之后删除或输入,会留下一个空段落。 |
| 更改列表类型 | 改成另一种列表时保留所有项;改成标题或正文时,只改变光标所在的项。 |
| 未知的块 | 新行和无法识别的元素(<div>、<section> 等)会成为正文段落。 |
图片、视频与卡片
| 操作 | 结果 |
| 插入分隔线、视频或表格 | 插入到正在编写的段落之后,光标移到下一个段落。 |
| 点击图片、卡片或视频后输入 | 字母、中文输入和 Enter 从其后的段落开始。图片说明内除外。 |
| 点击或拖动链接卡片、文件后输入 | 焦点留在编辑器中,输入不会丢失。 |
| 点击视频 | 第一次点击选中该块,第二次才播放。只读模式和查看器中直接播放。 |
| 粘贴以卡片或视频结尾的内容 | 光标落在其后的段落,按键不会传给播放器。 |
| 点击链接卡片 | 打开编辑对话框,而不是新标签页。正文中的链接用 Ctrl+点击 打开。 |
| HTML 块的高度 | 先按内容高度展开。拖动底边横条设置高度,双击恢复。设置的高度在 getHTML() 和查看器中保留。 |
说明 导入 HTML 时会解除其中的固定头部和内部滚动区域,因此内容不会被截断。
链接与撤销
| 操作 | 结果 |
| 添加链接 | 选中文本后按 Ctrl+K 或工具栏的链接按钮。输入 https://… 后按空格,或直接粘贴 URL,也会生成链接。example.com 会补上 https://。 |
| 粘贴 YouTube 链接 | 在空段落中会变成视频。在视频对话框中填入非 YouTube 链接时会显示提示。 |
| 撤销与重做 | 按单词逐步撤销,光标回到原位。浏览器菜单中的撤销也使用同一份历史记录,快速来回切换也不会破坏重做。 |
快捷键与无障碍
| 操作 | 快捷键 |
| 撤销 / 重做 | Ctrl+Z / Ctrl+Shift+Z · Ctrl+Y |
| 粗体 · 斜体 · 下划线 · 删除线 | Ctrl+B · Ctrl+I · Ctrl+U · Ctrl+Shift+X |
| 上标 · 下标 | Ctrl+. · Ctrl+, |
| 全选正文 | Ctrl+A |
| 查找和替换 | Ctrl+H |
| 粘贴为纯文本 | Ctrl+Shift+V |
| 添加或编辑链接 | Ctrl+K |
| 块内换行 | Shift+Enter |
| 代码块:换行 / 跳出代码块 | Enter / Ctrl+Enter · 在空的最后一行按 Enter |
| 列表:增加缩进 / 减少缩进 | Tab / Shift+Tab |
| 移到工具栏 / 回到正文 | Alt+F10 / Esc |
| 正文 · 标题 1–6 | Ctrl+Alt+0 · Ctrl+Alt+1–6(为保护表格,在表格单元格内不生效;转换引用或折叠块时,其中的每个列表项各成一行) |
| 编号列表 · 项目符号列表 · 引用 · 代码 · 任务列表 | Ctrl+Alt+7 · Ctrl+Alt+8 · Ctrl+Alt+9 · Ctrl+Alt+C · Ctrl+Alt+T |
| 块上移 · 下移 / 删除块 | Ctrl+Shift+↑ · Ctrl+Shift+↓ / Ctrl+Shift+D |
| 表格:下一个 / 上一个单元格 | Tab / Shift+Tab |
| 退出全屏 | Esc |
- macOS 用
Cmd 代替 Ctrl,用 Option 代替 Alt(例如 Cmd+Option+1)
- 欧洲键盘 用
Ctrl+Alt 输入的字符(AltGr+7 = {)不会被快捷键抢占。
- 工具栏 只占一个 Tab 停靠点,按钮之间用方向键、
Home 和 End 移动。
- 屏幕阅读器 编辑区带有无障碍名称(
ariaLabel,默认为对应语言的“富文本编辑器”)。
在正文段落开头输入以下内容,块会立即转换。按一次 Ctrl+Z 即可恢复为你输入的原文。
| 输入 | 结果 |
# 到 ###### + 空格 | 标题 1–6 |
- · * · + + 空格 | 项目符号列表 |
1. · 1) + 空格 | 编号列表(数字任意) |
[ ] · [] · [x] + 空格 | 任务列表([x] 表示已完成)。在项目符号列表项开头也可以使用。 |
> + 空格 | 引用 |
``` · ~~~ | 代码块。接着在第一行只输入语言名(py、js、sql …)并按 Enter,即可按该语言高亮(需设置高亮器)。 |
--- · *** | 分隔线 |
在空段落中粘贴 YouTube 链接会生成视频,其他 URL 会变成链接。粘贴或拖入图片文件会生成图片。标注框、折叠块、表格、链接卡片、文件附件和 HTML 导入,都在工具栏第一个按钮——块菜单中。
选项
| 选项 | 类型 | 默认值 | 说明 |
element | HTMLElement | — | 放置编辑器的元素(必填) |
initialHTML | string | — | 初始内容 |
placeholder | string | — | 内容为空时显示的提示 |
toolbar | { items, sticky } | false | DEFAULT_TOOLBAR | 工具栏项目。'|' 为分隔符 |
theme | 'light' | 'dark' | 'light' | 主题 |
locale | 'ko' | 'en' | 'ja' | 'zh' | 'ko' | 界面语言 |
height | number | string | 父元素高度 | 数字单位为 px。设置后正文在其中滚动 |
readOnly | boolean | false | 只读。工具栏只保留打印和全屏 |
statusBar | boolean | true | 底部状态栏(块数、字数、撤销) |
upload | { url, headers, handler, maxSize } | — | 图片和文件上传 |
onChange | (html) => void | — | 正文变化时调用 |
onError | (error, { code }) => void | console.error | code: 'upload' · 'paste' |
fonts | { label, stack, cssUrl? }[] | DEFAULT_FONTS | 字体列表 · 免费字体 |
fontSizes | number[] | DEFAULT_FONT_SIZES | 字号(pt) |
highlighter | CodeHighlighter | — | 代码高亮器(@aeriz/wysiwyg/highlight) |
favicon | (href) => string | null | — | 链接卡片的 favicon 地址。不设置时不绘制 favicon,也不调用外部服务。示例:(href) => `/favicon?url=${encodeURIComponent(href)}` |
htmlStyles | 'inline' | 'class' | 'inline' | getHTML() 的输出方式。'class' 适用于加载了样式表的页面 |
ariaLabel | string | “富文本编辑器”(zh) | 编辑区的无障碍名称 |
方法
| 方法 | 说明 |
getHTML({ styles? }) | 不含编辑界面的正文 HTML |
setHTML(html) | 替换正文(经过净化,算作一步撤销)。只带属性的空壳链接卡片、文件和视频(<a class="aw-file-attachment" href data-file-name></a>)会根据这些属性重建 |
getBlocks() · setBlocks(blocks) | 读写用于存储的 JSON 快照 |
setReadOnly(on) | 开启或关闭只读 |
setTheme(theme) | 切换主题 |
focus() · undo() · redo() | 聚焦、撤销、重做 |
openFind() · toggleSource() · toggleFullscreen() | 查找面板、源码视图、全屏 |
getState() · onStateChange(fn) | 块和选区的状态,以及对它的订阅(返回取消订阅的函数) |
destroy() | 移除监听器并清空元素 |
此外还导出:AerizViewer(只读渲染)、DEFAULT_TOOLBAR · DEFAULT_FONTS · DEFAULT_FONT_SIZES、免费字体 FREE_FONTS · freeFonts(),以及转换函数 renderBlocksToHTML · htmlToBlocks · blocksToMarkdown · markdownToBlocks · markdownToHtml · blocksToPlainText · sanitizeHTML · upgradeSnapshots。包内附带 TypeScript 类型定义。
入口路径
适配器路径:adapter react vue vue2 svelte jquery wc
| 路径 | 内容 |
@aeriz/wysiwyg | 编辑器、查看器和转换函数(作为副作用加载样式表) |
@aeriz/wysiwyg/style.css | 样式表 |
@aeriz/wysiwyg/highlight | 代码高亮器 |
@aeriz/wysiwyg/server | 不依赖 DOM 的转换函数 |
@aeriz/wysiwyg/react · /vue · /vue2 · /svelte · /angular · /jquery · /wc | 框架适配器 |
@aeriz/wysiwyg/adapter | 用于自行编写适配器的控制器 |
分发文件
打包工具、Node 和 CDN 选用的文件都经过压缩:去掉空白和注释并缩短局部变量名,但不做混淆,也不附带 source map。公开 API 的名称和类型保持不变,并保留 @__PURE__ 标记,打包工具仍可进行 tree-shaking。
| 使用方 | 文件 | 大小(gzip) |
import(打包工具) | dist/aeriz-wysiwyg.esm.min.js | 295 KB (83 KB) |
require(Node) | dist/aeriz-wysiwyg.min.cjs | — |
<script>(CDN) | dist/aeriz-wysiwyg.min.js(全局变量 AerizWysiwyg) | — |
| 未压缩,用于调试 | dist/aeriz-wysiwyg.esm.js · .cjs · .js | 仅通过 CDN 地址直接引用(例如 https://cdn.jsdelivr.net/npm/@aeriz/wysiwyg@2.0.1/dist/aeriz-wysiwyg.esm.js) |
从 1.x 升级到 2.0
2.0 整理了公开 API,让每件事只有一种做法。用 1.x 保存的快照可以直接打开。
| 1.x | 2.0 |
editor.serialize() | editor.getBlocks()(现在返回 BlockSnapshot[]) |
editor.getRawHTML() | editor.getHTML() |
onImageUpload · onFileUpload | upload: { handler: (file, kind) => url } |
imageUploadUrl · fileUploadUrl | upload: { url, headers, maxSize } |
<aeriz-editor image-upload-url file-upload-url> | upload-url 属性或 upload property |
| 代码高亮始终开启 | @aeriz/wysiwyg/highlight 的 highlighter 选项 |
| 字号以 px 为单位 | pt(fontSizes) |
| 字体列表中有 Google Fonts | 韩文系统字体。Web 字体通过 fonts 中的 cssUrl 指定 |
setLocale · t · getLocale | locale 选项 |
renderBlockToHTML · upgradeSnapshot · snapshotVersionOf | renderBlocksToHTML · upgradeSnapshots |
块的内部实现(BLOCK_TYPES 等) | 不再导出 |
新增
- 选项:
readOnly, height, upload, onError, fonts, fontSizes, ariaLabel, highlighter, favicon。
- 方法:
setReadOnly(), setBlocks(), openFind(), toggleSource(), toggleFullscreen()。
- 工具栏:行距、字间距、特殊字符、查找替换、源码视图、打印、全屏,以及表格菜单中的合并与拆分单元格。
2.0.1 更新内容
相对于 npm 2.0.0 的变更。已保存的快照和 HTML 可以直接打开,公开 API 只增不减。
查看全部变更
版权清理
- 工具栏和块图标都为本包从零重绘(20×20 网格,线宽 1.6),没有任何图标取自其他图标库。
- 链接卡片默认不再调用 Google 的 favicon 服务。如需显示 favicon,请用
favicon 选项指定地址。不设置时,卡片不绘制 favicon,也不发出任何外部请求。
- 新增 15 款已确认许可的免费韩文字体,可通过
FREE_FONTS · freeFonts() 使用(均为 SIL OFL 1.1)。包中不含字体文件,也没有默认的 CDN 地址。
新增
- 代码语言自动识别:读取粘贴代码上的
language-* class 和 data-lang,以及 py、sh、c++ 等代码围栏别名。在 ``` 之后的第一行输入语言名并按 Enter 即可设置。
- 链接:用
Ctrl+K 插入、编辑和删除。在 https://… 或 www.… 后按空格或 Enter 会生成链接;粘贴单个 URL 会生成链接(有选中文本时加在该文本上);在空段落中粘贴 YouTube 链接会生成视频块。example.com 和邮箱地址会自动补全为 https:// 和 mailto:。点击链接卡片会打开编辑对话框,而不是新标签页。
- 任务列表输入规则:在段落或项目符号列表项开头输入
[ ] 、[] 或 [x] (已完成)。按一次 Ctrl+Z 即可恢复为输入的文本。
- 导入的 HTML 块按内容高度展开(解除固定头部和内部滚动区域)。拖动底边设置高度,双击恢复。该高度在
getHTML()、查看器和 Markdown 导出中都会保留。
- 撤销以空格为分界,一次撤销删除一个单词,光标回到该次更改之前的位置。通过浏览器的编辑菜单和右键菜单执行的撤销,也使用编辑器自己的历史记录。
- macOS 上的
Cmd+Option 块快捷键按键位匹配,欧洲键盘上的 AltGr 字符(AltGr+7 = {)不会被抢占。
编辑(块边界)
Enter:在标题末尾按下,下一行为正文;在空列表项上按下,跳出列表;在引用、标注框和折叠块中,在空的最后一行按下即跳出框。代码块保持上一行的缩进,在空的最后一行按 Enter 或按 Ctrl+Enter 跳出。
- 用
Backspace 或 Delete 合并段落时不会添加 <span style>。表格和代码块不会被合并;分隔线、图片、视频、链接卡片和文件在删除前会先用红框标出一次。
- 在跨块选区、三击选中或
Ctrl/Cmd+A 之后输入、删除或剪切,只删除选区并继续编辑。即使文档以卡片或表格开头、结尾,Ctrl/Cmd+A 也能全选。
- 插入分隔线、视频、链接卡片或表格时,保留正在编写的段落,并插入到它后面。编辑时第一次点击视频会选中该块,按键不会传给播放器。
- 复制和剪切只携带文档中的内容(不含浏览器的计算样式)。关闭对话框后,光标回到原来的位置。
- 未知的块(
<div class>、<section>)会变成正文段落;引用中的卡片或引用、空表格、链接中的链接等损坏结构,一出现就会被修正。在表格单元格内不应用文本块类型的更改。
表格、粘贴与任务列表
- 工具栏的表格尺寸选择和列宽调整每帧只绘制一次,跟随鼠标不卡顿。不拖动而直接点击单元格右边缘,会把光标放进该单元格。
- 来自 HWP(韩文)和旧网页的
<font face color size> 会转换为字体、颜色、字号工具能读取的 <span style>。在链接文字中粘贴 URL 时只插入地址。
- 以空壳形式传入的链接卡片、文件和视频 HTML(例如经过服务端净化后)会在编辑器中重建。
- 修复:保存已完成的任务列表项并重新加载后,取消勾选时灰色删除线仍然残留。
分发
- 打包工具选用的 ES 模块,以及服务端、高亮器和框架文件,现在真正经过了压缩。主 ES 模块从 422 KB 降到 295 KB(gzip 后从 113 KB 降到 83 KB),npm 包从 904 KB 降到 871 KB。详见分发文件。
- 新增示例页:块展示、论坛发帖、评论框、粘贴实验室和工作报告。
修复
- 在韩文输入法组字时更改代码块语言,会重复输入字符并停止高亮。
- 粘贴到引用或标注框中的链接卡片会变成空框,文件和视频会丢失。粘贴到列表项或表格单元格中的卡片、文件和视频也会丢失(现在会保留为地址链接)。
- 粘贴内容以卡片或视频结尾后点击视频,接下来的按键会传给播放器。点击或拖动文件、链接卡片后输入的文字会丢失。
- 在引用、标注框或折叠块内的代码块中按
Enter,代码块会被段落包住,导致撤销再重做后文档发生变化。
- 在跨越多个表格单元格的选区上粘贴,会删除单元格,使表格不再是矩形。