15 KiB
15 KiB
WooCommerce 邮件编辑器
此文件夹包含 WooCommerce 邮件编辑器 PHP 包的代码。
此包涵盖引导邮件编辑器 JS 应用程序的功能，以及从古腾堡区块渲染邮件的代码。
您可以在 packages/js/email-editor 中找到 JS 包。
工作流命令
注意：该包在 WooCommerce 单体仓库 中开发。
我们使用 composer 运行脚本来执行命令。您可以使用 composer run <命令> 来运行它们。
如果您没有全局安装 composer，则需要全局安装它。请查看如何安装。
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 静态分析：
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 静态分析
示例：
# 要运行 tests/integration/Engine/Theme_Controller_Test.php 中定义的测试用例，请运行
composer run test:integration -- tests/integration/Engine/Theme_Controller_Test.php
更多测试指南请见 writing-tests.md
开发
PHP 包分为 engine 和 integrations 子目录。
Engine 包含编辑器核心的代码，而 integrations 用于扩展功能。
任何 WooCommerce 特定的内容都应放在 plugins/woocommerce/src/Internal/EmailEditor 文件夹中。
更多开发详情请见 development.md。
渲染器
内容渲染器
- 负责将已保存的模板 + 邮件内容渲染为 HTML 或为电子邮件客户端渲染
- 流程为：预处理器 > 区块渲染器 > 后处理器
Root Renderer.php
- 获取渲染后的内容 HTML 并将其放入电子邮件 HTML 模板 template-canvas.php 中（我知道我们有很多称为“模板”的项目 🙁）
集成
已知渲染问题
- 在某些（非全部）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，则日志记录被禁用
示例日志消息
该包记录各种事件，包括：
- 邮件编辑初始化
- 个性化标签注册
- 重复的个性化标签注册尝试
示例日志条目：
[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": "用户"}
自定义日志记录
您可以通过以下方式自定义日志记录行为：
- 使用
set_logger()方法设置委托日志记录器，以使用其他日志记录系统（例如，WooCommerce 的日志记录器） - 通过 wp-config.php 中的
WP_DEBUG_LOG常量配置 WordPress 调试日志记录，以启用 / 禁用记录到 wp-content/debug.log
最佳实践
- 为不同类型的消息使用适当的日志级别
- 在日志消息中包含相关的上下文数据
- 避免记录敏感信息
- 为详细的故障排除信息使用调试级别
- 为不影响功能的潜在问题使用警告级别
- 为影响功能的问题使用错误级别
