331 lines
No EOL
24 KiB
Markdown
331 lines
No EOL
24 KiB
Markdown
# WooCommerce 电子邮件编辑器
|
||
|
||
这是 WooCommerce 电子邮件编辑器包 - 一个用于构建和自定义电子邮件模板的 JavaScript 库。虽然目前与 WooCommerce 集成，但该包设计为可在其他项目中作为独立库使用。
|
||
|
||
您可以在 [WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/woocommerce/woocommerce/refs/heads/trunk/packages/js/email-editor/blueprint.json) 中试用此电子邮件编辑器。
|
||
|
||
此 JavaScript 包设计与其对应的 PHP 包协同工作，PHP 包可在同一代码库的 `packages/php/email-editor` 目录中找到。两个包都是实现完整功能所必需的。
|
||
|
||
## 初始化编辑器
|
||
|
||
> **注意：** `initializeEditor` 函数目前处于实验阶段，其 API 在未来版本中可能会发生变化。请注意，可能会发生破坏性变更。
|
||
|
||
要在项目中使用电子邮件编辑器，您需要使用 `initializeEditor` 函数来初始化它。编辑器要求在初始化之前在全局 `window.WooCommerceEmailEditor` 对象上设置某些数据：
|
||
|
||
```javascript
|
||
// 首先，在 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 可能会发生变化。
|
||
|
||
```jsx
|
||
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` 初始化商店。
|
||
|
||
```jsx
|
||
import { createStore, SendPreviewEmail } from '@woocommerce/email-editor';
|
||
|
||
createStore();
|
||
// ...
|
||
<SendPreviewEmail />;
|
||
```
|
||
|
||
#### `RichTextWithButton`
|
||
|
||
一个 WordPress `RichText` 输入框，增强了一个用于将个性化标签（例如客户姓名、订单详情）插入电子邮件内容的按钮。
|
||
|
||
> 要求商店通过 `createStore()`、`initializeEditor` 或 `ExperimentalEmailEditor` 进行初始化。
|
||
|
||
```jsx
|
||
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`。
|
||
|
||
> 需要商店初始化才能获得有意义的结果。
|
||
|
||
```js
|
||
import { createStore, useIsEmailEditor } from '@woocommerce/email-editor';
|
||
|
||
createStore();
|
||
// ...
|
||
const isEmailEditor = useIsEmailEditor();
|
||
```
|
||
|
||
#### `usePreviewTemplates`
|
||
|
||
通过将模板布局与内容合并，为电子邮件模板生成预览数据。可选择包含最近的电子邮件文章。
|
||
|
||
> 需要商店已初始化。
|
||
|
||
```js
|
||
import { createStore, usePreviewTemplates } from '@woocommerce/email-editor';
|
||
|
||
createStore();
|
||
// ...
|
||
const [ templates, recentPosts, hasRecentPosts ] = usePreviewTemplates();
|
||
```
|
||
|
||
#### `useEmailCss`
|
||
|
||
通过合并编辑主题选项、用户自定义设置和布局配置，为邮件编辑器生成完整的 CSS 样式。
|
||
|
||
> 需要商店已初始化。
|
||
|
||
```js
|
||
import { createStore, useEmailCss } from '@woocommerce/email-editor';
|
||
|
||
createStore();
|
||
// ...
|
||
const [ styles ] = useEmailCss();
|
||
```
|
||
|
||
### 商店
|
||
|
||
#### `storeName`
|
||
|
||
商店标识符：`'email-editor/editor'`。与 `@wordpress/data` 的 `select()` 和 `dispatch()` 调用一起使用。
|
||
|
||
#### `createStore`
|
||
|
||
使用 `@wordpress/data` 注册电子邮件编辑 Redux 商店。可安全多次调用；如果已注册，则返回现有商店。
|
||
|
||
```js
|
||
import { createStore } from '@woocommerce/email-editor';
|
||
|
||
createStore();
|
||
```
|
||
|
||
### 事件跟踪
|
||
|
||
#### `recordEvent`, `recordEventOnce`, `debouncedRecordEvent`
|
||
|
||
分析跟踪工具。事件前缀为 `email_editor_events_`，仅在启用跟踪时记录。`recordEventOnce` 会在每个会话中去重。`debouncedRecordEvent` 会等待 700 毫秒以批量处理快速操作。
|
||
|
||
```js
|
||
import {
|
||
recordEvent,
|
||
recordEventOnce,
|
||
debouncedRecordEvent,
|
||
} from '@woocommerce/email-editor';
|
||
|
||
recordEvent( 'button_clicked', { buttonType: 'save' } );
|
||
recordEventOnce( 'editor_loaded' );
|
||
debouncedRecordEvent( 'content_typed', { length: 42 } );
|
||
```
|
||
|
||
#### `isEventTrackingEnabled`
|
||
|
||
返回当前是否已启用活动跟踪。
|
||
|
||
```js
|
||
import { isEventTrackingEnabled } from '@woocommerce/email-editor';
|
||
|
||
if ( isEventTrackingEnabled() ) {
|
||
// 执行跟踪工作
|
||
}
|
||
```
|
||
|
||
## 工作流命令
|
||
|
||
我们使用 `pnpm` 运行脚本来执行命令。您可以使用 `pnpm run <命令>` 来运行它们。
|
||
请从 `pnpm install` 开始。
|
||
|
||
```bash
|
||
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 依赖提取插件以捆绑此包，而不是将其视为外部依赖：
|
||
|
||
```javascript
|
||
new DependencyExtractionWebpackPlugin( {
|
||
requestToExternal( request ) {
|
||
if ( request === '@wordpress/global-styles-engine' ) {
|
||
// 返回 null 以捆绑此包，而不是将其视为外部依赖
|
||
return null;
|
||
}
|
||
// ... 处理其他依赖项
|
||
},
|
||
} );
|
||
```
|
||
|
||
### 电子邮件编辑器
|
||
|
||
- 在插件中通过[电子邮件编辑器控制器](https://github.com/mailpoet/mailpoet/blob/13bf305aeb29bbadd0695ee02a3735e62cc4f21f/mailpoet/lib/EmailEditor/Integrations/MailPoet/EmailEditor.php)引导启动
|
||
- **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 文件夹](https://github.com/mailpoet/mailpoet/tree/13bf305aeb29bbadd0695ee02a3735e62cc4f21f/mailpoet/assets/js/src/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 | 用户点击"创建新优惠券"时调用的处理函数。应打开优惠券创建界面。 | |
