跳到主要内容

开始使用 Cart 和 Checkout 扩展

本文档是对 Cart 和 Checkout 模块扩展所需组件的高级概述。

为了开始，建议首先阅读 WordPress 的 Block Development Environment 文档，并按照 Tutorial: Build your first block 教程进行操作。

示例块模板包​

在 WooCommerce 仓库中有一个示例块模板。在阅读本文档时，如果已设置好此模板，可能会帮助您理解其中讨论的一些概念。请参阅 @woocommerce/extend-cart-checkout-block 包的文档，了解如何安装和运行示例块。

（注意：上面链接的仓库中的代码单独使用可能不太有用；这些代码是模板代码。按照 README 中的说明，这些代码将被转换为常规的 JS 和 PHP 代码。）

前端扩展​

要扩展模块的前端，扩展必须使用 JavaScript。JavaScript 文件必须在加载到网页上后才能产生任何效果。

构建系统​

某些扩展可能非常简单，只包含一个 JavaScript 文件，而其他扩展可能很复杂，代码可能被拆分为多个文件。无论如何，建议将这些文件打包在一起并压缩成一个单独的输出文件。如果您的扩展有几个不同的部分，并且这些部分仅在特定页面上加载，则建议使用打包拆分，但这超出了本文档的范围。

要设置构建系统，建议的做法是与 WordPress 保持一致，并使用一个名为 @wordpress/scripts 的 JavaScript 包。此包包含一个名为 build 的脚本。默认情况下，此脚本会将您的脚本构建成一个单独的输出文件，可以使用 wp_enqueue_script 进行加载。

@wordpress/scripts 中 build 脚本的基本配置可以通过在插件的根目录下创建一个 webpack.config.js 文件来覆盖。示例块展示了如何扩展基本配置。

WooCommerceDependencyExtractionWebpackPlugin​

请参考 WordPress Dependency Extraction Webpack Plugin 和 WooCommerce Dependency Extraction Webpack Plugin。

这个 Webpack 插件用于：

  • 将可作为 WordPress 站点上共享脚本或模块的依赖项外部化。
    • 这意味着，当您从 @woocommerce/blocks-checkout 导入内容时，它会将该路径解析为 window.wc.wcBlocksCheckout，而无需您修改代码。 这使得您的代码更易于阅读，并允许这些包只在页面上加载一次。
  • 为每个入口点添加一个资源文件，该文件声明一个包含入口点所需的 WordPress 脚本或模块依赖项列表的对象。 资源文件还包含针对当前源代码计算的当前版本。

此插件输出的 PHP "资源文件" 包含您的脚本注册所需的的信息，例如依赖项和路径。

如果您编写了使用 WooCommerce Dependency Extraction Webpack 插件进行构建的代码，则每个入口点都会生成一个资源文件。 此资源文件是一个 PHP 文件，其中包含有关您的脚本的信息，特别是依赖项和版本，以下是一个示例：

<?php
return array(
  'dependencies' => array(
    'react',
    'wc-settings',
    'wp-block-editor',
    'wp-blocks',
    'wp-components',
    'wp-element',
    'wp-i18n',
    'wp-primitives'
  ),
  'version' => '455da4f55e1ac73b6d34'
);

在注册您的脚本时，使用此资源文件可确保正确加载依赖项，并且客户端可以获取您脚本的最新版本（版本用于确保您的脚本是从新获取的，而不是从缓存中获取）。

<?php
$script_path = '/build/index.js';
$script_url  = plugins_url( $script_path, __FILE__ );

$script_asset_path = dirname( __FILE__ ) . '/build/index.asset.php';
$script_asset      = file_exists( $script_asset_path )
  ? require $script_asset_path
  : [
    'dependencies' => [],
    'version'      => $this->get_file_version( $script_path ),
  ];

wp_register_script(
  'example-blocks-integration-handle',
  $script_url,
  $script_asset['dependencies'],
  $script_asset['version'],
  true
);

请参阅 购物车和结账 – 处理脚本、样式和数据 文档，以获取有关如何使用 IntegrationInterface 正确注册脚本的更多信息。

创建一个区块​

在示例区块中，有一个名为 "checkout-newsletter-subscription-block" 的目录，其中包含在结账流程中注册内部区块所需的文件。 示例区块模板仅设置为导入和构建单个区块，但可以通过修改 Webpack 配置文件来构建多个区块。 此操作不在本文档的范围内，请参考 Webpack 文档。

教程：构建你的第一个区块 中涵盖的原则也适用于此处。

修改前端现有值​

您可能不需要创建区块来使您的扩展程序按照您想要的方式工作，例如，如果您的扩展程序仅通过过滤器修改现有内容。

在这种情况下，您可以从示例区块中移除区块文件夹，修改 Webpack 配置文件，使其不再从该目录读取，并将您需要的代码包含在入口 JavaScript 文件中。

有关如何使用过滤器的更多信息，请参阅 过滤器注册表 和 可用过滤器 文档。

将 WooCommerce 组件导入到您的扩展程序中​

可以从 @woocommerce/blocks-components (通过 @woocommerce/dependency-extraction-webpack-plugin 外部化为 window.wc.blocksComponents) 导入组件。 可用组件的列表可以在 WooCommerce Storybook 中查看，位于 "WooCommerce Blocks -> External components" 下。

导入 Button 组件的示例：

import { Button } from '@woocommerce/blocks-components';

const MyComponent = () => {
  return <div class="my-wrapper">
    <Button type="button" />
  </div>;
}

导入 WooCommerce 工具和 React Hooks​

一些结账工具和 React Hooks 可从 @woocommerce/blocks-checkout 外部使用。 请参阅 结账工具 文档，了解可用的工具。

要访问商店数据，建议使用 wc/store/... 数据存储，而不是导入内部 Hooks，例如 useStoreCart。

后端可扩展性​

在结账过程中修改信息​

可以使用 PHP 修改购物车和结账模块的服务器端部分。 一些来自短代码购物车/结账体验的操作和过滤器也可以使用，但并非全部。 我们有一个文档，详细说明了哪些钩子受支持，以及替代方案 (Hook alternatives document)。

扩展商店 API​

如果需要修改商店 API 的工作方式，或者扩展回复中的数据，请参阅 Extending the Store API。