# @defra/forms-model 中文文档

规范地址：https://npmcn.com/package/%40defra/forms-model/

版本：4\.0\.4
npm 元数据更新时间：2026-11-11T12:04:57.170Z
中文译文更新时间：2026-11-11T21:18:05.636Z
软件包许可：OGL-UK-3\.0

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

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

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

- 包体积（解压后）：2.5 MB，712 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.19\.0
- 运行依赖：5 个
- peer 依赖：joi ^18\.0\.0
- 首次发布：2024-03-18T14:53:35.759Z
- 最新版本发布：2026-11-11T12:04:54.670Z
- 近 30 天下载量：4295（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：703（近 12 个月 127 个）

## 中文简介

为 Defra 格式提供模型的 hopi 插件

## 安装

```sh
npm install @defra/forms-model
```

也可以使用：`pnpm add @defra/forms-model`、`yarn add @defra/forms-model`、`bun add @defra/forms-model`

## README

# Defra 格式模型

Defra表格模型和验证库,为形式定义、组件、验证和数据处理提供基础.

## 特征

-   **形式 定义** - 表格、页、组件和条件的核心结构
-   **构成部分库** - 有验证的预定义的形式组件
-   **杰森·斯克马** - JSON用于跨平台验证的准备使用程序文件
-   **条件引擎** - 确定形式流动和能见度的逻辑
-   **类型定义** - 完整的类型脚本类型安全
-   **元数据处理** - 支持形式元数据、版本和州管理

## 安装

```shell
npm install @defra/forms-model
```

## 使用量

### 形式 定义

```javascript
import { createForm } from '@defra/forms-model';

const form = createForm({
  name: 'my-form',
  pages: [
    {
      path: '/start',
      title: 'Start page',
      components: [/* components */]
    }
  ],
  sections: [/* sections */]
});
```

### 组件使用量

```javascript
import { ComponentType } from '@defra/forms-model';

const textField = {
  type: ComponentType.TextField,
  name: 'fullName',
  title: 'Full name',
  schema: {
    min: 2,
    max: 100
  }
};
```

### 表格验证

#### JSON Schema 文件

此包包括预生成的JSON schema文件, 用于外部 JSON Schema 校验器/ IDEs 林入等 :

```javascript
import formSchema from '@defra/forms-model/schemas/form-definition-schema.json';
```

可用的计划文件包括:

##### 表格定义

-   `form-definition-schema.json` - 完全形式定义验证
-   `form-definition-v2-schema.json` - 完整形式定义V2验证

##### 组件外观

-   `component-schema.json` - 构成部分验证
-   `component-schema-v2.json` - 构成部分验证(v2)

##### 页示马斯

-   `page-schema.json` - 页面验证
-   `page-schema-v2.json` - 页面验证(v2)

##### 列表图

-   `list-schema.json` - 清单验证
-   `list-schema-v2.json` - 清单验证(v2)

##### 窗体元数据表

-   `form-metadata-schema.json` - 表格元数据验证
-   `form-metadata-author-schema.json` - 表格元数据作者验证
-   `form-metadata-input-schema.json` - 表格元数据输入验证
-   `form-metadata-state-schema.json` - 表格元数据状态验证

##### 元数据字段图

-   `form-metadata-contact-schema.json` - 联系信息验证
-   `form-metadata-email-schema.json` - 电子邮件验证
-   `form-metadata-online-schema.json` - 在线形式元数据验证

##### 窗体编辑器Schems

-   `form-editor-input-page-schema.json` - 窗体编辑器输入页验证
-   `form-editor-input-check-answers-setting-schema.json` - 检查答案设置验证
-   `form-editor-input-question-schema.json` - 问题输入验证
-   `form-editor-input-page-settings-schema.json` - 页面设置验证

##### 窗体编辑器字段图

-   `page-type-schema.json` - 页面类型验证
-   `question-type-schema.json` - 问题类型验证
-   `question-type-full-schema.json` - 完全问题类型验证
-   `written-answer-sub-schema.json` - 书面答复子程序验证
-   `date-sub-schema.json` - 日期子基准验证

##### 表格提交图

-   `form-submit-payload-schema.json` - 表格提交有效载荷验证
-   `form-submit-record-schema.json` - 表格提交记录验证
-   `form-submit-recordset-schema.json` - 表格提交记录仪验证

##### 窗体管理器Schemas

-   `patch-page-schema.json` - 补丁页验证

##### 斯克马斯区

-   `question-schema.json` - 问题验证

##### 验证Schemas

-   `min-schema.json` - 最低价值验证
-   `max-schema.json` - 最大值验证
-   `min-length-schema.json` - 最小长度验证
-   `max-length-schema.json` - 最大长度验证
-   `max-future-schema.json` - 未来最大日期验证
-   `max-past-schema.json` - 最大过去日期验证

##### 常见图

-   `search-options-schema-ui.json` - 搜索选项验证(公式设计器)
-   `search-options-schema-manager.json` - 搜索选项验证(窗体管理)
-   `query-options-schema-ui.json` - 查询选项验证(公式设计器)
-   `query-options-schema-manager.json` - 查询选项验证(形式管理)
-   `pagination-options-schema.json` - 铺设选项验证
-   `sorting-options-schema.json` - 排序选项验证

## 发展

这个软件包以前是作为 `model` 工作空间 [窗体设计器](https://github.com/DEFRA/forms-designer)。 。 。 .

### 设置

```shell
nvm use
npm install
npm run build
```

### 常见命令

| 命令 | 说明 |
| --- | --- |
| `npm run build` | 构建类型声明、 JavaScript 模块和 JSON 计划 |
| `npm run lint` | 运行编辑器Config、 ESLint 和 TypeScript 检查 |
| `npm run format` | 用 Pretier 格式化文件 |
| `npm test` | 进行覆盖测试 |

### 测试消费服务的变化

为了测试消费服务(例如表格设计器)中未公布的更改,构建此包并将其链接:

```shell
# In forms-model
npm run build
npm link

# In the consuming service
npm link @defra/forms-model
```

运行 `npm run build` 每次修改后,在表格模型中,使消费服务能够收回新的 `dist` 输出。 运行 `npm unlink @defra/forms-model && npm install` 在消费服务中返回出版的版本.

### 出版

合并为 `main` 更改为 `src/`, (中文(简体) ), `scripts/`, (中文(简体) ), `babel.config.*` 或者说 `.browserslistrc` 运行 [发布](https://npmcn.com/package/%40defra/forms-model/.github/workflows/publish.yml) 工作流程,将补丁版本递增并发布到npm.

### 测试范围

单位测试覆盖阈值,低于该阈值的代码覆盖将失败 使用 jest 配置 设定,此时线覆盖阈值被设定为 92%,参见 [jest.config.js (英语)](https://npmcn.com/package/%40defra/forms-model/jest.config.js)

### JSON Schema 生成和出版

这个软件包在构建过程中生成由Joi验证计划产生的JSON Schema文件. 这些计划包含在已公布的npm包中,并可在运行时提供.

#### 如何运作

当你跑的时候 `npm run build`,脚本 `scripts/generate-schemas.js` 执行中:

1.  将Joi 验证计划转换为 JSON Schema 格式
2.  强化标题和描述的策略
3.  将计划文件写入 `schemas/` 目录

#### 已知的贵克人

1.  **需要第一个构建**: 在新克隆后, 你必须运行 `npm run build` 在本地获取计划文件之前 .

## 许可证

本资料系根据下列公开政府规定公布:

[http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3 互联网档案馆的存檔,存档日期2013-12-21](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3)

在使用此信息时, 您的产品和应用程序中引用以下的归属声明 MUST . \` , \`

> 载有根据《公开政府许可证》颁发的公共部门信息v3

### 关于执照

开放政府许可证(OGL)由女王陛下文具办公室(HMSO)主计长制定,目的是使公共部门的信息提供者能够根据共同开放许可证许可其信息的使用和再使用.

它旨在鼓励自由和灵活地使用和再使用信息,仅附带一些条件.

## 常见问题

### @defra/forms-model 是什么？

为 Defra 格式提供模型的 hopi 插件

### 如何安装 @defra/forms-model？

在项目目录运行 npm install @defra/forms-model，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：joi（^18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @defra/forms-model 支持 TypeScript 吗？

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

### @defra/forms-model 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @defra/forms-model 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @defra/forms-model 可以商用吗？

@defra/forms-model 使用 OGL-UK-3\.0 许可。声明的许可为 OGL-UK-3\.0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @defra/forms-model 的下载量有多少？

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

### @defra/forms-model 还在维护吗？

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