xref: /docs/en/application-dev/web/web-download.md (revision e41f4b71) 
1# Downloading Files
2
3## Listening for Downloads Initiated from Pages
4
5Call [setDownloadDelegate()](../reference/apis-arkweb/js-apis-webview.md#setdownloaddelegate11) to register a **DownloadDelegate** object with the **\<Web>** component to listen for downloads initiated from pages. While the **\<Web>** component downloads resources as requested, it notifies the application of the download progress through the **DownloadDelegate** object.
6
7In the following example, the **index.html** and **download.html** files are added to the **rawfile** folder of the application. After the application is started, a **\<Web>** component is created and the **index.html** file is loaded. After **setDownloadDelegate** is clicked, a **DownloadDelegate** object is registered with the **\<Web>** component. This **DownloadDelegate** object listens for any downloads initiated by clicking the download button on the page.
8
9```ts
10// xxx.ets
11import { webview } from '@kit.ArkWeb';
12import { BusinessError } from '@kit.BasicServicesKit';
13
14@Entry
15@Component
16struct WebComponent {
17  controller: webview.WebviewController = new webview.WebviewController();
18  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
19
20  build() {
21    Column() {
22      Button('setDownloadDelegate')
23        .onClick(() => {
24          try {
25            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
26              console.log("will start a download.");
27              // Pass in a download path and start the download.
28              // If the path is invalid, the file will be downloaded to the default directory at /data/storage/el2/base/cache/web/.
29              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
30            })
31            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
32              // Unique ID of a download task.
33              console.log("download update guid: " + webDownloadItem.getGuid());
34              // Download progress.
35              console.log("download update guid: " + webDownloadItem.getPercentComplete());
36              // Current download speed.
37              console.log("download update speed: " + webDownloadItem.getCurrentSpeed())
38            })
39            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
40              console.log("download failed guid: " + webDownloadItem.getGuid());
41              // Error code of a download task failure.
42              console.log("download failed guid: " + webDownloadItem.getLastErrorCode());
43            })
44            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
45              console.log("download finish guid: " + webDownloadItem.getGuid());
46            })
47            this.controller.setDownloadDelegate(this.delegate);
48          } catch (error) {
49            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
50          }
51        })
52      Web({ src: $rawfile('index.html'), controller: this.controller })
53    }
54  }
55}
56```
57HTML file to be loaded:
58```html
59<!-- index.html -->
60<!DOCTYPE html>
61<html>
62<body>
63<a href='data:text/html,%3Ch1%3EHello%2C%20World%21%3C%2Fh1%3E' download='download.html'>Download</a>
64</body>
65</html>
66```
67
68HTML file to be downloaded:
69```html
70<!-- download.html -->
71<!DOCTYPE html>
72<html>
73<body>
74<h1>download test</h1>
75</body>
76</html>
77```
78
79## Initiating a Download Task
80
81Call [startDownload()](../reference/apis-arkweb/js-apis-webview.md#startdownload11) to initiate a download task.
82For a download initiated by it, the **\<Web>** component works out the referrer based on the currently displayed URL and its own default referrer policy.
83
84  In the following example, clicking **setDownloadDelegate** registers a listener class with the **\<Web>** component, and clicking **startDownload** initiates a download task.
85  The application is notified of the download task progress through the configured **DownloadDelegate** object.
86
87```ts
88// xxx.ets
89import { webview } from '@kit.ArkWeb';
90import { BusinessError } from '@kit.BasicServicesKit';
91
92@Entry
93@Component
94struct WebComponent {
95  controller: webview.WebviewController = new webview.WebviewController();
96  delegate: webview.WebDownloadDelegate = new webview.WebDownloadDelegate();
97
98  build() {
99    Column() {
100      Button('setDownloadDelegate')
101        .onClick(() => {
102          try {
103            this.delegate.onBeforeDownload((webDownloadItem: webview.WebDownloadItem) => {
104              console.log("will start a download.");
105              // Pass in a download path and start the download.
106              webDownloadItem.start("/data/storage/el2/base/cache/web/" + webDownloadItem.getSuggestedFileName());
107            })
108            this.delegate.onDownloadUpdated((webDownloadItem: webview.WebDownloadItem) => {
109              console.log("download update guid: " + webDownloadItem.getGuid());
110            })
111            this.delegate.onDownloadFailed((webDownloadItem: webview.WebDownloadItem) => {
112              console.log("download failed guid: " + webDownloadItem.getGuid());
113            })
114            this.delegate.onDownloadFinish((webDownloadItem: webview.WebDownloadItem) => {
115              console.log("download finish guid: " + webDownloadItem.getGuid());
116            })
117            this.controller.setDownloadDelegate(this.delegate);
118          } catch (error) {
119            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
120          }
121        })
122      Button('startDownload')
123        .onClick(() => {
124          try {
125            // The specified download address here is https://www.example.com/. 
126            // Replace it with the URL from which you want to download files.
127            this.controller.startDownload('https://www.example.com/');
128          } catch (error) {
129            console.error(`ErrorCode: ${(error as BusinessError).code},  Message: ${(error as BusinessError).message}`);
130          }
131        })
132      Web({ src: 'www.example.com', controller: this.controller })
133    }
134  }
135}
136```
137