特性

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

插件

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

快速上手

安装

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

使用 npm 或者 yarn 安装引擎包

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

使用

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

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

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

插件

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

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

把 Bold 插件加入引擎

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

卡片

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

我们引入了 @hanfy/plugin-codeblock 代码块插件，该插件的语言下拉框使用 React 渲染，因此有所区别。Vue3 则使用 @hanfy/plugin-codeblock-vue。

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

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

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

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

节点约束

为了更方便的管理节点，降低复杂性。编辑器抽象化了节点属性和功能，制定了 mark inline block card 4 种类型节点，他们由不同的属性、样式或 html 结构组成，并统一使用 schema 对它们进行约束。

一个简单的 schema 看起来像是这样：

{
  name: 'p', // 节点名称
  type: 'block' // 节点类型
}

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

{
  name: 'span', // 节点名称
  type: 'mark', // 节点类型
  attributes: {
    // 节点有一个 style 属性
    style: {
      // 必须包含一个color的样式
      color: {
        required: true, // 必须包含
        value: '@color' // 值是一个符合css规范的颜色值，@color 是编辑器内部定义的颜色效验，此处也可以使用方法、正则表达式去判断是否符合需要的规则
      }
    },
    // 可选的包含一个 test 属性，他的值可以是任意的，但不是必须的
    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>

但是除了在 color 和 test 已经在 schema 中定义外，其它的属性(background-color、test1)在处理时都会被编辑器过滤掉。

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

工具栏

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

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

import Toolbar, { ToolbarPlugin, ToolbarComponent } from '@hanfy/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

协同编辑

该开源库通过监听编辑区域(contenteditable 根节点)内的 html 结构的变化，使用 MutationObserver 反推数据结构，并通过 WebSocket 与 Yjs 连接交互，实现多用户协同编辑的功能。

交互模式

每位编辑者作为 客户端 通过 @hanfy/plugin-yjs-websocket 插件中的 Websocket 与 服务端 进行通信交互。

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

项目图标

Iconfont

开发

React

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

yarn install

lerna bootstrap

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

yarn start

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

• packages 存放引擎和工具栏相关代码
• plugins 存放所有的插件
• api 提供一些插件所需要的 API 访问，默认使用 https://editor.aomao.com 作为 API 服务
• yjs-server 存放协同服务端代码，可通过 yarn dev 启动服务。

Vue

am-editor vue example

贡献