跳到主要内容

可用的格式化器

Formatters 是实用类，允许您格式化值，使其与 Store API 兼容。 默认格式化器处理诸如货币金额、货币信息或 HTML 之类的数值。

建议您在扩展 Store API 时使用这些格式化器。

为什么格式化器很有用？​

使用格式化器实用程序返回某些类型的数据，可以确保您的自定义数据与 Store API 的其他接口保持一致和兼容。 它们还处理任何可能影响数据格式化的商店特定设置，例如货币设置。

Store API 包含以下格式化器：

如何使用格式化器​

要获取格式化器，可以使用 ExtendSchema 类的 get_formatter 方法。 此方法接受一个字符串，即您想要使用的格式化器的名称。

get_formatter('money'); // 用于 MoneyFormatter
get_formatter('html'); // 用于 HtmlFormatter
get_formatter('currency'); // CurrencyFormatter

这将返回一个 FormatterInterface 对象，该对象具有 format 方法。 format 方法的签名如下：

format( $value, array $options = [] );

只有 MoneyFormatter 的行为可以通过 $options 参数进行控制。 此参数是可选的。

实际示例​

假设我们要通过 API 返回一些额外的价格数据。 我们希望以美分形式返回价格，以及商店的货币数据。 我们可以使用 MoneyFormatter 和 CurrencyFormatter 来实现此目的。

首先，我们需要确保可以访问格式化器类。 我们可以使用 use 关键字来实现：

use Automattic\WooCommerce\StoreApi\StoreApi;
use Automattic\WooCommerce\StoreApi\Utilities\ExtendSchema;

$extend = StoreApi::container()->get( ExtendSchema::class );

$my_custom_price = $extend->get_formatter( 'money' )->format( '10.00', [
  'rounding_mode' => PHP_ROUND_HALF_DOWN,
  'decimals'      => 2
] );

$price_response = $extend->get_formatter( 'currency' )->format( [
	'price'         => $my_custom_price,
] );

上述代码将使 $price_response 设置为：

[
    'price' => '1000'
    'currency_code' => 'GBP'
    'currency_symbol' => '£'
    'currency_minor_unit' => 2
    'currency_decimal_separator' => '.'
    'currency_thousand_separator' => ','
    'currency_prefix' => '£'
    'currency_suffix' => ''
]

MoneyFormatter​

[MoneyFormatter](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/trunk/src/StoreApi/Formatters/MoneyFormatter.php) 类可用于使用商店的 设置 格式化 货币 价值。 商店的 设置 可以通过将 选项 传递给此格式化器的 format 方法 来覆盖。

为了避免浮点数舍入错误，返回值以“分”为单位。 因此，在使用此格式化器时，您很可能还会使用 [CurrencyFormatter](#currencyformatter) 同时返回 货币 数据，以便 API 的使用者能够以预期的 格式 显示 价值。

参数​

参数类型描述
$valuenumber要格式化为 货币 值的数值。
$optionsarray应该包含两个键，decimals，它应该是一个 integer。
$options['decimals']number用于控制 货币 值中应显示多少位小数。 默认为商店的 设置。
$options['rounding_mode']number用于确定如何对 货币 值进行四舍五入。 这应该是 PHP 四舍五入模式之一，如 PHP round() 文档 中所述。 默认为 PHP_ROUND_HALF_UP。

示例用法和返回值​

get_formatter( 'money' )->format( 10.443, [
  'rounding_mode' => PHP_ROUND_HALF_DOWN,
  'decimals'      => 2
] );

返回 1044

CurrencyFormatter​

这个格式化器接收一个价格数组，并返回相同的数组，但附加了货币数据。添加的货币数据如下：

键类型描述
currency_codestring货币的字符串表示，例如：GBP 或 USD
currency_symbolstring货币的符号，例如：£ 或 $
currency_minor_unitnumber货币显示的十进制位数
currency_decimal_separatorstring用于分隔货币中整数部分和小数部分的字符串。
currency_thousand_separatorstring用于分隔货币中千位数的字符串，例如：£10,000 或 €10.000
currency_prefixstring应该出现在货币值之前的字符串。
currency_suffixstring应该出现在货币值之后的字符串。

然后，客户端/消费者可以使用这些数据，根据商店的设置正确地格式化价格。重要：传递给此格式化器的价格数组应该已经处于货币格式，因此您应该首先使用 MoneyFormatter。

参数​

参数类型描述
$valuenumber[]要与商店的货币设置合并的价格数组

示例用法和返回的值​

get_formatter( 'currency' )->format( [
  'price'         => 1800,
  'regular_price' => 1800,
  'sale_price'    => 1800,
] );

返回

'price' => '1800'
'regular_price' => '1800'
'sale_price' => '1800'
'price_range' => null
'currency_code' => 'GBP'
'currency_symbol' => '£'
'currency_minor_unit' => 2
'currency_decimal_separator' => '.'
'currency_thousand_separator' => ','
'currency_prefix' => '£'
'currency_suffix' => ''

HtmlFormatter​

这个格式化器会接收一个 HTML 字符串，并对其进行以下处理：wptexturize、convert_chars、trim 和 wp_kses_post，然后再返回结果。这个格式化器的目的是使 HTML 变得“安全”（即，正确地格式化了字符）。wp_kses_post 会确保只允许在 post 上下文中使用的 HTML 标签出现在字符串中。

参数​

参数类型描述
$valuestring您想要格式化成“安全”HTML 的字符串。

使用示例和返回的值​

get_formatter( 'html' )->format(
  "<script>alert('bad script!')</script> This \"coffee\" is <strong>very strong</strong>."
);

返回：

alert('bad script!') This &#8220;coffee&#8221; is <strong>very strong</strong>.

无论 HTML 是由用户生成还是其他方式生成，都应该在从 StoreAPI 返回 HTML 时使用此格式化器。这可以确保客户端/消费者能够安全地显示 HTML，并且不会出现编码问题。