woocommerce/packages/js/email-editor/zh-cn/README.md

WooCommerce 电子邮件编辑器

这是 WooCommerce 电子邮件编辑器包 - 一个用于构建和自定义电子邮件模板的 JavaScript 库。虽然目前与 WooCommerce 集成，但该包设计为可在其他项目中作为独立库使用。

您可以在 WordPress Playground 中试用此电子邮件编辑器。

此 JavaScript 包设计与其对应的 PHP 包协同工作，PHP 包可在同一代码库的 packages/php/email-editor 目录中找到。两个包都是实现完整功能所必需的。

初始化编辑器

注意： initializeEditor 函数目前处于实验阶段，其 API 在未来版本中可能会发生变化。请注意，可能会发生破坏性变更。

要在项目中使用电子邮件编辑器，您需要使用 initializeEditor 函数来初始化它。编辑器要求在初始化之前在全局 window.WooCommerceEmailEditor 对象上设置某些数据：

// 首先，在 window 对象上设置所需的数据
window.WooCommerceEmailEditor = {
    current_post_type: '', // 当前文章的帖子类型
    current_post_id: '', // 当前文章的 ID
    current_wp_user_email: '', // 当前用户的电子邮件
    editor_settings: {
        // 标准区块编辑器设置，以及电子邮件编辑器特定的选项。
        // 可用的选项请参见下面的“编辑器设置”部分。
    },
    editor_theme: {}, // 区块编辑器主题
    user_theme_post_id: '', // 用户主题文章的 ID
    urls: {
        listings: '', // 可选：列表页面的 URL
        send: '', // 可选：发送按钮的 URL
        back: '', // 可选：返回按钮的 URL（左上方角落）
    },
};

// 然后使用 HTML 元素 ID 初始化编辑器
import { initializeEditor } from '@woocommerce/email-editor';
initializeEditor( 'email-editor-container' );

initializeEditor 函数接受一个参数：

• htmlId（必需）：编辑器将挂载到的 HTML 元素的 ID

在调用 initializeEditor 之前，请确保在 window.WooCommerceEmailEditor 上设置好所需的数据。

编辑器设置

editor_settings 对象（或使用 ExperimentalEmailEditor 时的 config.editorSettings）接受所有标准的 WordPress 区块编辑器设置以及以下特定于邮件编辑器的选项：

设置	类型	默认值	描述
isFullScreenForced	boolean	false	当为 true 时，编辑器始终以全屏模式渲染，用户无法将其关闭。"更多菜单" 将被隐藏，标题栏中会显示一个返回按钮。
displaySendEmailButton	boolean	false	当为 true 时，编辑器标题栏中会显示一个"发送"按钮，允许用户直接从编辑器发布/发送邮件。
disableSnackbarNotices	boolean	false	当为 true 时，编辑器不会渲染其自身的 Snackbar 通知。固定的通知和验证通知不受影响。

汇出

组件

ExperimentalEmailEditor

一个替代 initializeEditor 的 React 组件。内联渲染电子邮件编辑器，而不是通过 ID 挂载到 DOM 元素。直接接受 config 属性，无需使用 window.WooCommerceEmailEditor。在卸载时清理全局编辑器设置。

注意： 此组件是实验性的，其 API 可能会发生变化。

import { ExperimentalEmailEditor } from '@woocommerce/email-editor';

<ExperimentalEmailEditor
    postId="123"
    postType="email"
    config={ {
        editorSettings: {
            // 标准区块编辑器设置，加上电子邮件编辑器特定的
            // 选项。详情请参阅“编辑器设置”部分。
        },
        theme: {
            /* ... */
        },
        urls: { listings: '/emails', back: '/' },
        userEmail: 'user@example.com',
        globalStylesPostId: 456,
    } }
/>;

SendPreviewEmail

一个用于发送测试邮件的模态框组件。提供邮件验证、发送状态反馈、错误处理和成功确认功能。与邮件编辑商店集成以管理模态框状态。

需要通过 createStore()、initializeEditor 或 ExperimentalEmailEditor 初始化商店。

import { createStore, SendPreviewEmail } from '@woocommerce/email-editor';

createStore();
// ...
<SendPreviewEmail />;

RichTextWithButton

一个 WordPress RichText 输入框，增强了一个用于将个性化标签（例如客户姓名、订单详情）插入电子邮件内容的按钮。

要求商店通过 createStore()、initializeEditor 或 ExperimentalEmailEditor 进行初始化。

import { createStore, RichTextWithButton } from '@woocommerce/email-editor';

createStore();
// ...
<RichTextWithButton
    label="电子邮件主题"
    placeholder="输入电子邮件主题..."
    attributeName="subject"
    attributeValue={ currentSubject }
    updateProperty={ ( name, value ) => setEmailProperty( name, value ) }
/>;

钩子

useIsEmailEditor

当当前上下文为邮件编辑时返回 true。检查邮件编辑商店，并将当前文章 ID/类型与编辑的配置进行比较。如果商店未初始化，则返回 false。

需要商店初始化才能获得有意义的结果。

import { createStore, useIsEmailEditor } from '@woocommerce/email-editor';

createStore();
// ...
const isEmailEditor = useIsEmailEditor();

usePreviewTemplates

通过将模板布局与内容合并，为电子邮件模板生成预览数据。可选择包含最近的电子邮件文章。

需要商店已初始化。

import { createStore, usePreviewTemplates } from '@woocommerce/email-editor';

createStore();
// ...
const [ templates, recentPosts, hasRecentPosts ] = usePreviewTemplates();

useEmailCss

通过合并编辑主题选项、用户自定义设置和布局配置，为邮件编辑器生成完整的 CSS 样式。

需要商店已初始化。

import { createStore, useEmailCss } from '@woocommerce/email-editor';

createStore();
// ...
const [ styles ] = useEmailCss();

商店

storeName

商店标识符：'email-editor/editor'。与 @wordpress/data 的 select() 和 dispatch() 调用一起使用。

createStore

使用 @wordpress/data 注册电子邮件编辑 Redux 商店。可安全多次调用；如果已注册，则返回现有商店。

import { createStore } from '@woocommerce/email-editor';

createStore();

事件跟踪

recordEvent, recordEventOnce, debouncedRecordEvent

分析跟踪工具。事件前缀为 email_editor_events_，仅在启用跟踪时记录。recordEventOnce 会在每个会话中去重。debouncedRecordEvent 会等待 700 毫秒以批量处理快速操作。

import {
    recordEvent,
    recordEventOnce,
    debouncedRecordEvent,
} from '@woocommerce/email-editor';

recordEvent( 'button_clicked', { buttonType: 'save' } );
recordEventOnce( 'editor_loaded' );
debouncedRecordEvent( 'content_typed', { length: 42 } );

isEventTrackingEnabled

返回当前是否已启用活动跟踪。

import { isEventTrackingEnabled } from '@woocommerce/email-editor';

if ( isEventTrackingEnabled() ) {
    // 执行跟踪工作
}

工作流命令

我们使用 pnpm 运行脚本来执行命令。您可以使用 pnpm run <命令> 来运行它们。 请从 pnpm install 开始。

pnpm run build                              # 运行构建命令
pnpm run start                              # 启动 webpack 开发服务器
pnpm run lint:css                           # 对所有 .scss 文件运行 stylelint
pnpm run lint:css-fix                       # 修复 `pnpm run lint:css` 报告的错误
pnpm run lint:js                            # 对所有 js 和 ts 文件（包括 .jsx 和 .tsx 版本）运行 eslint
pnpm run lint:js-fix                        # 修复 `pnpm run lint:js` 报告的错误
pnpm run lint:lang:types                    # 对所有 typescript 文件运行类型检查
pnpm run format                             # 在文件上运行 prettier。这使用 WordPress 编码标准。
pnpm run test:js                            # 使用 Jest 运行 JS 组件测试

开发

主要部分

邮件编辑器 – JS 应用程序。使用 WordPress (@wordpress) JS 包构建的自定义编辑器。最重要的包是 @wordpress/block-editor、@wordpress/editor、@wordpress/data 和 @wordpress/components。还有一些 PHP 代码用于引导启动编辑器。 存储 – 我们将邮件内容存储为自定义文章类型，并使用模板（几个硬编码的虚拟模板）来承载内容的共享部分（页眉、页脚）和样式设置。目前，我们为每个模板存储完整的样式设置。 渲染器 – 负责将古腾堡编辑器中保存的 HTML 转换为适用于邮件客户端的 HTML。 主题控制器 – 主题控制器用于为编辑器生成设置和样式。我们可以定义在设置中可用的内容处理功能。这些样式也用于渲染器。

依赖项

全局样式引擎

自 1.4.3 版本起，邮件编辑包依赖于 @wordpress/global-styles-engine，该包未被 WordPress 核心入队。与大多数 @wordpress/* 包不同，此包在 WordPress 环境中并非全局可用，必须进行捆绑。

影响：如果您的构建配置将所有 @wordpress/* 包标记为外部依赖（这在 webpack 配置中很常见），您将遇到运行时错误："Cannot find module '@wordpress/global-styles-engine'"。

解决方案：配置您的 webpack 依赖提取插件以捆绑此包，而不是将其视为外部依赖：

new DependencyExtractionWebpackPlugin( {
    requestToExternal( request ) {
        if ( request === '@wordpress/global-styles-engine' ) {
            // 返回 null 以捆绑此包，而不是将其视为外部依赖
            return null;
        }
        // ... 处理其他依赖项
    },
} );

电子邮件编辑器

• 在插件中通过电子邮件编辑器控制器引导启动
• Components 文件夹 - 基本上是编辑器的整个用户界面。古腾堡的大部分区块魔法都发生在 block-editor 文件夹中。
• Hooks 文件夹 – 几个自定义钩子，主要用于帮助我们传递数据和处理来自存储的数据，或将多个存储的数据组合起来。
• Store 文件夹 – 经典的 wordpress/data 存储。我们尽可能使用所构建包中的存储，但有时需要添加操作等。
• Layouts 文件夹 – 包含一个布局。古腾堡支持 flex、grid，但这些无法使用，因为电子邮件客户端不支持它们。Flex-email 是一种受限布局，支持 flex 的一些功能。它用于按钮。
• Blocks 文件夹 – 当我们添加对区块的支持时，通常需要进行一些调整并隐藏一些样式选项。这是通过 Blocks API 完成的，并保存在此文件夹中。
• Lock-unlock – 打开潘多拉魔盒的钥匙，内含来自 WP 包的私密组件
• .sccs 文件 – 我们不编写太多 CSS。我们为文章编辑器加载样式（这是在页面控制器中完成的），但有时我们需要进行一些调整或拥有自定义用户界面
• 自定义区块 - MailPoet 自定义区块应在mailpoet-custom-email-editor-blocks 文件夹中构建

邮件客户端

网页客户端

客户端	平台	需支持的版本	渲染引擎	百分比 (Litmus)	Litmus 检查	备注
Gmail.com	浏览器	最新版: Chrome, Firefox, Edge, Safari + 移动端	WebKit/Gecko	-/-	是	与应用程序合计约占 30%。Litmus 测试未覆盖移动网页版。
Yahoo! Mail	浏览器	最新版: Chrome, Firefox, Edge, Safari	WebKit/Gecko	3.37/2.89	是
Outlook.com + Office365	浏览器	最新版: Chrome, Firefox, Edge, Safari	WebKit/Gecko	-/0.67	是
Web.de	浏览器	最新版: Chrome, Firefox, Edge, Safari	WebKit/Gecko	-/-	是	应用程序与网页版合计使用率为 0.07%
Orange.fr	浏览器	最新版: Chrome, Firefox, Edge, Safari	WebKit/Gecko	-/-	否	应用程序与网页版合计使用率为 0.07%
Windows Live Mail	浏览器	最新版: Chrome, Firefox, Edge, Safari	WebKit/Gecko	-/0.06	否

应用程序客户

客户端	平台	支持的版本	渲染引擎	百分比 (Litmus)	Litmus 检查	备注
Gmail App	iOS	最新版	私有引擎	-/-	是
Gmail App	Android	Android 7.0 - 最新版	私有引擎	-/-	部分支持 (最高至 8.1)	Android 6 市场份额为 1.7%。Android 7 起始为 4.4%
Apple Mail	iOS	最新版	WebKit	-/-	是	无确切使用数据，但 iOS 和桌面版在 Litmus 上合计占比近 60%
Apple Mail	macOS	最新版	WebKit	-/-	是
Outlook	Windows	2021, 2019, 2016	Word	2.2/4.21	是	2006 版仍有 0.04% 的打开率，但 2013 版已于 2023 年 4 月正式停止支持。不确定 2021 和 2019 版使用何种用户代理。可能报告为 2016 版。它们仍使用 Word 作为渲染引擎。
Outlook	macOS	最新版	WebKit	-/-	是 (2016)
Google Android	Android	Android 7.0 - 最新版	?	-/1.48	是 (仅 6)	Android 6 市场份额为 1.7%。Android 7 起始为 4.4%
Samsung Mail	Android	Android 7.0 - 最新版	?	0.014/0.17	是 (Android 7)	Android 6 市场份额为 1.7%。Android 7 起始为 4.4%
Web.de	iOS/Android	最新版	?	-/0.07	否	应用 + 网页合计使用率 0.07%
Orange.fr	iOS/Android	最新版	?	-/0.07	否
Thunderbird	Windows, macOS, Linux	最新版	Gecko	-/0.61	是	它使用捆绑的渲染引擎，因此在一个平台上测试应该足够
Windows Mail	Windows	10, 11	Word	-/-	是	Windows 的默认客户端。在桌面客户端中市场份额应超过 6%

操作和筛选

这些操作和筛选目前正在进行中。 我们可能会添加、更新和删除其中的任何内容。

请谨慎使用。

操作

名称	参数	描述
woocommerce_email_editor_events	EventData.detail	邮件编辑活动

筛选

名称	参数	返回值	描述
woocommerce_email_editor_events_tracking_enabled	boolean (默认 false)	boolean	用于启用电子邮件编辑器事件跟踪和收集
woocommerce_email_editor_wrap_editor_component	JSX.Element 编辑器	JSX.Element 编辑器	主编辑器组件。自定义组件可以包装编辑器并提供额外功能
woocommerce_email_editor_send_button_label	string '发送'	string '发送' (默认)	电子邮件编辑器发送按钮标签。可以使用此过滤器更新 发送 文本
woocommerce_email_editor_send_action_callback	function sendAction	function sendAction	点击发送按钮时要执行的操作
woocommerce_email_editor_content_validation_rules	array rules	EmailContentValidationRule[] rules	电子邮件编辑器内容验证规则。验证在 点击发送按钮 时进行，并在 保存草稿 时重新验证
woocommerce_email_editor_check_sending_method_configuration_link	string link	string link	编辑或移除发送配置链接信息
woocommerce_email_editor_setting_sidebar_extension_component	JSX.Element RichTextWithButton	JSX.Element 边栏扩展组件	向电子邮件设置边栏添加组件
woocommerce_email_editor_preferred_template_title	string '', Post post	string 自定义（首选）模板标题	电子邮件预设模板选择器的自定义标题
woocommerce_email_editor_sidebar_email_type_info_icon	无	JSX.Element 图标组件	返回一个来自 @wordpress/icons 的图标，例如 () => <Icon icon={ postContent } />
woocommerce_email_editor_sidebar_email_type_info_content	无	JSX.Element 信息内容	返回一个包含有关当前模板或内容信息的 React 组件
woocommerce_email_editor_trash_modal_should_permanently_delete	boolean (默认 false)	boolean	控制回收站模态框的操作。返回 true 将确保模态框永久删除电子邮件（跳过回收站）。
woocommerce_email_editor_iframe_stylesheet_should_remove	boolean (默认 false), CSSStyleSheet 样式表	boolean	控制是否应移除 iframe 样式表。返回 true 将移除 iframe 样式表。
woocommerce_email_editor_close_action_callback	function backAction	function backAction	点击关闭（返回）按钮时要执行的操作
woocommerce_email_editor_close_content	React.ComponentType DefaultBackButtonContent	React.ComponentType 返回按钮内容	编辑器标题中返回按钮内容的自定义组件
woocommerce_email_editor_create_coupon_handler	() => void handler	() => void handler	用户点击"创建新优惠券"时调用的处理函数。应打开优惠券创建界面。