• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Class (WebDownloadDelegate)
2
3Implements a **WebDownloadDelegate** object to notify users of the download state.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
8>
9> - The initial APIs of this class are supported since API version 11.
10>
11> - You can preview how this component looks on a real device, but not in DevEco Studio Previewer.
12
13## Modules to Import
14
15```ts
16import { webview } from '@kit.ArkWeb';
17```
18
19## onBeforeDownload<sup>11+</sup>
20
21onBeforeDownload(callback: Callback\<WebDownloadItem>): void
22
23Invoked to notify users before the download starts. **WebDownloadItem.start("xxx")** must be called in this API, with a download path provided. Otherwise, the download remains in the PENDING state.
24
25> **NOTE**
26>
27>The file of the download task in the PENDING state is saved to a temporary directory. After the target path is specified by invoking **WebDownloadItem.start**, the temporary file is renamed as the target file, and the unfinished part is directly downloaded to the target path. To avoid generating temporary files before invoking **WebDownloadItem.start**, you can call **WebDownloadItem.cancel** to cancel the current download task and then call **WebDownloadManager.resumeDownload** to resume it.
28
29**System capability**: SystemCapability.Web.Webview.Core
30
31**Parameters**
32
33| Name | Type  | Mandatory| Description          |
34| ------- | ------ | ---- | :------------- |
35| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | Yes  | Callback for triggering a download.|
36
37**Example**
38
39```ts
40// xxx.ets
41import { webview } from '@kit.ArkWeb';
42import { BusinessError } from '@kit.BasicServicesKit';
43
44@Entry
45@Component
46struct WebComponent {
47  controller: webview.WebviewController = new webview.WebviewController();
48  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
49  download: webview.WebDownloadItem = new webview.WebDownloadItem();
50  failedData: Uint8Array = new Uint8Array();
51
52  build() {
53    Column() {
54      Button('setDownloadDelegate')
55        .onClick(() => {
56          try {
57            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
58              console.log("will start a download.");
59              // Pass in a download path and start the download.
60              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
61            })
62            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
63              console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
64              this.download = webDownloadItem;
65            })
66            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
67              console.log("download failed guid: " + webDownloadItem.getGuid());
68              // Serialize the failed download to a byte array.
69              this.failedData = webDownloadItem.serialize();
70            })
71            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
72              console.log("download finish guid: " + webDownloadItem.getGuid());
73            })
74            this.controller.setDownloadDelegate(this.delegate);
75          } catch (error) {
76            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
77          }
78        })
79      Button('startDownload')
80        .onClick(() => {
81          try {
82            this.controller.startDownload('https://www.example.com');
83          } catch (error) {
84            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
85          }
86        })
87      Button('resumeDownload')
88        .onClick(() => {
89          try {
90            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
91          } catch (error) {
92            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
93          }
94        })
95      Button('cancel')
96        .onClick(() => {
97          try {
98            this.download.cancel();
99          } catch (error) {
100            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
101          }
102        })
103      Button('pause')
104        .onClick(() => {
105          try {
106            this.download.pause();
107          } catch (error) {
108            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
109          }
110        })
111      Button('resume')
112        .onClick(() => {
113          try {
114            this.download.resume();
115          } catch (error) {
116            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
117          }
118        })
119      Web({ src: 'www.example.com', controller: this.controller })
120    }
121  }
122}
123```
124
125## onDownloadUpdated<sup>11+</sup>
126
127onDownloadUpdated(callback: Callback\<WebDownloadItem>): void
128
129Invoked when the download progress is updated.
130
131**System capability**: SystemCapability.Web.Webview.Core
132
133**Parameters**
134
135| Name | Type  | Mandatory| Description          |
136| ------- | ------ | ---- | :------------- |
137| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | Yes  | Callback invoked when the downloaded progress is updated.|
138
139**Example**
140
141```ts
142// xxx.ets
143import { webview } from '@kit.ArkWeb';
144import { BusinessError } from '@kit.BasicServicesKit';
145
146@Entry
147@Component
148struct WebComponent {
149  controller: webview.WebviewController = new webview.WebviewController();
150  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
151  download: webview.WebDownloadItem = new webview.WebDownloadItem();
152  failedData: Uint8Array = new Uint8Array();
153
154  build() {
155    Column() {
156      Button('setDownloadDelegate')
157        .onClick(() => {
158          try {
159            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
160              console.log("will start a download.");
161              // Pass in a download path and start the download.
162              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
163            })
164            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
165              console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
166              this.download = webDownloadItem;
167            })
168            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
169              console.log("download failed guid: " + webDownloadItem.getGuid());
170              // Serialize the failed download to a byte array.
171              this.failedData = webDownloadItem.serialize();
172            })
173            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
174              console.log("download finish guid: " + webDownloadItem.getGuid());
175            })
176            this.controller.setDownloadDelegate(this.delegate);
177          } catch (error) {
178            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
179          }
180        })
181      Button('startDownload')
182        .onClick(() => {
183          try {
184            this.controller.startDownload('https://www.example.com');
185          } catch (error) {
186            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
187          }
188        })
189      Button('resumeDownload')
190        .onClick(() => {
191          try {
192            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
193          } catch (error) {
194            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
195          }
196        })
197      Button('cancel')
198        .onClick(() => {
199          try {
200            this.download.cancel();
201          } catch (error) {
202            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
203          }
204        })
205      Button('pause')
206        .onClick(() => {
207          try {
208            this.download.pause();
209          } catch (error) {
210            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
211          }
212        })
213      Button('resume')
214        .onClick(() => {
215          try {
216            this.download.resume();
217          } catch (error) {
218            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
219          }
220        })
221      Web({ src: 'www.example.com', controller: this.controller })
222    }
223  }
224}
225```
226
227## onDownloadFinish<sup>11+</sup>
228
229onDownloadFinish(callback: Callback\<WebDownloadItem>): void
230
231Invoked when the download is complete.
232
233**System capability**: SystemCapability.Web.Webview.Core
234
235**Parameters**
236
237| Name | Type  | Mandatory| Description          |
238| ------- | ------ | ---- | :------------- |
239| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | Yes  | Callback invoked when the download is complete.|
240
241**Example**
242
243```ts
244// xxx.ets
245import { webview } from '@kit.ArkWeb';
246import { BusinessError } from '@kit.BasicServicesKit';
247
248@Entry
249@Component
250struct WebComponent {
251  controller: webview.WebviewController = new webview.WebviewController();
252  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
253  download: webview.WebDownloadItem = new webview.WebDownloadItem();
254  failedData: Uint8Array = new Uint8Array();
255
256  build() {
257    Column() {
258      Button('setDownloadDelegate')
259        .onClick(() => {
260          try {
261            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
262              console.log("will start a download.");
263              // Pass in a download path and start the download.
264              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
265            })
266            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
267              console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
268              this.download = webDownloadItem;
269            })
270            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
271              console.log("download failed guid: " + webDownloadItem.getGuid());
272              // Serialize the failed download to a byte array.
273              this.failedData = webDownloadItem.serialize();
274            })
275            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
276              console.log("download finish guid: " + webDownloadItem.getGuid());
277            })
278            this.controller.setDownloadDelegate(this.delegate);
279          } catch (error) {
280            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
281          }
282        })
283      Button('startDownload')
284        .onClick(() => {
285          try {
286            this.controller.startDownload('https://www.example.com');
287          } catch (error) {
288            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
289          }
290        })
291      Button('resumeDownload')
292        .onClick(() => {
293          try {
294            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
295          } catch (error) {
296            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
297          }
298        })
299      Button('cancel')
300        .onClick(() => {
301          try {
302            this.download.cancel();
303          } catch (error) {
304            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
305          }
306        })
307      Button('pause')
308        .onClick(() => {
309          try {
310            this.download.pause();
311          } catch (error) {
312            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
313          }
314        })
315      Button('resume')
316        .onClick(() => {
317          try {
318            this.download.resume();
319          } catch (error) {
320            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
321          }
322        })
323      Web({ src: 'www.example.com', controller: this.controller })
324    }
325  }
326}
327```
328
329## onDownloadFailed<sup>11+</sup>
330
331onDownloadFailed(callback: Callback\<WebDownloadItem>): void
332
333Invoked when the download fails.
334
335**System capability**: SystemCapability.Web.Webview.Core
336
337**Parameters**
338
339| Name | Type  | Mandatory| Description          |
340| ------- | ------ | ---- | :------------- |
341| callback | Callback\<[WebDownloadItem](./arkts-apis-webview-WebDownloadItem.md)> | Yes  | Callback invoked when the download fails.|
342
343**Example**
344
345```ts
346// xxx.ets
347import { webview } from '@kit.ArkWeb';
348import { BusinessError } from '@kit.BasicServicesKit';
349
350@Entry
351@Component
352struct WebComponent {
353  controller: webview.WebviewController = new webview.WebviewController();
354  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
355  download: webview.WebDownloadItem = new webview.WebDownloadItem();
356  failedData: Uint8Array = new Uint8Array();
357
358  build() {
359    Column() {
360      Button('setDownloadDelegate')
361        .onClick(() => {
362          try {
363            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
364              console.log("will start a download.");
365              // Pass in a download path and start the download.
366              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
367            })
368            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
369              console.log("download update percent complete: " + webDownloadItem.getPercentComplete());
370              this.download = webDownloadItem;
371            })
372            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
373              console.log("download failed guid: " + webDownloadItem.getGuid());
374              // Serialize the failed download to a byte array.
375              this.failedData = webDownloadItem.serialize();
376            })
377            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
378              console.log("download finish guid: " + webDownloadItem.getGuid());
379            })
380            this.controller.setDownloadDelegate(this.delegate);
381          } catch (error) {
382            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
383          }
384        })
385      Button('startDownload')
386        .onClick(() => {
387          try {
388            this.controller.startDownload('https://www.example.com');
389          } catch (error) {
390            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
391          }
392        })
393      Button('resumeDownload')
394        .onClick(() => {
395          try {
396            webview.WebDownloadManager.resumeDownload(webview.WebDownloadItem.deserialize(this.failedData));
397          } catch (error) {
398            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
399          }
400        })
401      Button('cancel')
402        .onClick(() => {
403          try {
404            this.download.cancel();
405          } catch (error) {
406            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
407          }
408        })
409      Button('pause')
410        .onClick(() => {
411          try {
412            this.download.pause();
413          } catch (error) {
414            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
415          }
416        })
417      Button('resume')
418        .onClick(() => {
419          try {
420            this.download.resume();
421          } catch (error) {
422            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
423          }
424        })
425      Web({ src: 'www.example.com', controller: this.controller })
426    }
427  }
428}
429```
430