Edtr.io API完全参考：从基础使用到高级功能调用

Edtr.io API完全参考：从基础使用到高级功能调用

【免费下载链接】edtr-ioEdtr.io is an open source WYSIWYG in-line web editor written in React. Its plugin architecture makes Edtr.io lean and extensive at the same time.项目地址: https://gitcode.com/gh_mirrors/ed/edtr-io

Edtr.io 是一个基于 React 构建的开源 WYSIWYG 在线编辑器，其插件架构使其兼具轻量与扩展性。本文将全面解析 Edtr.io 的 API 体系，帮助开发者从基础集成到高级功能定制，快速掌握这个强大编辑器的使用方法。

核心概念与架构概览 🧩

Edtr.io 的核心设计围绕插件化架构展开，所有功能通过插件实现。这种设计使编辑器能够按需加载功能，保持核心体积精简的同时支持丰富的扩展。项目主要 API 定义集中在以下目录：

• 核心 API：api/core.api.md
• 插件系统 API：api/plugin.api.md
• 渲染器 API：api/renderer.api.md
• 工具栏 API：api/plugin-toolbar.api.md

编辑器工作流示例

上图展示了 Edtr.io 的实际编辑界面，左侧为内容编辑区，右侧为互动练习组件，体现了其支持复杂内容类型的能力。

快速开始：基础 API 使用指南 🚀

1. 安装与初始化

要开始使用 Edtr.io，首先需要克隆仓库：

git clone https://gitcode.com/gh_mirrors/ed/edtr-io

2. 核心 Editor 组件

Editor组件是 Edtr.io 的入口点，定义在 api/core.api.md 中。基础使用示例：

import { Editor } from '@edtr-io/core' import { textPlugin } from '@edtr-io/plugin-text' const MyEditor = () => ( <Editor initialState={{ plugin: 'text', state: { content: 'Hello Edtr.io!' } }} plugins={{ text: textPlugin() }} /> )

关键参数说明：

• initialState: 指定初始编辑器内容和插件
• plugins: 注册可用插件集合
• editable: 控制编辑状态（默认为true）
• onChange: 内容变化回调函数

3. 状态管理基础

Edtr.io 使用 Redux 进行状态管理，提供了便捷的 hooks 访问作用域状态：

import { useScopedSelector, useScopedDispatch } from '@edtr-io/core' const MyComponent = () => { const content = useScopedSelector(state => state.content) const dispatch = useScopedDispatch() return ( <div> <p>{content}</p> <button onClick={() => dispatch(/* 操作 */)}>更新内容</button> </div> ) }

插件开发：构建自定义功能 🔌

1. 插件基础结构

每个插件遵循统一的接口定义，位于 packages/plugins/ 目录下。典型插件结构：

plugin-name/ ├── src/ │ ├── editor.tsx # 编辑组件 │ ├── renderer.tsx # 渲染组件 │ ├── config.ts # 配置定义 │ └── index.ts # 导出入口 └── package.json

2. 状态类型定义

使用插件 API 可以定义各种状态类型，如文本、数字、列表等：

import { string, number, list, object } from '@edtr-io/plugin' // 定义插件状态结构 const stateType = object({ title: string(''), count: number(0), items: list(string('')) })

常用状态类型 API：

• string(): 文本状态
• number(): 数字状态
• boolean(): 布尔状态
• list(): 列表状态
• object(): 对象状态
• child(): 子文档状态

3. 完整插件示例

以下是一个简单的计数器插件实现：

// src/index.ts import { EditorPlugin } from '@edtr-io/plugin' import { number } from '@edtr-io/plugin' import { CounterEditor } from './editor' import { CounterRenderer } from './renderer' export const counterPlugin: EditorPlugin = () => ({ stateType: number(0), Editor: CounterEditor, Renderer: CounterRenderer }) // src/editor.tsx export const CounterEditor = ({ state }) => ( <div> <button onClick={() => state.set(prev => prev - 1)}>-</button> <span>{state.value}</span> <button onClick={() => state.set(prev => prev + 1)}>+</button> </div> )

高级功能：深入 API 能力 ⚡

1. 子文档管理

Edtr.io 支持嵌套文档结构，通过SubDocument组件实现：

import { SubDocument } from '@edtr-io/core' const MyEditor = () => ( <div> <h2>主文档</h2> <SubDocument id="nested-document" /> </div> )

相关 API 定义在 api/core.api.md 的SubDocument接口中。

2. 文件上传处理

文件上传功能通过upload状态类型实现，定义在 api/plugin.api.md：

import { upload } from '@edtr-io/plugin' const stateType = upload({ url: '', name: '' }) // 在组件中使用 const FileUploader = ({ state }) => { const handleUpload = async (file) => { const result = await uploadFileToServer(file) state.set(result) } return <input type="file" onChange={(e) => handleUpload(e.target.files[0])} /> }

3. 主题定制

通过theme属性自定义编辑器样式：

<Editor initialState={...} plugins={...} theme={{ colors: { primary: '#4a6fff', secondary: '#ff7d00' }, fontFamily: 'Inter, sans-serif' }} />

主题接口定义在 api/ui.api.md 中。

常用插件 API 参考 📚

Edtr.io 提供了丰富的官方插件，每个插件都有独立的 API 文档：

文本插件高级用法

文本插件支持丰富的格式化功能和事件处理：

import { textPlugin } from '@edtr-io/plugin-text' const customTextPlugin = textPlugin({ maxLength: 1000, allowedFormats: ['bold', 'italic', 'link'], onLinkClick: (url) => { console.log('点击链接:', url) return false // 阻止默认行为 } })

最佳实践与性能优化 🛠️

1. 插件按需加载

为优化初始加载速度，建议使用动态导入加载非核心插件：

const ImagePlugin = React.lazy(() => import('@edtr-io/plugin-image')) // 在编辑器中使用 <Editor plugins={{ text: textPlugin(), image: ImagePlugin() }} />

2. 状态变更优化

使用useScopedSelector的选择器函数优化渲染性能：

// 避免不必要的重渲染 const title = useScopedSelector(state => state.title, (prev, next) => prev === next)

3. 错误处理

通过onError回调捕获编辑器错误：

<Editor initialState={...} plugins={...} onError={(error, info) => { logErrorToService(error, info) showUserFriendlyMessage() }} />

总结与资源 📝

Edtr.io 的 API 设计注重灵活性和可扩展性，通过插件系统和状态管理提供了构建复杂富文本编辑器的完整解决方案。无论是简单的文本编辑还是复杂的教育内容创作，Edtr.io 都能满足需求。

扩展资源

• 官方插件源码：packages/plugins/
• 核心编辑器实现：packages/public/core/src/editor.tsx
• 状态管理实现：packages/public/store/src/

通过本文介绍的 API 和示例，您应该能够快速上手 Edtr.io 并构建自定义编辑器解决方案。如需深入了解某个具体 API，建议查阅对应的 API 文档文件。

【免费下载链接】edtr-ioEdtr.io is an open source WYSIWYG in-line web editor written in React. Its plugin architecture makes Edtr.io lean and extensive at the same time.项目地址: https://gitcode.com/gh_mirrors/ed/edtr-io