安装

介绍

除引擎库纯javascript编写外，我们所提供的插件中，小部分插件 UI 比较复杂，使用前端库来渲染 UI 是一项比较轻松的工作。

下面这三个插件有区别

  • @aomao/toolbar 编辑器工具栏。按钮、图标、下拉框、颜色选择器等都是复杂的 UI

  • @aomao/plugin-codeblock 选择代码语言的下拉框具有搜索功能，使用前端库现有的 UI 是比较好的选择

  • @aomao/plugin-link 链接输入、文本输入，使用前端库现有的 UI 是比较好的选择

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

Vue3 案例 https://github.com/red-axe/am-editor-vue

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

安装

使用 npm 或者 yarn 安装编辑引擎

  1. $ npm install @aomao/engine
  2. # or
  3. $ yarn add @aomao/engine

使用

我们按从输出一个Hello word!入手。现在你可以在下方编辑了。

  1. /**
  2.  * defaultShowCode: true
  3.  */
  4. import React, { useEffect, useRef, useState } from 'react';
  5. import Engine, { EngineInterface } from '@aomao/engine';
  7. const EngineDemo = () => {
  8.     //编辑器容器
  9.     const ref = useRef<HTMLDivElement | null>(null);
  10.     //引擎实例
  11.     const [engine, setEngine] = useState<EngineInterface>();
  12.     //编辑器内容
  13.     const [content, setContent] = useState<string>('Hello word!');
  15.     useEffect(() => {
  16.         if (!ref.current) return;
  17.         //实例化引擎
  18.         const engine = new Engine(ref.current);
  19.         //设置编辑器值
  20.         engine.setValue(content);
  21.         //监听编辑器值改变事件
  22.         engine.on('change', () => {
  23.             const value = engine.getValue();
  24.             setContent(value);
  25.             console.log(`value:${value}`);
  26.         });
  27.         //设置引擎实例
  28.         setEngine(engine);
  29.     }, []);
  31.     return <div ref={ref} />;
  32. };
  33. export default EngineDemo;

插件

现在我们在上述代码基础上，引入@aomao/plugin-bold加粗插件

```tsx | pure import Bold from ‘@aomao/plugin-bold’;

  2. 然后将`Bold`插件加入引擎
  4. ```tsx | pure
  5. //实例化引擎
  6. const engine = new Engine(ref.current, {
  7.     plugins: [Bold],
  8. });

Bold插件的默认快捷键为 windows ctrl+b 或 mac ⌘+b，现在试试加粗效果吧

  1. import React, { useEffect, useRef, useState } from 'react';
  2. import Engine, { EngineInterface } from '@aomao/engine';
  3. import Bold from '@aomao/plugin-bold';
  5. const EngineDemo = () => {
  6.     //编辑器容器
  7.     const ref = useRef<HTMLDivElement | null>(null);
  8.     //引擎实例
  9.     const [engine, setEngine] = useState<EngineInterface>();
  10.     //编辑器内容
  11.     const [content, setContent] = useState<string>(
  12.         'Hello <strong>word</strong>!',
  13.     );
  15.     useEffect(() => {
  16.         if (!ref.current) return;
  17.         //实例化引擎
  18.         const engine = new Engine(ref.current, {
  19.             plugins: [Bold],
  20.         });
  21.         //设置编辑器值
  22.         engine.setValue(content);
  23.         //监听编辑器值改变事件
  24.         engine.on('change', () => {
  25.             const value = engine.getValue();
  26.             setContent(value);
  27.             console.log(`value:${value}`);
  28.         });
  29.         //设置引擎实例
  30.         setEngine(engine);
  31.     }, []);
  33.     return <div ref={ref} />;
  34. };
  35. export default EngineDemo;

卡片

卡片是编辑器中单独划分的一个区域，该区域的 UI 可以使用 React、Vue 等前端框架自定义渲染内容，最后再挂载到编辑器上。

引入@aomao/plugin-codeblock代码块插件，这个插件部分 UI 使用前端框架渲染，所以有区分。 vue3开发者使用 @aomao/plugin-codeblock-vue vue2开发者使用 am-editor-codeblock-vue2

```tsx | pure import CodeBlock, { CodeBlockComponent } from ‘@aomao/plugin-codeblock’;

  2. 将`CodeBlock`插件和`CodeBlockComponent`卡片组件加入引擎
  4. ```tsx | pure
  5. //实例化引擎
  6. const engine = new Engine(ref.current, {
  7.     plugins: [CodeBlock],
  8.     cards: [CodeBlockComponent],
  9. });

CodeBlock插件默认支持markdown，在编辑器一行开头位置输入代码块语法```javascript回车后，看看效果吧

  1. import React, { useEffect, useRef, useState } from 'react';
  2. import Engine, { EngineInterface } from '@aomao/engine';
  3. import CodeBlock, { CodeBlockComponent } from '@aomao/plugin-codeblock';
  5. const EngineDemo = () => {
  6.     //编辑器容器
  7.     const ref = useRef<HTMLDivElement | null>(null);
  8.     //引擎实例
  9.     const [engine, setEngine] = useState<EngineInterface>();
  10.     //编辑器内容
  11.     const [content, setContent] = useState<string>(
  12.         'Hello <strong>word</strong>!',
  13.     );
  15.     useEffect(() => {
  16.         if (!ref.current) return;
  17.         //实例化引擎
  18.         const engine = new Engine(ref.current, {
  19.             plugins: [CodeBlock],
  20.             cards: [CodeBlockComponent],
  21.         });
  22.         //设置编辑器值
  23.         engine.setValue(content);
  24.         //监听编辑器值改变事件
  25.         engine.on('change', () => {
  26.             const value = engine.getValue();
  27.             setContent(value);
  28.             console.log(`value:${value}`);
  29.         });
  30.         //设置引擎实例
  31.         setEngine(engine);
  32.     }, []);
  34.     return <div ref={ref} />;
  35. };
  36. export default EngineDemo;

工具栏

引入@aomao/toolbar工具栏，工具栏 UI 比较复杂，都是借助使用前端框架渲染，vue3开发者使用 @aomao/toolbar-vue vue2开发者使用 am-editor-toolbar-vue2

```tsx | pure import Toolbar, { ToolbarPlugin, ToolbarComponent } from ‘@aomao/toolbar’;

  2. 将`ToolbarPlugin`插件和`ToolbarComponent`卡片组件加入引擎，它将让我们在编辑器中可以使用快捷键`/`唤醒出工具栏
  4. ```tsx | pure
  5. //实例化引擎
  6. const engine = new Engine(ref.current, {
  7.     plugins: [ToolbarPlugin],
  8.     cards: [ToolbarComponent],
  9. });

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

```tsx | pure return ( … { engine && ( ) } … )

  2. ```tsx
  3. /**
  4.  * transform: true
  5.  */
  6. import React, { useEffect, useRef, useState } from 'react';
  7. import Engine, { EngineInterface } from '@aomao/engine';
  8. import Bold from '@aomao/plugin-bold';
  9. import CodeBlock, { CodeBlockComponent } from '@aomao/plugin-codeblock';
  10. import Toolbar, { ToolbarPlugin, ToolbarComponent } from '@aomao/toolbar';
  12. const EngineDemo = () => {
  13.     //编辑器容器
  14.     const ref = useRef<HTMLDivElement | null>(null);
  15.     //引擎实例
  16.     const [engine, setEngine] = useState<EngineInterface>();
  17.     //编辑器内容
  18.     const [content, setContent] = useState<string>(
  19.         'Hello <strong>word</strong>!',
  20.     );
  22.     useEffect(() => {
  23.         if (!ref.current) return;
  24.         //实例化引擎
  25.         const engine = new Engine(ref.current, {
  26.             plugins: [CodeBlock, Bold, ToolbarPlugin],
  27.             cards: [CodeBlockComponent, ToolbarComponent],
  28.         });
  29.         //设置编辑器值
  30.         engine.setValue(content);
  31.         //监听编辑器值改变事件
  32.         engine.on('change', () => {
  33.             const value = engine.getValue();
  34.             setContent(value);
  35.             console.log(`value:${value}`);
  36.         });
  37.         //设置引擎实例
  38.         setEngine(engine);
  39.     }, []);
  41.     return (
  42.         <>
  43.             {engine && <Toolbar engine={engine} items={[['bold']]} />}
  44.             <div ref={ref} />
  45.         </>
  46.     );
  47. };
  48. export default EngineDemo;

自己开发工具栏

@aomao/toolbar 更多的是提供了一个工具栏的 UI 展示，本质是调用 engine.command.execute 执行插件命令

  1. /**
  2.  * transform: true
  3.  */
  4. import React, { useEffect, useRef, useState } from 'react';
  5. import Engine, { EngineInterface } from '@aomao/engine';
  6. import Bold from '@aomao/plugin-bold';
  8. const EngineDemo = () => {
  9.     //编辑器容器
  10.     const ref = useRef<HTMLDivElement | null>(null);
  11.     //引擎实例
  12.     const [engine, setEngine] = useState<EngineInterface>();
  13.     //编辑器内容
  14.     const [content, setContent] = useState<string>(
  15.         'Hello <strong>word</strong>!',
  16.     );
  17.     // 按钮状态
  18.     const [btnActive, setBtnActive] = useState<boolean>(false);
  20.     useEffect(() => {
  21.         if (!ref.current) return;
  22.         //实例化引擎
  23.         const engine = new Engine(ref.current, {
  24.             plugins: [Bold],
  25.         });
  26.         //设置编辑器值
  27.         engine.setValue(content);
  28.         //监听编辑器值改变事件
  29.         engine.on('change', () => {
  30.             const value = engine.getValue();
  31.             setContent(value);
  32.             console.log(`value:${value}`);
  33.         });
  34.         // 监听光标改变
  35.         engine.on('select', () => {
  36.             // 查询bold插件的选中状态
  37.             setBtnActive(engine.command.queryState('bold'));
  38.         });
  39.         //设置引擎实例
  40.         setEngine(engine);
  41.     }, []);
  43.     const handleMouseDown = (event: React.MouseDown) => {
  44.         // 点击按钮避免编辑器光标丢失
  45.         event.preventDefault();
  46.     };
  48.     const handleBoldClick = () => {
  49.         // 执行加粗命令
  50.         engine?.command.execute('bold');
  51.     };
  53.     return (
  54.         <>
  55.             {engine && (
  56.                 <button
  57.                     onMouseDown={handleMouseDown}
  58.                     onClick={handleBoldClick}
  59.                     style={{ color: btnActive ? 'blue' : '' }}
  60.                 >
  61.                     Bold
  62.                 </button>
  63.             )}
  64.             <div ref={ref} />
  65.         </>
  66.     );
  67. };
  68. export default EngineDemo;

协同编辑

协同编辑基于ShareDB实现。每位编辑者作为客户端通过WebSocket与服务端通信交换数据。编辑器处理数据、渲染数据。

我们需要把服务端搭建好，然后配置客户端。查看完整示例

tsx | pure //实例化协作编辑客户端，传入当前编辑器引擎实例 const otClient = new OTClient(engine); //连接到协作服务端，uid这里做一个简单的身份验证演示，正常业务中应该需要token等身份验证信息。`demo` 是文档的唯一编号 otClient.connect( `ws://127.0.0.1:8080${currentMember ? '?uid=' + currentMember.id : ''}`, 'demo', );