woocommerce/packages/php/email-editor/docs/zh-cn/site-style-sync-hooks.md

站点风格同步钩子和筛选器

WooCommerce 电子邮件编辑站点风格同步功能提供了多个钩子和筛选器，开发者可以使用它们来自定义同步行为。

筛选器

woocommerce_email_editor_synced_site_styles

在应用到邮件主题前，过滤已同步的站点样式数据。

/**
 * 过滤已同步的站点样式数据
 *
 * @since 1.1.0
 * @param array $synced_data 转换后的邮件兼容主题数据
 * @param array $site_data 原始站点主题数据
 * @return array 修改后的同步数据
 */
apply_filters( 'woocommerce_email_editor_synced_site_styles', $synced_data, $site_data );

示例用法:

add_filter( 'woocommerce_email_editor_synced_site_styles', function( $synced_data, $site_data ) {
    // 为邮件覆盖特定颜色
    if ( isset( $synced_data['styles']['color'] ) ) {
        $synced_data['styles']['color']['background'] = '#ffffff'; // 强制白色背景
        $synced_data['styles']['color']['text'] = '#333333'; // 强制深色文本以提高可读性
    }
    
    // 添加自定义的邮件专用字体
    if ( isset( $synced_data['settings']['typography']['fontFamilies'] ) ) {
        $synced_data['settings']['typography']['fontFamilies'] = array(
            'slug' => 'email-custom',
            'name' => '邮件自定义字体',
            'fontFamily' => 'Arial, sans-serif'
        );
    }
    
    return $synced_data;
}, 10, 2
 );

woocommerce_email_editor_site_style_sync_enabled

控制是否启用站点样式同步功能。

/**
 * 用于启用/禁用站点样式同步功能的筛选器
 *
 * @since 1.1.0
 * @param bool $enabled 站点样式同步是否已启用
 * @return bool
 */
apply_filters( 'woocommerce_email_editor_site_style_sync_enabled', true );

用法示例:

// 为特定主题禁用站点样式同步
add_filter( 'woocommerce_email_editor_site_style_sync_enabled', function( $enabled ) {
    $current_theme = get_template();
    $incompatible_themes = array( 'legacy-theme', 'custom-theme' );
    
    if ( in_array( $current_theme, $incompatible_themes ) ) {
        return false;
    }
    
    return $enabled;
});

woocommerce_email_editor_site_theme

过滤用于邮件样式同步的站点主题数据。

此过滤器允许在同步邮件编辑器的全局样式时，覆盖所使用的站点主题。适用于无法直接访问主题数据的环境（例如，wp.com Atomic 和 Jetpack 站点）。

/**
 * 过滤用于邮件样式同步的站点主题数据。
 *
 * @since 2.3.0
 * @param WP_Theme_JSON $site_theme 站点主题数据。
 * @return WP_Theme_JSON 修改后的站点主题数据。
 */
apply_filters( 'woocommerce_email_editor_site_theme', $site_theme );

用法示例:

// 对于无法直接访问主题数据的环境，使用自定义主题数据覆盖站点主题
add_filter( 'woocommerce_email_editor_site_theme', function( $site_theme ) {
    // 从外部源获取主题数据
    $custom_theme_data = get_custom_theme_data();

    if ( $custom_theme_data ) {
        return new WP_Theme_JSON( $custom_theme_data, 'custom' );
    }

    return $site_theme;
});

高级自定义示例

自定义字体映射

add_filter( 'woocommerce_email_editor_synced_site_styles', function( $synced_data, $site_data ) {
    // 将特定的站点字体映射到首选的邮件字体
    $font_mappings = array(
        'Inter' => 'Arial, sans-serif',
        'Playfair Display' => 'Georgia, serif',
        'Roboto Mono' => '"Courier New", monospace',
    );
    
    if ( isset( $synced_data['styles']['typography']['fontFamily'] ) ) {
        $current_font = $synced_data['styles']['typography']['fontFamily'];
        
        foreach ( $font_mappings as $site_font => $email_font ) {
            if ( strpos( $current_font, $site_font ) !== false ) {
                $synced_data['styles']['typography']['fontFamily'] = $email_font;
                break;
            }
        }
    }
    
    return $synced_data;
}, 10, 2 );

基于电子邮件类型的条件同步

add_filter( 'woocommerce_email_editor_synced_site_styles', function( $synced_data, $site_data ) {
    global $post;
    
    // 为不同的电子邮件类型应用不同的样式
    if ( $post && get_post_meta( $post->ID, 'email_type', true ) === 'promotional' ) {
        // 为促销邮件使用品牌颜色
        $synced_data['styles']['color']['background'] = '#f8f9fa';
        $synced_data['styles']['elements']['button']['color']['background'] = '#007cba';
    } elseif ( $post && get_post_meta( $post->ID, 'email_type', true ) === 'transactional' ) {
        // 为交易邮件使用中性颜色
        $synced_data['styles']['color']['background'] = '#ffffff';
        $synced_data['styles']['elements']['button']['color']['background'] = '#666666';
    }
    
    return $synced_data;
}, 10, 2 );