1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
---
title: downloads.download()
slug: Mozilla/Add-ons/WebExtensions/API/downloads/download
tags:
- API
- Add-ons
- Extensions
- Method
- WebExtensions
- download
- downloads
translation_of: Mozilla/Add-ons/WebExtensions/API/downloads/download
---
<div>{{AddonSidebar()}}</div>
<p>{{WebExtAPIRef("downloads")}} API 的 <strong><code>download()</code></strong> 函数根据给出的URL和其他首选项下载一个文件。</p>
<ul>
<li>如果指定的 <code>url</code> 使用HTTP或者HTTPS协议, 那么下载请求将会包含当前为该域名所设置的所有cookie。</li>
<li>如果<code>filename</code> 和 <code>saveAs</code> 都已经指定，那么将会弹出“保存为” 对话框，并且默认名称显示为<code>filename</code>.</li>
</ul>
<p>这是一个异步函数，其返回值为 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>.</p>
<h2 id="语法">语法</h2>
<pre class="syntaxbox brush:js">var downloading = browser.downloads.download(
options // object
)
</pre>
<h3 id="参数">参数</h3>
<dl>
<dt><code>options</code></dt>
<dd>一个 <code>object</code> ，用来指定你想要下载的文件和其他想要在下载时设置的首选项。可以包含以下属性：</dd>
<dd>
<dl class="reference-values">
<dt><code>allowHttpErrors</code>{{optional_inline}}</dt>
<dd>一个 <code>boolean</code>，启用后即使遇到HTTP错误仍然继续下载。 例如，可以使用该标志下载服务错误页面。默认值为<code>false</code>. 当设置为以下值时:
<ul>
<li><code>false</code>,遇到HTTP错误时下载会被取消。</li>
<li><code>true</code>, 即使遇到HTTP错误也会继续下载，并且不会弹出HTTP服务错误报告。但是，如果下载失败的原因是文件相关，网络相关，用户相关，或者说其他错误，仍然会报错。<span style="display: none;"> </span></li>
</ul>
</dd>
<dt><code>body</code>{{optional_inline}}</dt>
<dd>一个 <code>string</code>，代表请求的内容。</dd>
<dt><code>conflictAction</code>{{optional_inline}}</dt>
<dd>一个字符串，表示如果存在命名冲突时你希望进行的操作，字符串内容所代表的类型由 {{WebExtAPIRef('downloads.FilenameConflictAction')}} 定义(未指定时默认为 "uniquify" )。</dd>
<dt><code>filename</code>{{optional_inline}}</dt>
<dd>一个 <code>string</code> ，表示相对默认保存位置的文件路径——这里提供你希望文件保存的位置，和你想要使用的文件名。绝对路径，空路径，以及包含反向引用的路径 (<code>../</code>) 会导致错误产生。 如果省略，该值将默认为已经提供给下载文件的文件名，并且直接保存到下载文件夹中。</dd>
<dt><code>headers</code>{{optional_inline}}</dt>
<dd>如果URL使用HTTP或者HTTPS协议, 保存在 <code>array</code> 中的一系列 <code>objects</code> 表示与请求一起发送的额外HTTP请求头。每一个请求头表示为字典对象，包含有关键字 <code>name</code> 还有 <code>value</code>或<code>binaryValue</code>中的一个。 无法指定 <code>XMLHttpRequest</code>和 <code>fetch</code>禁止的请求头，但是 Firefox 70 之后允许使用<code>Referer</code>请求头。尝试使用被禁止的请求头会产生一个错误。</dd>
<dt><code>incognito</code>{{optional_inline}}</dt>
<dd>一个 <code>boolean</code>：如果被设置为 true，那么这次下载会建立一个隐私浏览会话。 这意味着它只会出现在当前打开的任意隐私窗口的下载管理器。</dd>
<dt><code>method</code>{{optional_inline}}</dt>
<dd>一个 <code>string</code>，表示<code>url</code>使用HTTP[S] 协议时使用的HTTP方法。其值可能是 "GET" 或 "POST"。</dd>
<dt><code>saveAs</code>{{optional_inline}}</dt>
<dd>
<p>一个<code>boolean</code> 指定是(<code>true</code>)否(<code>false</code>)提供一个文件选择对话框允许用户选择文件名。.</p>
<p>如果该选项省略, 浏览器会根据用户对于该行为的偏好设置决定是否提供一个文件选择对话框 (在火狐这项设置标签在about:preferences里为"每次都问您要存到哪" ，或者about:config里 <code>browser.download.useDownloadDir</code> )。</p>
<div class="note">
<p><strong>Note</strong>: 如果 <code>saveAs</code> 被设置为 <code>true</code>，Firefox for Android 将会引发一个错误。 当 <code>saveAs</code> 为 <code>false</code> 或空时这个参数会被忽略.</p>
</div>
</dd>
<dt><code>url</code></dt>
<dd>一个 <code>string</code>，表示需要下载的链接地址。</dd>
</dl>
</dd>
</dl>
<h3 id="返回值">返回值</h3>
<p>一个 <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code>. 如果成功开始下载，promise会被新创建的{{WebExtAPIRef("downloads.DownloadItem")}} 的 <code>id</code> 填充。否则 promise 会被拒绝并产生一条{{WebExtAPIRef("downloads.InterruptReason")}}错误信息.</p>
<p>如果你使用 <a href="/en-US/docs/Web/API/URL/createObjectURL">URL.createObjectURL()</a> 下载由 JavaScript 创建的数据并且之后想要(使用 <a href="/en-US/docs/Web/API/URL/revokeObjectURL">revokeObjectURL</a>)撤销对象链接(并且强烈推荐这么做)，你必须在下载完成后再这么做。监听 <a href="/en-US/docs/Mozilla/Add-ons/WebExtensions/API/downloads/onChanged">downloads.onChanged</a> 事件来判断是否下载完成。</p>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p>
<p>{{Compat("webextensions.api.downloads.download")}}</p>
<h2 id="例子">例子</h2>
<p>下面这段代码尝试下载一个example文件，同时指定文件名和保存位置，还有 <code>uniquify</code> <code>conflictAction</code> 选项。</p>
<pre class="brush: js">function onStartedDownload(id) {
console.log(`Started downloading: ${id}`);
}
function onFailed(error) {
console.log(`Download failed: ${error}`);
}
var downloadUrl = "https://example.org/image.png";
var downloading = browser.downloads.download({
url : downloadUrl,
filename : 'my-image-again.png',
conflictAction : 'uniquify'
});
downloading.then(onStartedDownload, onFailed);</pre>
<p>{{WebExtExamples}}</p>
<div class="note"><strong>Acknowledgements</strong>
<p>这个 API 基于 Chromium的 <a href="https://developer.chrome.com/extensions/downloads#method-download"><code>chrome.downloads</code></a> API.</p>
</div>
<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
// * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
// * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>
|
