Easy-Email-Editor 自定义组件开发完整指南

Easy-Email-Editor 自定义组件开发完整指南

【免费下载链接】easy-email-editorEasy Email Editor is a feature-rich, top open-source SaaS email editor based on React and MJML.项目地址: https://gitcode.com/gh_mirrors/ea/easy-email-editor

什么是自定义组件

在 Easy-Email-Editor 中，自定义组件是将多个基础元素组合而成的专业邮件模块。它类似于前端开发中的复合组件概念，通过封装基础组件来创建更复杂、更专业的邮件内容。

举例来说，一个标准的邮件布局需要这样构建：

<Section> <Column> <Text>这里是邮件内容</Text> </Column> </Section>

而通过自定义组件，你只需这样使用：

<CustomEmailSection></CustomEmailSection>

核心优势

• 效率提升：减少重复布局工作
• 一致性：确保邮件设计风格统一
• 可复用性：一次开发，多次使用
• 专业化：针对特定业务场景定制组件

开发环境搭建

克隆项目

git clone https://gitcode.com/gh_mirrors/ea/easy-email-editor cd easy-email-editor npm install

项目结构了解

Easy-Email-Editor 采用 monorepo 架构，包含多个核心包：

• easy-email-core：核心引擎
• easy-email-editor：编辑器界面
• easy-email-extensions：扩展功能
• easy-email-localization：国际化支持

自定义组件开发步骤

第一步：定义组件类型

首先需要为自定义组件定义唯一的类型标识：

export enum CustomBlocksType { PRODUCT_RECOMMENDATION = 'PRODUCT_RECOMMENDATION', PROMOTION_BANNER = 'PROMOTION_BANNER', FOOTER_SECTION = 'FOOTER_SECTION' }

第二步：创建数据结构

定义组件的数据结构，包括属性和内容值：

export interface IProductRecommendation { type: CustomBlocksType.PRODUCT_RECOMMENDATION; data: { value: { title: string; buttonText: string; quantity: number; }; }; attributes: { 'background-color': string; 'button-text-color': string; 'button-color': string; 'product-name-color': string; 'product-price-color': string; 'title-color': string; }; children: IBlockData[]; }

第三步：实现创建方法

创建方法负责生成组件的初始数据：

const create: CreateInstance<IProductRecommendation> = (payload) => { const defaultData: IProductRecommendation = { type: CustomBlocksType.PRODUCT_RECOMMENDATION, data: { value: { title: '您可能也喜欢', buttonText: '立即购买', quantity: 3, }, }, attributes: { 'background-color': '#ffffff', 'button-text-color': '#ffffff', 'button-color': '#414141', 'product-name-color': '#414141', 'product-price-color': '#414141', 'title-color': '#222222', }, children: [], }; return merge(defaultData, payload); };

第四步：实现渲染方法

渲染方法将自定义组件转换为基础组件组合：

const render = ( data: IProductRecommendation, idx: string, mode: 'testing' | 'production', context?: IPage, dataSource?: { [key: string]: any } ) => { const { title, buttonText, quantity } = data.data.value; const attributes = data.attributes; return ( <Wrapper background-color={attributes['background-color']}> <Section> <Column> <Text color={attributes['title-color']}> {title} </Text> </Column> </Section> <Section> <Group> {new Array(quantity).fill(0).map((_, index) => ( <Column key={index}> <Image src={productPlaceholder.image} /> <Text color={attributes['product-name-color']}> {productPlaceholder.title} </Text> <Text color={attributes['product-price-color']}> {productPlaceholder.price} </Text> <Button background-color={attributes['button-color']} color={attributes['button-text-color']} href={productPlaceholder.url} > {buttonText} </Button> </Column> ))} </Group> </Section> </Wrapper> ); };

完整组件示例

下面是一个完整的产品推荐组件实现：

import { createCustomBlock } from 'easy-email-core'; import { BasicType } from 'easy-email-core'; export const ProductRecommendation = createCustomBlock<IProductRecommendation>({ name: '产品推荐', type: CustomBlocksType.PRODUCT_RECOMMENDATION, validParentType: [BasicType.PAGE], create, render, });

组件注册与使用

注册组件

开发完成后，需要将组件注册到编辑器中：

import { BlocksMap } from 'easy-email-editor'; BlocksMap.registerBlocks({ [CustomBlocksType.PRODUCT_RECOMMENDATION]: ProductRecommendation });

在编辑器中使用

注册成功后，组件将出现在编辑器左侧的组件库中，用户可以像使用基础组件一样拖拽使用。

高级功能

数据源集成

自定义组件支持从数据源获取动态内容：

const renderWithDataSource = (data, idx, mode, context, dataSource) => { const productList = mode === 'testing' ? new Array(data.data.value.quantity).fill(productPlaceholder) : (dataSource?.product_list || []).slice(0, data.data.value.quantity); return ( // 使用 dataSource 中的真实数据渲染组件 ); };

条件渲染

根据不同的条件显示不同的内容：

const conditionalRender = (data, idx, mode) => { if (mode === 'testing') { // 编辑模式下显示占位内容 return <PlaceholderComponent />; } else { // 生产模式下显示真实数据 return <RealDataComponent />; } };

最佳实践

1. 合理设计数据结构

提前规划好组件需要的数据结构，确保灵活性：

interface ICustomComponent { type: string; data: { value: { // 核心内容字段 mainContent: string; // 样式配置字段 styleConfig: { fontSize: string; color: string; }; }; }; attributes: { // 布局属性 padding: string; margin: string; // 样式属性 backgroundColor: string; }; }

2. 考虑多设备适配

确保组件在不同设备上都有良好的显示效果：

const responsiveComponent = (data) => { return ( <Wrapper> <Section> <Column width="100%"> {/* 移动端优化内容 */} </Column> </Section> </Wrapper> ); };

3. 错误处理机制

添加适当的错误处理，提高组件稳定性：

const safeRender = (data) => { try { // 正常的渲染逻辑 return <ComponentContent />; } catch (error) { // 错误时显示备用内容 return <FallbackComponent />; } };

调试与测试

开发环境调试

在开发过程中，可以使用以下方法调试组件：

// 添加日志输出 console.log('组件数据:', data); console.log('组件索引:', idx); console.log('运行模式:', mode);

生产环境测试

确保组件在生产环境下正常运行：

const productionTest = (data) => { if (mode === 'production') { // 生产环境特定的逻辑 } };

常见问题解决

组件不显示

检查组件注册是否正确，类型定义是否唯一。

样式异常

确保样式属性名称正确，值格式符合要求。

数据不更新

检查数据源是否正确传递，渲染逻辑是否正确处理数据变化。

总结

通过自定义组件开发，你可以显著提升邮件制作的效率和质量。无论是简单的文本组合还是复杂的产品展示，都可以通过自定义组件来实现专业级的邮件设计效果。

开始你的邮件组件开发之旅，创建属于你自己的专业邮件组件库！

【免费下载链接】easy-email-editorEasy Email Editor is a feature-rich, top open-source SaaS email editor based on React and MJML.项目地址: https://gitcode.com/gh_mirrors/ea/easy-email-editor