WooCommerce支付网关选项页添加自定义选项：标签与提示异常求助

问题背景 #

我正在开发一款插件，需要在特定WooCommerce支付网关的选项页中添加插件配置选项，不修改网关原有功能，仅展示自定义选项。参考官方文档编写代码后，复选框的保存/读取功能正常，但存在两个问题：

1. 复选框的label文本未显示
2. 设置desc_tip => true后，描述未以提示气泡形式展示，而是显示在复选框下方（后续添加的其他字段提示气泡正常）

代码实现 #

<?php

class MyPluginClass {   
    
    /**
    * Initialise the class
    **/

    public function init() {

        // Hook into the Payment tab of WooCommerce settings and add 
        // options to the Gateway's options page
        // (Tab's ID is 'checkout' even though the tab is called payments)

        add_filter( 'woocommerce_get_settings_checkout', array($this, 'add_options_to_gateway_options_page'), 10, 2 );
    }

    /**
    * Add options to the gateway's options page
    **/

    public function add_options_to_gateway_options_page( $settings, $current_section_id ) {

        // If the current section is not the required gateway, return the settings
        // (replace gateway_id with the actual gateway ID. this is 
        // the 'section' argument from the URL when viewing the gateway's options page)

        if ( 'gateway_id' != $current_section_id  ) return $settings;

        // Create settings

        $my_settings = array(
            array (
                'title' => __('Automation options'),
                'type' => 'title',
                'description' => ''
            ),
            array(
                'id' => 'my_plugin_enabled',
                'name' => 'my_plugin_enabled',
                'title' => __('Gateway automations', 'my_plugin'),
                'label' => __('Enable gateway automations', 'my_plugin'),
                'description' => __('Enable the gateway automations plugin', 'my_plugin'),
                'desc_tip' => true,
                'type' => 'checkbox',
                'default' => 'yes'
            ),
            array(
                'type' => 'sectionend',
                'id' => 'my_plugin'
            )
        );

        return $my_settings;
    }
}

$myPlugin = new MyPluginClass;
$myPlugin->init();

生成的HTML #

// The resulting HTML

<h2>Automation options</h2>
<table class="form-table">
    <tbody>
        <tr valign="top" class="">
            <th scope="row" class="titledesc">Gateway automations</th>
            <td class="forminp forminp-checkbox">
                <fieldset>
                    <legend class="screen-reader-text"><span>Gateway automations</span></legend>
                    <label for="my_plugin_enabled">
                        <input name="my_plugin_enabled" id="my_plugin_enabled" type="checkbox" class="" value="1">
                    </label>
                </fieldset>
            </td>
        </tr>
    </tbody>
</table>

问题更新 #

将'description' => __('...')修改为'desc' => __('...')后，描述显示在复选框下方，但仍不是提示气泡；后续添加的其他字段按相同格式配置，提示气泡正常工作，但所有字段的label依然不显示。

解决办法 #

1. 复选框Label不显示的问题 #

WooCommerce的checkbox类型字段默认渲染逻辑不会输出label参数内容，而是把title作为屏幕阅读器的legend文本。要显示自定义Label，可采用以下方案：

方案一：自定义字段渲染逻辑

通过woocommerce_admin_field_{type}钩子覆盖checkbox的输出，同时实现Label显示和提示气泡功能：

add_action('woocommerce_admin_field_checkbox', function($field) {
    // 仅针对目标字段修改
    if ($field['id'] !== 'my_plugin_enabled') {
        woocommerce_admin_field_checkbox($field);
        return;
    }
    ?>
    <tr valign="top">
        <th scope="row" class="titledesc">
            <label for="<?php echo esc_attr($field['id']); ?>"><?php echo esc_html($field['title']); ?></label>
            <?php if ($field['desc_tip']) : ?>
                <span class="woocommerce-help-tip" data-tip="<?php echo esc_attr($field['desc']); ?>"></span>
            <?php endif; ?>
        </th>
        <td class="forminp forminp-checkbox">
            <fieldset>
                <label for="<?php echo esc_attr($field['id']); ?>">
                    <input name="<?php echo esc_attr($field['id']); ?>" 
                           id="<?php echo esc_attr($field['id']); ?>" 
                           type="checkbox" 
                           value="1" 
                           <?php checked($field['value'], 'yes'); ?>>
                    <?php echo esc_html($field['label']); ?>
                </label>
                <?php if (!$field['desc_tip'] && $field['desc']) : ?>
                    <p class="description"><?php echo wp_kses_post($field['desc']); ?></p>
                <?php endif; ?>
            </fieldset>
        </td>
    </tr>
    <?php
});

方案二：合并内容到title

如果不需要单独的Label，可直接将Label文本合并到title中，利用左侧表头显示完整说明。

2. 提示气泡不显示的问题 #

确保满足以下条件：

• 使用desc参数而非description（已修改正确）
• desc_tip设置为true
• 站点未自定义CSS覆盖WooCommerce默认的.woocommerce-help-tip样式

注意：WooCommerce默认checkbox字段的提示气泡只会附加在左侧表头的title旁，若要让提示气泡关联到复选框，需使用上述自定义渲染逻辑。

内容的提问来源于stack exchange，提问作者Baddie