本文介绍如何在 react 应用中通过标准 url scheme 安全、可靠地打开 gmail 网页版的「新建邮件」界面，并自动填充收件人、主题和正文等内容，无需后端代理或 api 密钥。
本文介绍如何在 react 应用中通过标准 url scheme 安全、可靠地打开 gmail 网页版的「新建邮件」界面，并自动填充收件人、主题和正文等内容，无需后端代理或 api 密钥。
在 React 项目中实现一键跳转至 Gmail 并预填邮件内容，是一种轻量且用户友好的集成方式。Gmail 官方支持一组稳定的 mailto: 兼容 URL 参数（虽非正式文档化，但长期稳定可用），可通过 window.open() 调用 https://mail.google.com/mail/ 的特定路径实现。
以下是一个生产就绪的封装函数示例：
const openGmailCompose = ({
to = '',
cc = '',
bcc = '',
subject = '',
body = '',
}: {
to?: string;
cc?: string;
bcc?: string;
subject?: string;
body?: string;
}) => {
const params = new URLSearchParams({
view: 'cm',
fs: '1', // focus on compose (required)
...(to && { to: encodeURIComponent(to) }),
...(cc && { cc: encodeURIComponent(cc) }),
...(bcc && { bcc: encodeURIComponent(bcc) }),
...(subject && { su: encodeURIComponent(subject) }),
...(body && { body: encodeURIComponent(body) }),
});
const url = `https://mail.google.com/mail/?${params.toString()}`;
window.open(url, '_blank', 'noopener,noreferrer');
};
// 使用示例
<button onclick="{()">
openGmailCompose({
to: 'support@example.com',
subject: '订单咨询 #12345',
body: '您好，请问我的订单何时发货？\n\n谢谢！',
})
}>
通过 Gmail 联系客服
</button>
✅ 关键参数说明：
- view=cm：强制进入 compose 模式（必需）
- fs=1：确保焦点落在新窗口（提升用户体验）
- to / cc / bcc：支持多个邮箱，用英文逗号分隔（如 'a@b.com,c@d.com'）
- su：subject（已 URL 编码）
- body：纯文本内容（支持换行 \n，Gmail 会自动转为
）
⚠️ 注意事项：
- 不支持 HTML 格式正文：body 参数仅接受纯文本；富文本需用户手动编辑。
- 编码必须严格：务必使用 encodeURIComponent() 处理所有动态字段，否则空格、中文、特殊符号将导致链接失效。
- 邮箱格式需合法：to 字段若含非法字符（如未编码的 或空格），Gmail 可能静默忽略或报错。
- 浏览器兼容性：现代浏览器均支持 window.open()；Safari 在某些隐私模式下可能拦截弹窗，请确保该操作由用户显式点击触发（即不在异步回调或定时器中调用）。
- 无认证/权限要求：该方案完全前端驱动，不涉及 OAuth、Gmail API 或 CORS 问题，适合快速集成。
? 进阶建议：
- 若需更高定制性（如附件、HTML 邮件、发送日志），应切换至 Gmail REST API + OAuth2 方案；
- 可配合 useCallback 和 React.memo 封装为自定义 Hook（如 useGmailCompose），便于复用与测试；
- 建议添加降级逻辑：检测 window.open 返回 null 时提示用户检查弹窗拦截器。
该方法简洁、零依赖、符合 Web 标准，是 React 应用中连接 Gmail 最直接可靠的实践方案。
