---
title: EmailSubscribe
description: 使用 EmailSubscribe 组件在任意文档页添加新闻通讯或更新日志订阅表单：原生支持七家服务商，其余服务商支持嵌入代码。
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`<EmailSubscribe>` 只需一个 MDX 标签，即可在文档页中内嵌电子邮件订阅表单。在仪表板中[连接服务商](/cn/integrations/email-signups)后，它会渲染由 Jamdesk 托管的表单，将新订阅者直接写入你的受众列表。未连接服务商时，也可以托管其他服务的粘贴式嵌入代码。它适用于更新日志和版本说明页面，读者可以通过它了解最新动态。

## 快速开始

先在仪表板中连接服务商，然后使用该服务商的 ID 添加标签：

```mdx
<EmailSubscribe provider="resend" />
```

此标签会渲染一个带标签的电子邮件字段和一个 Subscribe 按钮。提交后，该地址会添加到你连接的受众列表中。连接任意原生服务商（`mailchimp`、`kit`、`loops`、`beehiiv`、`brevo` 或 `sendgrid`）后，同一个标签即可使用。

添加可选标题和辅助说明：

```mdx
<EmailSubscribe
  provider="resend"
  title="Get release notes"
  description="One email when we ship something new. No spam."
/>
```

## 属性

| 属性 | 类型 | 用途 |
|------|------|---------|
| `provider` | string | 服务商 ID：`resend`、`mailchimp`、`kit`、`loops`、`beehiiv`、`brevo`、`sendgrid`、`buttondown` 或 `substack`。 |
| `title` | string | 可选标题，显示在表单上方。 |
| `description` | string | 可选辅助说明，显示在标题下方。 |
| `collapsed` | boolean | 仅适用于原生服务商。初始状态显示为紧凑的 Subscribe 按钮，点击后展开完整表单。 |
| `username` | string | Buttondown / Substack 账户用户名（仅支持嵌入的服务商）。 |
| `snippet` | string | 任意服务商的原始嵌入标记。用于特殊情况（见下文）。 |
| `className` | string | 添加到包装器的额外 CSS 类。 |

## 原生服务商与嵌入服务商

你传入的 `provider` 决定表单的行为：

- **原生服务商**（`resend`、`mailchimp`、`kit`、`loops`、`beehiiv`、`brevo`、`sendgrid`）会渲染由 Jamdesk 托管的表单。Jamdesk 会捕获地址，并通过你已连接的密钥添加该地址。这种方式需要在仪表板中[连接服务商](/cn/integrations/email-signups)。
- **仅支持嵌入的服务商**（`buttondown`、`substack`）会渲染该服务自身的表单或 iframe。无需连接密钥：你只需提供 `username`，访客会直接向该服务商提交信息。

<Note>
如果你指定了尚未在仪表板中连接的原生服务商，表单将无法捕获信息。请先连接服务商，以便提交内容有对应的接收位置。
</Note>

### 仅支持嵌入的服务商

Buttondown 和 Substack 无需连接仪表板即可使用。传入你的账户用户名：

```mdx
<EmailSubscribe provider="buttondown" username="acme" />
<EmailSubscribe provider="substack" username="acme" />
```

### 特殊情况：粘贴任意嵌入代码

如果 Jamdesk 没有为某个服务商提供简写方式，可以将其嵌入标记粘贴到 `snippet` 中。它会在发布页面上原样渲染：

```mdx
<EmailSubscribe snippet={`<form action="https://example.com/subscribe">...</form>`} />
```

<Warning>
`snippet` 会在你的页面上运行服务商自己的代码。某些服务商提供的一次性脚本，在读者未完全重新加载页面而在页面之间导航时不会再次运行。请将基于脚本的嵌入代码放在专门的、直接加载的页面（例如更新日志页面）上，而不是放在较深的导航流程中。
</Warning>

## 紧凑模式

完整的电子邮件字段加上 Subscribe 按钮，占用页面中部空间较大。设置 `collapsed` 后，原生表单初始状态会改为仅显示一个 Subscribe 按钮。读者点击后即可在当前位置展开完整字段，无需重新加载页面：

```mdx
<EmailSubscribe provider="resend" collapsed title="Subscribe to updates" />
```

按钮标签取自 `title`；如果未设置，则使用 "Subscribe to updates"。此功能仅适用于原生服务商。嵌入服务商会渲染自己的标记，因此 Jamdesk 无法将其折叠。

## 已订阅的读者

读者通过原生表单订阅后，浏览器会记住这一状态。下次访问时，他们不会看到完整表单，而是看到一行简短提示：*You're subscribed to the newsletter.* 系统不会要求已经订阅的读者再次订阅。

如果读者想添加第二个地址，该提示中会显示一个 "Use a different email?" 控件，点击后可立即重新打开完整表单。此记录按浏览器保存（存储在 `localStorage` 中，而不是你的受众列表中），因此清除网站数据或更换浏览器后，表单会再次显示。无需进行任何配置：所有原生表单都会执行此操作。

## 在更新日志页面自动放置

你无需手动将标签添加到每个版本页面，可以在更新日志页面上自动挂载表单。在 `docs.json` 中，将新闻通讯集成的 `placement` 设置为 `changelog`：

```json
{
  "integrations": {
    "newsletter": {
      "provider": "resend",
      "title": "Get release notes",
      "placement": "changelog"
    }
  }
}
```

设置 `placement: "changelog"` 后，表单会挂载到每个更新日志页面（任何包含 `rss: true` 的页面）。如需在某个页面上跳过表单，请在该页面的 frontmatter 中设置 `newsletter: false`。如果页面已经手动放置了 `<EmailSubscribe>`，自动放置会让位，因此不会出现两个表单。

完整的 `integrations.newsletter` 配置块接受与组件相同的字段（`provider`、`title`、`description`、`collapsed`、`username`、`snippet`、`height`），以及 `placement`（`none`，默认值，或 `changelog`）。

<Tip>
你不必在 `docs.json` 中设置标题和辅助说明。仪表板中的 **Email Signups** 卡片包含 Form title 和 Form subtitle 输入框；如果 `docs.json` 中未填写这些字段，自动放置的表单会使用其中的值。只有希望此站点的 `docs.json` 覆盖仪表板文案时，才需要在此处设置 `title`/`description`。
</Tip>

## 接下来做什么？

<Columns cols={2}>
  <Card title="连接服务商" icon="envelope" href="/cn/integrations/email-signups">
    设置 Resend、Mailchimp、Kit、Loops、beehiiv、Brevo 或 SendGrid
  </Card>
  <Card title="Update Component" icon="timeline" href="/cn/components/update">
    编写订阅者将要收到的更新日志条目
  </Card>
</Columns>