文档/代码示例
配合你的技术栈

接入你的表单

选择技术栈和防护状态,再替换占位值。工作区表单页的“连接你的网站”会提供与你实际配置匹配的代码。

查看完整示例

网站的垃圾信息防护

此版本无需 Turnstile。保留 _intent_id 和 saved: true 判断:同一消息重试沿用 intent,只有确认保存或明确开始新消息时才更新。

<form data-fi-form action="https://formpostbox.com/f/YOUR_FORM_ID" method="post">
  <label>
    Email
    <input type="email" name="email" autocomplete="email" maxlength="254" required />
  </label>
  <label>
    Message
    <textarea name="message" maxlength="5000" required></textarea>
  </label>
  <input type="hidden" name="_intent_id" value="" />
  <button type="submit">Send message</button>
  <button type="reset">New message</button>
</form>
<script>
(() => {
  const form = document.currentScript?.previousElementSibling;
  if (!(form instanceof HTMLFormElement)) return;
  const intent = form.elements.namedItem("_intent_id");
  if (!(intent instanceof HTMLInputElement)) return;
  let sending = false;
  const status = document.createElement("p");
  status.setAttribute("role", "status");
  form.append(status);
  const clearFields = () => {
    form.querySelectorAll("input:not([type=hidden]), textarea, select").forEach((field) => {
      if (field instanceof HTMLInputElement && ["button", "submit", "reset", "image"].includes(field.type)) return;
      if (field instanceof HTMLInputElement && (field.type === "checkbox" || field.type === "radio")) field.checked = false;
      else if (field instanceof HTMLSelectElement) field.selectedIndex = -1;
      else if (field instanceof HTMLInputElement || field instanceof HTMLTextAreaElement) field.value = "";
    });
  };
  const startNewMessage = () => {
    intent.value = crypto.randomUUID();
  };
  form.addEventListener("reset", (event) => {
    // Prevent the native reset from clearing the newly generated intent.
    event.preventDefault();
    if (sending) return;
    clearFields();
    startNewMessage();
    status.textContent = "";
  });
  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    if (sending) return;
    // A network retry reuses this intent; only a new message rotates it.
    sending = true;
    form.querySelectorAll("button").forEach((button) => { button.disabled = true; });
    status.textContent = "Sending…";
    try {
      const payload = Object.fromEntries(new FormData(form).entries());
      const result = await fetch(form.action, {method: "POST", body: JSON.stringify(payload), headers: {"Content-Type": "application/json", Accept: "application/json"}});
      const body = await result.json().catch(() => null);
      if (result.status === 409 && body?.error === "conflict") {
        status.textContent = "This message conflicts with an earlier submission. Restore the original content to retry, or choose New message to start again.";
        return;
      }
      if (body?.saved === false) {
        status.textContent = "Message was not saved. Try again.";
        return;
      }
      if (!result.ok || !body?.saved) {
        status.textContent = "Could not confirm saving. Retry the same message.";
        return;
      }
      status.textContent = "Message saved.";
      clearFields();
      startNewMessage();
    } catch {
      status.textContent = "Could not confirm saving. Retry the same message.";
    } finally {
      sending = false;
      form.querySelectorAll("button").forEach((button) => { button.disabled = false; });
    }
  });
  startNewMessage();
})();
</script>

先选择与你的网站一致的防护状态。关闭防护时只替换表单 id;开启防护时需要两个占位符——YOUR_FORM_ID 和 YOUR_TURNSTILE_SITE_KEY——所以它们是参考资料,照原样还不能运行。每个示例都会把带 name 的字段(包括 _intent_id 和受保护网站所需的 cf-turnstile-response)提交到你的表单地址。

要获取与你表单匹配的代码,请在工作区打开表单并选择 连接你的网站。未开启防护版本会省略 widget、Turnstile 脚本、响应字段和令牌检查;请直接使用生成的代码,不要从这里的受保护示例中自行删除代码。本页两种版本都使用相同的保存与重试规则。

使用工作区生成的示例

配置好允许来源后,从你的表单页面复制。Turnstile 防护是可选的;开启防护时,永远不要把私密密钥放进前端代码——那里只应该出现公开的站点密钥。配置 Turnstile →

按防护状态替换所需值

  • YOUR_FORM_ID — 你的表单 id,显示在表单页面和生成的代码中。它看起来像 7f3c5b12-6db4-4f9a-91cb-7f5c5b7f8a31。只替换这一部分,并保持 https://formpostbox.com/f/ 原样:那是 FormPostbox 的提交地址,不是你网站的地址。
  • YOUR_TURNSTILE_SITE_KEY — 仅开启防护时需要:你 Turnstile widget 的公开站点密钥,与你在“网站 → 垃圾信息防护”中保存的值相同。它以 0x 开头。永远不要把私密密钥粘贴到这里。

三个地址,三项不同的工作

  • 提交地址 — https://formpostbox.com/f/YOUR_FORM_ID。放进表单的 action。它始终在 formpostbox.com 上;只有表单 id 会变化。
  • 允许的来源 — https://www.example.com。保存在你网站的 FormPostbox 设置中。表单运行的确切来源:协议、主机名和端口,不含路径。
  • Widget 主机名 — www.example.com。保存在你的 Cloudflare Turnstile widget 中。只填主机名,不含协议、端口或路径。

允许来源始终必须与你的网站匹配。开启防护时,widget 主机名也必须匹配;Turnstile 设置指南会并排介绍这两项设置。

把代码放到你的网站上

放置位置:HTML 标记放在表单位置,脚本紧随其后;React 示例是 .tsx 组件,在页面中导入并渲染 <ContactForm />,Next.js 保留 'use client';普通 React JavaScript 项目需移除类型标注和 declare global 等类型声明。Astro 放进 ContactForm.astro 并在页面引用。选择开启防护时才需要 Turnstile。

  • HTML — 把表单标记粘贴到表单应该出现的位置,并让脚本紧随其后:脚本会找到它上方的表单。每个字段都带 name 属性,被保存的正是这些带 name 的字段。
  • React — 保留 'use client' 指令:这个组件在浏览器中运行,只有开启防护的版本才会挂载 Turnstile。把它引入你的页面,渲染在表单应该出现的位置。
  • Astro — 保留 frontmatter 常量和 is:inline 脚本:Astro 会原样输出标记,脚本在浏览器中运行同一套表单生命周期。

三种用法的共同要点:只有开启防护时才需要由 widget 生成 Turnstile 令牌,不能写死;未开启防护的版本无需 widget 或令牌。_intent_id 在表单加载时创建,网络重试会复用它;新消息则一切重来——清空字段、生成新的 intent,只有开启防护时才重新验证。用大白话说:如果发送失败,再次点击 发送消息 会重试同一条消息,不会重复保存;一旦保存成功,表单会自动清空并准备好下一条消息,你可以立刻继续填写。想清空当前字段重新开始时,用 新消息。

检查你的第一条提交

从允许的网站发送一条测试,然后打开收件箱。确认消息已保存,并查看它独立的通知状态。

仍需帮助?联系 support@formpostbox.com. 请附上相关文档主题和脱敏后的错误信息,不要发送密钥或访客消息。

浏览全部主题 ↑