Ory Editor 自定义单元格插件开发指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01194/article/details/148418487

Ory Editor 自定义单元格插件开发指南

react-page 项目地址: https://gitcode.com/gh_mirrors/ed/editor

前言

Ory Editor 是一个功能强大的可视化编辑器框架，它允许开发者通过自定义单元格插件(Cell Plugin)来扩展编辑器的功能。本文将深入讲解如何为 Ory Editor 开发自定义单元格插件，从基础概念到高级用法，帮助开发者掌握插件开发的核心技术。

什么是单元格插件

单元格插件定义了用户可以在文档中添加的内容单元。每个插件由以下核心部分组成：

唯一标识符(id)：用于区分不同插件
标题(title)：在插件选择器中显示的名称
渲染器(Renderer)：实际显示内容的React组件
控制器(controls)：用于编辑插件内容的界面

基础插件开发

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

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

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

const myFirstCellPlugin: CellPlugin<Data> = {
  // 渲染组件
  Renderer: ({ data }) => (
    <div style={{ padding: 20, backgroundColor: '#f0f0f0' }}>
      <h2>{data.title}</h2>
    </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)

渲染器是插件的核心，它接收以下主要属性：

data：插件的数据对象
children：用于嵌套内容的子元素
readOnly：是否处于只读模式
onChange：数据变更回调函数

3. 单元格样式(cellStyle)

可以定义单元格的外层样式：

cellStyle: {
  padding: '10px',
  margin: '5px',
  border: '1px dashed #ccc'
}

// 或根据数据动态计算
cellStyle: (data) => ({
  backgroundColor: data.isHighlighted ? '#ffff00' : 'transparent'
})

控制器(Controls)类型

Ory Editor 提供了三种控制器实现方式：

1. 自动表单(autoform)

基于JSON Schema自动生成表单界面：

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

自动表单支持丰富的字段类型和验证规则，还可以自定义字段组件。

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. 嵌套内容

支持在插件内部嵌套其他插件：

createInitialChildren: () => [
  [
    {
      plugin: 'textPlugin',
      data: { text: '默认文本' }
    }
  ]
]

2. 数据迁移

当数据结构变更时，需要提供迁移逻辑：

migrations: [
  {
    version: 2,
    migrate: (data) => ({
      ...data,
      // 将旧字段转换为新字段
      newField: data.oldField || 'default'
    })
  }
]

3. 上下文提供者(Provider)

共享渲染器和控制器之间的状态：

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

实际案例：图片上传插件

让我们看一个完整的图片上传插件实现：

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

// 图片上传字段组件
const ImageUploadField = connectField(({ value, onChange }) => (
  <div>
    {value && <img src={value} style={{ maxWidth: 200 }} />}
    <input
      type="file"
      accept="image/*"
      onChange={(e) => {
        const file = e.target.files[0];
        if (file) {
          // 模拟上传过程
          setTimeout(() => {
            const url = URL.createObjectURL(file);
            onChange(url);
          }, 500);
        }
      }}
    />
  </div>
));

// 插件定义
const imagePlugin: CellPlugin<{
  imageUrl: string;
  caption: string;
  alignment: 'left' | 'center' | 'right';
}> = {
  id: 'imagePlugin',
  title: '图片插件',
  version: 1,
  
  Renderer: ({ data }) => (
    <div style={{ textAlign: data.alignment }}>
      <img 
        src={data.imageUrl} 
        style={{ maxWidth: '100%' }}
        alt={data.caption}
      />
      {data.caption && <p>{data.caption}</p>}
    </div>
  ),
  
  controls: {
    type: 'autoform',
    schema: {
      properties: {
        imageUrl: {
          type: 'string',
          uniforms: {
            component: ImageUploadField,
            label: '上传图片'
          }
        },
        caption: {
          type: 'string',
          uniforms: {
            label: '图片说明'
          }
        },
        alignment: {
          type: 'string',
          enum: ['left', 'center', 'right'],
          uniforms: {
            label: '对齐方式'
          }
        }
      },
      required: ['imageUrl']
    }
  }
};

这个插件实现了：