# @bluprynt/forms-viewer 中文文档

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

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

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

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

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

- 包体积（解压后）：158 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@bluprynt/forms-core ^4\.2\.0
- 首次发布：2026-03-20T10:40:53.646Z
- 最新版本发布：2026-10-21T14:52:36.194Z
- 近 30 天下载量：20803（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

无头反应组件用于渲染和编辑由JSON驱动的动态形式. 与 `@bluprynt/forms-core` 处理能见度,验证,和段导航——你提供UI组件,取景器将所有东西一起接通.

## 安装

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

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

## README

# @ bluprynt/ forms- 查看器

无头反应组件用于渲染和编辑由JSON驱动的动态形式. 与 `@bluprynt/forms-core` 处理能见度,验证,和段导航——你提供UI组件,取景器将所有东西一起接通.

## 密钥能力

-   **只读渲染** —— 说 `FormViewer` 使用自定义视图组件制作定义和文档中的窗体,并自动显示可见度和验证度.
-   **可编辑表单** —— 说 `FormEditor` 使每个字段的可编辑窗体 `onChange` 处理器、数组和数组列项的操作(添加、去除、移动),并在每个变化上进行活的再验证.
-   **区域导航** —— 说 `FormSections` 列出可见的顶层区域(包括用于未组合字段的合成根)并跟踪活性区域.
-   **验证显示** —— 说 `FormFieldsValidation` 按字段分组实地一级错误; `FormDocumentValidation` 使文档级别出错( schema 错配, 缺失) `submittedAt`(见a/c.5/49/70,附件).
-   **无头建筑** ——所有渲染都委托给您提供的组件地图(`ViewerComponentMap`, (中文(简体) ), `EditorComponentMap`),因此软件包的UI观点为零.

## 安装

```bash
npm install @bluprynt/forms-viewer @bluprynt/forms-core ajv react react-dom
```

`@bluprynt/forms-core`, (中文(简体) ), `react`,以及 `react-dom` 属于对等依赖,必须安装在您的工程中.

## 快速启动

### 设置窗体提供者

这个 `Form` 组件汇编定义,计算能见度,运行验证,并通过上下文曝光一切.

```tsx
import type { FC } from 'react'
import { Form } from '@bluprynt/forms-viewer'
import type { FormDefinition, FormDocument } from '@bluprynt/forms-viewer'

const definition: FormDefinition = { /* ... */ }
const document: FormDocument = { /* ... */ }

const App: FC = () => {
  return (
    <Form definition={definition} data={document}>
      {/* FormViewer, FormEditor, FormSections, etc. */}
    </Form>
  )
}
```

`Form` 道具 :

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `definition` | `FormDefinition` | —— 说 | 形式方案 |
| `data` | `FormDocument` | —— 说 | 窗体值文档 |
| `section` | `ROOT | number` | —— 说 | 活动区域 ID( 使用) `ROOT` 未组合字段) |
| `showInlineValidation` | `boolean` | `true` | 字段组件是否收到校验错误 |
| `children` | `ReactNode` | —— 说 | 儿童成分 |

### 使用表格编辑器( 只读)

使用 `FormViewer` 当您只需要不编辑而显示已提交的窗体值时。 它使每个字段通过您的组件映射以只读模式,应用能见度规则并显示验证状态.

```tsx
import type { FC } from 'react'
import { Form, FormViewer } from '@bluprynt/forms-viewer'
import type { ViewerComponentMap } from '@bluprynt/forms-viewer'

const components: ViewerComponentMap = {
  string: ({ field, value }) => <p>{field.label}: {value}</p>,
  number: ({ field, value }) => <p>{field.label}: {value}</p>,
  boolean: ({ field, value }) => <p>{field.label}: {value ? 'Yes' : 'No'}</p>,
  date: ({ field, value }) => <p>{field.label}: {value}</p>,
  select: ({ field, value, options }) => (
    <p>{field.label}: {options.find(o => o.value === value)?.label}</p>
  ),
  array: ({ field, children }) => <div>{field.label}: {children}</div>,
  file: ({ field, value }) => <p>{field.label}: {value?.name}</p>,
  section: ({ section, children }) => (
    <fieldset>
      <legend>{section.title}</legend>
      {children}
    </fieldset>
  ),
}

const ReadOnlyForm: FC = () => {
  return (
    <Form definition={definition} data={document}>
      <FormViewer components={components} />
    </Form>
  )
}
```

### 使用窗体编辑器( Ediable)

使用 `FormEditor` 当用户需要填写或编辑表格时。 它提供每个战地 `onChange` 处理器和对每次更改都发出回调 `FormDocument` JSON和当前验证结果.

```tsx
import { useState, type FC } from 'react'
import { Form, FormEditor } from '@bluprynt/forms-viewer'
import type { EditorComponentMap, FormDocument, FormValidationResult } from '@bluprynt/forms-viewer'

const components: EditorComponentMap = {
  string: ({ field, value, onChange }) => (
    <input value={value ?? ''} onChange={e => onChange(e.target.value)} />
  ),
  number: ({ field, value, onChange }) => (
    <input type="number" value={value ?? ''} onChange={e => onChange(Number(e.target.value))} />
  ),
  boolean: ({ field, value, onChange }) => (
    <input type="checkbox" checked={value ?? false} onChange={e => onChange(e.target.checked)} />
  ),
  date: ({ field, value, onChange }) => (
    <input type="date" value={value ?? ''} onChange={e => onChange(e.target.value)} />
  ),
  select: ({ field, value, options, onChange }) => (
    <select value={value ?? ''} onChange={e => onChange(e.target.value)}>
      {options.map(o => <option key={o.value} value={o.value}>{o.label}</option>)}
    </select>
  ),
  array: ({ field, children, onAddItem }) => (
    <div>
      {children}
      <button onClick={onAddItem}>Add item</button>
    </div>
  ),
  file: ({ field, value, onChange }) => (
    <input type="file" onChange={e => { /* handle file */ }} />
  ),
  section: ({ section, children }) => (
    <fieldset>
      <legend>{section.title}</legend>
      {children}
    </fieldset>
  ),
}

const EditableForm: FC = () => {
  const [data, setData] = useState<FormDocument>(initialDocument)

  const handleChange = (doc: FormDocument, validation: FormValidationResult) => {
    setData(doc)
    // validation.valid, validation.fieldErrors, etc.
  }

  return (
    <Form definition={definition} data={data}>
      <FormEditor components={components} onChange={handleChange} />
    </Form>
  )
}
```

### 导航使用窗体部分

使用 `FormSections` 来将窗体区域变成标签、侧边栏菜单或任何其他导航 UI,并让用户在它们之间切换。 它列举了可见的顶层区段并跟踪活动区段.

```tsx
import { useState, type FC } from 'react'
import { Form, FormViewer, FormSections, ROOT } from '@bluprynt/forms-viewer'

const FormWithSections: FC = () => {
  const [activeSection, setActiveSection] = useState<typeof ROOT | number>(ROOT)

  return (
    <Form definition={definition} data={document} section={activeSection}>
      <FormSections
        container={({ children }) => <nav>{children}</nav>}
        item={({ section, active, select }) => (
          <button onClick={select} style={{ fontWeight: active ? 'bold' : 'normal' }}>
            {section.title}
          </button>
        )}
        defaultSectionTitle="General"
        onSelect={setActiveSection}
      />
      <FormViewer components={viewerComponents} />
    </Form>
  )
}
```

### 使用窗体校正和窗体文档校正

使用 `FormDocumentValidation` 以显示文档级别错误 — 计划错配、 无效版本、 缺失 `submittedAt`以及类似的结构问题。 使用 `FormFieldsValidation` 以显示字段级错误——与表单中定义的验证规则不符的值(需要、分/最大、图案等).

```tsx
import type { FC } from 'react'
import { Form, FormFieldsValidation, FormDocumentValidation } from '@bluprynt/forms-viewer'

const ValidationSummary: FC = () => {
  return (
    <Form definition={definition} data={document}>
      <FormDocumentValidation
        container={({ children }) => <div className="doc-errors">{children}</div>}
        error={({ code, message }) => <p>{message} ({code})</p>}
      />
      <FormFieldsValidation
        container={({ children }) => <div className="field-errors">{children}</div>}
        field={({ field, errors, children }) => (
          <div>
            <strong>{field?.label}</strong>
            {children}
          </div>
        )}
        error={({ message, rule }) => <p>{message} [{rule}]</p>}
      />
    </Form>
  )
}
```

## 组件映射类型

### 查看器组件映射

只读渲染的组件映射 。 每个键将字段类型映射到反应组件.

| 密钥 | 道具类型 | 说明 |
| --- | --- | --- |
| `string` | `StringViewProps` | 文本字段显示 |
| `number` | `NumberViewProps` | 数字字段显示 |
| `boolean` | `BooleanViewProps` | 布尔字段显示 |
| `date` | `DateViewProps` | 日期字段显示 |
| `select` | `SelectViewProps` | 选择字段显示( 收到) `options`(中文(简体) ) |
| `array` | `ArrayViewProps` | 矩阵字段显示( 收件人) `children` 用于项目, `itemDef`(中文(简体) ) |
| `array_obj?` | `ArrayObjViewProps` | 数组显示. 接收 `itemsDef`,解决 `kind` (单位:千美元)`'list'` | `'table'`和 `children: ReactNode[][]`索引 `children[row][subField]` 并与 `itemsDef`。 。 。 . |
| `file` | `FileViewProps` | 文件字段显示 |
| `section` | `SectionViewProps` | 区域包装(收件) `children`(中文(简体) ) |
| `multiselect?` | `MultiselectViewProps` | 多选择显示 。 值为 `(string | number)[]`; 获得 `options`。 。 。 . |
| `static?` | `StaticViewProps` | 仅显示文本块 。 接收 **仅限** `field` 没有 `value`, (中文(简体) ), `errors` 或者说 `suggestion`。 。 。 . |
| `blockchain?` | `BlockchainViewProps` | CAIP 地址显示 。 值为 a `string`,以逐字记录形式储存. |
| `sustainability?` | `SustainabilityViewProps` | 可持续性参考显示。 值为 `{ address, ccri?, cmc? }`。 。 。 . |
| `error?` | `ErrorProps` | 可选内行出错渲染器 |

所有视图字段道具扩展 `BaseViewFieldProps` 规定 `field: FieldContentItem` 财务报告和审定财务报表 `errors: FieldValidationError[]`。 。 。 . `StaticViewProps` 是例外: 它只携带 `field: StaticFieldContentItem`,其 `text` 内容及其 `label` 是一个可选标题.

`array_obj`, (中文(简体) ), `multiselect`, (中文(简体) ), `static`, (中文(简体) ), `blockchain` 财务报告和审定财务报表 `sustainability` 为: **选项** 键,所以现有的地图会不断编译。 未提供部件的字段只能扔出.

### 编辑器组件映射

可编辑渲染的组件映射 。 用突变回调来扩展取景道具.

| 密钥 | 道具类型 | 说明 |
| --- | --- | --- |
| `string` | `StringEditProps` | 文本输入为 `onChange(value)` |
| `number` | `NumberEditProps` | 数字输入 `onChange(value)` |
| `boolean` | `BooleanEditProps` | 布尔输入 `onChange(value)` |
| `date` | `DateEditProps` | 输入日期与 `onChange(value)` |
| `select` | `SelectEditProps` | 选择输入方式 `onChange(value)` 财务报告和审定财务报表 `options` |
| `array` | `ArrayEditProps` | 矩阵编辑器 `onAddItem`, (中文(简体) ), `onRemoveItem(index)`, (中文(简体) ), `onMoveItem(from, to)` |
| `array_obj?` | `ArrayObjEditProps` | 与同为三行处理器的一行编辑器. `onAddItem` 附加一行; 每个单元格 `onChange` 到达每个子战地组件. |
| `file` | `FileEditProps` | 文件输入方式 `onChange(value)` |
| `section` | `SectionEditProps` | 区域包装(收件) `children`(中文(简体) ) |
| `multiselect?` | `MultiselectEditProps` | 复选框组 . `onChange((string | number)[] | undefined)` - 发送整个阵列. |
| `static?` | `StaticEditProps` | 仅显示文本块 。 页:1 `StaticViewProps`; 没有什么可编辑的. |
| `blockchain?` | `BlockchainEditProps` | 文本输入为 `onChange(value)`。CAIP格式从未被引擎检查过. |
| `sustainability?` | `SustainabilityEditProps` | 对象编辑器 `onChange(value)` - 发送整个 `{ address, ccri, cmc }`释放 `undefined` 当每个部分都是空白的. |
| `error?` | `ErrorProps` | 可选内行出错渲染器 |

所有编辑字段道具扩展 `BaseEditFieldProps`,则添加 `onChange(value)` 加可选 `onAcceptSuggestion()` 编号 : `onRejectSuggestion()` 处理器到基本视图道具. `StaticEditProps` 已经 不 静态块没有 `onChange`,因此同一部分为两种地图服务.

每个字段——只读可编辑——还收到字段撰写元数据 `field` (单位:千美元)`description`, (中文(简体) ), `placeholder`, (中文(简体) ), `answer_guidelines`, (中文(简体) ), `reference_id`)和可选 `suggestion` (单位:千美元)`{ value, confidence, source }`当文档中包含一个字段。 正在接受 将建议值复制到字段值并保留建议;拒绝删除 建议并留下价值。 见 [变化情况](https://npmcn.com/package/CHANGES.md)。 。 。 .

## 导出 API

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `Form` | 构成部分 | 背景提供者——编译定义,计算能见度和验证 |
| `useFormContext` | 钩子 | 访问形式上下文(定义、数据、引擎、能见度、验证) |
| `FormViewer` | 构成部分 | 只读窗体渲染器 |
| `FormEditor` | 构成部分 | 带有更改回调的可编辑窗体渲染器 |
| `FormSections` | 构成部分 | 区域导航列表 |
| `FormFieldsValidation` | 构成部分 | 字段级验证错误显示 |
| `FormDocumentValidation` | 构成部分 | 文件级验证错误显示 |
| `ROOT` | 符号 | 识别根( 未组合字段) 部分 |
| `ViewerComponentMap` | 类型 | 构成部分地图 `FormViewer` |
| `EditorComponentMap` | 类型 | 构成部分地图 `FormEditor` |
| `BaseViewFieldProps` | 类型 | 视图字段的基本道具 |
| `BaseEditFieldProps` | 类型 | 编辑字段组件的基础道具 |
| `ErrorProps` | 类型 | 内置错误组件的道具 |
| `FormSectionEntry` | 类型 | 区域条目 `FormSections` |
| `FormSectionItemProps` | 类型 | 区域项目渲染器的道具 |
| `FieldValidationFieldEntry` | 类型 | 字段 + 错误组 `FormFieldsValidation` |
| `FormValuesEditor` | 类 | 用于对照定义读取和书写形式值的流利编辑器 |
| `DocumentError` | 类 | 表示文档级别验证失败出错 |
| `FormDefinition` | 类型 | JSON 方案描述形式结构、字段、章节和规则 |
| `FormDocument` | 类型 | 包含用户提交的形式值和可选建议的 JSON 文件 |
| `FieldSuggestion` | 类型 | 机器拟议答案: `{ value, confidence, source }` |
| `FormSuggestions` | 类型 | 由字符串字段 ID 键入的建议分隔图 |
| `FormValidationResult` | 类型 | 文件一级和外地一级错误的验证结果 |
| `FieldType` | 类型 | 支助领域类型联盟(`string`, (中文(简体) ), `number`, (中文(简体) ), `boolean`, (中文(简体) ), `date`, (中文(简体) ), `select`, (中文(简体) ), `multiselect`, (中文(简体) ), `array`, (中文(简体) ), `array_obj`, (中文(简体) ), `file`, (中文(简体) ), `static`, (中文(简体) ), `blockchain`, (中文(简体) ), `sustainability`(中文(简体) ) |
| `FileValue` | 类型 | 包含名称、 MIME 类型、 大小和 URL 的文件字段值 |
| `SustainabilityValue` | 类型 | 可持续性领域价值: `{ address, ccri?, cmc? }` |

## 文档

-   [API 参考](https://npmcn.com/package/%40bluprynt/forms-viewer/docs/api-reference.md) - 所有出口部件、钩子和类型的详细说明
-   [建筑](https://npmcn.com/package/%40bluprynt/forms-viewer/docs/architecture.md) • 内部设计、数据流动和组件结构
-   [发展指南](https://npmcn.com/package/%40bluprynt/forms-viewer/docs/development-guide.md) 制定、测试和贡献准则

## 常见问题

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

无头反应组件用于渲染和编辑由JSON驱动的动态形式\. 与 @bluprynt/forms-core 处理能见度,验证,和段导航——你提供UI组件,取景器将所有东西一起接通\.

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

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

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

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

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

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

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

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

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

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

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

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