# @formio/react 中文文档

规范地址：https://npmcn.com/package/%40formio/react/

版本：6\.2\.2
npm 元数据更新时间：2026-10-09T19:33:34.219Z
中文译文更新时间：2026-11-15T09:05:46.441Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：257 kB，147 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：4 个
- peer 依赖：react \>=17，react-dom \>=17
- 首次发布：2020-06-12T16:24:15.745Z
- 最新版本发布：2026-10-09T19:33:33.941Z
- 近 30 天下载量：133493（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：79（近 12 个月 8 个）

## 中文简介

形式.io形式的反射渲染器.

## 安装

```sh
npm install @formio/react
```

也可以使用：`pnpm add @formio/react`、`yarn add @formio/react`、`bun add @formio/react`

## README

# @ formio/ 反应

用于根据 [表格.io](https://www.form.io/) 平台.

## 正式文件

最新文件、发布资料和指南一律参考本文中提供的官方表格:

**[https://help.form.io (英语)](https://help.form.io/dev/javascript-development/frameworks#react)**

## 安装

### 无

```bash
npm install @formio/react --save
npm install @formio/js --save
```

### 线条

```bash
yarn add @formio/react @formio/js
```

## 使用 Vite( 注: 当使用像 Next.js 或 Create React App 这样的框架时, 不需要额外的 Vite 配置)

当使用 @formio/ resact 在 Vite 创建的工程中( 特别是针对 React 18 和 19) 时, 请确保您安装 @ vitejs/ plugin- react 软件包并在您的 vite 中配置 。 配置.js文件.

安装 Vite 反应插件

```bash
yarn add --dev @vitejs/plugin-react
```

在您的 vite.config.js 中,添加反应插件 :

```bash
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});
```

## 钩子

### 使用Formio Context

向您的 React 组件提供全局Formio 上下文值的钩子 . **调用组件 `useFormioContext` 一定是一个孩子 `<FormioProvider />` 组件.**

#### 返回值

`useFormioContext` 返回具有下列参数的对象:

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 福尔米奥 | 福尔米奥类型 | 全球福尔米奥天体. 用于各种静态方法以及SDK函数,这些功能在 `new` 使用运算符. |
| 基数Url | 字符串 | Form.io 服务器的基础 URL . |
| 项目Url | 字符串 | Form.io企业项目的基础url. |
| 登录 | () 无效 | 一种方便方法,通过取消给定符并从本地存储中去掉来登录 Form.io会话. |
| 符号 | 字符串 | 表格.io JWT-token(如果用户得到认证). |
| 已认证 | 布尔 | 在Form.io会话中登录或退出时切换的便利值. |

#### 实例

使用由 `useFormioContext` 以评价用户的表单.io认证:

```tsx
import { createRoot } from 'react-dom/client';
import { useFormioContext, FormGrid, FormioProvider } from '@formio/react';

const App = () => {
    const { isAuthenticated } = useFormioContext();

    return isAuthenticated ? (
        <Router>
            <Route path="/form">
                <FormGrid
                    formQuery={{ type: 'form' }}
                    onFormClick={(id) => setLocation(`/form/${id}`)}
                />
            </Route>
            <Route path="/resource">
                <FormGrid
                    formQuery={{ type: 'resource' }}
                    onFormClick={(id) => setLocation(`/resource/${id}`)}
                />
            </Route>
        </Router>
    ) : (
        <Redirect to="/login" />
    );
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);
root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <App />
    </FormioProvider>,
);
```

使用 [表格.io SDK](https://help.form.io/dev/javascript-development/javascript-sdk) 与 Form.io 服务器交互:

```tsx
import { createRoot } from 'react-dom/client';
import { useEffect, useState } from 'react';
import {
    useFormioContext,
    FormioProvider,
    FormType,
    Form,
} from '@formio/react';

const FormsByUser = ({ userId }: { userId: string }) => {
    const { Formio, projectUrl } = useFormioContext();
    const [forms, setForms] = useState<FormType[]>([]);

    useEffect(() => {
        const fetchForms = async () => {
            const formio = new Formio(projectUrl);
            try {
                const forms = await formio.loadForms({
                    params: { type: 'form', owner: userId },
                });
                setForms(forms);
            } catch (err) {
                console.log(
                    `Error while loading forms for user ${userId}:`,
                    err,
                );
            }
        };
        fetchForms();
    }, [Formio, projectUrl, userId]);

    return forms.map(function (form) {
        return (
            <>
                <Form src={form} />
                <div style={{ marginBottom: '10px' }} />
            </>
        );
    });
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);
const root = createRoot();
root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <App />
    </FormioProvider>,
);
```

### 图片

向您的 React 组件提供限制/ skip 服务器 pagination 数据和方法的钩头 . **调用组件 `usePagination` 一定是一个孩子 `<FormioProvider />` 组件.**

#### 道具

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 初始页 | 编号 | 要获取的初始页面 . |
| 限制 | 字符串 | 每页结果数. |
| 数据 OrFetch 函数 | T\[\] Q( 限制: 数量, 跳过: 数量) QQ 承诺<T\[\]> | 要拼接的完整数据集或返回数据的函数。 如果一个函数,则必须支持限制并跳过,成为稳定的引用. |

#### 返回值

`usePagination` 返回具有下列参数的对象:

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 数据 | T\[ | 本页的数据. |
| 共计 | 数字 qq 未定义 | 如果有,则列出文件总数. |
| 页 次 | 编号 | 当前页码 . |
| 拥有更多 | 布尔 | 表示服务器是否有更多结果的值 。 没有全部文档数时有用 . |
| 下一页 | () 无效 | 一个将数据移动到下一个可用页面的函数. |
| 预选页 | () 无效 | 一个将数据移动到上一个可用页面的函数. |
| 获取页面 | (页:号码) | 一个将数据移动到指定页面的函数. |

#### 实例

贴出一组表格 :

```tsx
import { createRoot } from 'react-dom/client';
import { useCallback } from 'react';
import {
    useFormioContext,
    FormioProvider,
    FormType,
    Form,
} from '@formio/react';

const FormsByUser = ({ userId }: { userId: string }) => {
    const { Formio, projectUrl } = useFormioContext();
    const fetchFunction = useCallback(
        (limit: number, skip: number) => {
            const formio = new Formio(`${projectUrl}/form`);
            return formio.loadForms({ params: { type: 'form', limit, skip } });
        },
        [Formio, projectUrl],
    );
    const { data, page, nextPage, prevPage, hasMore } = usePagination<FormType>(
        1,
        10,
        fetchFunction,
    );

    return (
        <div>
            <div>
                {data.map((form) => (
                    <>
                        <Form src={form} />
                        <div style={{ marginBottom: '10px' }} />
                    </>
                ))}
            </div>
            <ul>
                <li
                    onClick={prevPage}
                    className={`${page === 1 ? 'disabled' : ''}`}
                >
                    Prev
                </li>
                <li
                    onClick={nextPage}
                    className={`${hasMore ? '' : 'disabled'}`}
                >
                    Next
                </li>
            </ul>
        </div>
    );
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);
const root = createRoot();
root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <App />
    </FormioProvider>,
);
```

## 构成部分

### 福尔米奥提供

使用此库中的一些钩和组件时需要的回放上下文提供者组件 .

#### 道具

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 福尔米奥 | 对象 | 要使用的 Formio 对象 . |
| 基数Url | 字符串 | Form.io服务器的基础 URL. |
| 项目Url | 字符串 | Form.io企业项目的url. |

#### 实例

从您自主机 Form.io 部署中生成一个简单的表格 :

```JSX
import { createRoot } from 'react-dom/client';
import { Form, FormioProvider } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
  <FormioProvider baseUrl="https://myformiodeployment.example.com/" projectUrl="https://myformiodeployment.example.com/myproject">
    <Form src="https://myformiodeployment.example.com/myproject/myexampleform" />
  </FormioProvider>
);
```

扩展Formio对象以使用外部模块 :

```JSX
import { createRoot } from 'react-dom/client';
import { Form, FormioProvider } from '@formio/react';
import { Formio } from '@formio/js';
import premium from '@formio/premium';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

Formio.use(premium);
root.render(
  <FormioProvider Formio={Formio}>
    <Form src="https://myproject.form.io/myformwithpremiumcomponents" />
  </FormioProvider>
);
```

### 表单

反光组件包装 [a 形式.io形式](https://help.form.io/dev/form-development/form-renderer#introduction)。可以使用 JSON 格式定义或 Form.io 格式 URL,并在您的 React 应用程序中制作格式.

#### 道具

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `src` | `Webform | string` |  | JSON 格式定义或源 URL 。 如果一个 URL,通常来自 form.io 服务器. |
| `url` | `string` |  | 形式定义的url. 与JSON表格定义一并使用 `src`,用于文件上传、OAuth以及需要了解Form.io表格的URL以便进一步处理的其他组件或动作。 表格将不会从此url中被载入, 提交文件也不会在此被保存 . |
| `submission` | `JSON` |  | 填表时提交数据。 您可以加载上一个提交件,也可以使用一些预填数据创建提交件。 如果不提交,表格将使用表格中的默认值初始化空提交. |
| `options` | `FormOptions` |  | 表格选项。 见 [这里](https://help.form.io/developers/form-development/form-renderer#form-renderer-options) 更多细节. |
| `onFormReady` | `(instance: Webform) => void` |  | 调用函数, 当窗体已打开时被调用 。 用于访问基本的@formio/js Webform 实例 . |
| `onSubmit` | `(submission: JSON, saved?: boolean) => void` |  | 当提交开始时调用回调函数 。 若为 `src` 这不是 Form.io 服务器 URL, 这将是最后提交事件 . |
| `onCancelSubmit` | `() => void` |  | 当提交被取消时调用回调功能 . |
| `onSubmitDone` | `(submission: JSON) => void` |  | 当提交文件成功提交到服务器时调用回调函数 。 只有在 `src` 设置为 Form.io 服务器 URL. |
| `onChange` | `(value: any, flags: any, modified: any) => void` |  | 当提交文件中的值改变时,调用函数. |
| `onComponentChange` | `(changed: { instance: Webform; component: Component; value: any; flags: any}) => void` |  | 当特定组件改变时,调用回调函数. |
| `onError` | `(error: EventError | false) => void` |  | 在提交时发生错误(例如验证错误)时被调用的回调函数. |
| `onRender` | `(param: any) => void` |  | 一个调用函数,当窗体完成渲染时被调用. `param` 将视窗体和显示类型而定. |
| `onCustomEvent` | `(event: { type: string; component: Component; data: JSON; event?: Event; }) => void` |  | 从配置为"Event"类型的按钮组件所触发的回调函数. |
| `onPrevPage` | `(page: number, submission: JSON) => void` |  | 向导表格的回调函数,在按下“上”按钮时被调用. |
| `onNextPage` | `(page: number, submission: JSON) => void` |  | 向导格式的回调功能,在按下"Next"按钮时被调用. |
| `otherEvents` | `[event: string]: (...args: any[]) => void;` |  | 用于签署其他活动的“全面捕捉”道具(完整列表见 [我们的文件](https://help.form.io/dev/form-development/form-renderer#form-events)) (中文(简体) ). |

#### 实例

从表格.io SaaS中生成一个简单的形式:

```JSX
import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <Form src="https://example.form.io/example" onSubmit={console.log} />,
);
```

从 JSON 形式定义中生成一个简单的形式 :

```JSX
import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
    type: "form",
    display: "form",
    components: [
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "button",
            key: "submit",
            label: "Submit",
            input: true
        }
    ]
}

root.render(<Form src={formDefinition} />);
```

访问基础形式实例(见 [这里](https://help.form.io/dev/form-development/form-renderer#form-properties) 详细情况:

```JSX
import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { Form } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
    type: "form",
    display: "form",
    components: [
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "button",
            key: "submit",
            label: "Submit",
            input: true
        }
    ]
}

const App = () => {
    const formInstance = useRef(null);

    const handleFormReady = (instance) => {
        formInstance.current = instance;
    }

    const handleClick = () => {
        if (!formInstance.current) {
            console.log("Our form isn't quite ready yet.");
            return;
        }
        formInstance.current.getComponent('firstName')?.setValue('John');
        formInstance.current.getComponent('lastName')?.setValue('Smith');
    }

    return (
        <div>
            <Form src={formDefinition} onFormReady={handleFormReady} />
            <button type="button" onClick={handleClick}>Set Names</button>
        </div>
    );
}

root.render(<App />);
```

#### 下一个. js 的使用

A. 《公约》的一些依赖性 `@formio/js` 依赖 Web API 和浏览器专用全域像 `window`。因为 Next.js 包含服务器侧渲染阶段,所以即使用于 [客户端组件](https://nextjs.org/docs/app/building-your-application/rendering/client-components)因此,我们建议使用 Next.js 动态导入表单组件 `dynamic` API : (英语)

```tsx
'use client';
import dynamic from 'next/dynamic';
import { Webform } from '@formio/js';

const Form = dynamic(
    () => import('@formio/react').then((module) => module.Form),
    { ssr: false },
);

export default function Home() {
    const formInstance = useRef<Webform | null>(null);

    const handleClick = () => {
        if (!formInstance.current) {
            console.log("Our form isn't quite ready yet.");
            return;
        }
        formInstance.current.getComponent('firstName')?.setValue('John');
        formInstance.current.getComponent('lastName')?.setValue('Smith');
    };

    return (
        <main className={styles.main}>
            <Form
                form="https://examples.form.io/example"
                onFormReady={(instance) => {
                    formInstance.current = instance;
                }}
            />
            <button onClick={handleClick}>Set Names</button>
        </main>
    );
}
```

### 窗体构建器

反光组件包装 [a.io 窗体构建器](https://help.form.io/dev/form-development/form-builder)。可以在您的 React 应用程序中创建窗体构建器.

#### 道具

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `initialForm` | `FormType` |  | JSON形式定义了在构建器中要渲染的初始形式. 通常,这必须是一个稳定的参考;否则它可能会破坏并再现潜在的构建者实例并引起出人意料的行为. |
| `options` | `FormBuilderOptions` |  | 窗体构建者选项 。 见 [这里](https://help.form.io/dev/form-development/form-builder#form-builder-options) 更多细节. |
| `onBuilderReady` | `(instance: FormBuilder) => void` |  | 在窗体构建器提供时被调用的回调函数 。 用于访问基本的 @formio/js FormBuilder 实例 . |
| `onChange` | `(form: FormType) => void` |  | 当正在构建的窗体改变时, 调用函数会被调用 . |
| `onSaveComponent` | `(component: Component, original: Component, parent: Component, path: string, index: number, isNew: boolean, originalComponentSchema: Component) => void;` |  | 一个调用函数,当组件被保存在构建器中时被调用. |
| `onEditComponent` | `(component: Component) => void` |  | 一个当某个组件被编辑时被调用的回调函数 . |
| `onUpdateComponent` | `(component: Component) => void` |  | 当组件更新时调用回调函数 . |
| `onDeleteComponent` | `(component: Component, parent: Component, path: string, index: number) => void` |  | 当一个组件被删除时调用回调函数 . |

#### 实例

以空白形式绘制简单的窗体构建器 :

```JSX
import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormBuilder />,
);
```

绘制一个初始形式定义的构建者 :

```JSX
import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
    display: "form",
    components: [
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "button",
            key: "submit",
            label: "Submit",
            input: true
        }
    ]
}

root.render(<FormBuilder form={formDefinition} />);
```

访问基础窗体构建器实例(参见 [这里](https://help.form.io/dev/form-development/form-builder#form-builder-sdk) 详细情况:

```JSX
import { useRef } from 'react';
import { createRoot } from 'react-dom/client';
import { FormBuilder } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

const formDefinition = {
    display: "form",
    components: [
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "textfield"
            key: "firstName",
            label: "First Name",
            input: true,
        },
        {
            type: "button",
            key: "submit",
            label: "Submit",
            input: true
        }
    ]
}

const App = () => {
    const formBuilderInstance = useRef(null);

    const handleFormReady = (instance) => {
        formBuilderInstance.current = instance;
    }

    const handleClick = () => {
        if (!formBuilderInstance.current) {
            console.log("Our form isn't quite ready yet.");
            return;
        }
        console.log("Here's our builder instance:", formBuilderInstance.current);
    }

    return (
        <div>
            <Form src={formDefinition} onFormReady={handleFormReady} />
            <button type="button" onClick={handleClick}>Log Our Builder</button>
        </div>
    );
}

root.render(<App />);
```

### 窗体编辑

FormEdit组件将FormBuilder组件包起来并添加了设置窗体,允许与Form.io服务器之间直接交互. **这个 `FormEdit` 组件必须是 `<FormioProvider />` 组件.**

#### 道具

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `initialForm` | `FormType` | `{ title: '', name: '', path: '', display: 'form' as const, type: 'form' as const, components: [] }` | 要修改的现有形式的形式定义. |
| `settingsForm` | `FormType` | `DEFAULT_SETTINGS_FORM` | "设置"表的形式定义,默认为定义正在编辑表的形式的标题,名称,路径,标记和显示. |
| `settingsFormOptions` | `FormOptions` | `{}` | 选项传递到设置窗体 . |
| `onSettingsFormReady` | `(instance: Webform) => void` |  | 这个 `onFormReady` 调用设置窗体 . |
| `onBuilderReady` | `(instance: FormioBuilder) => void` |  | 这个 `onBuilderReady` 调用窗体构建器 . |
| `builderOptions` | `FormBuilderOptions` | `{}` | 将选项传递给 FormBuilder . |
| `saveFormFn` | `(form: FormType) => Promise<CoreFormType>` |  | 默认使用Form.io SDK将窗体保存到Form.io服务器 `<FormioProvider />`。 。 。 . |
| `onSaveForm` | `(form: FormType) => void` |  | 后面的召回 `saveFormFn` 称为(道具或默认)。 一个可选功能,可以取代将窗体保存到 Form.io 服务器的默认行为. |

#### 样式

`FormEdit` 使用一个 `components` 包含每个“元素”的道具 `FormEdit` 组件,允许您输入自己的标记和样式。 这是它的类型:

```ts
type ComponentProp<T = object> = (props: T) => JSX.Element;
type Components = {
    Container?: ComponentProp<{ children: ReactNode }>;
    SettingsFormContainer?: ComponentProp<{ children: ReactNode }>;
    BuilderContainer?: ComponentProp<{ children: ReactNode }>;
    SaveButtonContainer?: ComponentProp<{ children: ReactNode }>;
    SaveButton?: ComponentProp<{
        onClick: () => void;
    }>;
};
```

#### 实例

装入简单 `FormEdit` 从 Form.io 服务器上装入窗体的组件:

```tsx
import { createRoot } from 'react-dom/client';
import { useState, useEffect } from 'react';
import {
    FormGrid,
    FormioProvider,
    useFormioContext,
    FormType,
} from '@formio/react';

const App = () => {
    const { Formio, projectUrl } = useFormioContext();
    const [form, setForm] = useState<FormType | undefined>();

    useEffect(() => {
        const fetchForm = async () => {
            try {
                const formio = new Formio(`${projectUrl}/example`);
                const form = await formio.loadForm();
                setForm(form);
            } catch (err) {
                console.log('Error while fetching form:', err);
            }
        };
    }, [Formio, projectUrl]);

    return form ? (
        <FormEdit
            initialForm={form}
            onSaveForm={() => console.log('Form saved to my Form.io server!')}
        />
    ) : null;
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <App />
    </FormioProvider>,
);
```

将自己的标记和样式输入组件:

```tsx
import { createRoot } from 'react-dom/client';
import { useState, useEffect } from 'react';
import {
    FormEdit,
    FormioProvider,
    useFormioContext,
    FormType,
} from '@formio/react';

const App = ({ name }: { name: string }) => {
    const { Formio, projectUrl } = useFormioContext();
    const [form, setForm] = useState<FormType | undefined>();

    useEffect(() => {
        const fetchForm = async () => {
            try {
                const formio = new Formio(`${projectUrl}/example`);
                const form = await formio.loadForm();
                setForm(form);
            } catch (err) {
                console.log('Error while fetching form:', err);
            }
        };
    }, [Formio, projectUrl]);

    return form ? (
        <FormEdit
            initialForm={form}
            onSaveForm={() => console.log('Form saved to my Form.io server!')}
            components={{
                SaveButtonContainer: ({ children }) => (
                    <div
                        className="save-form-bar button-wrap"
                        style={{ justifyContent: 'end' }}
                    >
                        {children}
                    </div>
                ),
                SaveButton: ({ onClick }) => (
                    <button className="button save-form" onClick={onClick}>
                        Save {name}
                    </button>
                ),
            }}
        />
    ) : null;
};
const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <App name="Form" />
    </FormioProvider>,
);
```

### 窗体图形

FormGrid组件可用于制作表格列表,每行都有一组动作. **这个 `FormGrid` 组件必须是 `<FormioProvider />` 组件.**

#### 道具

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `actions` | `Action[]` | `DEFAULT_ACTIONS` | 与每个窗体网格行上的按钮相对应的一系列动作。 默认为编辑动作( 将调用 `onFormClick` 函数道克)和一个删除动作(将使用Form.io SDK来软化删除窗体). |
| `forms` | `FormType[]` |  | 如果你愿意自己去取, 你可以通过一系列的表格 `FormGrid`。 。 。 . |
| `formQuery` | `Record<string, JSON>` | `{}` | 如果你不通过 `forms` 螺丝管, `FormGrid` 将使用 Form.io SDK 来获取基于 `formQuery` 道具 (英语). |
| `onFormClick` | `(id: string) => void` |  | 调用函数 `FormNameContainer` . |
| `limit` | `number` | `10` | 使用的页面大小限制 `usePagination`。 。 。 . |
| `components` | `Record<string, ComponentProp<T>>` | `{}` | 可样式组件列表 。 见 [样式](https://npmcn.com/package/%40formio/react/#readme-Styling) 详细情况. |

#### 样式

`FormGrid` 使用一个 `components` 包含每个“元素”的道具 `FormGrid` 组件,允许您输入自己的标记和样式。 这是它的类型:

```ts
type ComponentProp<T = object> = (props: T) => JSX.Element;
type Components = {
    Container?: ComponentProp<{ children: ReactNode }>;
    FormContainer?: ComponentProp<{ children: ReactNode }>;
    FormNameContainer?: ComponentProp<{
        children: ReactNode;
        onClick?: () => void;
    }>;
    FormActionsContainer?: ComponentProp<{ children: ReactNode }>;
    FormActionButton?: ComponentProp<{
        action: Action;
        onClick: () => void;
    }>;
    PaginationContainer?: ComponentProp<{ children: ReactNode }>;
    PaginationButton?: ComponentProp<{
        children: ReactNode;
        isActive?: boolean;
        disabled?: boolean;
        onClick: () => void;
    }>;
};
```

#### 实例

装入从 Form.io 服务器获取窗体的简单窗体网格(通过 `<FormioProvider />` 组件 :

```tsx
import { createRoot } from 'react-dom/client';
import { FormGrid, FormioProvider } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <FormGrid formQuery={{ type: 'form' }} />
    </FormioProvider>,
);
```

将自己的标记和样式输入组件:

```tsx
import { FormGridProps, FormGrid } from '@formio/react';
import { createRoot } from 'react-dom/client';

const Container: FormGridComponentProps['Container'] = ({ children }) => (
    <div className="panel">{children}</div>
);

const FormContainer: FormGridComponentProps['FormContainer'] = ({
    children,
}) => (
    <div className={`item-wrap form`}>
        <button className="item">{children}</button>
    </div>
);

const FormNameContainer: FormGridComponentProps['FormNameContainer'] = ({
    children,
    onClick,
}) => {
    return (
        <div className="item-title" onClick={onClick}>
            <img src={`icon-form.svg`} alt={`${type} icon`} />
            {children}
        </div>
    );
};

const FormActionsContainer: FormGridComponentProps['FormActionsContainer'] = ({
    children,
}) => <div className="item-buttons">{children}</div>;

const FormActionButton: FormGridComponentProps['FormActionButton'] = ({
    action,
    onClick,
}) => (
    <a
        className={`btn ${action && action.name === 'Edit' ? 'edit' : 'trash'}`}
        onClick={onClick}
    >
        <i
            className={`${action && action.name === 'Edit' ? 'ri-edit-box-line' : 'ri-delete-bin-line'}`}
        ></i>{' '}
        {action && action.name === 'Edit' ? 'Edit' : ''}
    </a>
);

const PaginationContainer: FormGridComponentProps['PaginationContainer'] = ({
    children,
}) => <div className="pagination-buttons">{children}</div>;

const PaginationButton: FormGridComponentProps['PaginationButton'] = ({
    isActive,
    disabled,
    children,
    onClick,
}) => (
    <a
        className={`pagination-btn${isActive ? ' active' : ''}${disabled ? ' disabled' : ''}`}
        onClick={onClick}
    >
        {children}
    </a>
);

export const MyFormGrid = () => {
    return (
        <FormGrid
            formQuery={{ type: 'form' }}
            onFormClick={(id) => console.log(`Form with id ${id} clicked!`)}
            components={{
                Container,
                FormContainer,
                FormNameContainer,
                FormActionsContainer,
                FormActionButton,
                PaginationContainer,
                PaginationButton,
            }}
        />
    );
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <MyFormGrid />
    </FormioProvider>,
);
```

### 提交图像

PresentGrid 组件可用于制作表格列表,每行都有一组动作. **这个 `SubmissionGrid` 组件必须是 `<FormioProvider />` 组件.**

#### 道具

| 名称 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `submissions` | `Submission[]` |  | 如果你愿意自己去取, 你可以通过一系列提交到 `SubmissionGrid`。 。 。 . |
| `formId` | `string` |  | 提交来文的表格编号 `SubmissionGrid` 如果 `submissions` 未提供道具. |
| `submissionQuery` | `Record<string, JSON>` | `{}` | 如果你不通过 `submissions` 螺丝管, `SubmissionsGrid` 将使用 Form.io SDK 来获取基于 `submissionQuery` 道具 (英语). |
| `onSubmissionClick` | `(id: string) => void` |  | 调用函数 `TableBodyRowContainer` 组件组件单击. |
| `limit` | `number` | `10` | 使用的页面大小限制 `usePagination`。 。 。 . |
| `components` | `Record<string, ComponentProp<T>>` | `{}` | 可样式组件列表 。 见 [样式](https://npmcn.com/package/%40formio/react/#readme-Styling) 详细情况. |

#### 样式

`SubmissionGrid` 使用一个 `components` 包含每个成分“元素”的道具 `SubmissionGrid` 组件,允许您输入自己的标记和样式。 这是它的类型:

```ts
type ComponentProp<T = object> = (props: T) => JSX.Element;
type Components = {
    Container?: ComponentProp<{ children: ReactNode }>;
    TableContainer?: ComponentProp<{ children: ReactNode }>;
    TableHeadContainer?: ComponentProp<{ children: ReactNode }>;
    TableHeadCell?: ComponentProp<{ children: ReactNode }>;
    TableBodyRowContainer?: ComponentProp<{
        children: ReactNode;
        onClick?: () => void;
    }>;
    TableHeaderRowContainer?: ComponentProp<{ children: ReactNode }>;
    TableBodyContainer?: ComponentProp<{ children: ReactNode }>;
    TableCell?: ComponentProp<{ children: ReactNode }>;
    PaginationContainer?: ComponentProp<{ children: ReactNode }>;
    PaginationButton?: ComponentProp<{
        children: ReactNode;
        isActive?: boolean;
        disabled?: boolean;
        onClick: () => void;
    }>;
};
```

#### 实例

装入从 Form.io 服务器获取窗体的简单提交网格(通过 `<FormioProvider />` 组件 :

```tsx
import { createRoot } from 'react-dom/client';
import { SubmissionGrid, FormioProvider } from '@formio/react';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <SubmissionGrid formId="57aa1d2a5b7a477b002717fe" />
    </FormioProvider>,
);
```

将自己的标记和样式输入组件:

```tsx
import { SubmissionGridProps, SubmissionGrid } from '@formio/react';
import { createRoot } from 'react-dom/client';

const components: SubmissionTableProps['components'] = {
    Container: ({ children }) => <div className="table-wrap">{children}</div>,
    TableContainer: ({ children }) => (
        <div className="table remember-focus-table">{children}</div>
    ),
    TableHeadContainer: ({ children }) => <div>{children}</div>,
    TableHeaderRowContainer: ({ children }) => (
        <div className="trow heading">{children}</div>
    ),
    TableHeadCell: ({ children }) => <div className="tcol">{children}</div>,
    TableBodyRowContainer: ({ children, onClick }) => (
        <div className="trow entry" onClick={onClick}>
            {children}
        </div>
    ),
    TableBodyContainer: ({ children }) => <div>{children}</div>,
    TableCell: ({ children }) => <div className="tcol">{children}</div>,
    PaginationContainer: ({ children }) => (
        <div className="table-pagination">
            <div className="table-pagination-controls">{children}</div>
        </div>
    ),
    PaginationButton: ({ children, isActive, onClick, disabled }) => (
        <a
            className={`pagination-btn${isActive ? ' active' : ''}${disabled ? ' disabled' : ''}`}
            onClick={onClick}
        >
            {children}
        </a>
    ),
};

export const MySubmissionGrid = ({ id }: { id: string }) => {
    return (
        <SubmissionGrid
            onSubmissionClick={(id) =>
                console.log(`Submission with id ${id} clicked!`)
            }
            components={components}
            formId={id}
        />
    );
};

const domNode = document.getElementById('root');
const root = createRoot(domNode);

root.render(
    <FormioProvider projectUrl="https://examples.form.io">
        <MySubmissionGrid id="57aa1d2a5b7a477b002717fe" />
    </FormioProvider>,
);
```

## 模块

模块包含Redux动作,还原器,常数和选择器来简化对形式.io表单的API请求. 减少器、动作和选择器都有名字。 这提供了命名空间,所以相同的动作和还原器可以在同一redux状态内被再用.

### 根号

根模块是其他模块,如所选的Root选择器共享的事物的容器.

#### 选择器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `selectRoot` | 名称:字符串,状态:对象 | 返回命名空间的状态. |
| `selectError` | 名称:字符串,状态:对象 | 返回命名空间的任何错误. |
| `selectIsActive` | 名称:字符串,状态:对象 | 返回为命名空间的有效状态. |

### 认证

认证模块旨在方便用户在反应内使用表单.io登录系统进行登录,注册和认证.

#### 递减器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `auth` | 配置:对象 | 将用户和访问信息挂载到状态树上。 配置目前没有使用,而是一个占位符,使其与其他还原符一致. |

#### 行动

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `initAuth` |  | 这通常在应用程序代码的开头使用. 它将检查本地Storage是否有一个用户代号,如果找到,请登录,并获取用户所需的信息. |
| `setUser` | 用户:对象 | 当用户登录时, 这将设置用户并获取该用户的访问信息 。 用户对象通常是来自登录或注册表的提交. |
| `logout` |  | 此动作会将全部重置到默认状态,包括去除任何本地Storage信息. |

### 表单

形式模块用于与单一形式互动.

#### 递减器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `form` | 配置:对象 | 将形式挂到州树上. 配置对象应当包含一个名称属性,为redux状态定义一个独有的名称. |

#### 行动

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `getForm` | 名称:字符串, id: 字符串, 已完成: 函数 | 从服务器获取表单 。 如果没有提供ID,则使用名称作为路径. 这个 `done` 动作完成后将调用回调 。 第一个参数是任意错误,第二个是形式定义. |
| `saveForm` | 名称:字符串,形式:对象,完成:函数 | 向服务器保存窗体 。 它会使用表格上的 id 属性来保存, 如果它存在的话 。 否则,它将创造出一种新的形式。 这个 `done` 动作完成后将调用回调 。 第一个参数是任意错误,第二个是形式定义. |
| `deleteForm` | 名称:字符串, id: 字符串, 已完成: 函数 | 用 ID 删除服务器上的窗体 . |
| `resetForm` | 将这个还原器重置回初始状态 。 这在删除后自动调用, 但也可以调用其他时间 . |  |

#### 选择器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `selectForm` | 名称:字符串,状态:对象 | 从状态中选择窗体定义. |

### 表单

形式模块处理多种形式,如形式列表.

#### 递减器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `forms` | 配置:对象 | 把表格挂到州树上 配置对象应当包含一个名称属性,为redux状态定义一个独有的名称. 配置对象也可以包含一个查询属性,该属性被添加到所有表格请求中. 例如: {tags:'common'} 将表格列表限制在只标有"common"的表格 . |

#### 行动

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `getForms` | 名称:字符串,页面:整数,参数:对象 | 从服务器获取表格列表 . `params` 是过滤窗体的查询对象. |
| `resetForms` | 将这个还原器重置回初始状态 。 这在删除后自动调用, 但也可以调用其他时间 . |  |

#### 选择器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `selectForms` | 名称:字符串,状态:对象 | 从状态中选择表格列表. |

### 提交日期

提交模块用于与单一提交书互动.

#### 递减器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `submission` | 配置:对象 | 将呈文挂入州树. 配置对象应当包含一个名称属性,为redux状态定义一个独有的名称. |

#### 行动

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `getSubmission` | 名称:字符串, id: 字符串, 窗体Id: 字符串, 已完成: 函数 | 从服务器获取提交文件 。 这个 `done` 动作完成后将调用回调 。 第一个参数是任何错误,第二个参数是提交. |
| `saveSubmission` | 名称:字符串,提交:对象,窗体Id:字符串,完成:函数 | 保存提交到服务器 。 它会使用提交文件中的 id 属性来保存,如果它存在的话 。 否则,它将产生新的呈文。 这个 `done` 动作完成后将调用回调 。 第一个参数是任何错误,第二个参数是提交. |
| `deleteSubmission` | 名称:字符串, id: 字符串, 窗体Id: 字符串, 已完成: 函数 | 用 ID 删除服务器上的提交 . |
| `resetSubmission` | 将这个还原器重置回初始状态 。 这在删除后自动调用, 但也可以调用其他时间 . |  |

#### 选择器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `selectSubmission` | 名称:字符串,状态:对象 | 从状态中选择提交数据. |

### 提交的材料

提交书模块处理多种提交书的形式,如提交书清单.

#### 递减器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `submissions` | 配置:对象 | 将提交文件上载到状态树上。 配置对象应当包含一个名称属性,为redux状态定义一个独有的名称. |

#### 行动

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `getSubmissions` | 名称:字符串,页面:整数,参数:对象,窗体Id:字符串 | 从服务器获取提交列表 . `params` 是过滤提交文件的查询对象. |
| `resetSubmissions` | 将这个还原器重置回初始状态 。 这在删除后自动调用, 但也可以调用其他时间 . |  |

#### 选择器

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `selectSubmissions` | 名称:字符串,状态:对象 | 选择来自状态的提交列表 . |

## 许可证

释放 [MIT 许可证](http://www.opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @formio/react 是什么？

形式\.io形式的反射渲染器\.

### 如何安装 @formio/react？

在项目目录运行 npm install @formio/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17）、react-dom（\>=17）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @formio/react 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/formio\_\_react 是否存在。

### @formio/react 支持 ESM 还是 CommonJS？

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

### @formio/react 可以商用吗？

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

### @formio/react 的下载量有多少？

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

### @formio/react 还在维护吗？

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