# @fillout/react 中文文档

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

版本：3\.1\.2
npm 元数据更新时间：2026-04-20T23:17:39.602Z
中文译文更新时间：2026-11-14T17:58:21.019Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fillout/react
原文对照：https://npmcn.com/package/%40fillout/react/?lang=original

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

- 包体积（解压后）：63.7 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.0 \|\| ^19\.0 \|\| ^19\.0\.0-rc，react-dom ^18\.0 \|\| ^19\.0 \|\| ^19\.0\.0-rc，@types/react \*，@types/react-dom \*
- 首次发布：2023-10-16T16:01:29.913Z
- 最新版本发布：2026-04-10T06:49:43.253Z
- 近 30 天下载量：94081（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 2 个）

## 中文简介

在您的 React 工程中嵌入填充表单

## 安装

```sh
npm install @fillout/react
```

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

## README

# 填充反应嵌入

嵌入 [填充数](https://fillout.com/) 在反应项目中直接显示窗体。 类型脚本包含, 没有依赖性 :)

_提示:如果你想在节点.js中使用填充API,请尝试 [@ fillout/ api](https://npmjs.org/package/@fillout/api)来啊!_

-   [设置](https://npmcn.com/package/%40fillout/react/#readme-setup)
-   [嵌入组件](https://npmcn.com/package/%40fillout/react/#readme-embed-components)
    -   [标准嵌入](https://npmcn.com/package/%40fillout/react/#readme-standard-embed)
    -   [完全嵌入](https://npmcn.com/package/%40fillout/react/#readme-fullscreen-embed)
    -   [弹出已嵌入](https://npmcn.com/package/%40fillout/react/#readme-popup-embed)
    -   [嵌入滑动器](https://npmcn.com/package/%40fillout/react/#readme-slider-embed)
    -   [弹出和滑动嵌入按钮](https://npmcn.com/package/%40fillout/react/#readme-popup-and-slider-embed-buttons)
-   [倾听形式事件](https://npmcn.com/package/%40fillout/react/#readme-listening-for-form-events)
-   [自定义域](https://npmcn.com/package/%40fillout/react/#readme-custom-domains)

## 设置

安装方式 `npm i @fillout/react`

## 嵌入组件

每个嵌入类型都有组件。 他们都要求 `filloutId` 道具,这是你的形式。 这个代码很容易在编辑器的url或活的形态中发现,例如, `forms.fillout.com/t/foAdHjd1Duus`。 。 。 .

所有嵌入组件允许您使用可选选项通过 URL 参数 `parameters` 道具,也可以使用 `inheritParameters` 使窗体继承主机页面url中的参数.

### 标准嵌入

这个很简单.

```js
import { FilloutStandardEmbed } from "@fillout/react";

function App() {
  return (
    <div
      style={{
        width: 400,
        height: 400,
      }}
    >
      <FilloutStandardEmbed filloutId="foAdHjd1Duus" />
    </div>
  );
}

export default App;
```

如果你不愿手动设置嵌入高地,而是将其扩展到形式大小,使用 `dynamicResize` 道具 (英语).

### 完全嵌入

这个 `FilloutFullScreenEmbed` 组件填充整个页面,由 `position: fixed`。 。 。 .

```js
import { FilloutFullScreenEmbed } from "@fillout/react";

function App() {
  return <FilloutFullScreenEmbed filloutId="foAdHjd1Duus" inheritParameters />;
}

export default App;
```

### 弹出已嵌入

此组件创建了弹出, 黑暗的背景覆盖了后面的页面内容 。 与"FullScreen"嵌入不同,它可以使用关闭按钮来关闭,也可以在弹出器外点击来关闭.

![popup screenshot](https://prod-fillout-oregon-s3.s3.us-west-2.amazonaws.com/orgid-9948/flowpublicid-foAdHjd1Duus/0d232c8c-d352-44de-91ab-ee829ab70418-fko1grlyaYLFEpwi1s8ixBBZeQ3ou2d4vLiQVfriYxIctfeRRYTqzyQzuZZ57YEOp4oxRoIoF4dK33X6bV7Re6mLKDLCSVvFz3z/popup.png)

你用自己的状态来控制它 这个 `isOpen` 财务报告和审定财务报表 `onClose` 需要道具.

```js
import { useState } from "react";
import { FilloutPopupEmbed } from "@fillout/react";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Schedule a call</button>

      <FilloutPopupEmbed
        filloutId="foAdHjd1Duus"
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      />
    </>
  );
}

export default App;
```

### 嵌入滑动器

与弹出嵌入式相似,此功能将和您自己的按钮和状态一起使用, 因此组件需要 `isOpen` 财务报告和审定财务报表 `onClose` 道具来. 窗体会从屏幕一侧滑出. 您可以控制它来自哪个方向 `sliderDirection`,这可以是 `left` 或者说 `right` (默认).

![slider screenshot](https://prod-fillout-oregon-s3.s3.us-west-2.amazonaws.com/orgid-9948/flowpublicid-foAdHjd1Duus/d3cf14e2-a6a1-4ca1-8670-7763e7a20ae0-SkWcSu1ZFm0ecjxVQxdb3kEgtDW5s5SE9LreXH2DT7AAqhO3QkLO5b0Ls61ouUPz7l1iog9KR4Diuwfrwv21YHDks84IxWuRDPN/slider.png)

```js
import { useState } from "react";
import { FilloutSliderEmbed } from "@fillout/react";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Schedule a call</button>

      <FilloutSliderEmbed
        filloutId="foAdHjd1Duus"
        inheritParameters
        parameters={{
          example: "abc",
        }}
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        sliderDirection="left"
      />
    </>
  );
}

export default App;
```

### 弹出和滑动嵌入按钮

如果您不愿自行管理弹出或滑动的开放状态, 请使用 `FilloutPopupEmbedButton` 或者说 `FilloutSliderEmbedButton`。这会使一个按钮在点击时打开嵌入层。 这些部件采用与独立对应设备相同的道具(除 `isOpen` 财务报告和审定财务报表 `onClose`),但拥有一些额外的可选道具来自定义按钮.

-   `text` - 更改按钮文本
-   `color` - 更改按钮背景颜色。 只要您指定了十六进制代码,文本颜色就会自动与它相对应.
-   `size` - 小型、中型或大型
-   `float` - 让你的按钮浮上屏幕. `bottomLeft` 或者说 `bottomRight`。 。 。 .

```js
import { FilloutSliderEmbedButton } from "@fillout/react";

function App() {
  return (
    <FilloutSliderEmbedButton
      filloutId="foAdHjd1Duus"
      inheritParameters
      parameters={{
        example: "abc",
      }}
      sliderDirection="left"
      text="Schedule a call"
      color="#444444"
      size="small"
      float="bottomRight"
    />
  );
}

export default App;
```

需要更多控制按钮外观的,只需自行制作并结合独立嵌入组件一起使用.

## 倾听形式事件

您可以使用 `onInit`, (中文(简体) ), `onPageChange` 财务报告和审定财务报表 `onSubmit` 道具来. 其中每一个都给出了提交UUID作为第一个参数,以及 `onPageChange` 道克给出了页面ID作为第二个参数.

```js
import { FilloutStandardEmbed } from "@fillout/react";

function App() {
  return (
    <FilloutStandardEmbed
      filloutId="4SVaJQNVdrus"
      dynamicResize
      onInit={(submissionUuid) => {
        console.log(
          `User started filling out the form (submission ID: ${submissionUuid})`
        );
      }}
      onPageChange={(submissionUuid, pageId) => {
        if (pageId === "qTcp") {
          console.log("User is on the review step");
        }
      }}
      onSubmit={async (submissionUuid) => {
        const email = await doSomethingOnYourServer(submissionUuid);
        console.log(`${email} finished filling out the form`);
      }}
    />
  );
}

export default App;
```

这可以结合 [@ fillout/ api](https://npmjs.org/package/@fillout/api) 软件包,以获取关于窗体结构的信息,并在获得提交UUID后获取字段值.

> {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 `onPageChange` 可能为窗体上的任何一页所触发,包括嵌入第一负载时的起始页。 您应该总是检查页面ID, 而不是仅仅因为函数被触发而假设用户在表格中的位置 .

## 自定义域

如果您想利用只有自有域内格式才能提供的特性,例如定制JS,你可以使用 `domain` 改变嵌入式url的道具.

```js
import { FilloutFullScreenEmbed } from "@fillout/react";

function App() {
  return (
    <FilloutFullScreenEmbed filloutId="foAdHjd1Duus" domain="example.com" />
  );
}

export default App;
```

## 常见问题

### @fillout/react 是什么？

在您的 React 工程中嵌入填充表单

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

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

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

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

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

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

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

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

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

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

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

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