am-editor

A rich text collaborative editor framework that can use React and Vue custom plug-ins

中文 · Demo · Documentation · Plugins · QQ-Group 907664876 ·

Thanks to Google Translate

Use the contenteditable attribute provided by the browser to make a DOM node editable.

The engine takes over most of the browser's default behaviors such as cursors and events.

Monitor the changes of the DOM tree in the editing area through MutationObserver, and generate a data format of json0 type to interact with the ShareDB library to achieve collaborative editing Needs.

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

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

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

Features

• Out of the box, it provides dozens of rich plug-ins to meet most needs
• High extensibility, in addition to the basic plug-in of mark, inlineandblocktype, we also providecardcomponent combined withReact, Vue and other front-end libraries to render the plug-in UI
• Rich multimedia support, not only supports pictures, audio and video, but also supports insertion of embedded multimedia content
• Support Markdown syntax
• Support internationalization
• The engine is written in pure JavaScript and does not rely on any front-end libraries. Plug-ins can be rendered using front-end libraries such as React and Vue. Easily cope with complex architecture
• Built-in collaborative editing program, ready to use with lightweight configuration
• Compatible with most of the latest mobile browsers

Plugins

Package	Version	Size	Description
@aomao/toolbar			Toolbar, for React.
@aomao/toolbar-vue			Toolbar, for Vue3.
am-editor-toolbar-vue2			Toolbar, for Vue2
@aomao/plugin-alignment			Alignment.
@aomao/plugin-backcolor			Background color.
@aomao/plugin-bold			Bold.
@aomao/plugin-code			Inline code.
@aomao/plugin-codeblock			Code block, for React.
@aomao/plugin-codeblock-vue			Code block, for Vue3.
am-editor-codeblock-vue2			Code Block, for Vue2
@aomao/plugin-fontcolor			Font color.
@aomao/plugin-fontfamily			Font.
@aomao/plugin-fontsize			Font size.
@aomao/plugin-heading			Heading.
@aomao/plugin-hr			Dividing line.
@aomao/plugin-indent			Indent.
@aomao/plugin-italic			Italic.
@aomao/plugin-link			Link, for React.
@aomao/plugin-link-vue			Link, for Vue3.
am-editor-link-vue2			Link, for Vue2
@aomao/plugin-line-height			Line height.
@aomao/plugin-mark			Mark.
@aomao/plugin-mention			Mention
@aomao/plugin-orderedlist			Ordered list.
@aomao/plugin-paintformat			Format Painter.
@aomao/plugin-quote			Quote block.
@aomao/plugin-redo			Redo history.
@aomao/plugin-removeformat			Remove style.
@aomao/plugin-selectall			Select all.
@aomao/plugin-status			Status.
@aomao/plugin-strikethrough			Strikethrough.
@aomao/plugin-sub			Sub.
@aomao/plugin-sup			Sup.
@aomao/plugin-tasklist			task list.
@aomao/plugin-underline			Underline.
@aomao/plugin-undo			Undo history.
@aomao/plugin-unorderedlist			Unordered list.
@aomao/plugin-image			Image.
@aomao/plugin-table			Table.
@aomao/plugin-file			File.
@aomao/plugin-mark-range			Mark the cursor, for example: comment.
@aomao/plugin-math			Mathematical formula.
@aomao/plugin-video			Video.

Getting Started

Installation

The editor consists of engine, toolbar, and plugin. Engine provides us with core editing capabilities.

Install engine package using npm or yarn

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

Usage

We follow the convention to output a Hello word!

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 word!</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', (value) => {
			setContent(value);
			console.log(`value:${value}`);
		});
		//Set the engine instance
		setEngine(engine);
	}, []);

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

Plugins

Import @aomao/plugin-bold bold plug-in

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

Add the Bold plugin to the engine

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

Card

A card is a separate area in the editor. The UI and logic inside the card can be customized using React, Vue or other front-end libraries to customize the rendering content, and finally mount it to the editor.

Import the @aomao/plugin-codeblock code block plugin. The Language drop-down box of this plugin is rendered using React, so there is a distinction. Vue3 uses @aomao/plugin-codeblock-vue

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

Add the CodeBlock plugin and CodeBlockComponent card component to the engine

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

The CodeBlock plugin supports markdown by default. Enter the code block syntax ````javascript` at the beginning of a line in the editor to trigger it after pressing Enter.

Toolbar

Import the @aomao/toolbar toolbar. Due to the complex interaction, the toolbar is basically rendered using React + Antd UI components, while Vue3 uses @aomao/toolbar-vue

Except for UI interaction, most of the work of the toolbar is just to call the engine to execute the corresponding plug-in commands after different button events are triggered. In the case of complicated requirements or the need to re-customize the UI, it is easier to modify after the fork.

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

Add the ToolbarPlugin plugin and ToolbarComponent card component to the engine, which allows us to use the shortcut key / in the editor to wake up the card toolbar

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

Rendering toolbar, the toolbar has been configured with all plug-ins, here we only need to pass in the plug-in name

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

For more complex toolbar configuration, please check the document https://editor.yanmao.cc/config/toolbar

Collaborative editing

Collaborative editing is implemented based on the ShareDB open source library. Those who are unfamiliar can learn about it first.

Interactive mode

Each editor acts as a Client through WebSocket and Server Communication and exchange of data in json0 format generated by the editor.

The server will keep a copy of the html structure data in the json format. After receiving the instructions from the client, it will modify the data, and finally forward it to each client.

Before enabling collaborative editing, we need to configure Client and Server

The server is a NodeJs environment, and a network service built using express + WebSocket.

Example

In the example, we have a relatively basic client code

View the complete React example

View the complete example of Vue3

View the complete example of Vue2

//Instantiate the collaborative editing client and pass in the current editor engine instance
const otClient = new OTClient(engine);
//Connect to the collaboration server, `demo` is the same as the server document ID
otClient.connect(
	`ws://127.0.0.1:8080${currentMember ? '?uid=' + currentMember.id : ''}`,
	'demo',
);

Project icon

Iconfont

Development

React

Need to install dependencies separately in am-editor root directory site-ssr ot-server

//After the dependencies are installed, you only need to execute the following commands in the root directory

yarn ssr

• packages engine and toolbar
• plugins all plugins
• site-ssr All backend API and SSR configuration. The egg used. Use yarn ssr in the am-editor root directory to automatically start site-ssr
• ot-server collaborative server. Start: yarn start

Visit localhost:7001 after startup

Vue

Just enter the examples/vue directory to install the dependencies

//After the dependencies are installed, execute the following commands in the examples/vue directory

yarn serve

In the Vue runtime environment, the default is the installed code that has been published to npm. If you need to modify the code of the engine or plug-in and see the effect immediately, we need to do the following steps:

• Delete the examples/vue/node_modules/@aomao folder
• Delete the examples/vue/node_modules/vue folder. Because there are plugins that depend on Vue, the Vue package will be installed in the project root directory. If you do not delete the Vue package in examples/vue, and the Vue package of the plugin is not in the same environment, the plugin cannot be loaded
• Execute and install all dependent commands in the root directory of am-editor, for example: yarn
• Finally restart in examples/vue

There is no backend API configured in the Vue case. For details, please refer to React and site-ssr

Contribution

Thanks pleasedmi、Elena211314、zb201307 for donation

Alipay

WeChat Pay

PayPal

https://paypal.me/aomaocom