> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 HTML 设计电子邮件

> 使用 OneSignal 的 HTML 编辑器发送完全自定义的品牌电子邮件——支持的 HTML 规则、内联 CSS、深色模式、取消订阅处理及客户端限制。

## 概述

HTML 编辑器让您使用自己的 HTML 发送完全自定义的品牌电子邮件。

您应该在以下情况下使用 HTML 编辑器：

* 需要完全控制布局、间距和样式
* 已有可投入生产的 HTML 电子邮件模板
* 熟悉电子邮件客户端限制

<Info>
  HTML 电子邮件与网页不同。许多 HTML 和 CSS 功能在电子邮件客户端中不受支持或渲染不一致。
</Info>

### 先决条件

在使用 HTML 编辑器之前，请确保您：

* 具有构建响应式 HTML 电子邮件的经验
* 在可公开访问的 URL 上托管所有图像（您的网站、CDN、S3 等）

#### 预期结果

设置后，您的电子邮件将：

* 在主要客户端（Gmail、Outlook、Apple Mail）中一致渲染
* 正确跟踪链接点击
* 包含有效的取消订阅机制
* 通过垃圾邮件和送达率检查

### 导入您自己的模板

如果您已有 HTML 电子邮件模板，可以通过以下任一方式将其添加到 OneSignal：

1. 使用[电子邮件模板转发](./email-template-forwarding)
2. 使用 [Create Template API](/reference/create-template) 程序化创建模板
3. 将 HTML 复制粘贴到 HTML 编辑器中

<Tip> 从经过验证的模板开始，而不是从头编写 HTML。</Tip>

### 在 Figma 中设计并导出到 OneSignal

如果您的电子邮件设计在 Figma 中，有两种方式可以将其作为 HTML 导入 OneSignal：

* **[Email Love](https://emaillove.com/figma-plugin)**：一款 Figma 插件，可将您的设计转换为可投入生产的 HTML 电子邮件，并直接上传到您的 OneSignal 模板。在插件的导出面板中输入您的 OneSignal App ID 和 API 密钥，然后点击上传。
* **[Figma MCP 服务器](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server)**：通过 MCP 服务器将 Figma 连接到 AI 编码工具。将其指向您的电子邮件设计框架，要求其生成 HTML 电子邮件代码，然后将输出粘贴到 HTML 编辑器中。

<Warning>
  **导致渲染或送达率问题的常见错误：**

  * **缺少取消订阅链接** — 营销电子邮件必须包含。没有取消订阅链接，收件箱提供商更容易将您的邮件标记为垃圾邮件。
  * **使用 `<style>` 块而非内联 CSS** — 大多数电子邮件客户端会删除 `<style>` 标签。请始终使用内联样式。
  * **无备用字体** — 自定义 Web 字体仅在少数客户端中加载。请始终声明系统字体备用项。
  * **图像过大** — 超过 1 MB 的电子邮件加载缓慢且可能被拦截。单张图像应在 200 KB 以下。
  * **不支持的 HTML** — JavaScript、`<iframe>`、表单和嵌入媒体会被电子邮件客户端删除。
</Warning>

***

## 使用 HTML 编辑器

创建电子邮件消息时，选择 **HTML 编辑器** 作为编辑器类型。

1. 在编辑器中粘贴或编写您的 HTML。
2. 使用**发送测试电子邮件**预览在各客户端和设备上的渲染效果。
3. 在计划或发送前修复布局问题。

<Frame caption="HTML 编辑器，包含代码输入和实时预览">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/966f520-html-editor-preheader.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=ceece56a7c1c52b3a51badea42685768" alt="HTML editor with code input and live preview" width="1300" height="1238" data-path="images/docs/966f520-html-editor-preheader.png" />
</Frame>

### 链接和跟踪

默认情况下，HTML 电子邮件启用链接跟踪。支持多链接跟踪，点击次数显示在消息报告中。

<Columns cols={2}>
  <Card title="链接" icon="link" href="./links#email">
    为电子邮件配置链接跟踪、多链接跟踪和点击分析。
  </Card>

  <Card title="深度链接" icon="arrow-up-right-from-square" href="./deep-linking">
    通过电子邮件链接将收件人路由到应用中的特定页面。
  </Card>
</Columns>

#### 取消订阅链接

所有营销电子邮件都必须包含取消订阅链接。

没有有效取消订阅选项的电子邮件更可能：

* 被标记为垃圾邮件
* 损害发件人声誉
* 被收件箱提供商拦截

<Tabs>
  <Tab title="OneSignal 的默认取消订阅链接">
    在 HTML 的任何位置（通常在页脚）包含以下占位符：

    ```html HTML theme={null}
    <a href="[unsubscribe_url]">取消订阅</a>
    ```

    点击此链接时，将取消订阅用户在 OneSignal 中的电子邮件[订阅](./subscriptions)。
  </Tab>

  <Tab title="使用自定义取消订阅页面（可选）">
    您可以链接到自己的取消订阅页面，但必须：

    * 捕获取消订阅操作
    * 更新用户的电子邮件订阅状态

    详情请参见[创建自定义取消订阅页面](./create-custom-unsubscribe-page)。

    <Warning> 如果您使用自定义取消订阅 URL 但未更新订阅，用户将继续收到电子邮件。</Warning>
  </Tab>
</Tabs>

***

## HTML 电子邮件最佳实践

### 始终使用内联 CSS

大多数电子邮件客户端会删除 `<style>` 块和外部样式表。

推荐工具：[响应式电子邮件 CSS 内联器](https://htmlemail.io/inline/)

### 深色模式样式

当启用深色模式时，许多电子邮件客户端会自动反转颜色，可能导致不可预测的结果——按钮可能显示为黑色背景和黑色文字，或徽标可能消失。请明确定义您的电子邮件在浅色和深色模式下的外观，以避免这些问题。

#### 各电子邮件客户端的深色模式行为

| 客户端                       | 行为                   | 是否支持 `prefers-color-scheme` CSS？ |
| ------------------------- | -------------------- | -------------------------------- |
| **Apple Mail**（iOS/macOS） | 完全颜色反转               | 是                                |
| **Gmail**（iOS/Android 应用） | 部分反转——更改浅色背景但不更改所有颜色 | 否                                |
| **Gmail**（Web）            | 不应用深色模式渲染            | 不适用                              |
| **Outlook**（Windows）      | 使用 Word 渲染引擎完全反转     | 否——忽略大多数 CSS 覆盖                  |
| **Outlook**（Mac/iOS）      | 部分反转                 | 是                                |
| **Yahoo Mail**            | 部分反转                 | 否                                |
| **Samsung Mail**          | 完全反转                 | 否                                |

#### 最佳实践

* **内联定义基础样式。** 始终直接在元素上设置背景色和文字色，而不是依赖默认值或透明度。
* **为深色模式使用媒体查询。** 支持 `@media (prefers-color-scheme: dark)` 的客户端（Apple Mail、Mac/iOS 上的 Outlook）允许您为深色模式覆盖样式。
* **谨慎使用 `!important`。** 为深色模式覆盖添加 `!important` 有助于防止收件箱在您的自定义样式之上叠加反转规则。
* **标示主题支持。** 在 HTML `<head>` 中包含以下元标记以减少自动反转：

```html theme={null}
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
```

* **避免纯白和纯黑。** 使用接近白色的浅色和深灰色，以减少完全反转客户端的影响。
* **谨慎使用透明 PNG。** 透明背景上的深色徽标在深色背景下会变得不可见。请添加浅色轮廓，或使用内置背景的版本。

<Note>
  有关使用拖放编辑器添加深色模式 CSS 的分步说明，请参见[使用拖放功能设置深色模式样式](./design-emails-with-drag-and-drop#dark-mode-styling-with-drag-and-drop)。
</Note>

### 推荐的电子邮件图像尺寸

<AccordionGroup>
  <Accordion title="纵横比">
    * 头部/横幅图像：`3:1` 或 `4:1`（例如，`600×200` 或 `600×150`）
    * 主图像：`16:9` 或 `2:1`（例如，`600×338` 或 `600×300`）
    * 方形图像：`1:1`（例如，`300×300`）— 适用于产品网格
    * 缩略图：`1:1` 或 `4:3`
    * 最大宽度：`600–700px` 是标准（大多数电子邮件客户端）
    * 为视网膜显示器以 `2x` 设计（例如，`1200px` 宽，显示为 `600px`）
  </Accordion>

  <Accordion title="文件大小">
    * 单张图像保持在 `100–200 KB` 以下
    * 总电子邮件大小（包括图像）在 `1 MB` 以下
    * 图像越小，加载越快，送达率越好
  </Accordion>

  <Accordion title="文件格式">
    * **JPG** — 最适合照片
    * **PNG** — 最适合图形、徽标及带透明度的图像
    * **GIF** — 用于简单动画（保持文件大小较小）
    * **WebP** — 在电子邮件中尚未得到广泛支持，建议避免使用
  </Accordion>

  <Accordion title="常规提示">
    * 始终包含 alt 文本以提高可访问性，并在图像无法加载时传达信息
    * 使用内联 CSS 进行样式设置（许多客户端会删除 `<style>` 标签）
    * 避免使用背景图像（客户端支持不一致）
    * 跨客户端测试——Gmail、Outlook 和 Apple Mail 的渲染方式各不相同
    * Outlook 经常忽略图像尺寸，因此请在 HTML 中同时设置 `width` 和 `height` 属性
  </Accordion>
</AccordionGroup>

### 为图像添加 alt 文本

Alt 文本提高可访问性，并确保即使图像被拦截或无法加载也能传达信息。大多数主要电子邮件客户端均会显示并样式化 alt 文本：

| 电子邮件客户端 | 拦截图像？ | 显示 Alt 文本 | 样式化 Alt 文本 |
| ------- | ----- | --------- | ---------- |
| AOL     | 是     | 是         | 是          |
| Gmail   | 是     | 是         | 是          |
| Yahoo   | 是     | 是         | 是          |
| Outlook | 有时    | 是         | 是          |

### 仅使用支持的 HTML

电子邮件客户端**不**支持：

* JavaScript
* `<iframe>`
* HTML 表单
* 嵌入音频或视频
* CSS 定位或分层技巧

对于交互式或多媒体内容，请使用链接到外部页面的方式。

### 发送前验证

发送前，请检查以下内容：

* 所有链接均有效（损坏的链接会影响送达率，并可能触发垃圾邮件过滤器）
* 取消订阅链接功能正常
* 测试电子邮件在 Gmail、Outlook 和 Apple Mail 中正常渲染
* 深色模式渲染效果可接受
* HTML 使用语义标签和适当缩进，以提高可访问性和可维护性

<Check> 如果您的电子邮件在主要客户端中正确渲染且取消订阅功能正常，则可以发送。</Check>

### 个性化

使用 Liquid 模板语言在 HTML 中直接插入订阅者特定内容，例如姓名、标签或备用值。示例：`{{ first_name | default: "there" }}`

<Columns cols={2}>
  <Card title="消息个性化" icon="user-pen" href="./message-personalization">
    可用的个性化变量及其使用方式。
  </Card>

  <Card title="使用 Liquid 语法" icon="code" href="./using-liquid-syntax">
    条件语句、过滤器、循环及高级 Liquid 模式。
  </Card>
</Columns>

***

## 常见问题

### 我可以重用现有的电子邮件模板吗？

可以。通过[电子邮件模板转发](./email-template-forwarding)将模板转发到 OneSignal，使用 [Create Template API](/reference/create-template) 上传模板，或将 HTML 直接复制粘贴到编辑器中。

### 我可以使用自定义字体吗？

可以，但支持程度各异。请使用 `@font-face` 声明自定义字体，并始终包含系统字体备用项。Windows 上的 Outlook 完全忽略 Web 字体，会回退到系统默认字体。

### 为什么我的电子邮件在深色模式下显示不同？

每个电子邮件客户端对深色模式的处理方式不同——有些完全反转颜色，有些部分反转，Gmail Web 版完全不应用深色模式。请参阅上方的[客户端行为表格](#各电子邮件客户端的深色模式行为)了解具体说明。建议明确定义浅色和深色模式样式以控制渲染效果。

### 电子邮件中不支持哪些 HTML 和 CSS 功能？

不支持 JavaScript、`<iframe>`、HTML 表单、嵌入音频/视频及 CSS 定位。请对所有样式使用内联 CSS——大多数客户端会删除 `<style>` 块和外部样式表。

### 我可以在电子邮件中添加"在浏览器中查看"链接吗？

OneSignal 不会生成您电子邮件的托管网页版本。要提供"在浏览器中查看"体验，请在您自己的网站上托管电子邮件内容，并添加一个指向该托管页面的标准 HTML 链接。

### 电子邮件的最大大小是多少？

总电子邮件大小（HTML + 图像）请保持在 1 MB 以下。HTML 超过 102 KB 的电子邮件会被 Gmail 截断，折叠以下的内容将隐藏在"查看完整消息"链接后面。

## 相关页面

<Columns cols={3}>
  <Card title="使用拖放功能设计电子邮件" icon="paintbrush" href="./design-emails-with-drag-and-drop">
    可视化电子邮件构建器，无需编写完整 HTML 即可设计电子邮件。
  </Card>

  <Card title="电子邮件概述" icon="envelope" href="./email-messaging">
    使用 OneSignal 发送电子邮件的端到端指南。
  </Card>

  <Card title="电子邮件模板" icon="copy" href="./templates">
    跨活动保存和重用电子邮件设计。
  </Card>

  <Card title="取消订阅链接" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    添加默认或自定义取消订阅链接以符合合规要求。
  </Card>

  <Card title="消息个性化" icon="user-pen" href="./message-personalization">
    使用标签、Liquid 语法和动态内容个性化电子邮件。
  </Card>

  <Card title="电子邮件模板转发" icon="envelope-open-text" href="./email-template-forwarding">
    将现有 HTML 电子邮件模板导入 OneSignal。
  </Card>
</Columns>