am-editor-001/packages/engine

am-editor

一个富文本协同编辑器框架，可以使用React和Vue自定义插件

English · Demo · 文档 · 插件 · QQ群 907664876 ·

广告：科学上网，方便、快捷的上网冲浪 稳定、可靠，访问 Github 或者其它外网资源很方便。

使用浏览器提供的 contenteditable 属性让一个 DOM 节点具有可编辑能力。

引擎接管了浏览器大部分光标、事件等默认行为。

可编辑器区域内的节点通过 schema 规则，制定了 mark inline block card 4 种组合节点，他们由不同的属性、样式或 html 结构组成，并对它们的嵌套进行了一定的约束。

通过 MutationObserver 监听编辑区域内的 DOM 树的改变，并生成 json0 类型的数据格式与 ShareDB 库进行交互，从而达到协同编辑的需要。

Vue2 案例 https://github.com/zb201307/am-editor-vue2

Vue3 案例 https://github.com/yanmao-cc/am-editor/tree/master/examples/vue

React 案例 https://github.com/yanmao-cc/am-editor/tree/master/examples/react

特性

• 开箱即用，提供几十种丰富的插件来满足大部分需求
• 高扩展性，除了 mark inline block 类型基础插件外，我们还提供 card 组件结合React Vue等前端库渲染插件 UI
• 丰富的多媒体支持，不仅支持图片和音视频，更支持插入嵌入式多媒体内容
• 支持 Markdown 语法
• 支持国际化
• 引擎纯 JavaScript 编写，不依赖任何前端库，插件可以使用 React Vue 等前端库渲染。复杂架构轻松应对
• 内置协同编辑方案，轻量配置即可使用
• 兼容大部分最新移动端浏览器

插件

包	版本	大小	描述
@aomao/toolbar			工具栏, 适用于 React
@aomao/toolbar-vue			工具栏, 适用于 Vue3
@aomao/plugin-alignment			对齐方式
@aomao/plugin-backcolor			背景色
@aomao/plugin-bold			加粗
@aomao/plugin-code			行内代码
@aomao/plugin-codeblock			代码块, 适用于 React
@aomao/plugin-codeblock-vue			代码块, 适用于 Vue3
@aomao/plugin-fontcolor			前景色
@aomao/plugin-fontfamily			字体
@aomao/plugin-fontsize			字体大小
@aomao/plugin-heading			标题
@aomao/plugin-hr			分割线
@aomao/plugin-indent			缩进
@aomao/plugin-italic			斜体
@aomao/plugin-link			链接, 适用于 React
@aomao/plugin-link-vue			链接, 适用于 Vue3
@aomao/plugin-line-height			行高
@aomao/plugin-mark			标记
@aomao/plugin-mention			提及
@aomao/plugin-orderedlist			有序列表
@aomao/plugin-paintformat			格式刷
@aomao/plugin-quote			引用块
@aomao/plugin-redo			重做
@aomao/plugin-removeformat			移除样式
@aomao/plugin-selectall			全选
@aomao/plugin-status			状态
@aomao/plugin-strikethrough			删除线
@aomao/plugin-sub			下标
@aomao/plugin-sup			上标
@aomao/plugin-tasklist			任务列表
@aomao/plugin-underline			下划线
@aomao/plugin-undo			撤销
@aomao/plugin-unorderedlist			无序列表
@aomao/plugin-image			图片
@aomao/plugin-table			表格
@aomao/plugin-file			文件
@aomao/plugin-mark-range			标记光标, 例如: 批注.
@aomao/plugin-math			数学公式
@aomao/plugin-video			视频

快速上手

安装

编辑器由 引擎、工具栏、插件 组成。引擎 为我们提供了核心的编辑能力。

使用 npm 或者 yarn 安装引擎包

$ npm install @aomao/engine
# or
$ yarn add @aomao/engine

使用

我们按照惯例先输出一个Hello word!

import React, { useEffect, useRef, useState } from 'react';
import Engine, { EngineInterface } from '@aomao/engine';

const EngineDemo = () => {
	//编辑器容器
	const ref = useRef<HTMLDivElement | null>(null);
	//引擎实例
	const [engine, setEngine] = useState<EngineInterface>();
	//编辑器内容
	const [content, setContent] = useState<string>('<p>Hello word!</p>');

	useEffect(() => {
		if (!ref.current) return;
		//实例化引擎
		const engine = new Engine(ref.current);
		//设置编辑器值
		engine.setValue(content);
		//监听编辑器值改变事件
		engine.on('change', () => {
			const value = engine.getValue();
			setContent(value);
			console.log(`value:${value}`);
		});
		//设置引擎实例
		setEngine(engine);
	}, []);

	return <div ref={ref} />;
};
export default EngineDemo;

插件

引入 @aomao/plugin-bold 加粗插件

import Bold from '@aomao/plugin-bold';

把 Bold 插件加入引擎

//实例化引擎
const engine = new Engine(ref.current, {
	plugins: [Bold],
});

卡片

卡片是编辑器中单独划分的一个区域，其 UI 以及逻辑在卡片内部可以使用 React、Vue 或其它前端库自定义渲染内容，最后再挂载到编辑器上。

引入 @aomao/plugin-codeblock 代码块插件，这个插件的 语言下拉框 使用 React 渲染，所以有区分。 Vue3 使用 @aomao/plugin-codeblock-vue

import CodeBlock, { CodeBlockComponent } from '@aomao/plugin-codeblock';

把 CodeBlock 插件和 CodeBlockComponent 卡片组件加入引擎

//实例化引擎
const engine = new Engine(ref.current, {
	plugins: [CodeBlock],
	cards: [CodeBlockComponent],
});

CodeBlock 插件默认支持 markdown，在编辑器一行开头位置输入代码块语法```javascript 回车后即可触发。

工具栏

引入 @aomao/toolbar 工具栏，工具栏由于交互复杂，基本上都是使用 React + Antd UI 组件渲染，Vue3 使用 @aomao/toolbar-vue

工具栏除了 UI 交互外，大部分工作只是对不同的按钮事件触发后调用了引擎执行对应的插件命令，在需求比较复杂或需要重新定制 UI 的情况下，Fork 后修改起来也比较容易。

import Toolbar, { ToolbarPlugin, ToolbarComponent } from '@aomao/toolbar';

把 ToolbarPlugin 插件和 ToolbarComponent 卡片组件加入引擎，它可以让我们在编辑器中可以使用快捷键 / 唤醒出卡片工具栏

//实例化引擎
const engine = new Engine(ref.current, {
	plugins: [ToolbarPlugin],
	cards: [ToolbarComponent],
});

渲染工具栏，工具栏已配置好所有插件，这里我们只需要传入插件名称即可

return (
    ...
    {
        engine && (
            <Toolbar
                engine={engine}
                items={[
                    ['collapse'],
                    [
                        'bold',
                    ],
                ]}
            />
        )
    }
    ...
)

更复杂的工具栏配置请查看文档 https://editor.aomao.com/zh-CN/config/toolbar

协同编辑

协同编辑基于 ShareDB 开源库实现，比较陌生的朋友可以先了解它。

交互模式

每位编辑者作为 客户端 通过 WebSocket 与 服务端 通信交换由编辑器生成的 json0 格式的数据。

服务端会保留一份 json 格式的 html 结构数据，接收到来自客户端的指令后，再去修改这份数据，最后再转发到每个客户端。

在启用协同编辑前，我们需要配置好 客户端 和 服务端

服务端是 NodeJs 环境，使用 express + WebSocket 搭建的网络服务。

案例

案例中我们已经一份比较基础的客户端代码

查看 React 完整案例

查看 Vue3 完整案例

查看 Vue2 完整案例

//实例化协作编辑客户端，传入当前编辑器引擎实例
const otClient = new OTClient(engine);
//连接到协作服务端，`demo` 与服务端文档ID相同
otClient.connect(
	`ws://127.0.0.1:8080${currentMember ? '?uid=' + currentMember.id : ''}`,
	'demo',
);

项目图标

Iconfont

开发

React

需要在 am-editor 根目录 site-ssr ot-server 中分别安装依赖

//依赖安装好后，只需要在根目录执行以下命令

yarn ssr

• packages 引擎和工具栏
• plugins 所有的插件
• site-ssr 所有的后端 API 和 SSR 配置。使用的 egg 。在 am-editor 根目录下使用 yarn ssr 自动启动 site-ssr
• ot-server 协同服务端。启动：yarn start

Vue3

只需要进入 examples/vue 目录安装依赖

//依赖安装好后，在 examples/vue 目录执行以下命令

yarn serve

在 Vue 运行环境中，默认是安装的已发布到 npm 上的代码。如果需要修改引擎或者插件的代码后立即看到效果，我们需要做以下步骤：

• 删除 examples/vue/node_modules/@aomao 文件夹
• 删除 examples/vue/node_modules/vue 文件夹。因为有插件依赖了 Vue，所以 Vue 的包会在项目根目录中安装。如果不删除 examples/vue 中的 Vue 包，和插件的 Vue 包不在一个环境中，就无法加载插件
• 在 am-editor 根目录下执行安装所有依赖命令，例如：yarn
• 最后在 examples/vue 中重新启动

Vue 案例中没有配置任何后端 API，具体可以参考 React 和 site-ssr

贡献

感谢 pleasedmi、Elena211314 的捐赠

如果您愿意，可以在这里留下你的名字。

支付宝

微信支付

PayPal

https://paypal.me/aomaocom