前端UI组件【免费下载链接】react-pageNext-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点击查看免费下载本文是 UPGRADE.md 的完整展开与深化面向正在使用 React-Page或此前名为 ory-editor的开发者系统梳理 0.6.x → 0.7.x → 1.0.0 各阶段的关键破坏性变更、包重命名对照、自定义 Cell 插件与自定义 Slate 插件的迁移步骤并结合本仓库源码packages/editor 等给出可验证的实现细节。读完本文你将能独立完成一次从旧版本 API 到新版本CellPlugin体系的平滑升级并理解数据自动迁移与渲染层变化背后的原理。一、为什么需要这份升级指南React-Page 的维护者在这份文档开篇即说明其意图尽可能降低破坏性变更breaking changes的迁移成本。同时坦诚地提醒两点文档不可能穷尽所有破坏性变更并非所有 breaking change 都会收录在本文档中破坏性变更的完整列表以官方 Release 说明为准升级前建议先核对版本发布记录。在动手升级前请记住 UPGRADE.md 给出的最重要的一条操作纪律升级前务必备份数据一旦发现问题立即反馈 issue。这直接与 1.0.0 引入的数据迁移机制有关详见下文数据自动迁移一节。二、1.0.0大规模内部重构与 API 收敛1.0.0 是一次大规模重构改动主要集中在内部changed and modernized a lot under the hood, but not much on the outside目标是让后续改进更容易、获得更好的性能、减小打包体积reduced bundle size。它引入了一些为了清晰化 API 而必须做的破坏性变更但官方认为迁移步骤是straight forward直接了当的。2.1 包结构统一多包并入 react-page/editor1.0.0 之前核心代码被拆分为多个包。1.0.0 起发生合并旧包新状态react-page/core不再存在react-page/ui不再存在react-page/renderer不再存在现在你只需要从react-page/editor导入一切。这与当前仓库的源码结构完全一致在 packages/editor/src/index.tsx 中export * from ./core/types、export * from ./core/components/hooks、export * from ./ui以及export default Editor等导出全部从单一入口完成Editor组件、Value类型、Migration类型、makeUniformsSchema、migrateValue、getTextContents、createValue等均可从此入口获得。仓库内所有内容插件也统一从react-page/editor导入类型例如 packages/plugins/content/image/src/createPlugin.tsx 中的import type { CellPlugin } from react-page/editor。注意一处细节UPGRADE.md 的Migrating custom plugins小节中写着import type { CellPlugin } from react-page/renderer但该文档同页已声明react-page/renderer不再存在。结合本仓库全部实际代码所有插件与示例均从react-page/editor导入正确的写法是从react-page/editor导入。请以仓库实际代码为准。2.2pluginsprop 更名为cellPluginsEditor /上的pluginsprop 被重命名为cellPlugins目的是为未来其他插件类型腾出命名空间。在 packages/editor/src/editor/Editor.tsx 中可以看到cellPlugins是Editor组件解构出的核心 prop并被放入renderOptions传入编辑内核同时EditorProps类型是Options Callbacks RenderOptions的交叉类型其中RenderOptions在 packages/editor/src/core/defaultOptions.ts 中定义为{ cellPlugins: [], cellSpacing: null }。实际用例如仓库示例 examples/pages/examples/simple.tsximport Editor, { Value } from react-page/editor; import slate from react-page/plugins-slate; import image from react-page/plugins-image; // Define which plugins we want to use. const cellPlugins [slate(), image]; export default function SimpleExample() { const [value, setValue] useStateValue | null(null); return ( PageLayout Editor cellPlugins{cellPlugins} value{value} onChange{setValue} / /PageLayout ); }注意这里cellPlugins接收的是CellPlugin[]数组且布局插件与内容插件已被统一为同一种CellPlugin类型见下一节。2.3 布局插件与内容插件统一为 CellPlugin1.0.0 之前layout 插件与 content 插件是两种不同的体系1.0.0 起它们被统一为CellPlugin。从 packages/editor/src/core/types/plugins.ts 的CellPlugin类型定义可以看出一个插件同时具备渲染Renderer、编辑控制controls、数据初始化createInitialData、子插件约束childConstraints、cellPlugins、内嵌布局cellSpacing、createInitialChildren等能力因此既能做内容插件如 image 插件也能做布局插件如packages/plugins/layout/background。这也是仓库中packages/plugins/content与packages/plugins/layout目录并存但共享同一类型体系的根本原因。2.4defaultPlugin不再需要1.0.0 之前编辑器需要defaultPlugin来自动填充空白单元。1.0.0 起defaultPlugin不再是必填项编辑器在内容为空时不再自动添加一个 cell取而代之的是在空白处显示一个添加新 cell的按钮由用户显式选择要插入的插件。2.5 数据自动迁移无向下迁移1.0.0 将内容数据迁移到新格式。迁移发生在用户下一次保存新内容时并且是单向的没有 down migration向下迁移因此官方强烈建议在升级前备份数据升级后一旦发现任何问题应立即填写 issue 求助。从源码看这套机制由 packages/editor/src/core/migrations/migrate.ts 中的migrate与migrateValue实现编辑器会根据Value中记录的version与当前内置的EDITABLE_MIGRATIONS列表循环执行fromVersion currentDataVersion toVersion currentDataVersion的迁移链逐级把旧数据推进到最新版本同时会对每个 cell 的插件数据执行插件自身的migrations当c.plugin.version与cellPlugins中对应插件version不一致时并调用unserialize还原数据。migrateValue也被显式导出可在 packages/editor/src/index.tsx 中看到方便你在服务端或保存前主动完成迁移。三、迁移自定义插件Migrating custom plugins如果你有自定义插件UPGRADE.md 给出了如下迁移清单下面逐条结合源码展开3.1 类型与导入强烈建议使用 TypeScript并将插件类型声明为import type { CellPlugin } from react-page/editor; const myPlugin: CellPluginMyData { ... };CellPlugin是一个泛型类型接收一个类型参数Data可选表示插件的数据对象类型。在 packages/editor/src/core/types/plugins.ts 中可见默认值DataTType Recordstring, unknown。3.2 字段改名name→idtext→titlename插件唯一标识改名为idtext插件人类可读标题改名为title。在 CellPlugin 类型定义 中id的注释明确写着the plugins unique id. Only one plugin with the same id may be used而name、text两个旧字段仍然保留但均被标注为deprecated please set id/deprecated please set title。这说明当前版本为平滑过渡保留了旧字段但新代码应一律使用新名字。3.3Component拆分为Renderercontrols旧版插件直接提供Component1.0.0 起改为分别定义渲染组件与编辑控件Renderer显示在 cell 中的组件接收一个dataprop其类型即Data。在 CellPlugin 类型 中Renderer被定义为React.ComponentTypeCellPluginComponentPropsDataT而 CellPluginComponentProps 提供了nodeId、data、onChange、remove、readOnly、focused、lang、isPreviewMode、isEditMode等完整上下文。注意类型注释中的提醒不要在 Renderer 中使用编辑器内部 hooks因为它们无法在 readOnly 模式下工作。controls定义如何编辑该插件两种方式二选一schema 驱动的自动表单{ type: autoform, schema: JsonSchema }由 JSON Schema 自动生成表单还可以通过columnCount控制列数、通过Content自定义表单内部布局见 AutoformControlsDef自定义控件组件{ type: custom, Component }提供完全自定义的控件组件见 CustomControlsDef。以仓库内置的 image 插件为例packages/plugins/content/image/src/createPlugin.tsxconst createPlugin (settings?: ImageSettings): CellPluginImageState { const mergedSettings { ...defaultSettings, ...settings }; const Controls mergedSettings.Controls; return { controls: { type: custom, Component: (props) ( Controls {...props} translations{mergedSettings.translations} imageUpload{mergedSettings.imageUpload} / ), }, Renderer: mergedSettings.Renderer, id: ory/editor/core/content/image, version: 1, icon: mergedSettings.icon, title: mergedSettings.translations?.pluginName, isInlineable: true, description: mergedSettings.translations?.pluginDescription, }; };这个实际实现恰好是 UPGRADE.md 迁移清单的完整示范id而非name、title而非text、Renderercontrols而非Component、version配合数据迁移使用。关于自定义 cell 插件的更完整指南见 docs/custom-cell-plugins.md内置插件清单见 docs/builtin_plugins.md。3.4 移除 create-plugin-materialui如果你使用了react-page/create-plugin-materialui1.0.0 起可以直接移除它——它不再需要改用上文提到的CellPlugin类型与controls体系即可仓库中也已不存在该包。四、迁移自定义 Slate 插件对于使用自定义数据的自定义 Slate 插件1.0.0 的 API 略有调整并且与 CellPlugin 的 API 完成了统一Slate 插件现在同样接收controlscontrols取值有两种形态与 CellPlugin 完全一致type: autoformschemaJsonSchema自动生成表单type: custom使用自定义控件。仓库中的 Slate 插件实现在 packages/plugins/content/slate/src 下其插件工厂如pluginFactories目录下的createComponentPlugin、createDataPlugin、createMarkPlugin、createListPlugin等与控件机制可作参考更详细的 Slate 插件开发文档见 docs/slate.md。五、0.7.x维护者变更与包重命名0.7.x 是一个特殊阶段该包的维护者发生变更项目更名为react-page。如果你仍在使用旧包名只需按下列对照表更新依赖即可旧包名新包名ory-editorreact-page/react-pageory-editor-corereact-page/coreory-editor-plugins-dividerreact-page/plugins-dividerory-editor-plugins-html5-videoreact-page/plugins-html5-videoory-editor-plugins-imagereact-page/plugins-imageory-editor-plugins-default-nativereact-page/plugins-default-nativeory-editor-plugins-slatereact-page/plugins-slateory-editor-plugins-spacerreact-page/plugins-spacerory-editor-plugins-videoreact-page/plugins-videoory-editor-plugins-backgroundreact-page/plugins-backgroundory-editor-plugins-parallax-backgroundreact-page/plugins-parallax-backgroundory-editor-rendererreact-page/rendererory-editor-uireact-page/ui注意这张表对应 0.7.x 时代的分包结构如果你要直接升级到 1.0.0请以第二节为准——react-page/core、react-page/renderer、react-page/ui等已全部并入react-page/editor。当前仓库的 monorepo 结构packages 目录中仅保留react-page/editor、react-page/plugins-*内容插件与布局插件、以及react-page/react-admin集成包与 1.0.0 的收敛目标一致。六、0.6.x全面 TypeScript 支持0.6.x 引入了完整的 TypeScript 支持。如果你使用 TypeScript 并编写自己的插件可能会因为对 ory-editor 传入 props 的错误假设而遇到类型报错。处理原则如果认为是 react-page 自身的问题请上报 issue如果是自己的代码问题请修正代码临时应急方案如果确实是 react-page 代码的问题又不想因此停滞开发进度可以利用 tsconfig 中的paths属性覆盖 react-page 的类型定义{ compilerOptions: { paths: { // 将 react-page/core 等指向你自己的类型修复文件 react-page/core: [./types-fixes/core.d.ts] } } }但官方明确提醒一旦官方修复了问题请尽快移除这些脏修复dirty fixes以便始终跟进最新变更。七、升级后的验证建议完成上述迁移后建议从以下几个方面验证升级正确性数据层升级前备份旧数据升级后让用户保存一次新内容确认 migrateValue 触发的自动迁移正常完成检查保存出的新格式内容是否完整尤其多语言dataI18n与嵌套rows。渲染层用readOnly模式渲染历史内容确认HTMLRenderer在 packages/editor/src/renderer/HTMLRenderer.tsx能正确输出Editor.tsx 中编辑器始终先以 readOnly 方式挂载再切换编辑态因此 SSR 场景也应在升级后回归。插件层逐个验证自定义插件在新CellPlugin类型下编译通过Renderer在编辑/只读模式下均正常controls的 autoform/custom 两种形态均可打开与保存。编辑器行为确认空内容时不再自动插入默认 cell而是显示添加按钮。仓库中还提供了多个可直接运行的示例用于对照验证例如编辑示例 examples/pages/examples/simple.tsx、只读示例 examples/pages/examples/readonly.tsx、以及展示自定义插件迁移成果的 customContentPlugin.tsx、customLayoutPlugin.tsx 等均可作为升级后的回归测试参照。赞分享前端UI组件【免费下载链接】react-pageNext-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点击查看免费下载相关推荐Flue 迁移指南从 1.0.0-beta.9 升级到 Flue 2 的完整实战手册Flue 迁移指南从 1.0.0 beta.9 升级到 Flue 2 的完整实战手册 本指南面向运行中的 beta 应用系统讲解将 Flue 代码库从 1.人工智能大模型AI AgentAgent 框架工具调用Agent 沙箱MCP ClientsActix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移Actix Web 4.0 升级迁移完全指南从 v3 到 v4 的 Breaking Changes 逐项解析与实战迁移 导读 本文以 actix web/M后端Web框架React Native Elements 4.0 迁移指南从 v3 升级到 rneui/themed 的完整实战手册React Native Elements 4.0 迁移指南从 v3 升级到 rneui/themed 的完整实战手册 React Native ElemeUI组件移动开发前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考