• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Class (WebDownloadDelegate)
2<!--Kit: ArkWeb-->
3<!--Subsystem: Web-->
4<!--Owner: @aohui-->
5<!--Designer: @yaomingliu-->
6<!--Tester: @ghiker-->
7<!--Adviser: @HelloCrease-->
8
9下载任务的状态会通过该类的回调接口通知给用户。
10
11> **说明：**
12>
13> - 本模块首批接口从API version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
14>
15> - 本Class首批接口从API version 11开始支持。
16>
17> - 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。
18
19## 导入模块
20
21```ts
22import { webview } from '@kit.ArkWeb';
23```
24
25## onBeforeDownload<sup>11+</sup>
26
27onBeforeDownload(callback: Callback\<WebDownloadItem>): void
28
29下载开始前通知给用户，用户需要在此接口中调用WebDownloadItem.start("xxx")并提供下载路径，否则下载会一直处于PENDING状态。
30
31> **说明：**
32>
33>处于PENDING状态的下载任务会首先将文件保存至临时目录。在调用WebDownloadItem.start并指定目标路径后，临时文件将被重命名为目标文件名，未完成下载的部分会在调用WebDownloadItem.start并指定目标路径后直接下载到目标路径。若希望避免在调用WebDownloadItem.start前生成临时文件，可先通过WebDownloadItem.cancel来取消当前的下载任务，之后再使用WebDownloadManager.resumeDownload来恢复被取消的下载任务。
34
35**系统能力：** SystemCapability.Web.Webview.Core
36
37**参数：**
38
39| 参数名  | 类型   | 必填 | 说明           |
40| ------- | ------ | ---- | :------------- |
41| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | 是   | 触发下载的回调。 |
42
43**示例：**
44
45```ts
46// xxx.ets
47import { webview } from '@kit.ArkWeb';
48import { BusinessError } from '@kit.BasicServicesKit';
49
50@Entry
51@Component
52struct WebComponent {
53  controller: webview.WebviewController = new webview.WebviewController();
54  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
55  download: webview.WebDownloadItem = new webview.WebDownloadItem();
56  failedData: Uint8Array = new Uint8Array();
57
58  build() {
59    Column() {
60      Button('setDownloadDelegate')
61        .onClick(() => {
62          try {
63            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
64              console.info("will start a download.");
65              // 传入一个下载路径，并开始下载。
66              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
67            })
68            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
69              console.info("download update percent complete: " + webDownloadItem.getPercentComplete());
70              this.download = webDownloadItem;
71            })
72            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
73              console.info("download failed guid: " + webDownloadItem.getGuid());
74              // 序列化失败的下载到一个字节数组。
75              this.failedData = webDownloadItem.serialize();
76            })
77            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
78              console.info("download finish guid: " + webDownloadItem.getGuid());
79            })
80            this.controller.setDownloadDelegate(this.delegate);
81          } catch (error) {
82            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
83          }
84        })
85      Button('startDownload')
86        .onClick(() => {
87          try {
88            this.controller.startDownload('https://www.example.com');
89          } catch (error) {
90            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
91          }
92        })
93      Button('resumeDownload')
94        .onClick(() => {
95          try {
96            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
97          } catch (error) {
98            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
99          }
100        })
101      Button('cancel')
102        .onClick(() => {
103          try {
104            this.download.cancel();
105          } catch (error) {
106            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
107          }
108        })
109      Button('pause')
110        .onClick(() => {
111          try {
112            this.download.pause();
113          } catch (error) {
114            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
115          }
116        })
117      Button('resume')
118        .onClick(() => {
119          try {
120            this.download.resume();
121          } catch (error) {
122            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
123          }
124        })
125      Web({ src: 'www.example.com', controller: this.controller })
126    }
127  }
128}
129```
130
131## onDownloadUpdated<sup>11+</sup>
132
133onDownloadUpdated(callback: Callback\<WebDownloadItem>): void
134
135下载过程中的回调，通过该回调的参数可以了解下载进度等信息。
136
137**系统能力：** SystemCapability.Web.Webview.Core
138
139**参数：**
140
141| 参数名  | 类型   | 必填 | 说明           |
142| ------- | ------ | ---- | :------------- |
143| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | 是   | 下载的回调已更新。 |
144
145**示例：**
146
147```ts
148// xxx.ets
149import { webview } from '@kit.ArkWeb';
150import { BusinessError } from '@kit.BasicServicesKit';
151
152@Entry
153@Component
154struct WebComponent {
155  controller: webview.WebviewController = new webview.WebviewController();
156  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
157  download: webview.WebDownloadItem = new webview.WebDownloadItem();
158  failedData: Uint8Array = new Uint8Array();
159
160  build() {
161    Column() {
162      Button('setDownloadDelegate')
163        .onClick(() => {
164          try {
165            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
166              console.info("will start a download.");
167              // 传入一个下载路径，并开始下载。
168              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
169            })
170            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
171              console.info("download update percent complete: " + webDownloadItem.getPercentComplete());
172              this.download = webDownloadItem;
173            })
174            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
175              console.info("download failed guid: " + webDownloadItem.getGuid());
176              // 序列化失败的下载到一个字节数组。
177              this.failedData = webDownloadItem.serialize();
178            })
179            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
180              console.info("download finish guid: " + webDownloadItem.getGuid());
181            })
182            this.controller.setDownloadDelegate(this.delegate);
183          } catch (error) {
184            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
185          }
186        })
187      Button('startDownload')
188        .onClick(() => {
189          try {
190            this.controller.startDownload('https://www.example.com');
191          } catch (error) {
192            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
193          }
194        })
195      Button('resumeDownload')
196        .onClick(() => {
197          try {
198            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
199          } catch (error) {
200            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
201          }
202        })
203      Button('cancel')
204        .onClick(() => {
205          try {
206            this.download.cancel();
207          } catch (error) {
208            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
209          }
210        })
211      Button('pause')
212        .onClick(() => {
213          try {
214            this.download.pause();
215          } catch (error) {
216            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
217          }
218        })
219      Button('resume')
220        .onClick(() => {
221          try {
222            this.download.resume();
223          } catch (error) {
224            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
225          }
226        })
227      Web({ src: 'www.example.com', controller: this.controller })
228    }
229  }
230}
231```
232
233## onDownloadFinish<sup>11+</sup>
234
235onDownloadFinish(callback: Callback\<WebDownloadItem>): void
236
237下载完成的通知。
238
239**系统能力：** SystemCapability.Web.Webview.Core
240
241**参数：**
242
243| 参数名  | 类型   | 必填 | 说明           |
244| ------- | ------ | ---- | :------------- |
245| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | 是   | 下载的回调已完成。 |
246
247**示例：**
248
249```ts
250// xxx.ets
251import { webview } from '@kit.ArkWeb';
252import { BusinessError } from '@kit.BasicServicesKit';
253
254@Entry
255@Component
256struct WebComponent {
257  controller: webview.WebviewController = new webview.WebviewController();
258  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
259  download: webview.WebDownloadItem = new webview.WebDownloadItem();
260  failedData: Uint8Array = new Uint8Array();
261
262  build() {
263    Column() {
264      Button('setDownloadDelegate')
265        .onClick(() => {
266          try {
267            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
268              console.info("will start a download.");
269              // 传入一个下载路径，并开始下载。
270              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
271            })
272            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
273              console.info("download update percent complete: " + webDownloadItem.getPercentComplete());
274              this.download = webDownloadItem;
275            })
276            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
277              console.info("download failed guid: " + webDownloadItem.getGuid());
278              // 序列化失败的下载到一个字节数组。
279              this.failedData = webDownloadItem.serialize();
280            })
281            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
282              console.info("download finish guid: " + webDownloadItem.getGuid());
283            })
284            this.controller.setDownloadDelegate(this.delegate);
285          } catch (error) {
286            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
287          }
288        })
289      Button('startDownload')
290        .onClick(() => {
291          try {
292            this.controller.startDownload('https://www.example.com');
293          } catch (error) {
294            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
295          }
296        })
297      Button('resumeDownload')
298        .onClick(() => {
299          try {
300            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
301          } catch (error) {
302            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
303          }
304        })
305      Button('cancel')
306        .onClick(() => {
307          try {
308            this.download.cancel();
309          } catch (error) {
310            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
311          }
312        })
313      Button('pause')
314        .onClick(() => {
315          try {
316            this.download.pause();
317          } catch (error) {
318            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
319          }
320        })
321      Button('resume')
322        .onClick(() => {
323          try {
324            this.download.resume();
325          } catch (error) {
326            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
327          }
328        })
329      Web({ src: 'www.example.com', controller: this.controller })
330    }
331  }
332}
333```
334
335## onDownloadFailed<sup>11+</sup>
336
337onDownloadFailed(callback: Callback\<WebDownloadItem>): void
338
339下载失败的通知。
340
341**系统能力：** SystemCapability.Web.Webview.Core
342
343**参数：**
344
345| 参数名  | 类型   | 必填 | 说明           |
346| ------- | ------ | ---- | :------------- |
347| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | 是   | 下载回调失败。 |
348
349**示例：**
350
351```ts
352// xxx.ets
353import { webview } from '@kit.ArkWeb';
354import { BusinessError } from '@kit.BasicServicesKit';
355
356@Entry
357@Component
358struct WebComponent {
359  controller: webview.WebviewController = new webview.WebviewController();
360  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
361  download: webview.WebDownloadItem = new webview.WebDownloadItem();
362  failedData: Uint8Array = new Uint8Array();
363
364  build() {
365    Column() {
366      Button('setDownloadDelegate')
367        .onClick(() => {
368          try {
369            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
370              console.info("will start a download.");
371              // 传入一个下载路径，并开始下载。
372              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
373            })
374            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
375              console.info("download update percent complete: " + webDownloadItem.getPercentComplete());
376              this.download = webDownloadItem;
377            })
378            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
379              console.info("download failed guid: " + webDownloadItem.getGuid());
380              // 序列化失败的下载到一个字节数组。
381              this.failedData = webDownloadItem.serialize();
382            })
383            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
384              console.info("download finish guid: " + webDownloadItem.getGuid());
385            })
386            this.controller.setDownloadDelegate(this.delegate);
387          } catch (error) {
388            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
389          }
390        })
391      Button('startDownload')
392        .onClick(() => {
393          try {
394            this.controller.startDownload('https://www.example.com');
395          } catch (error) {
396            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
397          }
398        })
399      Button('resumeDownload')
400        .onClick(() => {
401          try {
402            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
403          } catch (error) {
404            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
405          }
406        })
407      Button('cancel')
408        .onClick(() => {
409          try {
410            this.download.cancel();
411          } catch (error) {
412            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
413          }
414        })
415      Button('pause')
416        .onClick(() => {
417          try {
418            this.download.pause();
419          } catch (error) {
420            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
421          }
422        })
423      Button('resume')
424        .onClick(() => {
425          try {
426            this.download.resume();
427          } catch (error) {
428            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
429          }
430        })
431      Web({ src: 'www.example.com', controller: this.controller })
432    }
433  }
434}
435```