1# 拉起邮件类应用（startAbilityByType） 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: AGC--> 5<!--Owner: @liusu23--> 6<!--Designer: @xukeke--> 7<!--Tester: @lusq--> 8<!--Adviser: @huipeizi--> 9 10本章节介绍如何拉起邮件类应用扩展面板。 11> **说明：** 12> 13> 如果拉起方的参数为mailto协议字符串，可以[使用mailto方式拉起邮件应用](start-email-apps-by-mailto.md)。邮件应用会解析收到的mailto协议字符串，并填充发件人、收件人、邮件内容等信息。 14 15## 邮件类应用扩展面板参数说明 16 17startAbilityByType接口中type字段为mail，对应的wantParam参数： 18 19| 参数名 | 类型 | 必填 | 说明 | 20| ------------------------------------- | ------------------------------------------------------------ | ------ | ------------------------------------------------------------ | 21| email | string[ ] | 否 | 收件人邮箱地址（支持多个且以逗号分隔）。 | 22| cc | string[ ] | 否 | 抄收人邮箱地址（支持多个且以逗号分隔）。 | 23| bcc | string[ ] | 否 | 密送人邮箱地址（支持多个且以逗号分隔）。 | 24| subject | string | 否 | 邮件主题。 | 25| body | string | 否 | 邮件内容。 | 26| ability.params.stream | string[ ] | 否 | 邮件附件（附件的uri地址列表）。 | 27| ability.want.params.uriPermissionFlag | [wantConstant.Flags](../reference/apis-ability-kit/js-apis-app-ability-wantConstant.md#flags) | 否 | 给邮件附件赋予至少读权限。邮件附件参数存在时，该参数也必须要传。 | 28| sceneType | number | 否 | 意图场景，表明本次请求对应的操作意图。1：发邮件。默认为1。 | 29 30> **说明：** 31> 32> * 邮件类应用扩展面板中的类型为string的参数，都要经过encodeURI编码。 33> 34> * 邮件类应用扩展面板中的类型为string[]的参数，数组中的元素都要经过encodeURI编码。 35 36## 拉起方开发步骤 371. 导入相关模块。 38 ```ts 39 import { common, wantConstant } from '@kit.AbilityKit'; 40 ``` 412. 构造接口参数并调用startAbilityByType接口。 42 43 ```ts 44 @Entry 45 @Component 46 struct Index { 47 @State hideAbility: string = 'hideAbility' 48 49 build() { 50 Row() { 51 Column() { 52 Text(this.hideAbility) 53 .fontSize(30) 54 .fontWeight(FontWeight.Bold) 55 .onClick(() => { 56 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 57 let wantParam: Record<string, Object> = { 58 'sceneType': 1, 59 'email': [encodeURI('xxx@example.com'), encodeURI('xxx@example.com')], // 收件人邮箱地址，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码 60 'cc': [encodeURI('xxx@example.com'), encodeURI('xxx@example.com')], // 抄收人邮箱地址，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码 61 'bcc': [encodeURI('xxx@example.com'), encodeURI('xxx@example.com')], // 密送人邮箱地址，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码 62 'subject': encodeURI('邮件主题'), // 邮件主题，对内容使用encodeURI()方法进行url编码 63 'body': encodeURI('邮件正文'), // 邮件正文，对内容使用encodeURI()方法进行url编码 64 'ability.params.stream': [encodeURI('附件uri1'), encodeURI('附件uri2')], // 附件uri，多值以逗号分隔，对数组内容使用encodeURI()方法进行url编码 65 'ability.want.params.uriPermissionFlag': wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION 66 }; 67 let abilityStartCallback: common.AbilityStartCallback = { 68 onError: (code: number, name: string, message: string) => { 69 console.error(`onError code ${code} name: ${name} message: ${message}`); 70 }, 71 onResult: (result) => { 72 console.info(`onResult result: ${JSON.stringify(result)}`); 73 } 74 } 75 76 context.startAbilityByType("mail", wantParam, abilityStartCallback, 77 (err) => { 78 if (err) { 79 console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`); 80 } else { 81 console.info(`success`); 82 } 83 }); 84 }); 85 } 86 .width('100%') 87 } 88 .height('100%') 89 } 90 } 91 ``` 92 效果示例图： 93 94  95 96## 目标方开发步骤 97 981. 在module.json5中新增[linkFeature](../quick-start/module-configuration-file.md#skills标签)属性并设置声明当前应用支持的特性功能，从而系统可以从设备已安装应用中找到当前支持该特性的应用，取值范围如下： 99 100 | 取值 | 含义 | 101 | --------------| ------------------------- | 102 | ComposeMail | 声明应用支持撰写邮件功能 | 103 104 ```json 105 { 106 "abilities": [ 107 { 108 "skills": [ 109 { 110 "uris": [ 111 { 112 "scheme": "mailto", // 这里仅示意，应用需确保这里声明的uri能被外部正常拉起 113 "host": "", 114 "path": "", 115 "linkFeature": "ComposeMail" // 声明应用支持撰写邮件功能 116 } 117 ] 118 } 119 ] 120 } 121 ] 122 } 123 ``` 124 1252. 解析面板传过来的参数并做对应处理。 126 127 ```ts 128 UIAbility.onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void 129 ``` 130 131 在参数**want.parameters**中会携带Caller方传入的参数（与调用方传入的有些差异），如下表所示： 132 133 | 参数名 | 类型 | 必填 | 说明 | 134 | ------- | --------- | ---- | -------------------------------------- | 135 | email | string[ ] | 否 | 收件人邮箱地址（支持多个且以逗号分隔）。 | 136 | cc | string[ ] | 否 | 抄收人邮箱地址（支持多个且以逗号分隔）。 | 137 | bcc | string[ ] | 否 | 密送人邮箱地址（支持多个且以逗号分隔）。 | 138 | subject | string | 否 | 邮件主题。 | 139 | body | string | 否 | 邮件内容。 | 140 | stream | string[ ] | 否 | 邮件附件列表（附件的uri地址列表）。 | 141 142 > **说明：** 143 > 144 > * 目标方接收的类型为string的参数，都要经过decodeURI解码。 145 > 146 > * 目标方接收的类型为string[]的参数，数组中的元素都要经过decodeURI解码。 147 148**完整示例：** 149 150```ts 151import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 152import { hilog } from '@kit.PerformanceAnalysisKit'; 153import { window } from '@kit.ArkUI'; 154 155const TAG = 'MailTarget1.EntryAbility' 156 157export default class EntryAbility extends UIAbility { 158 windowStage: window.WindowStage | null = null; 159 160 email: string[] | undefined; 161 cc: string[] | undefined; 162 bcc: string[] | undefined; 163 subject: string | undefined; 164 body: string | undefined; 165 stream: string[] | undefined; 166 167 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 168 hilog.info(0x0000, TAG, `onCreate, want=${JSON.stringify(want)}`); 169 super.onCreate(want, launchParam); 170 this.parseWant(want); 171 } 172 173 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 174 hilog.info(0x0000, TAG, `onNewWant, want=${JSON.stringify(want)}`); 175 super.onNewWant(want, launchParam); 176 this.parseWant(want); 177 if (!this.windowStage) { 178 hilog.error(0x0000, TAG, 'windowStage is null'); 179 this.context.terminateSelf(); 180 return; 181 } 182 this.loadPage(this.windowStage); 183 } 184 185 private parseWant(want: Want): void { 186 this.email = this.decodeStringArr(want.parameters?.email as string[]); 187 this.cc = this.decodeStringArr(want.parameters?.cc as string[]); 188 this.bcc = this.decodeStringArr(want.parameters?.bcc as string[]); 189 this.subject = decodeURI(want.parameters?.subject as string);// 使用decodeURI()方法对邮件主题进行url解码，其他字段处理方法相同 190 this.body = decodeURI(want.parameters?.body as string);// 使用decodeURI()方法对邮件内容进行url解码，其他字段处理方法相同 191 this.stream = this.decodeStringArr(want.parameters?.stream as string[]); 192 } 193 194 // 使用decodeURI()方法对string数组内容进行解码 195 private decodeStringArr(source: string[] | undefined): string[] { 196 let target: string[] = []; 197 source?.forEach(e => { 198 target.push(decodeURI(e)); 199 }) 200 return target; 201 } 202 203 private loadPage(windowStage: window.WindowStage): void { 204 const storage: LocalStorage = new LocalStorage({ 205 "email": this.email, 206 "cc": this.cc, 207 "bcc": this.bcc, 208 "subject": this.subject, 209 "body": this.body, 210 "stream": this.stream 211 } as Record<string, Object>); 212 213 windowStage.loadContent('pages/ComposeMailPage', storage); 214 215 } 216 217 onDestroy(): void { 218 hilog.info(0x0000, TAG, `onDestroy`); 219 } 220 221 onWindowStageCreate(windowStage: window.WindowStage): void { 222 hilog.info(0x0000, TAG, `onWindowStageCreate`); 223 this.windowStage = windowStage; 224 this.loadPage(this.windowStage); 225 } 226 227 onWindowStageDestroy(): void { 228 hilog.info(0x0000, TAG, `onWindowStageDestroy`); 229 } 230 231 onForeground(): void { 232 hilog.info(0x0000, TAG, `onForeground`); 233 } 234 235 onBackground(): void { 236 hilog.info(0x0000, TAG, `onBackground`); 237 } 238} 239``` 240
