# am-editor
**Repository Path**: zzzPython/am-editor
## Basic Information
- **Project Name**: am-editor
- **Description**: 一个富文本实时协同编辑器框架，可以使用React和Vue自定义插件。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://editor.aomao.com
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 30
- **Created**: 2025-01-19
- **Last Updated**: 2025-01-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
> 在这里，我们有一个新的富文本编辑器 [Editable](https://github.com/editablejs/editable)，它没有使用原生的可编辑属性[~~contenteditable~~](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/contenteditable)，而是采用自定义的渲染器。这样做可以更好地控制编辑器的行为。
# am-editor
一个支持协同编辑的富文本编辑器，可以自由的使用React、Vue 等前端常用库扩展定义插件。
English ·
Demo ·
文档 ·
插件 ·
QQ群 907664876 ·
`广告`：[科学上网，方便、快捷的上网冲浪](https://xiyou4you.us/r/?s=18517120) 稳定、可靠，访问 Github 或者其它外网资源很方便。
**`Vue2`** DEMO [https://github.com/zb201307/am-editor-vue2](https://github.com/zb201307/am-editor-vue2)
**`Vue3`** DEMO [https://github.com/red-axe/am-editor-vue3-demo](https://github.com/red-axe/am-editor-vue3-demo)
**`React`** DEMO [https://github.com/big-camel/am-editor/tree/master/examples/react](https://github.com/big-camel/am-editor/tree/master/examples/react)
**`Vue2 DEMO`** [https://github.com/big-camel/am-editor-demo-vue2](https://github.com/big-camel/am-editor-demo-vue2)
**`Vue2 Nuxt DEMO`** [https://github.com/big-camel/am-editor-nuxt](https://github.com/big-camel/am-editor-nuxt)
## 特性
- 🎁 开箱即用，提供几十种丰富的插件来满足大部分需求
- 🚀 高扩展性，除了 `mark` `inline` `block` 类型基础插件外，我们还提供 `card` 组件结合 `React` `Vue` 等前端库渲染插件 UI
- 🎨 丰富的多媒体支持，不仅支持图片和音视频，更支持插入嵌入式多媒体内容
- 📝 支持 `Markdown` 语法
- 🌍 支持国际化
- 💻 引擎纯 `JavaScript` 编写，不依赖任何前端库，插件可以使用 `React` `Vue` 等前端库渲染。复杂架构轻松应对
- 👥 内置协同编辑方案，轻量配置即可使用
- 📱 兼容大部分最新移动端浏览器
## 插件
| **包** | **版本** | **大小** | **描述** |
| :---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------- |
| [`@aomao/toolbar`](./packages/toolbar) | [](./packages/toolbar/package.json) | [](https://unpkg.com/@aomao/toolbar/dist/index.js) | 工具栏, 适用于 `React` |
| [`@aomao/toolbar-vue`](./packages/toolbar-vue) | [](./packages/toolbar-vue/package.json) | [](https://unpkg.com/@aomao/toolbar-vue/dist/index.js) | 工具栏, 适用于 `Vue3` |
| [`am-editor-toolbar-vue2`](https://github.com/zb201307/am-editor-vue2/tree/main/packages/toolbar) | [](https://github.com/zb201307/am-editor-vue2/blob/main/packages/toolbar/package.json) | [](https://unpkg.com/am-editor-toolbar-vue2/dist/index.js) | 工具栏, 适用于 `Vue2` |
| [`@aomao/plugin-alignment`](./plugins/alignment) | [](./plugins/alignment/package.json) | [](https://unpkg.com/@aomao/plugin-alignment/dist/index.js) | 对齐方式 |
| [`@aomao/plugin-embed`](./plugins/embed) | [](./plugins/embed/package.json) | [](https://unpkg.com/@aomao/plugin-embed/dist/index.js) | 嵌入网址 |
| [`@aomao/plugin-backcolor`](./plugins/backcolor) | [](./plugins/backcolor/package.json) | [](https://unpkg.com/@aomao/plugin-backcolor/dist/index.js) | 背景色 |
| [`@aomao/plugin-bold`](./plugins/bold) | [](./plugins/bold/package.json) | [](https://unpkg.com/@aomao/plugin-bold/dist/index.js) | 加粗 |
| [`@aomao/plugin-code`](./plugins/code) | [](./plugins/code/package.json) | [](https://unpkg.com/@aomao/plugin-code/dist/index.js) | 行内代码 |
| [`@aomao/plugin-codeblock`](./plugins/codeblock) | [](./plugins/codeblock/package.json) | [](https://unpkg.com/@aomao/plugin-codeblock/dist/index.js) | 代码块, 适用于 `React` |
| [`@aomao/plugin-codeblock-vue`](./plugins/codeblock-vue) | [](./plugins/codeblock-vue/package.json) | [](https://unpkg.com/@aomao/plugin-codeblock-vue/dist/index.js) | 代码块, 适用于 `Vue3` |
| [`am-editor-codeblock-vue2`](https://github.com/zb201307/am-editor-vue2/tree/main/packages/codeblock) | [](https://github.com/zb201307/am-editor-vue2/tree/main/packages/codeblock/package.json) | [](https://unpkg.com/am-editor-codeblock-vue2/dist/index.js) | 代码块, 适用于 `Vue2` |
| [`@aomao/plugin-fontcolor`](./plugins/fontcolor) | [](./plugins/fontcolor/package.json) | [](https://unpkg.com/@aomao/plugin-fontcolor/dist/index.js) | 前景色 |
| [`@aomao/plugin-fontfamily`](./plugins/fontfamily) | [](./plugins/fontfamily/package.json) | [](https://unpkg.com/@aomao/plugin-fontfamily/dist/index.js) | 字体 |
| [`@aomao/plugin-fontsize`](./plugins/fontsize) | [](./plugins/fontsize/package.json) | [](https://unpkg.com/@aomao/plugin-fontsize/dist/index.js) | 字体大小 |
| [`@aomao/plugin-heading`](./plugins/heading) | [](./plugins/heading/package.json) | [](https://unpkg.com/@aomao/plugin-heading/dist/index.js) | 标题 |
| [`@aomao/plugin-hr`](./plugins/hr) | [](./plugins/hr/package.json) | [](https://unpkg.com/@aomao/plugin-hr/dist/index.js) | 分割线 |
| [`@aomao/plugin-indent`](./plugins/indent) | [](./plugins/indent/package.json) | [](https://unpkg.com/@aomao/plugin-indent/dist/index.js) | 缩进 |
| [`@aomao/plugin-italic`](./plugins/italic) | [](./plugins/italic/package.json) | [](https://unpkg.com/@aomao/plugin-italic/dist/index.js) | 斜体 |
| [`@aomao/plugin-link`](./plugins/link) | [](./plugins/link/package.json) | [](https://unpkg.com/@aomao/plugin-link/dist/index.js) | 链接, 适用于 `React` |
| [`@aomao/plugin-link-vue`](./plugins/link-vue) | [](./plugins/link-vue/package.json) | [](https://unpkg.com/@aomao/plugin-link-vue/dist/index.js) | 链接, 适用于 `Vue3` |
| [`am-editor-link-vue2`](https://github.com/zb201307/am-editor-vue2/tree/main/packages/link) | [](https://github.com/zb201307/am-editor-vue2/tree/main/packages/link/package.json) | [](https://unpkg.com/am-editor-link-vue2/dist/index.js) | 链接, 适用于 `Vue2` |
| [`@aomao/plugin-line-height`](./plugins/line-height) | [](./plugins/line-height/package.json) | [](https://unpkg.com/@aomao/plugin-line-height/dist/index.js) | 行高 |
| [`@aomao/plugin-mark`](./plugins/mark) | [](./plugins/mark/package.json) | [](https://unpkg.com/@aomao/plugin-mark/dist/index.js) | 标记 |
| [`@aomao/plugin-mention`](./plugins/mention) | [](./plugins/mention/package.json) | [](https://unpkg.com/@aomao/plugin-mention/dist/index.js) | 提及 |
| [`@aomao/plugin-orderedlist`](./plugins/orderedlist) | [](./plugins/orderedlist/package.json) | [](https://unpkg.com/@aomao/plugin-orderedlist/dist/index.js) | 有序列表 |
| [`@aomao/plugin-paintformat`](./plugins/paintformat) | [](./plugins/paintformat/package.json) | [](https://unpkg.com/@aomao/plugin-paintformat/dist/index.js) | 格式刷 |
| [`@aomao/plugin-quote`](./plugins/quote) | [](./plugins/quote/package.json) | [](https://unpkg.com/@aomao/plugin-quote/dist/index.js) | 引用块 |
| [`@aomao/plugin-redo`](./plugins/redo) | [](./plugins/redo/package.json) | [](https://unpkg.com/@aomao/plugin-redo/dist/index.js) | 重做 |
| [`@aomao/plugin-removeformat`](./plugins/removeformat) | [](./plugins/removeformat/package.json) | [](https://unpkg.com/@aomao/plugin-removeformat/dist/index.js) | 移除样式 |
| [`@aomao/plugin-selectall`](./plugins/selectall) | [](./plugins/selectall/package.json) | [](https://unpkg.com/@aomao/plugin-selectall/dist/index.js) | 全选 |
| [`@aomao/plugin-status`](./plugins/status) | [](./plugins/status/package.json) | [](https://unpkg.com/@aomao/plugin-status/dist/index.js) | 状态 |
| [`@aomao/plugin-strikethrough`](./plugins/strikethrough) | [](./plugins/strikethrough/package.json) | [](https://unpkg.com/@aomao/plugin-strikethrough/dist/index.js) | 删除线 |
| [`@aomao/plugin-sub`](./plugins/sub) | [](./plugins/sub/package.json) | [](https://unpkg.com/@aomao/plugin-sub/dist/index.js) | 下标 |
| [`@aomao/plugin-sup`](./plugins/sup) | [](./plugins/sup/package.json) | [](https://unpkg.com/@aomao/plugin-sup/dist/index.js) | 上标 |
| [`@aomao/plugin-tasklist`](./plugins/tasklist) | [](./plugins/tasklist/package.json) | [](https://unpkg.com/@aomao/plugin-tasklist/dist/index.js) | 任务列表 |
| [`@aomao/plugin-underline`](./plugins/underline) | [](./plugins/underline/package.json) | [](https://unpkg.com/@aomao/plugin-underline/dist/index.js) | 下划线 |
| [`@aomao/plugin-undo`](./plugins/undo) | [](./plugins/undo/package.json) | [](https://unpkg.com/@aomao/plugin-undo/dist/index.js) | 撤销 |
| [`@aomao/plugin-unorderedlist`](./plugins/unorderedlist) | [](./plugins/unorderedlist/package.json) | [](https://unpkg.com/@aomao/plugin-unorderedlist/dist/index.js) | 无序列表 |
| [`@aomao/plugin-image`](./plugins/image) | [](./plugins/image/package.json) | [](https://unpkg.com/@aomao/plugin-image/dist/index.js) | 图片 |
| [`@aomao/plugin-table`](./plugins/table) | [](./plugins/table/package.json) | [](https://unpkg.com/@aomao/plugin-table/dist/index.js) | 表格 |
| [`@aomao/plugin-file`](./plugins/file) | [](./plugins/file/package.json) | [](https://unpkg.com/@aomao/plugin-file/dist/index.js) | 文件 |
| [`@aomao/plugin-mark-range`](./plugins/mark-range) | [](./plugins/mark-range/package.json) | [](https://unpkg.com/@aomao/plugin-mark-range/dist/index.js) | 标记光标, 例如: 批注. |
| [`@aomao/plugin-math`](./plugins/math) | [](./plugins/math/package.json) | [](https://unpkg.com/@aomao/plugin-math/dist/index.js) | 数学公式 |
| [`@aomao/plugin-video`](./plugins/video) | [](./plugins/video/package.json) | [](https://unpkg.com/@aomao/plugin-video/dist/index.js) | 视频 |
## 快速上手
### 安装
编辑器由 `引擎`、`工具栏`、`插件` 组成。`引擎` 为我们提供了核心的编辑能力。
使用 `npm` 或者 `yarn` 安装引擎包
```bash
$ npm install @aomao/engine
# or
$ yarn add @aomao/engine
```
### 使用
我们按照惯例先输出一个`Hello world!`
```tsx
import React, { useEffect, useRef, useState } from 'react';
import Engine, { EngineInterface } from '@aomao/engine';
const EngineDemo = () => {
//编辑器容器
const ref = useRef(null);
//引擎实例
const [engine, setEngine] = useState();
//编辑器内容
const [content, setContent] = useState('Hello world!
');
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 ;
};
export default EngineDemo;
```
### 插件
引入 `@aomao/plugin-bold` 加粗插件
```tsx
import Bold from '@aomao/plugin-bold';
```
把 `Bold` 插件加入引擎
```tsx
//实例化引擎
const engine = new Engine(ref.current, {
plugins: [Bold],
});
```
### 卡片
卡片是编辑器中的一个独立区域，其 UI 和逻辑在卡片内部可以使用 `React`、`Vue` 或其他前端库自定义渲染内容，最后再挂载到编辑器上。
我们引入了 `@aomao/plugin-codeblock` 代码块插件，该插件的语言下拉框使用 `React` 渲染，因此有所区别。Vue3 则使用 `@aomao/plugin-codeblock-vue`。
```tsx
import CodeBlock, { CodeBlockComponent } from '@aomao/plugin-codeblock';
```
把 `CodeBlock` 插件和 `CodeBlockComponent` 卡片组件加入引擎
```tsx
//实例化引擎
const engine = new Engine(ref.current, {
plugins: [CodeBlock],
cards: [CodeBlockComponent],
});
```
`CodeBlock` 插件默认支持 `markdown`，在编辑器一行开头位置输入代码块语法` ```javascript ` 空格后即可触发。
## 节点约束
为了更方便的管理节点，降低复杂性。编辑器抽象化了节点属性和功能，制定了 `mark` `inline` `block` `card` 4 种类型节点，他们由不同的属性、样式或 `html` 结构组成，并统一使用 `schema` 对它们进行约束。
一个简单的 `schema` 看起来像是这样：
```ts
{
name: 'p', // 节点名称
type: 'block' // 节点类型
}
```
除此之外，还可以描述属性、样式等，比如：
```ts
{
name: 'span', // 节点名称
type: 'mark', // 节点类型
attributes: {
// 节点有一个 style 属性
style: {
// 必须包含一个color的样式
color: {
required: true, // 必须包含
value: '@color' // 值是一个符合css规范的颜色值，@color 是编辑器内部定义的颜色效验，此处也可以使用方法、正则表达式去判断是否符合需要的规则
}
},
// 可选的包含一个 test 属性，他的值可以是任意的，但不是必须的
test: '*'
}
}
```
下面这几种节点都符合上面的规则：
```html
```
但是除了在 color 和 test 已经在 `schema` 中定义外，其它的属性(background-color、test1)在处理时都会被编辑器过滤掉。
可编辑器区域内的节点通过 `schema` 规则，制定了 `mark` `inline` `block` `card` 4 种组合节点，他们由不同的属性、样式或 `html` 结构组成，并对它们的嵌套进行了一定的约束。
### 工具栏
引入 `@aomao/toolbar` 工具栏，工具栏由于交互复杂，基本上都是使用 `React` + `Antd` UI 组件渲染，`Vue3` 使用 `@aomao/toolbar-vue`
工具栏除了 UI 交互外，大部分工作只是对不同的按钮事件触发后调用了引擎执行对应的插件命令，在需求比较复杂或需要重新定制 UI 的情况下，Fork 后修改起来也比较容易。
```tsx
import Toolbar, { ToolbarPlugin, ToolbarComponent } from '@aomao/toolbar';
```
把 `ToolbarPlugin` 插件和 `ToolbarComponent` 卡片组件加入引擎，它可以让我们在编辑器中可以使用快捷键 `/` 唤醒出卡片工具栏
```tsx
//实例化引擎
const engine = new Engine(ref.current, {
plugins: [ToolbarPlugin],
cards: [ToolbarComponent],
});
```
渲染工具栏，工具栏已配置好所有插件，这里我们只需要传入插件名称即可
```tsx
return (
...
{
engine && (
)
}
...
)
```
更复杂的工具栏配置请查看文档 [https://editor.aomao.com/zh-CN/config/toolbar](https://editor.aomao.com/zh-CN/config/toolbar)
### 协同编辑
该开源库通过监听编辑区域(contenteditable 根节点)内的 html 结构的变化，使用 `MutationObserver` 反推数据结构，并通过 `WebSocket` 与 [Yjs](https://github.com/yjs/yjs) 连接交互，实现多用户协同编辑的功能。
#### 交互模式
每位编辑者作为 [客户端](https://github.com/red-axe/am-editor/blob/master/examples/react/components/editor/index.tsx#L250) 通过 `@aomao/plugin-yjs-websocket` 插件中的 `Websocket` 与 [服务端](https://github.com/big-camel/am-editor/tree/master/yjs-server) 进行通信交互。
- `@aomao/yjs` 实现编辑器与 `Yjs` 数据的转换
- `@aomao/plugin-yjs-websocket` 提供编辑器与 `Yjs` 的 `WebSocket` 客户端功能
- `@aomao/plugin-yjs-websocket/server` 提供 `Yjs` 的 `WebSocket` 服务端，使用 Node.js 编写，并支持使用 `MongoDB` 和 `LevelDB` 存储数据。
### 项目图标
[Iconfont](https://at.alicdn.com/t/project/1456030/0cbd04d3-3ca1-4898-b345-e0a9150fcc80.html?spm=a313x.7781069.1998910419.35)
## 开发
### React
在使用该开源库之前，需要先在项目根目录中安装依赖。
```base
yarn install
leran bootstrap
```
依赖安装好后，只需要在根目录执行以下命令即可启动项目：
```base
yarn start
```
该开源库的开发目录结构如下：
- `packages` 存放引擎和工具栏相关代码
- `plugins` 存放所有的插件
- `api` 提供一些插件所需要的 API 访问，默认使用 https://editor.aomao.com 作为 API 服务
- `yjs-server` 存放协同服务端代码，可通过 `yarn dev` 启动服务。
### Vue
[am-editor vue example](https://github.com/red-axe/am-editor-vue3-demo)
## 贡献
感谢 [pleasedmi](https://github.com/pleasedmi)、[Elena211314](https://github.com/Elena211314)、[zb201307](https://github.com/zb201307)、[cheon](https://github.com/number317) 的捐赠
如果您愿意，可以在这里留下你的名字。
### 支付宝
### 微信支付
### PayPal
[https://paypal.me/aomaocom](https://paypal.me/aomaocom)