From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- files/zh-cn/web/api/clipboard/index.html | 89 ++++++++++++++++++++++ files/zh-cn/web/api/clipboard/read/index.html | 84 ++++++++++++++++++++ files/zh-cn/web/api/clipboard/readtext/index.html | 68 +++++++++++++++++ files/zh-cn/web/api/clipboard/write/index.html | 76 ++++++++++++++++++ files/zh-cn/web/api/clipboard/writetext/index.html | 68 +++++++++++++++++ 5 files changed, 385 insertions(+) create mode 100644 files/zh-cn/web/api/clipboard/index.html create mode 100644 files/zh-cn/web/api/clipboard/read/index.html create mode 100644 files/zh-cn/web/api/clipboard/readtext/index.html create mode 100644 files/zh-cn/web/api/clipboard/write/index.html create mode 100644 files/zh-cn/web/api/clipboard/writetext/index.html (limited to 'files/zh-cn/web/api/clipboard') diff --git a/files/zh-cn/web/api/clipboard/index.html b/files/zh-cn/web/api/clipboard/index.html new file mode 100644 index 0000000000..834376f01e --- /dev/null +++ b/files/zh-cn/web/api/clipboard/index.html @@ -0,0 +1,89 @@ +--- +title: Clipboard +slug: Web/API/Clipboard +tags: + - API + - Clipboard + - 剪切 + - 剪切板 + - 剪贴板 + - 参考 + - 复制 + - 接口 + - 粘贴 + - 编辑 +translation_of: Web/API/Clipboard +--- +
{{APIRef("Clipboard API")}}
+ +

Clipboard 接口实现了 Clipboard API，如果用户授予了相应的权限，就能提供系统剪贴板的读写访问。在 Web 应用程序中，Clipboard API 可用于实现剪切、复制和粘贴功能。

+ +

系统剪贴板暴露于全局属性 {{domxref("Navigator.clipboard")}} 之中。

+ +

如果用户没有适时使用 Permissions API 授予相应权限和"clipboard-read" 或 "clipboard-write" 权限，调用 Clipboard 对象的方法不会成功。

+ +
+

注意：实际上，现在浏览器对于访问剪贴板权限的索取各有不同，在章节 {{anch("剪贴板可用性")}} 查看更多细节。

+
+ +

所有剪贴板 API 方法都是异步的；它们返回一个 {{jsxref("Promise")}} 对象，在剪贴板访问完成后被执行。如果剪贴板访问被拒绝，promise 也会被拒绝。

+ +
+

剪贴板 是用于短期数据储存或转移的数据缓存区，数据转移可以发生在文档和应用程序之间。剪贴板常常实现为一个匿名的、临时的 数据缓存，有时也叫做粘贴缓存，可由绝大部分位于已定义编程接口的环境中的程序访问。

+ +

一个典型的应用程序常通过将 用户输入 如 组合键, 菜单选择 等映射到这些接口来访问剪贴板。

+
+ +

方法

+ +

Clipboard 继承自 {{domxref("EventTarget")}} 接口，因此拥有它的方法。

+ +
+
{{domxref("Clipboard.read()","read()")}}
+
从剪贴板读取数据（比如图片），返回一个 {{jsxref("Promise")}} 对象。When the data has been retrieved, the promise is resolved with a {{domxref("DataTransfer")}} object that provides the data。
+
{{domxref("Clipboard.readText()","readText()")}}
+
从操作系统读取文本；returns a Promise which is resolved with a {{domxref("DOMString")}} containing the clipboard's text once it's available。
+
{{domxref("Clipboard.write()","write()")}}
+
写入任意数据至操作系统剪贴板。This asynchronous operation signals that it's finished by resolving the returned Promise。
+
{{domxref("Clipboard.writeText()","writeText()")}}
+
写入文本至操作系统剪贴板。returning a Promise which is resolved once the text is fully copied into the clipboard。
+
+ +

剪贴板可用性

+ +

异步剪贴板 API 是一个相对较新的 API，浏览器仍在逐渐实现它。由于潜在的安全问题和技术复杂性，大多数浏览器正在逐步集成这个 API。

+ +

例如，Firefox 不支持 "clipboard-read" 和 "clipboard-write" 权限，所以使用其他方式访问或改变剪贴板中的内容会受限。

+ +

对于浏览器扩展来说，你可以要求 clipboardRead 和 clipboardWrite 权限以使用 clipboard.readText() 和 clipboard.writeText()。但基于 HTTP 的网站中包含的脚本则不能获得剪贴板对象。参考 extensions in Firefox 63。

+ +

除此之外, {{domxref("Clipboard.read", "read()")}} 以及{{domxref("Clipboard.write", "write()")}} 是默认禁用且需要修改偏好设置来启用的。在使用之前请先确认浏览器兼容性表格。

+ +

规范

+ + + + + + + + + + + + + + +
规范状态备注
{{SpecName('Clipboard API','#clipboard-interface','Clipboard')}}{{Spec2('Clipboard API')}}Initial definition.
+ +

浏览器兼容性

+ + + +

{{Compat("api.Clipboard")}}

+ +

参见

+ + diff --git a/files/zh-cn/web/api/clipboard/read/index.html b/files/zh-cn/web/api/clipboard/read/index.html new file mode 100644 index 0000000000..7b0ffa7bda --- /dev/null +++ b/files/zh-cn/web/api/clipboard/read/index.html @@ -0,0 +1,84 @@ +--- +title: Clipboard.read() +slug: Web/API/Clipboard/read +tags: + - API + - Clip + - Clipboard + - Clipboard API + - read +translation_of: Web/API/Clipboard/read +--- +
{{APIRef("Clipboard API")}}
+ +

The read() method of the {{domxref("Clipboard")}} interface requests a copy of the clipboard's contents, delivering the data to the returned {{jsxref("Promise")}} when the promise is resolved. Unlike {{domxref("Clipboard.readText", "readText()")}}, the read() method can return arbitrary data, such as images.

+ +

To read from the clipboard, you must first have the "clipboard-read" permission.

+ +
+

Note: The asynchronous Clipboard and Permissions APIs are still in the process of being integrated into most browsers, so they often deviate from the official rules for permissions and the like. Be sure to review the {{anch("Browser compatibility", "compatibility table")}} before using these methods.

+
+ +

语法

+ +
var promise = navigator.clipboard.read();
+ +

Parameters

+ +

None.

+ +

Return value

+ +

A {{jsxref("Promise")}} that resolves with a {{domxref("DataTransfer")}} object containing the clipboard's contents. The promise is rejected if permission to access the clipboard is not granted.

+ +

例子

+ +

After using {{domxref("Permissions.query", "navigator.permissions.query()")}} to find out if we have (or if the user will be prompted to allow) "clipboard-read" access, this example fetches the data currently on the clipboard. If it's not plain text, an error message is presented. Otherwise, an element referred to using the variable textElem has its contents replaced with the clipboard's contents.

+ +
// First, ask the Permissions API if we have some kind of access to
+// the "clipboard-read" feature.
+
+navigator.permissions.query({name: "clipboard-read"}).then(result => {
+  // If permission to read the clipboard is granted or if the user will
+  // be prompted to allow it, we proceed.
+
+  if (result.state == "granted" || result.state == "prompt") {
+    navigator.clipboard.read().then(data => {
+      for (let i=0; i<data.items.length; i++) {
+        if (data.items[i].type != "text/plain") {
+          alert("Clipboard contains non-text data. Unable to access it.");
+        } else {
+          textElem.innerText = data.items[i].getAs("text/plain");
+        }
+      }
+    });
+  }
+});
+
+ +
+

Note: At this time, while Firefox does implement read(), it does not recognize the "clipboard-read" permission, so attempting to use the Permissions API to manage access to the API will not work.

+
+ +

规范

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('Clipboard API','#h-clipboard-read','read()')}}{{Spec2('Clipboard API')}}Initial definition.
+ +

浏览器兼容性

+ + + +

{{Compat("api.Clipboard.read")}}

diff --git a/files/zh-cn/web/api/clipboard/readtext/index.html b/files/zh-cn/web/api/clipboard/readtext/index.html new file mode 100644 index 0000000000..44f5d76e5e --- /dev/null +++ b/files/zh-cn/web/api/clipboard/readtext/index.html @@ -0,0 +1,68 @@ +--- +title: Clipboard.readText() +slug: Web/API/Clipboard/readText +tags: + - API + - Async Clipboard API + - Clip + - Clipboard + - readText + - 复制 + - 粘贴 +translation_of: Web/API/Clipboard/readText +--- +
{{APIRef("Clipboard API")}}
+ +
{{domxref("Clipboard")}} 接口的readText()方法解析系统剪贴板的文本内容返回一个{{jsxref("Promise")}} 。
+ +

语法

+ +
var promise = navigator.clipboard.readText()
+ +

参数

+ +

None.

+ +

返回值

+ +

A {{jsxref("Promise")}} that resolves with a {{domxref("DOMString")}} containing the textual contents of the clipboard. Returns an empty string if the clipboard is empty, does not contain text, or does not include a textual representation among the {{domxref("DataTransfer")}} objects representing the clipboard's contents.

+ +

要从剪贴板中读取非文本内容，请改用{{domxref("Clipboard.read", "read()")}}方法。您可以使用 {{domxref("Clipboard.writeText", "writeText()")}}将文本写入剪贴板

+ +

例子

+ +

此示例检索剪贴板的文本内容，并将返回的文本插入元素的内容中。

+ +
navigator.clipboard.readText().then(
+  clipText => document.getElementById("outbox").innerText = clipText);
+ +

规范

+ + + + + + + + + + + + + + +
规范状态注解
{{SpecName('Clipboard API','#h-clipboard-readtext','readText()')}}{{Spec2('Clipboard API')}}Initial definition.
+ +

浏览器兼容性

+ + + +

{{Compat("api.Clipboard.readText")}}

+ +

See also

+ + diff --git a/files/zh-cn/web/api/clipboard/write/index.html b/files/zh-cn/web/api/clipboard/write/index.html new file mode 100644 index 0000000000..a7f69da118 --- /dev/null +++ b/files/zh-cn/web/api/clipboard/write/index.html @@ -0,0 +1,76 @@ +--- +title: Clipboard.write() +slug: Web/API/Clipboard/write +translation_of: Web/API/Clipboard/write +--- +

{{APIRef("Clipboard API")}}

+ +
 
+ +

 

+ +
 
+ +

{{domxref("Clipboard")}} 的方法 write() 写入图片等任意的数据到剪贴板。 这个方法可以用于实现剪切和复制的功能。

+ +

但是你要提前获取 "Permissions API" 的 "clipboard-write" 权限才能将数据写入到剪贴板。

+ +
+

注意: 浏览器对这个异步剪贴板的 API 仍然在讨论中。所以在使用它之前请检查 {{anch("Browser compatibility", "compatibility table")}} 和 {{SectionOnPage("/en-US/docs/Web/API/Clipboard", "Clipboard availability")}} 以获得更多的兼容性信息。

+
+ +

语法

+ +
var promise = navigator.clipboard.write(dataTransfer)
+ +

参数

+ +
+
dataTransfer
+
{{domxref("DataTransfer")}} 对象包含了要写入剪贴板的数据。
+
+ +

返回值

+ +

当数据被写入到剪贴板的时候，{{jsxref("Promise")}} resolve 回调被执行。如果剪贴板不能完成剪贴操作，{{jsxref("Promise")}}  reject 回调被执行。

+ +

示例

+ +

这个例子展示了如何将当前剪贴板的内容替换为给定的内容。

+ +
function setClipboard(text) {
+  let data = new DataTransfer();
+
+  data.items.add("text/plain", text);
+  navigator.clipboard.write(data).then(function() {
+    /* success */
+  }, function() {
+    /* failure */
+  });
+}
+
+ +

代码创建了一个 {{domxref("DataTransfer")}} 对象，要替换的内容存储在这里。执行 {{domxref("DataTransferItemList.add()")}} 将数据写入进去，然后执行 write() 方法，指定执行成功或错误的结果。

+ +

规范

+ + + + + + + + + + + + + + +
规范状态备注
{{SpecName('Clipboard API','#h-clipboard-write-data','write()')}}{{Spec2('Clipboard API')}}Initial definition.
+ +

浏览器兼容性

+ + + +

{{Compat("api.Clipboard.write")}}

diff --git a/files/zh-cn/web/api/clipboard/writetext/index.html b/files/zh-cn/web/api/clipboard/writetext/index.html new file mode 100644 index 0000000000..e60e7204fe --- /dev/null +++ b/files/zh-cn/web/api/clipboard/writetext/index.html @@ -0,0 +1,68 @@ +--- +title: Clipboard.writeText() +slug: Web/API/Clipboard/writeText +tags: + - API + - Clip + - Clipboard + - Clipboard API + - writeText +translation_of: Web/API/Clipboard/writeText +--- +
{{APIRef("Clipboard API")}}
+ +

{{domxref("Clipboard")}} 接口的 writeText() 方法可以写入特定字符串到操作系统的剪切板。

+ +
+

Note: 规范要求在写入剪贴板之前使用 Permissions API 获取“剪贴板写入”权限。但是，不同浏览器的具体要求不同，因为这是一个新的API。有关详细信息，请查看{{anch("Browser compatibility", "compatibility table")}} and {{SectionOnPage("/en-US/docs/Web/API/Clipboard", "Clipboard availability")}}。

+
+ +

语法

+ +
var promise = navigator.clipboard.writeText(newClipText)
+ +

参数

+ +
+
newClipText
+
The {{domxref("DOMString")}} to be written to the clipboard.
+
+

返回值

+
+
+ +

一个{{jsxref("Promise")}} ，一旦剪贴板的内容被更新，它就会被解析。如果调用者没有写入剪贴板的权限，则拒绝写入剪切板（reject）

+ +

例子

+ +

此示例将剪贴板的内容设置为字符串“<empty clipboard>”。

+ +
navigator.clipboard.writeText("<empty clipboard>").then(function() {
+  /* clipboard successfully set */
+}, function() {
+  /* clipboard write failed */
+});
+
+ +

规范

+ + + + + + + + + + + + + + +
规范状态注解
{{SpecName('Clipboard API','#h-clipboard-writetext-data','writeText()')}}{{Spec2('Clipboard API')}}Initial definition.
+ +

浏览器兼容性

+ + + +

{{Compat("api.Clipboard.writeText")}}

-- cgit v1.2.3-54-g00ecf