recursal/MDN huggingface dataset:
Screen.orientation
==================

**实验性:** **这是一项实验性技术**  
在将其用于生产之前，请仔细检查浏览器兼容性表格。

**`orientation`** 是 `Screen` 接口的一个只读属性，返回屏幕当前的方向。

语法
--
```

var orientation = window.screen.orientation;
```

### 返回值

一个 `ScreenOrientation` (en-US) 的实例，表示屏幕的方向。

注意在更早的、有前缀的版本中会返回一个 `DOMString` 值，相当于 `ScreenOrientation.type` (en-US) 的值。

示例
--


```js
var orientation =
  (screen.orientation || {}).type ||
  screen.mozOrientation ||
  screen.msOrientation;

if (orientation === "landscape-primary") {
  console.log("That looks good.");
} else if (orientation === "landscape-secondary") {
  console.log("Mmmh... the screen is upside down!");
} else if (
  orientation === "portrait-secondary" ||
  orientation === "portrait-primary"
) {
  console.log("Mmmh... you should rotate your device to landscape");
} else if (orientation === undefined) {
  console.log("The orientation API isn't supported in this browser :(");
}
```

规范
--

| Specification |
| --- |
| Screen Orientation # dom-screen-orientation |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `ScreenOrientation` (en-US)
* `Screen.onorientationchange` (en-US)
* Managing screen orientation (en-US)
Screen.width
============

概述
--

返回屏幕的宽度。

语法
--
```

lWidth = window.screen.width
```

示例
--


```js
// crude way to check that the screen is at 1024x768
if (window.screen.width > 1000) {
  // resolution is below 10 x 7
}
```

备注
--

注意，该属性返回的宽度值不一定就是浏览器窗口可使用的宽度。当有其他小工具占据了屏幕空间时，浏览器有时不能占用小工具（如任务栏）占据的空间。`window.screen.width` 和 `window.screen.availWidth` 两者不同。相关属性 `window.screen.height`。

在返回该值时，IE 会考虑缩放设置。只有在缩放比例为 100% 时，IE 才返回真实的屏幕宽度。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-width |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
Screen.availWidth
=================

概述
--

返回浏览器窗口可占用的水平宽度（单位：像素）。

语法
--
```

window.screen.availWidth
```

示例
--


```js
var screenAvailWidth = window.screen.availWidth;

console.log(screenAvailWidth);
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-availwidth |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
Screen.pixelDepth
=================

返回屏幕的位深度/色彩深度（bit depth）。根据 CSSOM( CSS 对象模型 ) 视图，为兼容起见，该值总为 24。

示例
--


```js
// 如果没有足够的位深度/色彩深度（bit depth），就选择一个更纯的颜色
if (window.screen.pixelDepth > 8) {
  document.style.color = "#FAEBD7";
} else {
  document.style.color = "#FFFFFF";
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-screen-pixeldepth |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Screen.colorDepth`
VisualViewport.offsetTop
========================

**实验性:** **这是一项实验性技术**  
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`VisualViewport` 接口的只读属性 **`offsetTop`** 返回视觉视口的顶部相对于布局视口的顶部的偏移量，以 CSS 像素为单位。

语法
--
```

var offsetTop = VisualViewport.offsetTop
```

### 值

一个双精度值。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-visualviewport-offsettop |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
OfflineAudioContext: complete event
===================================

`complete`当离线音频上下文的呈现完成时，将触发`OfflineAudioContext`接口的事件。

|  |  |
| --- | --- |
| 泡泡 | 没有 |
| 取消 | 没有 |
| 默认操作 | 没有 |
| 接口 | `OfflineAudioCompletionEvent` (en-US) |
| 事件处理程序属性 | `OfflineAudioContext.oncomplete` (en-US) |

例子
--

处理完成后，你可能希望使用`oncomplete`处理程序提示用户现在可以播放音频，并启用播放按钮：


```js
offlineAudioCtx.addEventListener("complete", () => {
  console.log("Offline audio processing now complete");
  showModalDialog("Song processed and ready to play");
  playBtn.disabled = false;
});
```


You can also set up the event handler using the `OfflineAudioContext.oncomplete` (en-US) property:


```js
offlineAudioCtx.oncomplete = function () {
  console.log("Offline audio processing now complete");
  showModalDialog("Song processed and ready to play");
  playBtn.disabled = false;
};
```

Specifications
--------------

| Specification |
| --- |
| Web Audio API # OfflineAudioCompletionEvent |
| Web Audio API # dom-offlineaudiocontext-oncomplete |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `离线音频上下文.oncomplete`
* Web Audio API (en-US)
OfflineAudioContext.OfflineAudioContext()
=========================================

**`OfflineAudioContext()`** 构造函数创建一个新的 `OfflineAudioContext` 对象实例。

语法
--


```js
new OfflineAudioContext(options)

new OfflineAudioContext(numberOfChannels, length, sampleRate)
```

### 参数

`numberOfChannels`

An integer 代表该缓冲区拥有的声道的数目。该实现需要支持至少 32 个声道。

`length`

代表采样帧缓冲区的大小的整数。

`sampleRate`

采样帧每一秒的线性音频数据的采样率。该实现必须支持在 22050 到 96000 之间的采样率，44100 是最经常用到的采样率。

这里有个重要的警告，你可以通过不带参数的使用 `new AudioContext()` 构造函数创建一个新的 `AudioContext`，但是 `OfflineAudioContext()` 构造函数必须带上三个参数。当你通过 `AudioContext.createBuffer` 方法创建一个新的`AudioBuffer` 时，你也是需要做一样的事情。想要知道更多信息，请阅读我们的基本概念指南的 音频片段：帧，样本和声道。

**备注：** 像普通的 `AudioContext`，`OfflineAudioContext` 可以成为事件的目标，因此它的实现是 `EventTarget` 接口。

例子
--


```js
// 定义一个在线或者离线的音频上下文

var audioCtx = new AudioContext();
var offlineCtx = new OfflineAudioContext(2, 44100 \* 40, 44100);

source = offlineCtx.createBufferSource();

// 更多代码...
```


**备注：** 想要获取完整的例子，请看我们在 Github 仓库的 offline-audio-context-promise （也可以看 源代码 ）

规范
--

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-offlineaudiocontext |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
OfflineAudoContext.length
=========================

**实验性:** **这是一项实验性技术**  
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`OfflineAudioContext` 接口的 **`length`** 属性返回一个代表采样帧的缓冲区大小的整数。

语法
--
```

var length = OfflineAudioContext.length;
```

### 值

一个代表采样帧的缓冲区大小的整数。

规范
--

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-length |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
suspend
=======

The **`suspend()`** method of the `OfflineAudioContext` interface schedules a suspension of the time progression in the audio context at the specified time and returns a promise. This is generally useful at the time of manipulating the audio graph synchronously on OfflineAudioContext.

Note that the maximum precision of suspension is the size of the render quantum and the specified suspension time will be rounded down to the nearest render quantum boundary. For this reason, it is not allowed to schedule multiple suspends at the same quantized frame. Also scheduling should be done while the context is not running to ensure the precise suspension.

语法
--
```

OfflineAudioContext.suspend(suspendTime).then(function() { ... });
```

### 参数

暂停时间

A `double` 指定暂停的时间。

### 返回值

A `Promise` resolving to void.

### 异常

发生任何异常，promise 就会拒绝。

`InvalidStateError` `DOMException`

如果帧数出现下列情况，则抛出该异常：

* 一个负值
* 小于或等于当前时间
* 大于或等于渲染的总渲染时间
* is scheduled by another suspend for the same time

Specifications
--------------

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocontext-suspend |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.keys()
===================

`DOMTokenList` **的** **`keys()`** 方法返回一个`iterator`, 可以用来遍历这个对象中的所有的键，键的类型是`无符号整型`。

语法
--
```

tokenList.keys();
```

### 参数

无。

### 返回值

返回一个 `iterator`.

示例
--

在下面的例子中，我们获取了一个使用 `Element.classList`属性获取了一个 `DOMTokenList` ，在这里它表示了这个 `<span>` 元素的所有 class 属性值的键（索引）。然后我们使用了它的 `keys()`方法获取了一个 iterator，最后再使用 for ... of 循环来对所有键（这里是索引）进行遍历，将遍历的每一个结果都写到这个 `<span>` 标签内（使用`Node.textContent`属性）显示。

首先，例子使用的 HTML 代码为：


```html
<span class="a b c"></span>
```


这是 JavaScript 代码：


```js
var span = document.querySelector("span");
var classes = span.classList;
var iterator = classes.keys();

for (var value of iterator) {
  span.textContent += value + " ++ ";
}
```


输出为：

规范
--

#### No specification found

No specification data found for `api.DOMTokenList.keys`.  
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.add()
==================

`DOMTokenList` 接口的 **`add()`** 方法将给定的标记添加到列表中。

语法
--
```

tokenList.add(token1[, token2[, ...tokenN]]);
```

### 参数

token*N*

一个 `DOMString`，表示你要添加到列表里的标记。

### 返回值

`undefined`

示例
--

在下面的例子中，我们使用 `Element.classList` 将 `<span>` 元素上设置的类列表检索为 `DOMTokenList`。然后，我们将新标记添加到列表中，并将列表写入 `<span>` 元素的`Node.textContent`。

HTML:


```html
<span class="a b c"></span>
```


JavaScript:


```js
var span = document.querySelector("span");
var classes = span.classList;
classes.add("d");
span.textContent = classes;
```


结果如下：

你也可以添加多个标记：


```js
span.classList.add("d", "e", "f");
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-add① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.toggle()
=====================

`DOMTokenList` 接口的 **`toggle()`** 方法从列表中删除一个给定的标记并返回 `false`。如果标记不存在，则添加并且函数返回 `true`。

语法
--


```js
toggle(token);
toggle(token, force);
```

### 参数

`token`

一个字符串，表示你想要 toggle 的标记。

`force` 可选

如果包含该值，设置后会将方法变成单向操作。如果设置为 `false`，*仅*会删除标记列表中匹配的给定标记，且不会再度添加。如果设置为 `true`，*仅*在标记列表中添加给定标记，且不会再度删除。

### 返回值

一个布尔值，`true` 或者 `false`，表示在调用 toggle 后，标记是否存在于列表中。

示例
--

### 在点击后 toggle class

以下示例我们使用 `Element.classList` 检索 `<span>` 元素的 class 集合列表（其返回值为 `DOMTokenList`）。然后我们替换集合中的一个标记，并将集合写入 `<span>` 的 `Node.textContent`

这是 HTML：


```html
<span class="a b">classList is 'a b'</span>
```


现在是 JavaScript：


```js
const span = document.querySelector("span");
const classes = span.classList;

span.addEventListener("click", () => {
  const result = classes.toggle("c");

  if (result) {
    span.textContent = `'c' added; classList is now "${classes}".`;
  } else {
    span.textContent = `'c' removed; classList is now "${classes}".`;
  }
});
```


输出如下所示，并且每次点击文本时都会发生变化：

### 设置 force 参数

第二个参数可以用于决定是否包含 class 属性。这个例子仅在浏览器窗口宽度超过 1000 像素时才会包含‘c’属性。


```js
span.classList.toggle("c", window.innerWidth > 1000);
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-toggle① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.length
===================

\*\*`length`\*\*是 **`DOMTokenList`** 接口的一个只读属性，以整数来表示，代表着当前对象中值的个数。

语法
--
```

tokenList.length;
```

### 数值

一个整数。

示例
--

在示范例子里我们编写了一个 span 元素，使用`Element.classList`去检索元素`<span>`拥有的类，放回一个实时的`DOMTokenList`集合，然后把该集合中的数值个数写进 `<span>`的 `Node.textContent` 属性中。

HTML 代码：


```html
<span class="a b c"></span>
```


JavaScript 代码：


```js
var span = document.querySelector("span");
var classes = span.classList;
var length = classes.length;

span.textContent = "classList length = " + length;
```


运行得出的结果如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-length① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.contains()
=======================

`DOMTokenList`接口的 **`contains()`** 方法返回 `Boolean` (en-US) 类型。若传入的参数 `token` 包含在列表中时则返回`true`，否则返回 `false`。

语法
--
```

tokenList.contains(token);
```

### 参数

`token`

`DOMString`类型，用于判断是否存在于列表中的标记。

### 返回值

`Boolean` (en-US)类型，当`token`包含在列表中时返回`true`，否则返回`false`。

示例
--

在下面的列子中，我们通过`Element.classList`方法从 `<span>` 元素中获取`DOMTokenList` 对象。然后测试验证`"c"` 是否包含在列表中，结果输出到 `<span>`标签的内容 `Node.textContent`。

HTML:


```html
<span class="a b c"></span>
```


JavaScript:


```js
let span = document.querySelector("span");
let classes = span.classList;
let result = classes.contains("c");
if (result) {
  span.textContent = "The classList contains 'c'";
} else {
  span.textContent = "The classList does not contain 'c'";
}
```


结果如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-contains① |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.remove()
=====================

**`remove()`** 方法从 `DOMTokenList` 中移除指定标记。

语法
--
```

tokenList.remove(token1[, token2[, ...]]);
```

### 参数列表

token*N*...

表示要从列表中移除的一个 `DOMString`。如果列表中不存在该字符串，不会出错也没有任何变化。

### 返回值

`undefined`

示例
--

在下面的示例中，我们使用 `Element.classList` 检索 `<span>` 元素上设置的 class 列表作为 DOMTokenList。然后从列表中删除一个标记，并将该列表写入`<span>`的 `Node.textContent` 中。

### HTML


```html
<span class="a b c"></span>
```

### JavaScript


```js
var span = document.querySelector("span");
var classes = span.classList;
classes.remove("c");
span.textContent = classes;
```


输出如下：

要一次删除多个 class，可以提供多个标记。书写顺序不必与它们在列表中出现的顺序匹配：


```js
let span = document.getElementsByTagName("span")[0],
  classes = span.classList;

classes.remove("c", "b");
span.textContent = classes;
```

描述
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-remove① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.item()
===================

`DOMTokenList`接口的 **`item()`** 方法返回一个在列表中的索引的项。

语法
--
```

tokenList.item(index)
```

### 参数

`index`

`DOMString` 类型，一个表示要返回的项的索引。

### 返回值

`DOMString`类型，一个表示要返回的项。如果数字大于或等于列表的`length`，则返回`null`。

示例
--

在下面的列子中，我们通过`Element.classList`方法从`<span>`元素中获取`DOMTokenList`对象。然后使用`item(tokenList.length - 1)`检索列表中的最后的一个项，并将其写入<span>元素的 `Node.textContent`。

首先，HTML：


```html
<span class="a b c"></span>
```


然后，JavaScript：


```js
let span = document.querySelector("span");
let classes = span.classList;
let item = classes.item(classes.length - 1);
span.textContent = item;
```


输出结果如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-item① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.replace()
======================

`DOMTokenList`接口的 **`replace()`** 方法可以将列表中一个已存在的 token 替换为一个新 token。如果第一个参数 token 在列表中不存在， `replace()` 立刻返回`false` ，而不会将新 token 字符串添加到列表中。

语法
--
```

tokenList.replace(oldToken, newToken);
```

### 参数

`oldToken`

`DOMString`类型，想要替换掉的字符串。

`newToken`

`DOMString`类型，表示要将`oldToken`字符串替换成的字符串。

### 返回值

boolean 类型，如果`oldToken`被成功替换，返回 `true` ，否则返回`false`

**备注：** In older browsers, `replace()` returns void.

Examples
--------

在下面的例子中，我们使用`Element.classList`方法，将设置在`<span>` 元素上的 class 列表检索为`DOMTokenList` 类型。接着我们替换一个字符串，并且将新列表写入到 `<span>` 的内容`Node.textContent`中。

首先，HTML 代码如下：


```html
<span class="a b c"></span>
```


然后是 JavaScript:


```js
let span = document.querySelector("span");
let classes = span.classList;

let result = classes.replace("c", "z");
console.log(result);

if (result) {
  span.textContent = classes;
} else {
  span.textContent = "token not replaced successfully";
}
```


输出如下：

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-replace① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
DOMTokenList.supports()
=======================

如果给定的 `token` 位于关联属性支持的 token 列表中，则 `DOMTokenList` 接口的 **`supports()`** 方法返回 `true`。这个方法旨在支持特性检查。

语法
--


```js
supports(token);
```

### 参数

`token`

一个字符串，包含了用于查询的 token。

### 返回值

一个布尔值，表示是否查询到 token。

示例
--


```js
const iframe = document.getElementById("display");

if (iframe.sandbox.supports("an-upcoming-feature")) {
  // support code for mystery future feature
} else {
  // fallback code
}

if (iframe.sandbox.supports("allow-scripts")) {
  // instruct frame to run JavaScript
  //
  // (NOTE: This feature is well-supported; this is just an example!)
  //
}
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-domtokenlist-supports① |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
FileSystemWritableFileStream：seek() 方法
======================================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`FileSystemWritableFileStream` 接口的 **`seek()`** 方法用于更新文件当前指针的偏移到指定的位置（以字节为单位）。

语法
--


```js
seek(position)
```

### 参数

`position`

一个数字，表示从文件开头起的字节位置。

### 返回值

一个 `Promise`，会兑现 `undefined`。

### 异常

`NotAllowedError` `DOMException`

如果 `PermissionStatus.state` (en-US) 不为 `granted`，抛出此异常。

`TypeError`

如果 `position` 参数不是一个数字或者未定义，抛出此错误。

示例
--

下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 `FileSystemFileHandle`。由此，使用 `FileSystemFileHandle.createWritable()` 方法创建一个写入流。

然后我们按以下流程写入内容到流中：

1. 向流中写入一个字符串。
2. 使用 `seek()` 方法将指针放置到流的开头。
3. 向流中写入第二个字符串，覆写第一次写入的。

随后将流关闭。


```js
async function saveFile() {
  try {
    // 创建一个新句柄。
    const newHandle = await window.showSaveFilePicker();

    // 创建一个 FileSystemWritableFileStream 用于写入。
    const writableStream = await newHandle.createWritable();

    // 写入我们的文件。
    await writableStream.write("My first file content");
    await writableStream.seek(0);
    await writableStream.write("My second file content");

    // 关闭文件并将内容写入磁盘。
    await writableStream.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```


如果你运行了上面的函数，然后打开磁盘上被创建的文件，你应该会看到文本“My second file content”。

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemwritablefilestream-seek |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemWritableFileStream：truncate() 方法
==========================================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`FileSystemWritableFileStream` 接口的 **`truncate()`** 方法用于将与流相关联的文件调整为指定字节大小。

如果指定的大小大于文件当前的大小，文件会被用 `0x00` 字节补充。

调用 `truncate()` 方法同时也会更新文件的指针。如果偏移小于大小，指针会保留原位。如果偏移大于大小，偏移会被设为相应的大小。这是为了确保随后的写入操作不会发生错误。

在流被关闭前，更改不会写入到磁盘上实际的文件，而是通常会被先写入到临时文件。

语法
--


```js
truncate(size)
```

### 参数

`size`

一个数字，表示要将流调整到的字节数。

### 返回值

一个 `Promise`，会兑现 `undefined`。

### 异常

`NotAllowedError` `DOMException`

如果 `PermissionStatus.state` (en-US) 不为 `granted`，抛出此异常。

`QuotaExceededError` `DOMException`

如果文件新的大小大于文件原来的大小并且超出了浏览器的存储配额，抛出此异常。

`TypeError`

如果 `size` 参数不是一个数字或者未定义，抛出此错误。

示例
--

下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 `FileSystemFileHandle`。由此，使用 `FileSystemFileHandle.createWritable()` 方法创建一个写入流。

然后我们按以下流程写入内容到流中：

1. 向流中写入一个字符串。
2. 使用 `truncate()` 方法将文件大小调整为 8 字节。
3. 向流中写入第二个字符串，覆写第一次写入的。

随后将流关闭。


```js
async function saveFile() {
  try {
    // 创建一个新句柄。
    const newHandle = await window.showSaveFilePicker();

    // 创建一个 FileSystemWritableFileStream 用于写入。
    const writableStream = await newHandle.createWritable();

    // 写入我们的文件。
    await writableStream.write("This is my first file content");
    await writableStream.truncate(8);
    await writableStream.write("my second file content");

    // 关闭文件并将内容写入磁盘。
    await writableStream.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```


如果你运行了上面的函数，然后打开磁盘上被创建的文件，你应该会看到文本“This is my second file content”。

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemwritablefilestream-truncate |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemWritableFileStream：write() 方法
=======================================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

`FileSystemWritableFileStream` 接口的 **`write()`** 方法用于在调用此方法的文件上的当前指针偏移处写入内容。

在流被关闭前，更改不会写入到磁盘上实际的文件，而是通常会被先写入到临时文件。这个方法也能被用于定位到流中的字节点位还有进行裁剪以改变文件内容的总字节数。

语法
--


```js
write(data)
```

### 参数

`data`

可以是以下之一：

* 用于写入的文件数据，可以是 `ArrayBuffer`、`TypedArray`、`DataView`、`Blob` 或字符串形式。
* 一个包含以下属性的对象：

`type`

一个字符串，值为 `"write"`、`"seek"` 或 `"truncate"`。

`data`

用于写入的文件数据，可以是 `ArrayBuffer`、`TypedArray`、`DataView`、`Blob` 或字符串形式。这个属性要求 `type` 被设为 `"write"`。

`position`

当 `type` 为 `"seek"` 时，表示文件当前指针应该移动到的位置。`type` 被设为 `"write"` 时也可以使用，这种情况下将会在指定的位置开始写入。

`size`

一个数字，表示流应当包含的字节数。这个属性要求 `type` 被设为 `"truncate"`。

### 返回值

一个 `Promise`，会兑现 `undefined`。

### 异常

`NotAllowedError` `DOMException`

如果 `PermissionStatus.state` (en-US) 不为 `granted`，抛出此异常。

`QuotaExceededError` `DOMException`

如果文件新的大小大于文件原来的大小并且超出了浏览器的存储配额，抛出此异常。

`TypeError`

如果未定义 `data` 或者 `position` 或 `size` 选项的值无效，抛出此错误。

示例
--

下面的异步函数会打开“保存文件”选择器，选择器在有文件被选择后会返回一个 `FileSystemFileHandle`。由此，使用 `FileSystemFileHandle.createWritable()` 方法创建一个写入流。

然后向流中写入一个文本字符串，随后关闭该流。


```js
async function saveFile() {
  try {
    // 创建一个新句柄。
    const newHandle = await window.showSaveFilePicker();

    // 创建一个 FileSystemWritableFileStream 用于写入。
    const writableStream = await newHandle.createWritable();

    // 写入我们的文件。
    await writableStream.write("This is my file content");

    // 关闭文件并将内容写入磁盘。
    await writableStream.close();
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```


下面的例子展示能够向 `write()` 方法传递的不同选项。


```js
// 只传递数据（没有选项）
writableStream.write(data);

// 向流中指定位置写入数据
writableStream.write({ type: "write", position, data });

// 将文件当前的指针更新到指定的偏移位置
writableStream.write({ type: "seek", position });

// 调整文件至指定字节长度
writableStream.write({ type: "truncate", size });
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemwritablefilestream-write |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
DataTransferItem：kind 属性
========================

只读属性 **`DataTransferItem.kind`** 返回代表*拖动数据项*的 `DataTransferItem` 对象的类别——字符串或文件。

值
-

一个表示拖动数据项类别的字符串。它必须是以下值之一：

`'file'`

拖动数据项是文件。

`'string'`

拖动数据项是*纯文本的 Unicode 字符串*。

示例
--

以下示例展示了 `kind` 属性的用法。


```js
function dropHandler(ev) {
  console.log("放置");
  ev.preventDefault();
  const data = event.dataTransfer.items;
  for (let i = 0; i < data.length; i += 1) {
    if (data[i].kind === "string" && data[i].type.match("^text/plain")) {
      // 该项目是目标节点
      data[i].getAsString((s) => {
        ev.target.appendChild(document.getElementById(s));
      });
    } else if (data[i].kind === "string" && data[i].type.match("^text/html")) {
      // 拖动数据项是 HTML
      console.log("… Drop: HTML");
    } else if (data[i].kind === "file" && data[i].type.match("^image/")) {
      // 拖动数据项是图像文件
      const f = data[i].getAsFile();
      console.log("……放置：文件");
    }
  }
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-datatransferitem-kind-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 拖放 API
* 拖动操作
* 推荐拖动类型
* DataTransfer 测试——粘贴和拖动