am-editor

机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

这里，我们有一个新的富文本编辑器，叫做 Editable，它不使用本地的可编辑属性 contenteditable，而是使用自定义渲染器。这种方法使我们能够更好地控制编辑器的行为。

am编辑器

一个支持协作编辑的富文本编辑器，你可以自由使用 React、Vue 及其他前端常用库来扩展和定义插件。

预览 · 文档 · 插件

Vue2

Vue3

React

Vue2 Demo

Vue2 Nuxt Demo

功能

• 🎁 开箱即用的解决方案，配备数十个丰富的插件以满足大多数需求
• 🚀 高度可扩展，除了提供用于标记、内联和块类型的基本插件外，我们还提供与前端库如 React 和 Vue 结合的卡片组件来渲染插件界面
• 🎨 丰富的多媒体支持，不仅支持图片和音频/视频，还支持嵌入多媒体内容
• 📝 支持 Markdown 语法
• 🌍 支持国际化
• 💻 引擎完全用 JavaScript 编写，不依赖任何前端库，插件可以使用 React 和 Vue 等前端库渲染。能够轻松处理复杂架构
• 👥 内置协作编辑解决方案，轻量级配置即可使用
• 📱 兼容大多数最新移动浏览器

插件

入门

安装

编辑器由 engine、toolbar 和 plugins 组成。engine 提供了核心编辑功能。

使用 npm 或 yarn 安装引擎包。

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

用法

我们将像往常一样先输出“Hello world!”消息。

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

const EngineDemo = () => {
    //Editor container
    const ref = useRef<HTMLDivElement | null>(null);
    //Engine instance
    const [engine, setEngine] = useState<EngineInterface>();
    //Editor content
    const [content, setContent] = useState<string>('<p>Hello world!</p>');

    useEffect(() => {
        if (!ref.current) return;
        //Instantiate the engine
        const engine = new Engine(ref.current);
        //Set the editor value
        engine.setValue(content);
        //Listen to the editor value change event
        engine.on('change', () => {
            const value = engine.getValue();
            setContent(value);
            console.log(`value:${value}`);
        });
        //Set the engine instance
        setEngine(engine);
    }, []);

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

插件

导入 @aomao/plugin-bold 粗体插件。

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

将 Bold 插件添加到引擎中。

//Instantiate the engine
const engine = new Engine(ref.current, {
    plugins: [Bold],
});

卡片

卡片是在编辑器中单独定义的区域，其 UI 和逻辑用于在卡片内部渲染自定义内容，可以使用 React、Vue 或其他前端库，然后再挂载到编辑器上。

介绍 @aomao/plugin-codeblock，这是一个带有语言下拉菜单的代码块插件，使用 React 渲染，与使用 @aomao/plugin-codeblock-vue 的 Vue3 区别开来。

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

将 CodeBlock 插件和 CodeBlockComponent 卡片组件添加到引擎中。

//Instantiate the engine
const engine = new Engine(ref.current, {
    plugins: [CodeBlock],
    cards: [CodeBlockComponent],
});

CodeBlock 插件默认支持 markdown。你可以在编辑器中通过在一行的开头输入代码块语法，然后加一个空格和语言名称来触发它，例如 ``` javascript。

节点约束

为了更方便地管理节点并减少复杂性，编辑器对节点属性和功能进行了抽象，并定义了四种类型的节点：mark、inline、block 和 card。它们由不同的属性、样式或 HTML 结构组成，并使用统一的模式进行约束。

一个简单的 schema 如下所示：

{
  name:'p', // node name
  type:'block' // node type
}

此外，还可以描述属性、样式等，例如：

{
  name:'span', // node name
  type:'mark', // node type
  attributes: {
    // The node has a style attribute
    style: {
      // Must contain a color style
      color: {
        required: true, // must contain
        value:'@color' // The value is a color value that conforms to the css specification. @color is the color validation defined in the editor. Here, methods and regular expressions can also be used to determine whether the required rules are met
      }
    },
    // Optional include a test attribute, its value can be arbitrary, but it is not required
    test:'*'
  }
}

以下类型的节点符合上述规则：

<span style="color:#fff"></span>
<span style="color:#fff" test="test123" test1="test1"></span>
<span style="color:#fff;background-color:#000;"></span>
<span style="color:#fff;background-color:#000;" test="test123"></span>

但除了颜色和测试已在 schema 中定义之外，其他属性（background-color、test1）将在处理过程中被编辑器过滤掉。

可编辑区域中的节点具有 mark、inline、块 , and、卡片 through the、模式 rule. They are composed of different attributes, styles or HTML 结构的四种组合节点。在嵌套方面施加了某些约束。

工具栏

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

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

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

将 ToolbarPlugin 插件和 ToolbarComponent 卡片组件添加到引擎中，这允许我们在编辑器中使用快捷键 / 来唤醒卡片工具栏

//Instantiate the engine
const engine = new Engine(ref.current, {
    plugins: [ToolbarPlugin],
    cards: [ToolbarComponent],
});

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

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

有关更复杂的工具栏配置，请查看文档 https://editor.aomao.com/config/toolbar

协作编辑

这个开源库监听编辑区域（contenteditable 根节点）的 HTML 结构的变化，使用 MutationObserver 对数据结构进行逆向工程，并通过 WebSocket 连接和与 Yjs 交互，以实现多用户协作编辑。

交互模式

每个编辑器作为 客户端，通过 @aomao/plugin-yjs-websocket 插件中的 WebSocket 功能与 服务器 进行通信和交互。

• @aomao/yjs 实现编辑器和 Yjs 数据的转换
• @aomao/plugin-yjs-websocket 提供编辑器和 Yjs 的 WebSocket 客户端功能
• @aomao/plugin-yjs-websocket/server 提供 Yjs 的 WebSocket 服务器，使用 Node.js 编写，并支持使用 MongoDB 和 LevelDB 进行数据存储。

项目图标

Iconfont

开发

反应

在使用这个开源库之前，你需要在项目根目录中安装依赖项。

yarn install

lerna bootstrap

安装依赖项后，你只需要在根目录下执行以下命令即可启动项目：

yarn start

此开源库的开发目录结构如下：

• packages 包含引擎和工具栏相关的代码
• plugins 包含所有插件
• api 提供某些插件所需的 API 访问，并使用 https://editor.aomao.com 作为默认 API 服务
• yjs-server 包含协作服务器代码，可由 yarn dev 启动。

Vue

am-editor vue 示例

贡献

感谢 pleasedmi、Elena211314、zb201307、cheon 的捐赠

支付宝

微信支付

贝宝

https://paypal.me/aomaocom