# @bluprynt/forms-core 中文文档

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

版本：4\.2\.0
npm 元数据更新时间：2026-10-21T14:54:03.951Z
中文译文更新时间：2026-11-08T09:04:36.916Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40bluprynt/forms-core
原文对照：https://npmcn.com/package/%40bluprynt/forms-core/?lang=original
项目主页：https://blupryntco.github.io/forms-engine/
源码仓库：https://github.com/blupryntco/forms-engine

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

- 包体积（解压后）：637 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：ajv ^8\.0\.0
- 首次发布：2026-03-20T10:40:53.274Z
- 最新版本发布：2026-10-21T14:54:03.705Z
- 近 30 天下载量：20846（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

JSON驱动的动态形式的框架不可知性引擎. Given a form schema (JSON),引擎通过条件逻辑处理字段能见度,根据特定类型的规则验证用户输入,并生成结构化的形式文档(JSON).

## 安装

```sh
npm install @bluprynt/forms-core
```

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

## README

# @ bluprynt/ 形式- 核心

JSON驱动的动态形式的框架不可知性引擎. Given a form schema (JSON),引擎通过条件逻辑处理字段能见度,根据特定类型的规则验证用户输入,并生成结构化的形式文档(JSON).

## 密钥能力

-   **Schema 汇编** ——通过依赖性分析和循环检测,验证JSON形式定义并将其编成运行时引擎.
-   **有条件的能见度** ——以其他字段值为基础动态地显示/hides字段和分段,并带有串连的亲子能见度和地形评价顺序.
-   **类型意识验证** ——对照每个字段的规则(要求,分/最大,图案,日期范围,数组限制等)验证形成值,自动跳过隐藏字段.
-   **文档兼容性验证** - 核实表格文件的 `form.id` 财务报告和审定财务报表 `form.version` 在字段验证前匹配引擎定义.
-   **窗体定义编辑** ——流利建设API(`FormDefinitionEditor`用于方案构建和修改形式方案.
-   **窗体值编辑** ——流利编辑 API (`FormValuesEditor`)用于对定义进行程序读取和书写形式值,同时进行阵列操纵,验证和能见度查询.
-   **相对日期** ——日期界限如: `"+7d"` 或者说 `"-1m"` 在评估时按所需表格解决 `submittedAt` 时间戳,允许动态但可复制的日期限制.

## 快速启动

```ts
import { FormEngine } from '@bluprynt/forms-core'

// 1. Compile the form definition
const engine = new FormEngine(formDefinition)

// 2. Create a form document (with optional initial values)
const doc = engine.createFormDocument({ "1": "Alice", "2": 30 })

// 3. Compute visibility
const visibility = engine.getVisibilityMap(doc)

// 4. Validate (checks document compatibility + field rules)
const result = engine.validate(doc)
if (!result.valid) {
  result.documentErrors?.forEach(e => console.log(`Document: ${e.message}`))
  for (const [fieldId, errs] of result.fieldErrors) {
    for (const err of errs) {
      console.log(`Field ${fieldId}: ${err.message}`)
    }
  }
}
```

### 建立形式定义

```ts
import { FormDefinitionEditor } from '@bluprynt/forms-core'

const editor = new FormDefinitionEditor({
  id: 'my-form', version: '1.0.0', title: 'My Form', content: [],
})

editor
  .addField({ type: 'string', label: 'Name', validation: { required: true } })
  .addSection({ type: 'section', title: 'Details' })
  .addField({ type: 'number', label: 'Age' }, 2) // into section id=2

const definition = editor.toJSON()
```

### 编辑窗体值

```ts
import { FormValuesEditor } from '@bluprynt/forms-core'

// 1. Create an editor (optionally pre-populate from an existing document)
const editor = new FormValuesEditor(formDefinition)

// 2. Set field values (fluent chaining)
editor
  .setFieldValue(1, 'Alice')
  .setFieldValue(2, 30)
  .addArrayItem(6, 'TypeScript')
  .addArrayItem(6, 'React')
  .setSubmittedAt('2025-01-01T00:00:00Z')

// 3. Optionally record and resolve machine-proposed answers
editor
  .setSuggestion(1, { value: 'Alice Smith', confidence: 0.8, source: 'Passport MRZ, line 2' })
  .acceptSuggestion(1)   // copies the value across, keeps the suggestion
  .rejectSuggestion(2)   // removes a suggestion, leaves the value untouched

// 4. Validate and extract the document
const result = editor.validate()
const doc = editor.toJSON()
```

文件的可选建议 `suggestions` 块,绝不影响验证或 可见度. `confidence` 是一个 `0..1` 分数 块和三个元数据属性 (单位:千美元)`placeholder`, (中文(简体) ), `answer_guidelines`, (中文(简体) ), `reference_id`)关于字段和部分是可选的,因此存在 定义和文件保持不变.

## 文档

| 文档 | 说明 |
| --- | --- |
| [建筑](https://npmcn.com/package/%40bluprynt/forms-core/docs/architecture.md) | 项目结构、模块依赖图、关键设计模式 |
| [API 参考](https://npmcn.com/package/%40bluprynt/forms-core/docs/api-reference.md) | 完整的公共 API——类,方法,类型,错误处理 |
| [验证条件( C)](https://npmcn.com/package/%40bluprynt/forms-core/docs/validation-and-conditions.md) | 每个字段类型、条件操作符、可见度分辨率的验证规则如何工作 |
| [Schema 问题代码](https://npmcn.com/package/%40bluprynt/forms-core/docs/schema-issue-codes.md) | 全体 `DocumentError` 错误代码、 验证阶段、 错误处理 |
| [发展指南](https://npmcn.com/package/%40bluprynt/forms-core/docs/development-guide.md) | 如何构建、测试、涂料和扩展引擎(例如添加新的字段类型) |

出口类别、类型和公用事业的完整清单见 [API 参考](https://npmcn.com/package/%40bluprynt/forms-core/docs/api-reference.md)。 。 。 .

## 支持的外地类型

| 类型 | 数值 | 说明 |
| --- | --- | --- |
| `string` | `string` | 文本输入 |
| `number` | `number` | 数字输入 |
| `boolean` | `boolean` | 真假切换 |
| `date` | `string` (ISO 8601) (中文(简体) ) | 选取日期者 |
| `select` | `string | number` | 从预定义选项中选择 |
| `array` | `T[]` | 按顺序排列的平面值列表 |
| `file` | `FileValue` 对象 | 文件上传元数据( 名称、 mimeType、 大小、 url) |

## 常见问题

### @bluprynt/forms-core 是什么？

JSON驱动的动态形式的框架不可知性引擎\. Given a form schema \(JSON\),引擎通过条件逻辑处理字段能见度,根据特定类型的规则验证用户输入,并生成结构化的形式文档\(JSON\)\.

### 如何安装 @bluprynt/forms-core？

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

### @bluprynt/forms-core 支持 TypeScript 吗？

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

### @bluprynt/forms-core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bluprynt/forms-core 可以商用吗？

@bluprynt/forms-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bluprynt/forms-core 的下载量有多少？

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

### @bluprynt/forms-core 还在维护吗？

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