Ajv 中文网

# 类型强制规则

¥Type coercion rules

要启用类型强制，请使用 true 或 array（默认情况下为 false）将选项 coerceTypes 传递给 Ajv。参见 example。

¥To enable type coercion pass option coerceTypes to Ajv with true or array (it is false by default). See example.

强制转换规则与 JavaScript 不同：

¥The coercion rules are different from JavaScript:

  • 按预期校验用户输入

    ¥to validate user input as expected

  • 使强制可逆

    ¥to have the coercion reversible

  • 正确校验子结构中需要不同类型的情况（例如，在 anyOf 中）。

    ¥to correctly validate cases where different types are required in subschemas (e.g., in anyOf).

仅当存在 type 关键字时才会发生类型强制，如果没有强制，校验将失败。如果成功强制转换为所需类型，则继续校验其他关键字，否则校验失败。

¥Type coercion only happens if there is type keyword and if without coercion the validation would have failed. If coercion to the required type succeeds then the validation continues to other keywords, otherwise the validation fails.

如果 type 关键字中允许有多种类型，则仅当没有任何类型与数据匹配并且存在某些标量类型时才会发生强制转换（不可能强制到 object/array 或从 object/array 进行强制转换）。在这种情况下，校验函数将尝试按顺序将数据强制为每种类型，直到其中一些成功。

¥If there are multiple types allowed in type keyword the coercion will only happen if none of the types match the data and some of the scalar types are present (coercion to/from object/array is not possible). In this case the validating function will try coercing the data to each type in order until some of them succeeds.

应用这些规则可能会产生一些意想不到的后果。Ajv 可以根据结构中不同点的需要多次强制相同的值（这就是需要强制可逆性的原因）。这在使用 oneOf 时尤其明显，它必须测试所有子结构。Ajv 将强制每个子结构的类型，如果它可以强制匹配多个子结构，则可能会导致意外失败。即使成功，Ajv 也不会回溯，因此你将获得最终强制转换的类型，即使这不是允许数据通过校验的类型。如果可能，请使用 anyOf 构建结构，这样一旦遇到匹配的子结构就不会校验后续子结构。

¥Application of these rules can have some unexpected consequences. Ajv may coerce the same value multiple times (this is why coercion reversibility is required) as needed at different points in the schema. This is particularly evident when using oneOf, which must test all of the subschemas. Ajv will coerce the type for each subschema, possibly resulting in unexpected failure if it can coerce to match more than one of the subschemas. Even if it succeeds, Ajv will not backtrack, so you'll get the type of the final coercion even if that's not the one that allowed the data to pass validation. If possible, structure your schema with anyOf, which won't validate subsequent subschemas as soon as it encounters one subschema that matches.

可能的类型强制：

¥Possible type coercions:

从类型→
到类型↓		 string number 布尔值 null array*
string * x→""+x false→"false"
true→"true"		 null→"" [x]→x
number /
integer		 Valid number /
integer:x→+x
 * false→0
true→1		 null→0 [x]→x
布尔值 "false"→false
"true"→true
"abc"⇸
""⇸		 0→false
1→true
x⇸		 * null→false [false]→false
[true]→true
null ""→null
"null"⇸
"abc"⇸		 0→null
x⇸		 false→null
true⇸		 * [null]→null
array* x→[x] x→[x] false→[false]
true→[true]		 null→[null] *
  • Requires option {coerceTypes: "array"}

# 从字符串值强制转换

¥Coercion from string values

# 至号码类型

¥To number type

如果字符串是有效数字，则可以强制转换为 number，并使用 +data。

¥Coercion to number is possible if the string is a valid number, +data is used.

# 转为整数类型

¥To integer type

如果字符串是不带小数部分 (data % 1 === 0) 的有效数字，则可以强制转换为 integer。

¥Coercion to integer is possible if the string is a valid number without fractional part (data % 1 === 0).

# 为布尔类型

¥To boolean type

与 JavaScript 不同，只有这些字符串可以被强制转换为 boolean：

¥Unlike JavaScript, only these strings can be coerced to boolean:

  • "true" -> true

  • "false" -> false

# 为空类型

¥To null type

空字符串被强制转换为 null，其他字符串不能被强制转换。

¥Empty string is coerced to null, other strings can't be coerced.

# 来自数值的强制转换

¥Coercion from number values

# 转为字符串类型

¥To string type

总是可能的，使用 '' + data

¥Always possible, '' + data is used

# 为布尔类型

¥To boolean type

与 JavaScript 不同，只有这些数字可以被强制转换为 boolean：

¥Unlike JavaScript, only these numbers can be coerced to boolean:

  • 1 -> true

  • 0 -> false

# 为空类型

¥To null type

0 强制转换为 null，其他数字不能强制转换。

¥0 coerces to null, other numbers can't be coerced.

# 来自布尔值的强制转换

¥Coercion from boolean values

# 转为字符串类型

¥To string type

  • true -> "true"

  • false -> "false"

# 转为数字/整数类型

¥To number/integer types

  • true -> 1

  • false -> 0

# 为空类型

¥To null type

false 强制 null，true 不能强制。

¥false coerces to null, true can't be coerced.

# 从 null 强制转换

¥Coercion from null

# 转为字符串类型

¥To string type

null 强制为空字符串。

¥null coerces to the empty string.

# 转为数字/整数类型

¥To number/integer types

null 强制 0

¥null coerces to 0

# 为布尔类型

¥To boolean type

null 强制 false

¥null coerces to false

# 强制传入和传出数组

¥Coercion to and from array

这些强制要求选项 coerceTypes 是 "array"。

¥These coercions require that the option coerceTypes is "array".

如果存在标量数据并且需要数组，Ajv 会将标量数据封装在数组中。

¥If a scalar data is present and array is required, Ajv wraps scalar data in an array.

如果存在包含一项的数组并且需要标量，则 Ajv 会将数组强制为其项。

¥If an array with one item is present and a scalar is required, Ajv coerces array into its item.

  • "foo" -> [ "foo" ]

  • [ "foo" ] -> "foo"

←