React-Page 项目中的自定义单元格插件开发指南

React-Page 项目中的自定义单元格插件开发指南

react-page Next-gen, highly customizable content editor for the browser - based on React and written in TypeScript. WYSIWYG on steroids. 项目地址: https://gitcode.com/gh_mirrors/rea/react-page

前言

React-Page 是一个强大的页面构建器，允许开发者创建灵活的内容编辑界面。其中，单元格插件(Cell Plugin)是构建内容块的核心概念。本文将深入讲解如何开发自定义单元格插件，帮助开发者充分利用 React-Page 的扩展能力。

什么是单元格插件？

单元格插件定义了用户可以在文档中添加的内容单元。每个插件由唯一ID、标题和一个渲染组件(Renderer)组成，Renderer 是显示在该单元格中的React组件。

基础插件结构

让我们从一个最简单的插件示例开始：

import { CellPlugin } from '@react-page/editor';
import React from 'react';

// 定义数据类型
type Data = {
  title: string
}

const myFirstCellPlugin: CellPlugin<Data> = {
  Renderer: ({ data }) => (
    <div>{data.title}</div>
  ),
  id: 'myFirstCellPlugin',
  title: '我的第一个单元格插件',
  description: '这个插件仅显示一个标题',
  version: 1,
  controls: {
    type: 'autoform',
    schema: {
      properties: {
        title: {
          type: 'string',
          default: '默认标题',
        },
      },
      required: ['title'],
    },
  },
};

核心属性详解

1. 基本属性

• id: 插件的唯一标识符，必须确保全局唯一
• title: 插件在菜单中显示的名称
• description: 插件的描述信息，显示在插件抽屉中
• icon: 可选的React节点，用于在插件抽屉中显示图标
• version: 数据版本号，当数据结构变更时需要递增

2. 渲染器(Renderer)

Renderer 是插件的核心组件，负责显示内容。它接收以下属性：

• data: 插件的数据对象
• children: 用于渲染嵌套的行和单元格
• readOnly: 布尔值，表示是否处于只读模式
• onChange: 用于更新单元格数据的回调函数

3. 单元格样式(cellStyle)

可以是一个样式对象或返回样式对象的函数，应用于单元格的最外层div，而非Renderer组件内部。

cellStyle: (data) => ({
  padding: data.compact ? '5px' : '20px',
  backgroundColor: '#f5f5f5'
})

控制面板配置

React-Page 提供了三种控制面板配置方式：

1. 自动表单(autoform)

自动表单基于JSON Schema自动生成编辑界面，底层使用uniforms库：

controls: {
  type: 'autoform',
  schema: {
    properties: {
      title: { type: 'string' },
      count: { type: 'number' }
    }
  }
}

高级表单特性

• 字段属性传递：通过uniforms属性定制字段行为
• 条件显示：使用showIf实现条件字段
• 自定义组件：覆盖默认的字段组件

controls: {
  type: 'autoform',
  schema: {
    properties: {
      imageUrl: {
        type: 'string',
        uniforms: {
          component: ImageUploader,
          showIf: (data) => data.useImage
        }
      }
    }
  }
}

2. 自定义控制面板(custom)

当自动表单不能满足需求时，可以使用完全自定义的控制组件：

controls: {
  type: 'custom',
  Component: ({ data, onChange }) => (
    <div>
      <input 
        value={data.title} 
        onChange={(e) => onChange({ ...data, title: e.target.value })}
      />
    </div>
  )
}

3. 多标签控制面板

对于复杂插件，可以分多个标签页组织控制项：

controls: [
  {
    title: '基本设置',
    controls: { type: 'autoform', schema: { /*...*/ } }
  },
  {
    title: '高级设置',
    controls: { type: 'autoform', schema: { /*...*/ } }
  }
]

高级功能

1. 嵌套内容管理

• cellPlugins: 定义允许在当前单元格内使用的插件列表
• createInitialChildren: 创建初始的嵌套行和单元格结构

createInitialChildren: () => [
  [ // 一行
    { // 一个单元格
      plugin: 'textPlugin',
      data: { text: '初始文本' }
    }
  ]
]

2. 数据迁移

当数据结构变更时，通过迁移处理旧数据：

migrations: [
  new Migration({
    toVersion: 2,
    migrate: (data) => ({ ...data, newField: 'default' })
  })
]

3. 内联元素

• isInlinable: 允许插件作为浮动内联元素
• allowInlineNeighbours: 允许接收内联邻居

4. 交互控制

• allowClickInside: 允许在编辑模式下点击单元格内部
• hideInMenu: 在插件抽屉中隐藏该插件

5. 上下文共享(Provider)

共享Renderer和控制面板之间的上下文：

Provider: ({ children, ...props }) => (
  <MyContext.Provider value={someValue}>
    {children}
  </MyContext.Provider>
)

最佳实践

1. 类型安全：始终使用TypeScript类型定义数据结构和属性
2. 版本控制：每次数据结构变更时递增版本号并添加迁移
3. 组件复用：对于复杂表单字段，创建可复用的自定义组件
4. 性能优化：避免在Renderer中进行不必要的渲染
5. 用户体验：为复杂插件提供清晰的分组和标签

总结

React-Page 的单元格插件系统提供了极大的灵活性，从简单的文本显示到复杂的嵌套结构都能胜任。通过合理利用自动表单、自定义控制和高级功能，开发者可以构建出功能丰富且用户友好的内容编辑体验。

希望本指南能帮助你快速掌握 React-Page 插件开发的核心概念和技巧。在实际开发中，建议从小型插件开始，逐步探索更复杂的功能组合。

react-page Next-gen, highly customizable content editor for the browser - based on React and written in TypeScript. WYSIWYG on steroids. 项目地址: https://gitcode.com/gh_mirrors/rea/react-page