174 lines
No EOL
15 KiB
Markdown
174 lines
No EOL
15 KiB
Markdown
# WooCommerce 邮件编辑器
|
||
|
||
此文件夹包含 WooCommerce 邮件编辑器 PHP 包的代码。
|
||
|
||
此包涵盖引导邮件编辑器 JS 应用程序的功能，以及从古腾堡区块渲染邮件的代码。
|
||
|
||
您可以在 [`packages/js/email-editor`](https://github.com/woocommerce/woocommerce/tree/trunk/packages/js/email-editor) 中找到 JS 包。
|
||
|
||
## 工作流命令
|
||
|
||
注意：该包在 [WooCommerce 单体仓库](https://github.com/woocommerce/woocommerce/tree/trunk/packages/php/email-editor) 中开发。
|
||
|
||
我们使用 `composer` 运行脚本来执行命令。您可以使用 `composer run <命令>` 来运行它们。
|
||
如果您没有全局安装 `composer`，则需要全局安装它。[请查看如何安装](https://getcomposer.org/doc/00-intro.md)。
|
||
|
||
```bash
|
||
composer run env:start # 启动测试环境
|
||
composer run env:stop # 停止测试环境
|
||
composer run test:unit # 运行所有单元测试
|
||
composer run test:unit -- [path_to_tests] # 运行单个单元测试或一个目录的测试
|
||
composer run test:integration # 运行所有集成测试
|
||
composer run test:integration -- [path_to_tests] # 运行单个集成测试或一个目录的测试
|
||
composer code-style # 检查代码风格
|
||
```
|
||
|
||
## PHPStan 命令
|
||
|
||
以下命令可通过 pnpm 用于运行 PHP 静态分析：
|
||
|
||
```bash
|
||
pnpm run phpstan [--skip-cleanup] # 使用 PHP 8.4 进行 PHPStan PHP 静态分析。使用 skip-cleanup 时，该命令不会删除已安装的依赖项。
|
||
pnpm run phpstan:php8 [--skip-cleanup] # 命令 `phpstan` 的别名
|
||
pnpm run phpstan:php7 [--skip-cleanup] # 使用 PHP 7.4 进行 PHPStan PHP 静态分析
|
||
```
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 要运行 tests/integration/Engine/Theme_Controller_Test.php 中定义的测试用例，请运行
|
||
composer run test:integration -- tests/integration/Engine/Theme_Controller_Test.php
|
||
```
|
||
|
||
更多测试指南请见 [writing-tests.md](packages/php/email-editor/zh-cn/writing-tests)
|
||
|
||
## 开发
|
||
|
||
**PHP** 包分为 `engine` 和 `integrations` 子目录。
|
||
Engine 包含编辑器核心的代码，而 integrations 用于扩展功能。
|
||
任何 **WooCommerce** 特定的内容都应放在 `plugins/woocommerce/src/Internal/EmailEditor` 文件夹中。
|
||
|
||
更多开发详情请见 [development.md](packages/php/email-editor/zh-cn/development)。
|
||
|
||
### 渲染器
|
||
|
||
#### 内容渲染器
|
||
|
||
- 负责将已保存的模板 + 邮件内容渲染为 HTML 或为电子邮件客户端渲染
|
||
- 流程为：预处理器 > 区块渲染器 > 后处理器
|
||
|
||
#### Root Renderer.php
|
||
|
||
- 获取渲染后的内容 HTML 并将其放入电子邮件 HTML 模板 template-canvas.php 中（我知道我们有很多称为“模板”的项目 🙁）
|
||
|
||
### 集成
|
||
|
||
[请查找 MailPoet PHP 集成。](https://github.com/mailpoet/mailpoet/tree/13bf305aeb29bbadd0695ee02a3735e62cc4f21f/mailpoet/lib/EmailEditor/Integrations/MailPoet)
|
||
|
||
[WooCommerce 集成](https://github.com/woocommerce/woocommerce/tree/6dfd5f16aecbeee2fae0ec30e0c7ce7036cfeaac/plugins/woocommerce/src/Internal/EmailEditor)
|
||
|
||
## 已知渲染问题
|
||
|
||
- 在某些（非全部）Outlook版本中，列宽度未被正确遵循。列将以全宽渲染。
|
||
|
||
## 操作和过滤器
|
||
|
||
这些操作和过滤器目前**仍在开发中**。
|
||
我们可能会添加、更新或删除其中任何一项。
|
||
|
||
**请谨慎使用**。
|
||
|
||
### 操作
|
||
|
||
| 名称 | 参数 | 描述 |
|
||
|--------------------------------------------------------------|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `woocommerce_email_editor_initialized` | `null` | 当电子邮件编辑初始化时调用 |
|
||
| `woocommerce_email_blocks_renderer_initialized` | `BlocksRegistry` | 当区块内容渲染器初始化时调用。您可以使用此操作添加新的 BlockRenderer |
|
||
| `woocommerce_email_editor_register_templates` | | 当基本空白电子邮件模板注册时调用。您可以通过 register_block_template 添加更多模板 |
|
||
| `woocommerce_email_editor_send_preview_email_before_wp_mail` | `string` $to, `string` $subject, `string` $body | 在通过 wp_mail 发送预览电子邮件前调用。使用此操作修改电子邮件头（例如，发件人地址、发件人名称）或执行发送前操作。 |
|
||
| `woocommerce_email_editor_send_preview_email_after_wp_mail` | `string` $to, `string` $subject, `string` $body, `bool` $result | 在通过 wp_mail 发送预览电子邮件后调用。使用此操作清理过滤器、记录结果或执行发送后操作。`$result` 表示成功与否。 |
|
||
| `woocommerce_email_editor_personalization_tags_for_post` | `int` $post_id | 在检索个性化标签前触发，允许扩展根据文章上下文注册或修改标签。仅在 post_id 为有效整数时触发。 |
|
||
|
||
### 筛选
|
||
|
||
| 名称 | 参数 | 返回值 | 描述 |
|
||
|--------------------------------------------------------------------|------------------------------------------------------------------|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `woocommerce_email_editor_post_types` | `Array` $post_types | `Array` EmailPostType | 应用于 `getPostTypes` 方法使用的帖子类型列表 |
|
||
| `woocommerce_email_editor_theme_json` | `WP_Theme_JSON` $core_theme_data | `WP_Theme_JSON` $theme_json | 应用于主题 json 数据。此主题 json 数据由 `WP_Theme_JSON_Resolver::get_core_data` 和 WooCommerce 自有的 `theme.json` 文件合并创建 |
|
||
| `woocommerce_email_renderer_styles` | `string` $template_styles, `WP_Post` $post | `string` $template_styles | 应用于电子邮件编辑模板样式。 |
|
||
| `woocommerce_email_content_renderer_styles` | `string` $content_styles, `WP_Post` $post | `string` $content_styles | 应用于 CSS 内联器使用前的内联内容样式。 |
|
||
| `woocommerce_is_email_editor_page` | `boolean` $is_editor_page | `boolean` | 检查当前页是否为电子邮件编辑页面 |
|
||
| `woocommerce_email_editor_send_preview_email` | `Array` $post_data | `boolean` 处理结果。邮件是否成功发送？ | 允许覆盖发送预览邮件功能。用户可选择使用自定义实现 |
|
||
| `woocommerce_email_editor_post_sent_status_args` | `Array` `sent` 帖子状态参数 | `Array` register_post_status 参数 | 允许更新已发送帖子状态的参数 |
|
||
| `woocommerce_email_blocks_renderer_parsed_blocks` | `Array` 已解析的区块数据 | `Array` 已解析的区块数据 | 可以在区块被电子邮件渲染器处理前修改已解析的区块。 |
|
||
| `woocommerce_email_editor_rendering_email_context` | `Array` $email_context | `Array` $email_context | 在电子邮件渲染期间应用，为区块渲染器提供上下文数据（例如 `recipient_email`、`user_id`、`order_id`）。 |
|
||
| `woocommerce_email_editor_send_preview_email_rendered_data` | `string` $data 已渲染的电子邮件, `WP_Post` $post | `string` 已渲染的电子邮件 | 允许在预览中显示或发送时修改已渲染的电子邮件 |
|
||
| `woocommerce_email_editor_send_preview_email_personalizer_context` | `string` $content_styles, `WP_Post` $post` $personalizer_context | `Array` 个性化器上下文数据 | 允许修改发送预览邮件功能的个性化器上下文数据 |
|
||
| `woocommerce_email_editor_send_preview_email_subject` | `string` $subject, `WP_Post` $post | `string` 电子邮件主题 | 允许在预览邮件发送或渲染前修改其主题。默认为文章标题。 |
|
||
| `woocommerce_email_editor_synced_site_styles` | `Array` $synced_data, `Array` $site_data | `Array` 修改后的同步数据 | 用于在将同步的站点样式数据应用于电子邮件主题前进行过滤。 |
|
||
| `woocommerce_email_editor_site_style_sync_enabled` | `bool` $enabled | `bool` | 用于控制站点样式同步功能是否启用或禁用。返回 `false` 将禁用站点主题同步。 |
|
||
| `woocommerce_email_editor_site_theme` | `WP_Theme_JSON` $site_theme | `WP_Theme_JSON` | 在将样式同步到电子邮件编辑前修改站点主题。 |
|
||
| `woocommerce_email_editor_allowed_iframe_style_handles` | `Array` $allowed_iframe_style_handles | `Array` $allowed_iframe_style_handles | 过滤编辑器 iframe 中允许的样式表句柄列表。 |
|
||
| `woocommerce_email_editor_script_localization_data` | `Array` $localization_data | `Array` $localization_data | 用于修改电子邮件编辑客户端使用的内联 JavaScript 变量。 |
|
||
| `woocommerce_email_editor_styles_unsupported_props` | `Array` $unsupported_props | `Array` $unsupported_props | 过滤不受支持的样式属性列表（作为嵌套键路径），这些属性将在区块样式转换为 CSS 前被移除。 |
|
||
|
||
## 日志记录
|
||
|
||
电子邮件编辑包包含日志记录功能，以帮助开发者识别和调试问题。该包提供了一个简单的日志记录器，可以写入 WordPress 调试日志或委托给另一个日志记录器。
|
||
|
||
### 用法
|
||
|
||
日志记录器在邮件编辑器初始化时会自动初始化。邮件编辑器内部使用它来记录各种事件和操作。
|
||
|
||
### 日志级别
|
||
|
||
支持以下日志级别：
|
||
|
||
- `emergency`：系统不可用
|
||
- `alert`：必须立即采取行动
|
||
- `critical`：严重条件
|
||
- `error`：错误条件
|
||
- `warning`：警告条件
|
||
- `notice`：正常但重要的条件
|
||
- `info`：信息性消息
|
||
- `debug`：调试级别消息
|
||
|
||
### 日志位置
|
||
|
||
默认情况下，如果 `WP_DEBUG_LOG` 已启用，日志会写入 WordPress 调试日志。具体行为取决于 `WP_DEBUG_LOG` 的配置方式：
|
||
|
||
- 如果 `WP_DEBUG_LOG` 设置为 `true`，日志会写入 `wp-content/debug.log`
|
||
- 如果 `WP_DEBUG_LOG` 设置为一个字符串路径（例如，`/path/to/custom/debug.log`），日志会写入该自定义位置
|
||
- 如果 `WP_DEBUG_LOG` 未定义或设置为 `false`，则日志记录被禁用
|
||
|
||
### 示例日志消息
|
||
|
||
该包记录各种事件，包括：
|
||
|
||
1. 邮件编辑初始化
|
||
2. 个性化标签注册
|
||
3. 重复的个性化标签注册尝试
|
||
|
||
示例日志条目：
|
||
|
||
```text
|
||
[2025-01-01 12:00:00] INFO: 正在初始化邮件编辑
|
||
[2025-01-01 12:00:00] INFO: 个性化标签注册表已初始化 {"tags_count": 15}
|
||
[2025-01-01 12:00:00] 警告：个性化标签已注册 {"token": "[user/firstname]", "name": "名", "category": "用户"}
|
||
```
|
||
|
||
### 自定义日志记录
|
||
|
||
您可以通过以下方式自定义日志记录行为：
|
||
|
||
1. 使用 `set_logger()` 方法设置委托日志记录器，以使用其他日志记录系统（例如，WooCommerce 的日志记录器）
|
||
2. 通过 wp-config.php 中的 `WP_DEBUG_LOG` 常量配置 WordPress 调试日志记录，以启用 / 禁用记录到 wp-content/debug.log
|
||
|
||
### 最佳实践
|
||
|
||
1. 为不同类型的消息使用适当的日志级别
|
||
2. 在日志消息中包含相关的上下文数据
|
||
3. 避免记录敏感信息
|
||
4. 为详细的故障排除信息使用调试级别
|
||
5. 为不影响功能的潜在问题使用警告级别
|
||
6. 为影响功能的问题使用错误级别 |
