woocommerce-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WooCommerce Extension Architecture

WooCommerce扩展架构

Reference for WooCommerce extension setup, plugin headers, compatibility declarations, and architecture fundamentals.

For specific topics see the related skills:

woocommerce-payments — Payment gateways, block checkout integration
woocommerce-data — Order/product/customer CRUD, HPOS, Store API, REST API
woocommerce-hooks — Hooks, settings pages, custom emails, WP-CLI, testing

本指南为WooCommerce扩展的搭建、插件头部配置、兼容性声明以及架构基础提供参考。

如需了解特定主题，请查看相关技能：

woocommerce-payments — 支付网关、区块结账集成
woocommerce-data — 订单/产品/客户CRUD操作、HPOS、Store API、REST API
woocommerce-hooks — 钩子、设置页面、自定义邮件、WP-CLI、测试

1. Check WooCommerce Is Active

1. 检查WooCommerce是否激活

Always gate your plugin on WooCommerce availability:

php

add_action( 'plugins_loaded', 'mce_init' );

function mce_init(): void {
    if ( ! class_exists( 'WooCommerce' ) ) {
        add_action( 'admin_notices', function (): void {
            echo '<div class="error"><p>' .
                esc_html__( 'My Extension requires WooCommerce.', 'my-extension' ) .
                '</p></div>';
        } );
        return;
    }
    // Safe to use WooCommerce APIs from here.
}

始终要先检查WooCommerce是否可用，以此作为插件运行的前提：

php

add_action( 'plugins_loaded', 'mce_init' );

function mce_init(): void {
    if ( ! class_exists( 'WooCommerce' ) ) {
        add_action( 'admin_notices', function (): void {
            echo '<div class="error"><p>' .
                esc_html__( 'My Extension requires WooCommerce.', 'my-extension' ) .
                '</p></div>';
        } );
        return;
    }
    // 从此处开始可以安全使用WooCommerce的API。
}

2. Plugin Header

2. 插件头部信息

php

/**
 * Plugin Name: My WooCommerce Extension
 * Plugin URI:  https://example.com/my-extension
 * Description: Extends WooCommerce with custom features.
 * Version:     1.0.0
 * Author:      Your Name
 * Requires Plugins: woocommerce
 * WC requires at least: 8.0
 * WC tested up to: 10.4
 * Requires PHP: 7.4
 */

Header	Purpose
`Requires Plugins: woocommerce`	WordPress 6.5+ enforces the dependency automatically
`WC requires at least`	Minimum WooCommerce version
`WC tested up to`	Latest tested WooCommerce version (shows in admin)

php

/**
 * Plugin Name: My WooCommerce Extension
 * Plugin URI:  https://example.com/my-extension
 * Description: Extends WooCommerce with custom features.
 * Version:     1.0.0
 * Author:      Your Name
 * Requires Plugins: woocommerce
 * WC requires at least: 8.0
 * WC tested up to: 10.4
 * Requires PHP: 7.4
 */

头部字段	用途
`Requires Plugins: woocommerce`	WordPress 6.5+会自动强制检查该依赖项
`WC requires at least`	兼容的最低WooCommerce版本
`WC tested up to`	已测试的最新WooCommerce版本（会在后台显示）

3. Declaring Feature Compatibility

3. 声明功能兼容性

php

add_action( 'before_woocommerce_init', function (): void {
    if ( class_exists( '\Automattic\WooCommerce\Utilities\FeaturesUtil' ) ) {
        // Declare HPOS compatibility.
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
        // Declare Block Checkout compatibility.
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'cart_checkout_blocks',
            __FILE__,
            true
        );
    }
} );

Feature key	What it declares
`custom_order_tables`	HPOS (High-Performance Order Storage) compatibility
`cart_checkout_blocks`	Block Checkout compatibility

php

add_action( 'before_woocommerce_init', function (): void {
    if ( class_exists( '\Automattic\WooCommerce\Utilities\FeaturesUtil' ) ) {
        // 声明HPOS兼容性。
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
        // 声明区块结账兼容性。
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
            'cart_checkout_blocks',
            __FILE__,
            true
        );
    }
} );

功能标识	声明内容
`custom_order_tables`	HPOS（高性能订单存储）兼容性
`cart_checkout_blocks`	区块结账兼容性

4. Interactivity API Stores Are Private

4. Interactivity API存储为私有

All WooCommerce Interactivity API stores use

lock: true

— they are not extensible. Removing or changing store state/selectors is not a breaking change. Do not depend on WC store internals in your extension.

所有WooCommerce Interactivity API存储均使用

lock: true

设置——它们不支持扩展。移除或修改存储状态/选择器不属于破坏性变更。请不要在你的扩展中依赖WC存储的内部实现。

5. Common Mistakes

5. 常见错误

Mistake	Fix
Not checking if WooCommerce is active	Wrap init in `class_exists('WooCommerce')` check
Not declaring HPOS compatibility	Add `FeaturesUtil::declare_compatibility('custom_order_tables', ...)`
Not declaring Block Checkout compatibility	Add `FeaturesUtil::declare_compatibility('cart_checkout_blocks', ...)`
Using `new` for DI-managed WC classes	Use `wc_get_container()->get( ClassName::class )` for `src/` singletons
Depending on WC Interactivity API stores	All WC stores are `lock: true` (private) — can change without notice
Missing `Requires Plugins: woocommerce` header	Add it — WordPress 6.5+ enforces the dependency

错误	修复方案
未检查WooCommerce是否激活	将初始化代码包裹在 `class_exists('WooCommerce')` 检查中
未声明HPOS兼容性	添加 `FeaturesUtil::declare_compatibility('custom_order_tables', ...)` 代码
未声明区块结账兼容性	添加 `FeaturesUtil::declare_compatibility('cart_checkout_blocks', ...)` 代码
直接使用 `new` 实例化由DI管理的WC类	对于 `src/` 目录下的单例类，使用 `wc_get_container()->get( ClassName::class )` 获取实例
依赖WC Interactivity API存储	所有WC存储均为 `lock: true` （私有）——其实现可能会随时变更，无需提前通知
缺少 `Requires Plugins: woocommerce` 头部	添加该头部——WordPress 6.5+会自动强制检查该依赖