验证数据存储 (wc/store/validation)

概述

验证数据存储提供了一种在购物车或结账模块中显示字段错误的机制。

存储中的数据应该是一个单独的对象，其键是 错误 ID，值是与该错误信息相关的数据。对象中的值应该包含 message 和 hidden 字段。message 是要显示的错误信息，hidden 是一个布尔值，指示是否应该显示该错误。

以下是一个数据结构示例：

{
    "error-id-1": {
        message: "这是一个错误信息",
        hidden: false,
    },
    "error-id-2": {
        message: "这是另一个错误信息",
        hidden: true,
    },
}

当结账流程开始时，它将检查此数据存储是否包含任何条目，如果包含，则会阻止结账流程继续。它还会显示任何被隐藏的错误。将错误设置为隐藏不会将其从数据存储中清除！

用法

要使用此存储，您需要在引用它的任何模块中导入 validationStore StoreDescriptor。 假设 @woocommerce/block-data 已注册为指向 wc.wcBlocksData 的外部依赖，您可以通过以下方式导入 StoreDescriptor：

const { validationStore } = window.wc.wcBlocksData;

示例

为了更好地理解验证存储 (Validation Store)，让我们以古腾堡编辑器中“条款和条件”的必选复选框为例。在网页编辑器中，商家可以设置要求买家同意“条款和条件”，方法是使该复选框成为必选项。

在 WooCommerce Blocks 中，我们使用 useEffect 钩子来检查复选框是否为必选项以及是否已选中。如果复选框为必选项但未选中，我们将向存储添加一个验证错误。如果复选框为必选项且已选中，我们将从存储中清除验证错误。

useEffect( () => {
	if ( ! checkbox ) {
		return;
	}
	if ( checked ) {
		clearValidationError( validationErrorId );
	} else {
		setValidationErrors( {
			[ validationErrorId ]: {
				message: __(
					'Please read and accept the terms and conditions.',
					'woo-gutenberg-products-block'
				),
				hidden: true,
			},
		} );
	}
	return () => {
		clearValidationError( validationErrorId );
	};
}, [
	checkbox,
	checked,
	validationErrorId,
	clearValidationError,
	setValidationErrors,
] );

默认情况下，验证错误是隐藏的。这是因为我们不想在买家尝试提交表单之前显示错误信息。在提交结账表单之前，验证信息已经在验证存储中可见。

当买家在未选中“条款和条件”复选框的情况下提交结账表单时，hidden: true 将更改为 hidden: false，并且显示验证信息。

在 WooCommerce Blocks 中，我们使用以下代码检查文本输入字段是否具有验证错误：

const hasError = validationError?.message && ! validationError?.hidden;

💡 从这个示例中需要记住的主要内容是：

• hidden: true 表示存在验证错误，但该错误未显示给用户。
• hidden: false 表示正在主动向用户显示验证错误。

在上面的示例中，message 是隐藏的，只有文字颜色变为红色，以突出显示该字段存在验证错误。

在某些情况下，希望向用户显示验证错误消息。例如，如果买家尝试在未填写必填字段的情况下提交结账表单。一个例子是当“名”、“姓氏”和“地址”字段为空时：

在 WooCommerce Blocks 中，以下函数处理验证错误消息的显示逻辑：

# 验证输入错误组件

该组件用于显示验证输入时的错误信息。

**功能：**

*   显示错误信息。
*   根据配置显示或隐藏错误信息。
*   提供错误 ID 用于定位错误元素。

**参数：**

| 参数名           | 类型       | 描述                                   |
| ---------------- | ---------- | -------------------------------------- |
| `errorMessage`   | `string`   | 错误信息，如果未提供，则尝试从 `validationError` 获取。 |
| `propertyName`   | `string`   | 属性名，用于从验证商店获取错误信息。          |
| `elementId`      | `string`   | 元素 ID，用于获取错误 ID。                  |

**返回值：**

*   `JSX.Element | null`:  如果存在错误信息，则返回包含错误信息的 `div` 元素；否则，返回 `null`。

**代码示例：**

```ts
export const ValidationInputError = ( {
	errorMessage = '',
	propertyName = '',
	elementId = '',
}: ValidationInputErrorProps ): JSX.Element | null => {
	const { validationError, validationErrorId } = useSelect( ( select ) => {
		const store = select( validationStore );
		return {
			validationError: store.getValidationError( propertyName ),
			validationErrorId: store.getValidationErrorId( elementId ),
		};
	} );

	if ( ! errorMessage || typeof errorMessage !== 'string' ) {
		if ( validationError?.message && ! validationError?.hidden ) {
			errorMessage = validationError.message;
		} else {
			return null;
		}
	}

	return (
		<div className="wc-block-components-validation-error" role="alert">
			<p id={ validationErrorId }>{ errorMessage }</p>
		</div>
	);
};

上述代码片段的简化版本如下：

{
	validationError?.hidden === false && (
		<div className="wc-block-components-validation-error" role="alert">
			<p>{ validationError?.message }</p>
		</div>
	);
}

说明：

• ValidationInputError 组件接收 errorMessage、propertyName 和 elementId 作为参数。
• 如果 errorMessage 未提供，组件会尝试从 validationError 对象获取错误信息。
• useSelect 钩子用于从 validationStore 获取验证错误信息和错误 ID。
• role="alert" 属性用于指示该元素是一个警报。
• 如果 validationError 对象存在且 hidden 属性为 false，则显示错误信息。
• 如果 errorMessage 为空或不是字符串类型，则从 validationError 对象获取错误信息。
• 如果 validationError 对象不存在或 hidden 属性为 true，则不显示任何内容。

使用方法：

<ValidationInputError
  errorMessage="请输入正确的邮箱地址"
  propertyName="email"
  elementId="email-input"
/>

注意事项：

• 确保 validationStore 已经正确初始化。
• propertyName 和 elementId 必须与验证配置中的值相匹配。
• 可以根据需要自定义错误信息的样式。

## 操作

### `clearValidationError(errorId)`

清除一个验证错误。

#### 参数

-   `_errorId_` `string`: 用于清除验证错误的错误 ID。

#### 示例

```js
const store = dispatch(validationStore);
store.clearValidationError('billing-first-name');

clearValidationErrors(errors)

一次性清除多个验证错误。 如果未传递任何错误 ID，则将清除所有验证错误。

参数

• _errors_ string[] 或 undefined: 用于清除验证错误的错误 ID。 它可以是未定义，如果是，则将清除所有验证错误。

示例

1. 这将仅清除数组中指定的验证错误。

const store = dispatch(validationStore);
store.clearValidationErrors([
    'billing-first-name',
    'billing-last-name',
    'terms-and-conditions',
]);

2. 这将清除所有验证错误。

const store = dispatch(validationStore);
store.clearValidationErrors();

setValidationErrors(errors)

设置验证错误。 errors 中的条目将被 添加到 验证错误列表中。 列表中已存在的条目将使用新值进行 更新。

参数

• _errors_ object: 新的验证错误，对象的键是验证错误 ID，值应该是包含 message string 和 hidden boolean 的对象。

示例

const { dispatch } = wp.data;
const { setValidationErrors } = dispatch(validationStore);

setValidationErrors({
    'billing-first-name': {
        message: '名 不能为空。',
        hidden: false,
    },
    'billing-last-name': {
        message: '姓氏 不能为空。',
        hidden: false,
    },
});

hideValidationError(errorId)

通过将 hidden 属性设置为 true 来隐藏一个验证错误。 这不会从数据存储中清除它！

参数

• _errorId_ string: 要隐藏的错误 ID。

示例

const { dispatch } = wp.data;
const { hideValidationError } = dispatch(validationStore);

hideValidationError('billing-first-name');

showValidationError(errorId)

通过将 hidden 属性设置为 false 来显示一个验证错误。

参数

• _errorId_ string: 要显示的错误 ID。

示例

const { dispatch } = wp.data;
const { showValidationError } = dispatch(validationStore);

showValidationError('billing-first-name');

showAllValidationErrors

通过将 hidden 属性设置为 false 来显示所有验证错误。

示例

const { dispatch } = wp.data;
const { showAllValidationErrors } = dispatch(validationStore);

showAllValidationErrors();

clearAllValidationErrors

通过从商店中删除它们来清除所有验证错误。

示例

const { clearAllValidationErrors } = dispatch(validationStore);
clearAllValidationErrors();

选择器

getValidationError( errorId )

返回验证错误。

参数

• errorId string: 用于获取验证错误的错误 ID。

返回值

• object: 验证错误，是一个包含 message string 和 hidden boolean 的对象。

示例

const store = select( validationStore );
const billingFirstNameError = store.getValidationError( 'billing-first-name' );

getValidationErrorId( errorId )

获取一个用于 HTML 的验证错误 ID，可以将其用作 CSS 选择器，或用于引用错误消息。 如果验证错误 hidden 设置为 true，或者验证错误在商店中不存在，则此方法将返回以 validate-error- 为前缀的错误 ID。

参数

• errorId string: 用于获取验证错误 ID 的错误 ID。

返回值

• string: 用于 HTML 的验证错误 ID。

示例

const store = select( validationStore );
const billingFirstNameErrorId =
	store.getValidationErrorId( 'billing-first-name' );

getValidationErrors

返回商店中的所有验证错误。

返回值

• Record<string, FieldValidationStatus>: 所有验证错误，其中键是错误 ID，值是包含 message string 和 hidden boolean 的 FieldValidationStatus 对象。

示例

const store = select( validationStore );
const allValidationErrors = store.getValidationErrors();

hasValidationErrors

如果发生验证错误，则返回 true，否则返回 false。

返回值

• boolean: 是否发生验证错误。

示例

const store = select( validationStore );
const hasValidationErrors = store.hasValidationErrors();