• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 拉起邮件类应用（mailto方式）
2
3## 使用场景
4
5通过mailto电子邮件协议，可以创建指向电子邮件地址的超链接，方便用户通过网页或应用中的超链接直接跳转电子邮件应用。同时，支持在`mailto:`的相关字段中定义邮件的收件人、主题、正文内容等，节省用户编辑邮件的时间。
6
7常见的应用场景举例如下：
8
9- 从网页拉起：
10    - 用户在购物网站浏览产品页面时，看到“联系我们”按钮，点击后会拉起默认邮件客户端。收件人自动填写为客服邮箱，邮件主题设定为产品咨询。
11    - 在招聘岗位页面，点击“申请职位”按钮，会拉起邮件客户端。收件人地址为招聘邮箱，邮件主题为“应聘某职位”，正文可以预先填入申请模板。
12- 从应用拉起：
13    - 移动应用中，用户点击“反馈”按钮时，应用调用系统功能，拉起默认邮件客户端，预先填写反馈邮箱、问题描述等信息。
14    - 移动应用中，当用户点击“通过邮件分享”按钮时，应用会通过 `mailto` 调用邮件客户端，预填邮件主题和正文。
15> **说明：**
16>
17> - 如果使用mailto方式拉起邮件应用，需要拉起方先按mailto格式封装字符串，再使用mailto方式拉起。邮件应用会解析收到的mailto协议字符串，并填充发件人、收件人、邮件内容等信息。
18> - 如果拉起方已知发件人、收件人、邮件内容等信息，推荐[使用startAbilityByType方式拉起邮件应用](start-email-apps.md)。
19
20## mailto协议格式
21
22mailto协议标准格式如下：
23
24```
25mailto:someone@example.com?key1=value1&key2=value2
26```
27
28+ `mailto:`：mailto scheme，必填。
29+ `someone@example.com`：收件人地址，选填。如果存在多个地址，用英文逗号分隔。
30+ `?`：邮件头声明开始符号。如果带邮件头参数，则必填。
31+ `key-value`：邮件头参数，详细参数见下表。
32
33  | 邮件头| 含义| 数据类型 | 是否必填|
34  | --- | --- | --- | --- |
35  | subject | 邮件主题 | string | 否 |
36  | body | 邮件正文 | string | 否 |
37  | cc| 抄送人，多个用逗号分隔 | string | 否 |
38  | bcc| 密送人，多个用逗号分隔 | string | 否 |
39
40特殊符号处理：
41
42如果邮件头参数值中存在特殊字符，如@、?、=、&等符号，可能导致配置不生效。建议将特殊字符替换为ASCII码，并在ASCII码前加百分号%。
43
44常用符号替换为ASCII码的对照表如下：
45
46|特殊符号 | :    | @    | ?    | =    | &    | #    | $    |
47|---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
48|替换编码 | %3A  | %40  | %3F  | %3D  | %26  | %23  | %24  |
49
50## 拉起方开发步骤
51
52### 从网页拉起
53
54网页中的超链接需要满足mailto协议。示例如下：
55
56
57```
58<a href="mailto:support@example.com?subject=Product Inquiry&body=I am interested in...">联系我们</a>
59```
60实际开发时，需要将邮箱地址替换为真实的邮箱，邮件内容可以根据需要进行配置。
61
62实现效果如下：
63![image](figures/mailto-html.gif)
64
65### 从应用拉起
66
67保证mailto字符串传入uri参数即可，在应用中page页面可通过 getHostContext() 获取context，在ability中可通过this.context获取context。
68
69```ts
70import { common } from '@kit.AbilityKit';
71
72@Entry
73@Component
74struct Index {
75  build() {
76    Column() {
77      Button('反馈')
78        .onClick(() => {
79          let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext;
80          ctx.startAbility({
81            action: 'ohos.want.action.sendToData',
82            uri: 'mailto:feedback@example.com?subject=App Feedback&body=Please describe your feedback here...'
83          })
84        })
85    }
86  }
87}
88```
89
90实现效果如下：
91![image](figures/mailto-app.gif)
92
93## 目标方开发步骤
94
951. 为了能够支持被其他应用通过mailto协议拉起，目标应用需要在[module.json5配置文件](../quick-start/module-configuration-file.md)中声明mailto。
96
97    ```json
98    {
99      "module": {
100        // ...
101        "abilities": [
102          {
103            // ...
104            "skills": [
105              {
106              "actions": [
107                  'ohos.want.action.sendToData'
108                ],
109                "uris": [
110                  {
111                    "scheme": "mailto",
112                    // linkFeature 用于适配垂类面板拉起
113                    "linkFeature": 'ComposeMail'
114                  }
115                ]
116              }
117            ]
118          }
119        ]
120      }
121    }
122    ```
123
1242. 目标应用在代码中取出uri参数进行解析。
125
126    ```ts
127    export default class EntryAbility extends UIAbility {
128      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
129        // 应用冷启动生命周期回调，其他业务处理...
130        parseMailto(want);
131      }
132
133      onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
134        // 应用热启动生命周期回调，其他业务处理...
135        parseMailto(want);
136      }
137
138      public parseMailto(want: Want) {
139        const uri = want?.uri;
140        if (!uri || uri.length <= 0) {
141          return;
142        }
143        // 开始解析 mailto...
144      }
145    }
146
147    ```
148