repository·master·Indexed 23 days ago
https://github.com/microsoft/roosterjsA framework-independent JavaScript rich-text editor that operates on an internal Content Model rather than directly on the DOM. It provides a robust architecture for building customizable editors by separating content representation from the rendering layer. The library includes a facade for quick starts, a core content model for deep customization, and specialized packages for DOM conversion, plugins, and legacy v8 compatibility via the roosterjs-editor-adapter.
In addition to the core packages, RoosterJS provides specialized extension packages:
roosterjs-content-model-markdown: Provides public APIs to enable conversions between Markdown and the RoosterJS Content Model.roosterjs-color-utils: Provides color transformation utilities to support dark mode in your editor.RoosterJS is modular. Depending on whether you want a quick start or a highly customized editor, you should choose from the following core packages:
roosterjs: A facade package for a quick start. Use createEditor() to create an editor with default configurations.roosterjs-content-model-core: The foundation for building and customizing your own editor. Use this instead of the facade if you need to define custom infrastructure.roosterjs-content-model-api: Provides the APIs required to modify content and formatting within an editor built with roosterjs-content-model-core.roosterjs-content-model-dom: Handles conversions between the DOM tree and the RoosterJS Content Model.roosterjs-content-model-plugins: Contains basic plugins for common editor features.roosterjs-content-model-types: Contains all public interfaces, enumerations, Content Model types, and API parameters.RoosterJS is built on a middle layer called the Content Model. All formatting APIs and editing operations use this Content Model as the internal format, which is then converted to HTML for display.
Depending on your needs, you can use different packages:
roosterjs: A facade for quick starts using createEditor().roosterjs-content-model-core: The foundation for building and customizing your own editor. Use this instead of the facade if you need deep customization.roosterjs-content-model-api: Provides APIs for scenario-based operations (e.g., user-triggered formatting).roosterjs-content-model-dom: Handles conversion between the DOM tree and the Content Model.roosterjs-content-model-plugins: Contains basic plugins for common features.roosterjs-content-model-types: Defines public interfaces, enumerations, and Content Model types.To quickly implement a rich-text editor, use the roosterjs.createEditor() function. This function takes a DOM element (like a <div>) and initializes the editor within it. You can then use facade methods like toggleBold, toggleItalic, and toggleUnderline to perform formatting operations.
<html
<body>
<div style="width: 500px; height: 400px; border: solid 1px black" id="contentDiv"></div>
<button id="buttonB">B</button> <button id="buttonI">I</button>
<button id="buttonU">U</button>
<script src="rooster.js"></script>
<script>
var contentDiv = document.getElementById('contentDiv');
var editor = roosterjs.createEditor(contentDiv);
editor.setContent('Welcome to <b>RoosterJs</b>!');
document.getElementById('buttonB').addEventListener('click', function () {
roosterjs.toggleBold(editor);
});
document.getElementById('buttonI').addEventListener('click', function () {
roosterjs.toggleItalic(editor);
});
document.getElementById('buttonU').addEventListener('click', function () {
roosterjs.toggleUnderline(editor);
});
</script>
</body>
</html>The EditorAdapter class allows RoosterJS v9 packages to remain compatible with legacy v8 plugins. It works by providing a translation of Content Model plugin events that are compatible with the older plugin architecture.
To implement this, replace the standard Editor class with EditorAdapter and move your existing v8 plugins into the legacyPlugins property of the EditorAdapterOptions object.
import { EditorAdapter } from 'roosterjs-editor-adapter';
// ...
const options: EditorAdapterOptions = {
legacyPlugins: [], /// Array of V8 plugins
plugins: [], /// Array of v9 plugins
...
};
return new EditorAdapter(div, options);To enable compatibility between RoosterJS v9 and legacy (v8._) plugins, install the roosterjs-editor-adapter package via npm.
npm install roosterjs-editor-adapterYou can install the full RoosterJS facade or individual sub-packages using NPM or Yarn. The roosterjs package is recommended for a quick start as it provides a facade for all Rooster code and includes the createEditor() function with default configurations.
# Install the full package
yarn add roosterjs
# Or install sub-packages separately
yarn add roosterjs-content-model-core
yarn add roosterjs-content-model-apiIf you are upgrading to RoosterJS v9.* but need to support legacy v8.* plugins, use the EditorAdapter class from the roosterjs-editor-adapter package. This class allows the new editor to act like a v8.* editor.
Legacy plugins can be registered via the EditorAdapterOptions.legacyPlugins option.
If you are migrating from version 8.*, please refer to the official migration guide on the RoosterJS Wiki: https://github.com/microsoft/roosterjs/wiki/RoosterJs-9.
To maintain compatibility with legacy plugins from version 8., you can use the EditorAdapter class from the roosterjs-editor-adapter package. This allows the new Editor (9.) to work with old plugins via the EditorAdapterOptions.legacyPlugins option.
roosterjs-content-model-plugins package provides a collection of plugins to extend the functionality of a RoosterJS editor. These plugins handle various editor features such as formatting, shortcuts, table editing, markdown support, and more. You can import specific plugins and their associated options/types to customize your editor experience.Plugins allow you to intercept editor events and perform custom logic. To create a plugin, implement the EditorPlugin interface, providing getName(), initialize(), dispose(), and onPluginEvent(). The onPluginEvent method allows you to react to specific eventTypes (like 'input') and inspect the rawEvent.
class HelloRooster implements EditorPlugin {
getName() {
return 'HelloRooster';
}
initialize(editor: IEditor) {}
dispose() {}
onPluginEvent(e: PluginEvent) {
if (e.eventType == 'input' && e.rawEvent.which == 65) {
alert('Hello Rooster');
}
}
}When using EditorAdapter, the options object uses specific keys to distinguish between plugin versions:
legacyPlugins: An array of RoosterJS v8 plugins.plugins: An array of RoosterJS v9 plugins.const options: EditorAdapterOptions = {
legacyPlugins: [], /// Array of V8 plugins
plugins: [], /// Array of v9 plugins
...
}