# 表单

在控制台中构建表单，发布到专属链接，并可嵌入任意页面。每次提交都会作为推送通知发送到你的手机，与 Webhook 使用相同的投递路径，因此路由、优先级和消息历史的工作方式与你已经熟悉的一致。

中间没有邮箱，也不用反复查看电子表格。

## 创建表单

**表单 → 创建。** 构建器包含五个标签页，旁边有实时预览：

| 标签页 | 内容 |
|-----|---------------|
| 字段 | 标题、引导文字、字段本身、页脚文字 |
| 设计 | 主题、颜色、字体、字号、圆角、提交按钮 |
| 设置 | 推送标题、路由、优先级、响应限制、消息 |
| 分享 | 公开链接、二维码、嵌入代码 |
| 预览 | 相同的实时预览，供窄屏幕查看 |

保存后，“分享”标签页会给出链接：`https://frms.click/<id>`。

## 字段类型

| 分组 | 类型 |
|-------|-------|
| 文本 | 短文本、长文本、邮箱、手机、数字、URL、日期 |
| 选择 | 下拉菜单、单选按钮、复选框、单个复选框（同意条款） |
| 评分 | 星级评分（1–5）、NPS（0–10） |
| 布局 | 标题、段落、分隔线 |
| 追踪 | 隐藏字段 |

每个表单最多 **30 个字段**，选择类字段最多 50 个选项。邮箱、手机、数字和 URL 字段会在浏览器和服务器端同时校验，浏览器端校验只是为了方便，服务器端校验才是真正的保障。

布局字段仅用于装饰，永远不会出现在消息中。暂不支持文件上传和付款。

### 隐藏字段

隐藏字段可将链接中的值带入消息。为其设置参数名后，URL 中的 `?utm_source=newsletter` 就会出现在通知中。点击一次即可一次性添加全部五个 UTM 参数。

嵌入表单时，会传递**宿主页面**的参数，因此营销落地页无需额外设置，就能为其自身的提交打上标记。

## 消息的样子

回答内容排在最前面，顺序与字段出现的顺序一致：

```
Name: Jane Doe
Email: jane@example.com
Rating: ★★★★☆ 4/5
Message: Do you ship to Canada?

utm_source: newsletter
Form: Contact
IP: 203.0.113.10
Submitted: 2026-09-23 14:05
```

隐藏字段、访客 IP 和时间戳位于回答之后的底部。时间戳使用你账户设置的时区。所有内容都会使用你的个人密钥加密存储，与其他消息完全一致。

## 推送标题

默认情况下，通知标题为 `Form: <form name>`。使用模板可以让标题一眼就能看出重点：

```
New lead: {Name} ({Email})
```

占位符通过**字段标签**引用字段，不区分大小写，另外可用 `{form}` 表示表单名称。回答为空的占位符会从标题中省略；如果标题内容全部为空，则使用默认标题。模板内容不会在公开页面上显示。

## Pocket Alert 徽标

已发布的表单底部会显示一个小的“Powered by Pocket Alert”链接。付费套餐用户可以在**设计 → 品牌**中将其关闭。

决定权在 API，而不在浏览器：在免费套餐中保存该标志会被重置；如果付费套餐到期，徽标会自动重新出现在公开页面上，无需你修改表单。

## 路由与优先级

表单可以指定某个应用和特定设备，并可设置从静默到紧急的优先级，与 API 的优先级相同。将级别保持为*默认*，表单就会遵循你正常的投递规则。

每次提交都会消耗每日上限中的一条消息。当上限用完后，访客会看到一条中性的“请稍后再试”提示，不会提及你的套餐，而你会收到常规的上限邮件。

## 关闭表单

有三个相互独立的开关，任意一个开启即可关闭表单：

- **接受回复**：关闭后立即停止接收
- **回复上限**：提交达到 N 次后关闭；在创建消息之前就会预留名额，因此突发流量不会超出上限
- **关闭时间**：按你所在时区设置的日期和时间

已关闭的表单仍可正常访问：访客看到的是你设置的关闭提示，而不是字段，服务器端也会拒绝提交。

## 嵌入

“分享”标签页提供脚本嵌入方式：

```html
<div data-pocketalert-form="<id>"></div>
<script src="https://frms.click/embed/form.js" async></script>
```

表单会在一个 iframe 中加载，并自动报告自身高度，因此不会出现内部滚动条，也无需维护固定高度。页面背景会透出来，将表单卡片颜色设为适合透明背景的色调，即可与页面融为一体。

提交后，容器会触发 `pocketalert:submit` 事件，你可以在此接入分析工具：

```js
document.querySelector('[data-pocketalert-form]')
  .addEventListener('pocketalert:submit', () => gtag('event', 'generate_lead'));
```

如果页面不允许加载脚本，也提供普通的 `<iframe>` 代码片段：高度固定，且不会传递 URL 参数。

## 限制表单的使用范围

表单 ID 是公开的，会出现在链接和二维码中，因此默认情况下任何拿到它的人都可以把表单嵌入任意页面。**设置 → 可使用的位置**可以提供域名列表来限制这一点：

- 只有这些站点可以嵌入该表单（页面会附带匹配的 `frame-ancestors` 策略）；
- 来源 `Origin`（或 `Referer`）不在列表中的提交会被以 `403` 拒绝；
- 表单自身的链接始终可用。

请填写主机名，而不是完整 URL：例如 `example.com`、`app.example.com`，`*.example.com` 表示所有子域名，开发时可填 `localhost:3000`。最多 10 条。`www.` 会被忽略，因此 `example.com` 同时覆盖 `www.example.com`。

列表为空表示“任何地方”，这适合在个人简介中分享的链接，或海报上的二维码。

> **Warning: 此功能能阻止什么，不能阻止什么**
>
> `Origin` 由浏览器设置，页面无法伪造。直接调用 API 的脚本可以发送任意请求头，因此白名单只能阻止你的表单被嵌入到他人网站上，并不能防御蓄意的刷量攻击。下文的速率限制即针对这种情况。

## 提交来源

当提交来自嵌入的表单时，宿主域名会与 IP 一同记录在消息中：

```
Form: Contact (abc123)
Source: shop.example.com
IP: 203.0.113.10
```

来自表单自身页面的提交不包含 `Source` 行。

## 垃圾信息防护

- 蜜罐字段：人类永远看不到。机器人填写该字段后会看到看似正常的成功页面，但消息不会被投递。
- 速率限制：同一 IP 每分钟最多 10 次提交，每个表单每分钟最多 60 次、每小时最多 300 次。设置小时上限是为了防止洪水攻击在几分钟内耗尽一整天的消息额度。
- 公开表单页面带有 `noindex`，因此表单不会仅因存在而出现在搜索结果中。

目前表单不需要、也未提供验证码（CAPTCHA）。

## 套餐限制

| 套餐 | 表单数量 |
|------|-------|
| 免费 | 1 |
| 入门 | 10 |
| 中级 | 30 |
| 大型 | 不限 |

提交本身仅受每日消息额度限制。

## API

构建器的所有功能都可以通过 REST API 使用：

| 端点 | 作用 |
|----------|--------------|
| [`GET /v1/forms`](https://info.pocketalert.app/api/forms/get-forms.md) | 列出你的表单 |
| [`POST /v1/forms`](https://info.pocketalert.app/api/forms/create.md) | 创建表单 |
| [`PUT /v1/forms/:tid`](https://info.pocketalert.app/api/forms/update.md) | 替换其字段、设计和设置 |
| [`DELETE /v1/forms/:tid`](https://info.pocketalert.app/api/forms/delete.md) | 删除表单 |
| [`GET /v1/forms/:tid`](https://info.pocketalert.app/api/forms/get-form.md) | 公开：获取已上线表单的字段和设计 |
| [`POST /v1/forms/:tid/submit`](https://info.pocketalert.app/api/forms/submit.md) | 公开：接收提交 |

前四个端点使用你常规的令牌；后两个是表单页面本身调用的接口。
