WooCommerce 文档

title: "如何扩展 WooCommerce 分析报告" post_status: publish comment_status: open taxonomy: category: - woocommerce post_tag: - Analytics - Features - Repos

如何扩展 WooCommerce 分析报告

简介

本文档旨在指导您如何通过基本的 UI 下拉菜单、添加查询参数以及修改 SQL 查询和最终的报告数据来扩展 WC-Admin 报告。 此示例将创建一个货币选择器，用于根据特定货币查看订单报告。

快速开始

我们将使用 @woocommerce/create-woo-extension 来构建一个现代的 WordPress JavaScript 开发环境，用于插件。 该工具创建了一个完全可用的开发环境，用于与 WooCommerce 集成。

在此示例中，我们将使用 sql-modification 变体来创建一个基本的报告扩展，以便您可以在此基础上进行构建。

在您的 wp-content/plugins 目录中，运行以下命令来创建您的扩展：

npx @wordpress/create-block -t @woocommerce/create-woo-extension --variant=sql-modification my-extension-name

导航到新创建的文件夹并开始开发：

cd my-extension-name
npm run start

可选地，您可以使用 wp-env 来创建一个本地的 WordPress 环境：

npm -g i @wordpress/env
wp-env start

不要忘记前往 /wp-admin/plugins.php 并激活您的插件。

填充测试数据

接下来，设置一些订单以获取示例数据。 在 WooCommerce > 设置 > 货币 中，我添加了三个测试订单，分别使用墨西哥比索、美元和新西兰元。

完成此操作后，请查看 WC-Admin 以确保订单已显示，方法是访问 /wp-admin/admin.php?page=wc-admin&period=today&path=%2Fanalytics%2Forders&compare=previous_year。 请注意，在没有进行任何修改的情况下，货币显示值将根据您在 WooCommerce 设置中当前配置的货币，在本例中为新西兰元。

wp-admin 界面截图，显示正在处理的订单

我们可以通过在 wp_posts 表上运行以下查询并连接 wp_postmeta 来获取元值，来确认每个订单的货币。 结果显示了使用 NZD、USD 和 MXN 的订单。 此查询与我们将在本指南后面实现的查询类似，用于收集和显示货币值。

SELECT
    ID,
    post_name,
    post_type,
    currency_postmeta.meta_value AS currency
FROM `wp_posts`
JOIN wp_postmeta currency_postmeta ON wp_posts.ID = currency_postmeta.post_id
WHERE currency_postmeta.meta_key = '_order_currency'
ORDER BY wp_posts.post_date DESC
LIMIT 3

查询结果截图

添加一个 UI 下拉菜单

为了以不同的货币查看报告，需要一个过滤器或下拉菜单。 我们可以通过添加一个类似于 订单报告中的这个配置对象 的配置对象，为报告添加一个基本过滤器。

首先，我们需要向客户端提供数据以渲染下拉菜单。 最佳方法是将数据添加到 wcSettings 全局对象中。 此全局对象可用于从 PHP 将静态配置数据传输到客户端。 在主 PHP 文件中，将货币设置添加到数据注册表中，以填充 window.wcSettings.multiCurrency。

function add_currency_settings() {
    $currencies = array(
        array(
            'label' => __( 'United States Dollar', 'dev-blog-example' ),
            'value' => 'USD',
        ),
        array(
            'label' => __( 'New Zealand Dollar', 'dev-blog-example' ),
            'value' => 'NZD',
        ),
        array(
            'label' => __( 'Mexican Peso', 'dev-blog-example' ),
            'value' => 'MXN',
        ),
    );

    $data_registry = Automattic\WooCommerce\Blocks\Package::container()->get(
        Automattic\WooCommerce\Blocks\Assets\AssetDataRegistry::class
    );

    $data_registry->add( 'multiCurrency', $currencies );
}

add_action( 'init', 'add_currency_settings' );

在控制台中，您可以确认数据已安全地传输到客户端。

控制台截图

在 index.js 中，创建自定义货币过滤器，并将其添加到订单报告中。

import { addFilter } from "@wordpress/hooks";
import { __ } from "@wordpress/i18n";

const addCurrencyFilters = (filters) => {
  return [
    {
      label: __("Currency", "dev-blog-example"),
      staticParams: [],
      param: "currency",
      showFilters: () => true,
      defaultValue: "USD",
      filters: [...(wcSettings.multiCurrency || [])],
    },
    ...filters,
  ];
};

addFilter(
  "woocommerce_admin_orders_report_filters",
  "dev-blog-example",
  addCurrencyFilters
);

如果查看订单报告，我们可以看到新的下拉菜单。 尝试使用它，您会注意到货币查询参数被添加到 URL 中。 如果查看“网络”选项卡，您还会看到此值包含在用于填充报告的数据请求中。 例如，请查看对订单统计端点的请求，/wp-json/wc-analytics/reports/orders/stats。 接下来，我们将使用该查询参数来调整报告结果。

显示 wp-admin 中 UI 下拉菜单的截图

在服务器端处理货币参数

现在，由于我们的下拉菜单为数据请求添加了一个 currency 查询参数，因此，第一步是将其作为查询参数添加到“订单”数据存储和“订单统计”数据存储中。这些数据存储使用查询参数进行缓存，因此，通过添加我们的参数，我们可以确保在参数更改时执行新的数据库查询。请在您的主 PHP 文件中添加此查询参数。

function apply_currency_arg( $args ) {
    $currency = 'USD';

    if ( isset( $_GET['currency'] ) ) {
        $currency = sanitize_text_field( wp_unslash( $_GET['currency'] ) );
    }

    $args['currency'] = $currency;

    return $args;
}

add_filter( 'woocommerce_analytics_orders_query_args', 'apply_currency_arg' );
add_filter( 'woocommerce_analytics_orders_stats_query_args', 'apply_currency_arg' );

现在，我们已经确保在 currency 查询参数发生变化时执行新的数据库查询，我们可以开始向收集数据的查询中添加 SQL 语句。

首先，为“订单”表、订单统计和订单图表添加一个 JOIN。

function add_join_subquery( $clauses ) {
    global $wpdb;

    $clauses[] = "JOIN {$wpdb->postmeta} currency_postmeta ON {$wpdb->prefix}wc_order_stats.order_id = currency_postmeta.post_id";

    return $clauses;
}

add_filter( 'woocommerce_analytics_clauses_join_orders_subquery', 'add_join_subquery' );
add_filter( 'woocommerce_analytics_clauses_join_orders_stats_total', 'add_join_subquery' );
add_filter( 'woocommerce_analytics_clauses_join_orders_stats_interval', 'add_join_subquery' );

接下来，添加一个 WHERE 子句。

function add_where_subquery( $clauses ) {
  global $wpdb;

    $currency = 'USD';

    if ( isset( $_GET['currency'] ) ) {
        $currency = sanitize_text_field( wp_unslash( $_GET['currency'] ) );
    }

  // Use $wpdb->prepare to safely escape the currency value for SQL.
  $prepared_clause = $wpdb->prepare(
      'AND currency_postmeta.meta_key = %s AND currency_postmeta.meta_value = %s',
      '_order_currency',
      $currency
  );

  $clauses[] = $prepared_clause;

    return $clauses;
}

add_filter( 'woocommerce_analytics_clauses_where_orders_subquery', 'add_where_subquery' );
add_filter( 'woocommerce_analytics_clauses_where_orders_stats_total', 'add_where_subquery' );
add_filter( 'woocommerce_analytics_clauses_where_orders_stats_interval', 'add_where_subquery' );

最后，添加一个 SELECT 子句。

function add_select_subquery( $clauses ) {
    $clauses[] = ', currency_postmeta.meta_value AS currency';

    return $clauses;
}

add_filter( 'woocommerce_analytics_clauses_select_orders_subquery', 'add_select_subquery' );
add_filter( 'woocommerce_analytics_clauses_select_orders_stats_total', 'add_select_subquery' );
add_filter( 'woocommerce_analytics_clauses_select_orders_stats_interval', 'add_select_subquery' );

订单报告

让我们返回到“订单”报告，看看它是否正常工作。您可以操作下拉菜单，并在表格中查看相应的订单信息。

WooCommerce “订单”标签页在 wp-admin 中的截图，显示表格中反映的相应订单。

完成最后的调整

Orders 表格可以通过自定义来反映所选的货币。 我们可以通过在 index.js 文件中添加一个列来显示货币。 reportTableData 参数是一个包含表头、行和数据的对象，这些都是数据数组。 我们需要添加一个新的表头，并将货币附加到每一行的 data 数组中。

const addTableColumn = (reportTableData) => {
  if ("orders" !== reportTableData.endpoint) {
    return reportTableData;
  }

  const newHeaders = [
    {
      label: "货币",
      key: "currency",
    },
    ...reportTableData.headers,
  ];
  const newRows = reportTableData.rows.map((row, index) => {
    const item = reportTableData.items.data[index];
    const newRow = [
      {
        display: item.currency,
        value: item.currency,
      },
      ...row,
    ];
    return newRow;
  });

  reportTableData.headers = newHeaders;
  reportTableData.rows = newRows;

  return reportTableData;
};

addFilter("woocommerce_admin_report_table", "dev-blog-example", addTableColumn);

自定义表格的截图

虽然添加列很有帮助，但表格和图表中的货币数值仅反映商店的货币。

报告截图

为了更改报告的货币和数值格式，我们可以使用 woocommerce_admin_report_currency JS 钩子。 您可以在 wcSettings.currency 中看到商店的默认货币，但我们需要根据正在查看的货币以及查询参数 ?currency=NZD 来更改这些设置。

货币设置的截图

首先，让我们在 index.js 中创建一些配置。

const currencies = {
  MXN: {
    code: "MXN",
    symbol: "$MXN", // 仅为示例。
    symbolPosition: "left",
    thousandSeparator: ",",
    decimalSeparator: ".",
    precision: 2,
  },
  NZD: {
    code: "NZD",
    symbol: "$NZ",
    symbolPosition: "left",
    thousandSeparator: ",",
    decimalSeparator: ".",
    precision: 2,
  },
};

最后，将我们的函数添加到钩子中，该钩子会根据货币查询参数应用配置。

const updateReportCurrencies = (config, { currency }) => {
  if (currency && currencies[currency]) {
    return currencies[currency];
  }
  return config;
};

addFilter(
  "woocommerce_admin_report_currency",
  "dev-blog-example",
  updateReportCurrencies
);

🎉 现在，我们可以查看我们的 Orders 报告，并在整个报告中看到货币反映在货币数值中。

自定义订单报告的截图

结论

在本指南中，我们添加了一个用户界面 元素，用于修改发送到 服务器 的 查询参数，并使用这些 参数 的 价值 来 修改 收集报表 数据 的 SQL 语句。 通过这样做，我们建立了一种高度自定义 WC-Admin 报表的方法。 希望这个 例子 能够说明如何通过 扩展 来定制该平台，从而为用户带来强大的体验。