# @eggjs/ajv-formats 中文文档

规范地址：https://npmcn.com/package/%40eggjs/ajv-formats/

版本：3\.0\.1
npm 元数据更新时间：2026-06-30T15:34:08.119Z
中文译文更新时间：2026-11-13T11:43:23.538Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eggjs/ajv-formats
原文对照：https://npmcn.com/package/%40eggjs/ajv-formats/?lang=original
项目主页：https://github.com/eggjs/ajv-formats#readme
源码仓库：https://github.com/eggjs/ajv-formats

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：56.7 kB，15 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-04-07T06:34:43.621Z
- 最新版本发布：2024-04-07T06:34:43.945Z
- 近 30 天下载量：4146（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

Ajv v7+ 的格式验证

## 安装

```sh
npm install @eggjs/ajv-formats
```

也可以使用：`pnpm add @eggjs/ajv-formats`、`yarn add @eggjs/ajv-formats`、`bun add @eggjs/ajv-formats`

## README

# ajv 格式

> 防御: 删除 `peerDependencies` 让它依靠蛋蛋.

Ajv 的 JSON Schema 格式

[![Build Status](https://travis-ci.org/ajv-validator/ajv-formats.svg?branch=master)](https://travis-ci.org/ajv-validator/ajv-formats) [![npm](https://img.shields.io/npm/v/ajv-formats.svg)](https://www.npmjs.com/package/ajv-formats) [![Gitter](https://img.shields.io/gitter/room/ajv-validator/ajv.svg)](https://gitter.im/ajv-validator/ajv) [![GitHub Sponsors](https://img.shields.io/badge/$-sponsors-brightgreen)](https://github.com/sponsors/epoberezkin)

## 使用量

```javascript
// ESM/TypeScript import
import Ajv from "ajv"
import addFormats from "ajv-formats"
// Node.js require:
const Ajv = require("ajv")
const addFormats = require("ajv-formats")

const ajv = new Ajv()
addFormats(ajv)
```

## 格式

软件包定义了这些格式:

-   _日期_: 根据 [RFC3339 (法语)](http://tools.ietf.org/html/rfc3339#section-5.6)。 。 。 .
-   _时间_:时间(时间区是强制性的).
-   _日期时间_:日期-时间(时间-区是强制性的).
-   _同时_: 时间带有可选的时区.
-   _时间_:带有可选时区的日期-时间.
-   _会期_: 从 [RFC3339 (法语)](https://tools.ietf.org/html/rfc3339#appendix-A)
-   _乌里_:全URI. .
-   _微量参考_:URI参考文献,包括完整和相亲的URI.
-   _尿温_: 根据 [RFC6570 (法语)](https://tools.ietf.org/html/rfc6570)
-   _url 密码_ (折旧): [URL 记录](https://url.spec.whatwg.org/#concept-url)。 。 。 .
-   _电子邮件_: 电子邮件地址.
-   _主机名_: 主机名称 [RFC1034 (法语)](http://tools.ietf.org/html/rfc1034#section-3.5)。 。 。 .
-   _ipv4 数据_: IP地址为v4.
-   _ipv6 数据_: IP地址为v6.
-   _正则_:通过将字符串传递到 RegExp 构造器来测试一个字符串是否是一个有效的正则表达式.
-   _乌伊德_: 通用唯一标识符 [RFC4122 导弹](http://tools.ietf.org/html/rfc4122)。 。 。 .
-   _json-指针_: JSON指针根据 [RFC6901 (法语)](https://tools.ietf.org/html/rfc6901)。 。 。 .
-   _相对 json 指针_根据 [本草案](http://tools.ietf.org/html/draft-luff-relative-json-pointer-00)。 。 。 .
-   _字节_: 基数64根据 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)
-   _单位32_: 根据 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)
-   _单位64_: 根据 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)
-   _浮动_: 根据 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)
-   _双_: 根据 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)
-   _密码_: 根据 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)
-   _二进制_: 二进制字符串 [打开 Api 3.0.0 规格](https://spec.openapis.org/oas/v3.0.0#data-types)

参见用于格式验证的正则表达式和用于格式验证的源 [格式.ts 类型](https://github.com/ajv-validator/ajv-formats/blob/master/src/formats.ts)。 。 。 .

**请注意**: JSON Schema 草案07 也定义了格式 `iri`, (中文(简体) ), `iri-reference`, (中文(简体) ), `idn-hostname` 财务报告和审定财务报表 `idn-email` 用于URL、主机名和带有国际字符的电子邮件。 这些格式可用于 [ajv-formats-草案2019](https://github.com/luzlab/ajv-formats-draft2019) 插件 .

## 用于比较数值的关键字 : `formatMaximum` 编号 : `formatMinimum` 财务报告和审定财务报表 `formatExclusiveMaximum` 编号 : `formatExclusiveMinimum`

当格式关键词定义命令时,这些关键词可以定义最小/最大限制(`compare` 函数在格式定义中).

这些关键字添加到 ajv 实例中, 当 ajv 格式用于没有选项或带有选项时 `keywords: true`。 。 。 .

这些关键字仅适用于字符串. 如果数据不是字符串,则验证成功.

关键词的值 `formatMaximum`编号 :`formatMinimum` 财务报告和审定财务报表 `formatExclusiveMaximum`编号 :`formatExclusiveMinimum` 应该是一个字符串或 [数据参考](https://github.com/ajv-validator/ajv/blob/master/docs/guide/combining-schemas.md#data-reference)。这个值是允许数据有效的最大(最小)值,由 `format` 关键词 若为 `format` 关键词不为当前计划编译将丢出例外 .

当这些关键字被添加时,它们也会在格式中添加比较功能 `"date"`, (中文(简体) ), `"time"` 财务报告和审定财务报表 `"date-time"`。用户定义的格式也可以有比较功能。 见 [添加格式](https://github.com/ajv-validator/ajv/blob/master/docs/api.md#api-addformat) 方法.

```javascript
require("ajv-formats")(ajv)

const schema = {
  type: "string",
  format: "date",
  formatMinimum: "2016-02-06",
  formatExclusiveMaximum: "2016-12-27",
}

const validDataList = ["2016-02-06", "2016-12-26"]

const invalidDataList = ["2016-02-05", "2016-12-27", "abc"]
```

## 选项

选项可以通过第二个参数传递. 选项值可以是

1.  添加到 ajv 实例中的格式名称列表 :

```javascript
addFormats(ajv, ["date", "time"])
```

**请注意**: 当 ajv 遇到未定义的格式时, 它会丢出例外( 除非 ajv 实例被配置到 `strict: false` 选项)。 为了允许特定的未定义格式,它们必须通过 ajv 实例传递给 `formats` 选项 `true` 值 :

```javascript
const ajv = new Ajv({formats: {date: true, time: true}}) // to ignore "date" and "time" formats in schemas.
```

2.  格式验证模式( 默认为 `"full"`),可选的格式名称列表和 `keywords` 选项以添加其他格式比较关键字:

```javascript
addFormats(ajv, {mode: "fast"})
```

或者说

```javascript
addFormats(ajv, {mode: "fast", formats: ["date", "time"], keywords: true})
```

单位 `"fast"` 以下格式被简化: `"date"`, (中文(简体) ), `"time"`, (中文(简体) ), `"date-time"`, (中文(简体) ), `"iso-time"`, (中文(简体) ), `"iso-date-time"`, (中文(简体) ), `"uri"`, (中文(简体) ), `"uri-reference"`, (中文(简体) ), `"email"`。例如, `"date"`, (中文(简体) ), `"time"` 财务报告和审定财务报表 `"date-time"` 不验证区域 `"fast"` 模式,只有字符串结构,以及其他格式有简化正则表达式.

## 测试

```bash
npm install
git submodule update --init
npm test
```

## 许可证

[麻省理工学院](https://github.com/ajv-validator/ajv-formats/blob/master/LICENSE)

## 常见问题

### @eggjs/ajv-formats 是什么？

Ajv v7\+ 的格式验证

### 如何安装 @eggjs/ajv-formats？

在项目目录运行 npm install @eggjs/ajv-formats，或使用 pnpm add / yarn add / bun add。

### @eggjs/ajv-formats 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eggjs/ajv-formats 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @eggjs/ajv-formats 可以商用吗？

@eggjs/ajv-formats 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eggjs/ajv-formats 的下载量有多少？

根据 npm 官方下载统计，@eggjs/ajv-formats 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,146 次，日均约 138 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eggjs/ajv-formats 还在维护吗？

最新版本 3\.0\.1 发布于 2024/04/07（2 年前）；至今共发布 1 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。