title: "为 WooCommerce 扩展创建自定义设置" post_status: publish comment_status: open taxonomy: category: - woocommerce post_tag: - Settings And Config - Extensions - Repos

为 WooCommerce 扩展创建自定义设置

如果您正在定制 WooCommerce 或为其添加自定义功能，您可能需要一个设置页面。创建设置页面最简单的方法之一是利用 WC_Integration 类。使用 Integration 类会自动在 WooCommerce > 设置 > 集成 下创建一个新的设置页面，并且会自动保存和清理您的数据。我们创建了这个教程，以便您了解如何创建新的集成。

配置集成

创建集成至少需要两个文件，因此您需要创建一个目录。

创建主插件文件

创建您的主插件文件，使用钩子挂载到 plugins_loaded 钩子，并检查 WC_Integration 类是否存在。如果不存在，则用户很可能没有激活 WooCommerce。完成此操作后，您需要注册该集成。加载集成文件（稍后会介绍该文件）。使用 woocommerce_integrations 过滤器，将一个新的集成添加到数组中。

创建集成类

现在我们已经完成了框架的搭建，接下来我们来实现这个集成类。已经存在一个 WC_Integration 类，所以我们想要创建一个子类。这样它就能继承所有现有的方法和数据。你需要为你的集成设置一个 ID、一个描述和一个标题。这些信息将在集成页面上显示。你还需要通过调用 $this->init_form_fields(); 和 $this->init_settings(); 来加载设置。你还需要通过调用 woocommerce_update_options_integration_{你的方法 ID} 钩子来保存你的选项。最后，你必须输入一些设置来保存！我们在下面包含了两个虚拟字段，但我们将在下一部分更详细地介绍字段。

添加到名为 class-wc-integration-demo-integration.php 的文件中。

<?php
/**
 * 集成示例集成。
 *
 * @package  WC_Integration_Demo_Integration
 * @category 分类
 * @author   Patrick Rauland
 */
if ( ! class_exists( 'WC_Integration_Demo_Integration' ) ) :
    /**
     * 示例集成类。
     */
    class WC_Integration_Demo_Integration extends WC_Integration {
        /**
         * 初始化并注册钩子。
         */
        public function __construct() {
            global $woocommerce;

            $this->id                 = 'integration-demo';
            $this->method_title       = __( '集成示例', 'woocommerce-integration-demo' );
            $this->method_description = __( '一个集成示例，用于展示如何轻松扩展 WooCommerce。', 'woocommerce-integration-demo' );

            // 加载设置。
            $this->init_form_fields();
            $this->init_settings();

            // 定义用户设置的变量。
            $this->api_key = $this->get_option( 'api_key' );
            $this->debug   = $this->get_option( 'debug' );

            // 操作。
            add_action( 'woocommerce_update_options_integration_' .  $this->id, array( $this, 'process_admin_options' ) );
        }

WooCommerce 集成示例

简介

本插件演示了如何添加新的 WooCommerce 集成。

术语表

已发布: Published
设置: Settings
安装: Install
个人资料: Profile
作者: Author
调试: Debug
错误: Error
API: API
发布者: Published by
集成: Integration
表单字段: Form fields
插件名称: Plugin name
调试日志: Debug Log
文件名: File name
复选框: Checkbox
注册: Register
版本: Version
作者：: Author:
版本：: Version:
许可证: Licenses

添加到名为 wc-integration-demo.php 的文件。

<?php
/**
 * 插件名称: WooCommerce 集成示例
 * 插件 URI: https://gist.github.com/BFTrick/091d55feaaef0c5341d8
 * 描述: 一个插件，演示如何添加新的 WooCommerce 集成。
 * 作者: Patrick Rauland
 * 作者 URI: http://speakinginbytes.com/
 * 版本: 1.0
 *
 * 本程序是自由软件：您可以根据自由软件基金会发布的 GNU 通用公共许可证（版本 3 或更高版本）的条款重新分发和/或修改它。
 *
 * 本程序旨在提供帮助，但不对其提供任何保证；不提供任何明示或暗示的保证，包括适销性和特定用途的适用性。有关更多详细信息，请参阅 GNU 通用公共许可证。
 *
 * 应该随本程序一起提供 GNU 通用公共许可证的副本。如果未提供，请参阅 <http://www.gnu.org/licenses/>。
 *
 */
if ( ! class_exists( 'WC_Integration_Demo' ) ) :
    /**
     * 集成示例类。
     */
    class WC_Integration_Demo {
        /**
         * 构造函数。
         */
        public function __construct() {
            add_action( 'plugins_loaded', array( $this, 'init' ) );
        }

        /**
         * 初始化插件。
         */
        public function init() {
            // 检查 WooCommerce 是否已安装。
            if ( class_exists( 'WC_Integration' ) ) {
                // 包含我们的集成类。
                include_once 'class-wc-integration-demo-integration.php';
                // 注册集成。
                add_filter( 'woocommerce_integrations', array( $this, 'add_integration' ) );
            } else {
                // 如果需要，可以抛出管理员错误。
            }
        }

        /**
         * 初始化集成设置表单字段。
         */
        public function init_form_fields() {
            $this->form_fields = array(
                'api_key' => array(
                    'title'       => __( 'API Key', 'woocommerce-integration-demo' ),
                    'type'        => 'text',
                    'description' => __( '请输入您的 API Key。您可以在 "个人资料" 下拉菜单（右上角）> API Keys 中找到它。', 'woocommerce-integration-demo' ),
                    'desc_tip'    => true,
                    'default'     => '',
                ),
                'debug' => array(
                    'title'       => __( 'Debug Log', 'woocommerce-integration-demo' ),
                    'type'        => 'checkbox',
                    'label'       => __( '启用日志记录', 'woocommerce-integration-demo' ),
                    'default'     => 'no',
                    'description' => __( '记录 API 请求等事件。', 'woocommerce-integration-demo' ),
                ),
            );
        }
    }
endif;

/**
         * 向 WooCommerce 添加一个新的集成。
         *
         * @param array 集成的数组。
         */
        public function add_integration( $integrations ) {
            $integrations[] = 'WC_Integration_Demo_Integration';
            return $integrations;
        }
    }
endif;

$WC_Integration_Demo = new WC_Integration_Demo( __FILE__ );

创建设置

如果您查看了上一部分，您会看到我们使用 init_form_fields() 方法添加了两个虚拟设置。

设置的类型

WooCommerce 支持 8 种类型的设置。

text (文本)
price (价格)
decimal (小数)
password (密码)
textarea (文本域)
checkbox (复选框)
select (选择)
multiselect (多选)

这些设置具有属性，您可以用于自定义它们。这些属性会影响设置在设置页面上的外观和行为，但不会影响设置本身。属性的表现方式会根据设置的类型而略有不同。例如，占位符 (placeholder) 不适用于复选框。要了解它们的确切工作方式，您应该查看源代码。例如：

title (标题)
class (类)
css (CSS)
placeholder (占位符)
description (描述)
default (默认值)
desc_tip (提示信息)

创建您自己的设置

内置的设置非常棒，但您可能需要额外的控件来创建您的设置页面。这就是为什么我们提供了一些方法来帮助您完成。首先，通过将其添加到 $this->form_fields 数组中来定义一个设置，并在 type 下指定您想要的表单控件类型。您可以通过创建一个以 generate_{ type }_html 命名的函数来覆盖默认的 HTML 标记，该函数将输出 HTML 标记。要指定如何渲染按钮，您需要添加一个名为 generate_button_html 的函数。对于文本区域，您需要添加一个 generate_textarea_html 函数，依此类推。（请查看 WooCommerce 源代码中 WC_Settings_API 类的 generate_settings_html 方法，以了解 WooCommerce 如何使用此方法。）下面的示例创建了一个按钮，该按钮链接到 WooCommerce.com。

/**
 * 初始化集成设置表单字段。
 *
 * @return void
 */
public function init_form_fields() {
    $this->form_fields = array(
        // 别忘了在这里添加您的其他设置
        'customize_button' => array(
            'title'             => __( '自定义!', 'woocommerce-integration-demo' ),
            'type'              => 'button',
            'custom_attributes' => array(
                'onclick' => "location.href='https://woocommerce.com'",
            ),
            'description'       => __( '通过直接访问集成站点来自定义您的设置。', 'woocommerce-integration-demo' ),
            'desc_tip'          => true,
        )
    );
}


/**
 * 生成按钮 HTML。
 *
 * @access public
 * @param mixed $key
 * @param mixed $data
 * @since 1.0.0
 * @return string
 */
public function generate_button_html( $key, $data ) {
    $field    = $this->plugin_id . $this->id . '_' . $key;
    $defaults = array(
        'class'             => 'button-secondary',
        'css'               => '',
        'custom_attributes' => array(),
        'desc_tip'          => false,
        'description'       => '',
        'title'             => '',
    );

    $data = wp_parse_args( $data, $defaults );

    ob_start();
    ?>
    <tr valign="top">
        <th scope="row" class="titledesc">
            <label for="<?php echo esc_attr( $field ); ?>"><?php echo wp_kses_post( $data['title'] ); ?></label>
            <?php echo $this->get_tooltip_html( $data ); ?>
        </th>
        <td class="forminp">
            <fieldset<
                <legend class="screen-reader-text"><span><?php echo wp_kses_post( $data['title'] ); ?></span></legend>
                <button class="<?php echo esc_attr( $data['class'] ); ?>" type="button" name="<?php echo esc_attr( $field ); ?>" id="<?php echo esc_attr( $field ); ?>" style="<?php echo esc_attr( $data['css'] ); ?>" <?php echo $this->get_custom_attribute_html( $data ); ?>><?php echo wp_kses_post( $data['title'] ); ?></button>
                <?php echo $this->get_description_html( $data ); ?>
            </fieldset>
        </td>
    </tr>
    <?php
    return ob_get_clean();
}

数据验证与清洗

为了提供最佳的用户体验，您很可能需要验证和清洗您的数据。集成类已经执行了基本的清洗操作，以确保没有恶意代码，但您可以通过删除未使用的数据来进一步进行清洗。清洗数据的示例是与第三方服务集成，其中所有 API 密钥都使用大写字母。您可以将 API 密钥转换为大写，这对于用户来说会更清晰。

清洗

我们将首先演示如何清洗数据，因为它更容易理解。但是，您需要记住的一点是，清洗操作发生在验证之后。因此，如果某些数据未通过验证，则不会进入清洗步骤。

/**
 * 初始化并注册钩子。
 */
public function __construct() {

    // 执行其他构造函数操作

    // 过滤器。
    add_filter( 'woocommerce_settings_api_sanitized_fields_' . $this->id, array( $this, 'sanitize_settings' ) );

}

/**
 * 清洗我们的设置
 */
public function sanitize_settings( $settings ) {
    // 我们将 API 密钥转换为大写，因为我们的虚拟 API 这样工作
    if ( isset( $settings ) &&
         isset( $settings['api_key'] ) ) {
        $settings['api_key'] = strtoupper( $settings['api_key'] );
    }
    return $settings;
}

验证

验证并非总是必要的，但进行验证是很有用的。如果您的 API 密钥始终是 10 个字符长，并且有人输入了长度不是 10 的密钥，则您可以打印错误信息，并避免用户在他们认为输入正确时遇到的许多问题。首先，为每个要验证的字段设置一个 validate_{设置键}_field 方法。例如，对于 api_key 字段，您需要一个 validate_api_key_field() 方法。

public function validate_api_key_field( $key, $value ) {
    if ( isset( $value ) && 20 < strlen( $value ) ) {
        WC_Admin_Settings::add_error( esc_html__( '看起来您在 API 密钥字段中犯了一个错误。 确保它不超过 20 个字符', 'woocommerce-integration-demo' ) );
    }

    return $value;
}

一个完整的示例

如果您一直关注，您应该有一个完整的集成示例。如果您遇到任何问题，请参阅我们的完整集成演示。