# @doany-ai/forms 中文文档

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

版本：0\.2\.3
npm 元数据更新时间：2026-11-13T03:30:04.384Z
中文译文更新时间：2026-11-13T03:42:09.628Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：68.3 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0，@doany-ai/sdk ^0\.3\.0-alpha\.2 \|\| ^0\.4\.0 \|\| ^0\.5\.0，@doany-ai/app-core ^0\.2\.3，@tanstack/react-query ^5\.0\.0
- 首次发布：2026-10-09T06:32:41.590Z
- 最新版本发布：2026-11-13T03:30:04.093Z
- 近 30 天下载量：2623（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

企业在 Doany 站点上的表单: 格式钩和默认组件, 生成表单的问题并提交答案

## 安装

```sh
npm install @doany-ai/forms
```

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

## README

# @ doany-ai/ 窗体

企业在多亚尼网站的表格:联系,询问,订阅,申请,问答. 企业界定了一种表格(它提出的问题、它询问的服务、随后显示什么);网站制作并提交访客填写的内容。 一份呈文在企业的收件箱里 这里什么也没有创造出形式.

```jsx
import { Form } from "@doany-ai/forms";

// /contact — the form by its id, as the business defined it
<Form formId="…" context={{ page_path: "/contact" }} />
```

列出页面 `doany/features.jsonc` 下级 `forms`。 。 。 .

## 记录

-   **窗体视图** (单位:千美元)`useForm`: `id`, (中文(简体) ), `type` (单位:千美元)`contact` | `inquiry` | `subscription` | `promotion` | `application` | `quiz` | `custom…`, (中文(简体) ), `definition_hash` (你应当叙述)他们所见的, `definition` (单位:千美元)`title`, (中文(简体) ), `description`, (中文(简体) ), `fields[]`, (中文(简体) ), `settings`, (中文(简体) ), `availability` (单位:千美元)`can_submit`, (中文(简体) ), `reason`数字 : `preview_only` 平台不提交(地址不是网站), `example_only` 对于软件包的例子, `no_service_options` (一) 所需服务问题无任何可提供时), `livemode` (单位:千美元)`false` 在网站编辑器中:有测试的提交.
-   **表单字段**数字 : `key`, (中文(简体) ), `type`, (中文(简体) ), `label`, (中文(简体) ), `help`, (中文(简体) ), `required`, (中文(简体) ), `control` (单位:千美元)`radio` | `dropdown` 选择权; `hidden` 编号 `service` (d) 问题,然后没有用它提供的服务来显示和回答, `validation` (单位:千美元)`min_length`, (中文(简体) ), `max_length`, (中文(简体) ), `min`, (中文(简体) ), `max`, (中文(简体) ), `after_field`, (中文(简体) ), `options[]` (单位:千美元)`value`, (中文(简体) ), `label`, (中文(简体) ), `selection` 财务报告和审定财务报表 `resolved_options[]` (单位:千美元)`service` 问题:提供的服务, `service_mode` `booking` | `order` | `inquiry`, (中文(简体) ), `consent` (单位:千美元)`mode` `checkbox` | `on_submit`) (中文(简体) ).
-   字段类型 : `text`, (中文(简体) ), `textarea`, (中文(简体) ), `email`, (中文(简体) ), `phone`, (中文(简体) ), `number`, (中文(简体) ), `date`, (中文(简体) ), `select`, (中文(简体) ), `multiselect`, (中文(简体) ), `checkbox`, (中文(简体) ), `scale`, (中文(简体) ), `agreement`, (中文(简体) ), `consent`, (中文(简体) ), `hidden`, (中文(简体) ), `statement`, (中文(简体) ), `service`。 。 。 .
-   **格式缩写** (单位:千美元)`useSubmitForm`: `id`, (中文(简体) ), `submitted_at`, (中文(简体) ), `score` 财务报告和审定财务报表 `outcome` (考试), `completion` (表单的) `thank_you_message`, (中文(简体) ), `redirect_url`, (中文(简体) ), `cta`) (中文(简体) ).

## `Form`

将问题渲染,提交答案,显示表格集的确认(或一个测试的结果),当表格中说到时重定向.

| 道具 |  |
| --- | --- |
| `formId` | 所需经费 |
| `context` | `{ page_path?, referrer?, utm?, language?, timezone?, source_service_id? }`,保留在呈件中 |
| `defaultAnswers` | 按字段键开头的答案(a) `hidden` 值,预选服务) |
| `submitLabel` | 胜过 `submit` 标签 |
| `renderSuccess` | `(receipt) => node`: 替换确认 |
| `showTitle` | 表格的标题和问题上的描述; 默认 `true` |
| `variant` | `"single"` (默认):每页上的问题. `"steps"`:页中的问题,有进步栏和Back / Next——一项调查。 这些页面是: `steps` 如果给出,则每页增加一页 `statement` 问题(声明首页),另一页。 每页都有问题门 |
| `steps` | 页:1 `variant="steps"`: 每页的字段密钥, 按顺序排列; 在最后一页被忽略的密钥 |
| `frame` | `"plain"` (默认):只是问题. `"card"`:在升起的牌上,表格嵌入一页的方式 |
| `onSubmitted` | `(receipt) => void` |
| `labels`, (中文(简体) ), `className` |  |

答案按字段键到平台:文本、日期和单项选择作为字符串,若干选择作为数组, `checkbox` 编号 : `agreement` 编号 : `consent` 如布尔,数字为数字;空白被忽略。 A 类 `consent` 与 `mode: "on_submit"` 表格提交时按协议发送.

两个约会问题,设定 `validation: { "after_field": "arrival" }` 关于形式定义中的离开问题。 如果两者都得到答复,离开必须严格晚于抵达. `Form` 在提交前检查对子,包括问题在不同步骤时,并显示 `dateAfterField(earlierLabel)` 在后来的问题之下。 平台检查所有提交文件的相同规则。 用每个问题 `required` 如果两个答案都是强制的,则使用标记.

一个可能空白的问题说 `Optional` 在其标签行的末尾; 需要问的问题无所取用(商家应用惯例). 所需 `text`, (中文(简体) ), `textarea`, (中文(简体) ), `email` 或者说 `phone` 问题一旦修剪显示即为空白 `answerRequired` 并集中精神。 无效的电话和电子邮件格式显示 `phoneFormat` 财务报告和审定财务报表 `emailFormat` 同样的方式。 接下来是脚踏实地的表格,在前进前检查它的页面。 电子邮件仍然使用浏览器的电子邮件格式检查,浏览器检查其余的本土限制. 田园是 `@doany-ai/app-core/form`'s,与预订表共享:一个电子邮件问题显示一个信封和一个实例地址;一个电话问题被打成一个国家后面的本地号码,显示为它的旗帜和呼叫代码(芯片打开一个可以搜索的列表,首先是美国,然后从开始;一个数字用自己的号码输入) `+` 或者说 `00` 以E.164格式发送.

在网站编辑器中,文件被保存为 **测试** (docs/specs/preview-test-records.md):它在企业的收件箱中显示有测试标记,没有给任何人签名,也没有接触到客户端. 表格本身的外观和发送方式与公布的网站(收据)完全相同 `livemode` 实值 `false`); 编辑说在页面上保存的东西.

平台未提交文件(`availability.reason` `preview_only`,或者例子' `example_only`),在问题之前出现通知. 来访者可以填写答案,验证答案,并浏览每页的已加附表格. 最终行动在当地检查,保留答案,不提交;它从来不打电话 `onSubmitted`,使成功接收或跟踪完成重定向。 一个后端 `INVALID_STATE` 与 `details.reason="preview_only"` 如果页面的可用性较旧,处理方式相同。 需要的服务问题,没有选项,仍然无法提交.

失败 : `VERSION_CONFLICT` (问题同时被改变) 重新阅读表格,并说是这样; `RATE_LIMITED` 请求等待; a `VALIDATION_ERROR` 谁 `details.errors[].field` 询问访客姓名(`answers.<key>`在它下面说`answerRequired` 或者说 `answerInvalid`),在其页面上;其他任何显示网站的 `submitFailed` 标签设定时, 否则平台的信息 .

将窗体放入弹出、侧边栏或滑入面板中,将其包入 `Embed` 从 `@doany-ai/app-core/ui`;内部, `useEmbed().markSubmitted()` 财务报告和审定财务报表 `close()` 告诉贝壳 访客结束了.

## 钩子

| 钩子 | 返回时 |
| --- | --- |
| `useForm(formId)` | 查询 `FormView` |
| `useSubmitForm(formId)` | 变异: `mutate({ definition_hash, answers, context? })` → `FormSubmitReceipt` |

## 标签

`submit`, (中文(简体) ), `submitting`, (中文(简体) ), `thanks`, (中文(简体) ), `score(score)`, (中文(简体) ), `loading`, (中文(简体) ), `loadError`, (中文(简体) ), `submitFailed`, (中文(简体) ), `previewOnly`, (中文(简体) ), `previewChecked`, (中文(简体) ), `noServiceOptions`, (中文(简体) ), `definitionChanged`, (中文(简体) ), `rateLimited`, (中文(简体) ), `tryAgain`, (中文(简体) ), `notFound`, (中文(简体) ), `choose`, (中文(简体) ), `optional`, (中文(简体) ), `emailPlaceholder`, (中文(简体) ), `emailFormat`, (中文(简体) ), `dateAfterField(earlierLabel)`, (中文(简体) ), `country`, (中文(简体) ), `searchCountry`, (中文(简体) ), `noCountry`, (中文(简体) ), `phoneFormat`, (中文(简体) ), `answerRequired`, (中文(简体) ), `answerInvalid` (单位:千美元)`required` 用于设置它的地点,未使用. `loading` 在形式加载时用骨架出现。 问题本身的词出自表格的定义.

## 自定义

1.  **主题**:站点的变量样式为输入,按钮和确认.
2.  **道具**数字 : `labels`, (中文(简体) ), `submitLabel`, (中文(简体) ), `renderSuccess`, (中文(简体) ), `defaultAnswers`, (中文(简体) ), `className`。 。 。 .
3.  **钩子**: 自己绘制表格 `useForm` 财务报告和审定财务报表 `useSubmitForm`。 。 。 .

在表格中,每个问题都是其标签、字段、帮助文本和错误信息(a) `<p>` 在字段下,在拒绝答复时显示 `<button>`s. 关于这些要素的站点规则,或在包装上对这些要素的站点规则(`.contact p`中,也重新样式:见自定义 `@doany-ai/app-core`。 。 。 .

没有CSS的包裹船:该地的Tailwind所建扫描 `node_modules/@doany-ai/forms/dist`。 。 。 .

## 4个可循环用途

官方的例子与这个软件包同在 `@doany-ai/forms/examples`数字 :

```jsx
import { FormExample } from "@doany-ai/forms/examples";

<FormExample mode="default" />
<FormExample mode="css" />
<FormExample mode="props" />
<FormExample mode="hook" />
```

`mode` 默认为 `default`。每个都挂载一个私人 `DoanyProvider` 查询 缓存,读取相同的三地接触固定,并保存自己的答案. 它从不使用附件提供者的连接客户端.

-   **默认 :** 实际数 `Form` 及其本地预览验证.
-   **CSS: 请检查DATE=中的日期值 (帮助) CSS:** 不变 `Form` 道具;只有范围主题变量改变. 没有 生成样式表或复制字段样式。 这些例子没有门户; 一个真实的网站的全球主题属于 `:root`。 。 。 .
-   **道具 :** 使用卡片、两个步骤和自定义按钮/进度标签 `Form`。 。 。 .
-   **钩:** 使用 `useForm`, (中文(简体) ), `useSubmitForm` 变异状态和辅助核心控制。 本地字段检查电子邮件 语法和长度; 示例检查修剪需要值。 它支持 只有这个固定, 从来没有打电话 `mutate`一般性问题, 勘测导航和连接提交仍在 `Form`。 。 。 .

`formExampleView` 财务报告和审定财务报表 `createFormExampleClient()` 也被导出。 客户 返回其本地表格 ID 的新副本,拒绝提交 `INVALID_STATE` 编号 : `example_only`,并拒绝不相关的账户/上载操作 与 `EXAMPLE_ONLY`。它不提出网络请求或真正的提交,永远不会 生成收据,而不遵循完成重定向。 使用网站的 SDK客户端和连接窗体的主包条目.

## 开发

```bash
npm install
npm run typecheck   # includes tests/sdk-contract.types.ts
npm test
npm run build
```

本地降级使用 App-core 的 `NativeSelect`,并带有左向的文本和一个内置箭头。 日期字段将浏览器的取日期器保留在正确的边缘 。 这些控制要求 `@doany-ai/app-core` 0.2.3或后入0.2系列.

## 常见问题

### @doany-ai/forms 是什么？

企业在 Doany 站点上的表单: 格式钩和默认组件, 生成表单的问题并提交答案

### 如何安装 @doany-ai/forms？

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

### @doany-ai/forms 支持 TypeScript 吗？

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

### @doany-ai/forms 支持 ESM 还是 CommonJS？

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

### @doany-ai/forms 可以商用吗？

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

### @doany-ai/forms 的下载量有多少？

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

### @doany-ai/forms 还在维护吗？

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