Clipboard.read()

Clipboard インターフェイスの read() メソッドは、クリップボードの内容のコピーを要求し、戻り値の Promise が解決されたときにそのデータを取得できます。readText() とは異なり、read() メソッドは画像など任意のデータを取得することができます。

クリップボードから読み込みを行うためには、まず "clipboard-read" パーミッションを取得する必要があります。

注意: 非同期の Clipboard API と Permissions API は、ほとんどのブラウザーでは組み込み途中の状態です。そのため、パーミッションなどが公式仕様とは異なっていることがよくあります。これらのメソッドを使う前に ブラウザー実装状況 を確認してください。

構文

var promise = navigator.clipboard.read();

パラメーター

なし。

戻り値

クリップボードの内容を持つ DataTransfer に解決される、Promise オブジェクト。クリップボードへのアクセスが許可されない場合、この Promise は拒否される。

この使用例は、最初に navigator.permissions.query() を使って "clipboard-read" 権限があるかどうか (またはプロンプトによってユーザーがそれを許可するかどうか) を調べ、その後クリップボードに現在あるデータを取得します。もしデータがプレーンテキストでない場合、エラーメッセージを表示します。そうでない場合は、変数 textElem により参照している要素の内容を、クリップボードの内容に置き換えます。

// まず、Permissions API を使って、
// "clipboard-read" 機能を使えるかどうか確認します。

navigator.permissions.query({name: "clipboard-read"}).then(result => {
  // クリップボードの読み取りが許可されているか、またはプロンプトによって
  // ユーザーがそれを許可する場合、処理を続行します。

  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("クリップボードの内容がテキストでないため、読み込めません。");
        } else {
          textElem.innerText = data.items[i].getAs("text/plain");
        }
      }
    });
  }
});

注意: 現時点で Firefox は read() を実装していますが、"clipboard-read" パーミッションは認識できません。そのため、Permissions API を使ってこの API にアクセスしようとしても、失敗するでしょう。

日本語訳注: 翻訳時点 (2020/02/15) で、この使用例は Google Chrome (v80) でも実行できなくなっています。クリップボードから取得するデータの型が DataTransfer から ClipboardItems に変更されるなど、仕様が変更されているためです。

仕様

仕様書 策定状況 コメント
Clipboard API and events
read() の定義
草案 初回定義

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
readChrome 部分対応 76
補足
部分対応 76
補足
補足 From version 76, the image/png MIME type is supported.
部分対応 66
補足
補足 Images are not supported.
Edge 完全対応 79Firefox 完全対応 63
補足 無効
完全対応 63
補足 無効
補足 Currently works just like readText(); non-text content is not currently supported.
無効 From version 63: this feature is behind the dom.events.asyncClipboard.dataTransfer preference (needs to be set to true). To change preferences in Firefox, visit about:config.
IE 未対応 なしOpera 完全対応 63Safari 完全対応 13.1WebView Android 部分対応 84
補足
部分対応 84
補足
補足 From version 84, the image/png MIME type is supported.
部分対応 66
補足
補足 Images are not supported.
Chrome Android 部分対応 84
補足
部分対応 84
補足
補足 From version 84, the image/png MIME type is supported.
部分対応 66
補足
補足 Images are not supported.
Firefox Android 完全対応 63
補足 無効
完全対応 63
補足 無効
補足 Currently works just like readText(); non-text content is not currently supported.
無効 From version 63: this feature is behind the dom.events.asyncClipboard.dataTransfer preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera Android 完全対応 54Safari iOS 完全対応 13.4Samsung Internet Android 完全対応 12.0

凡例

完全対応  
完全対応
部分対応  
部分対応
未対応  
未対応
実装ノートを参照してください。
実装ノートを参照してください。
ユーザーが明示的にこの機能を有効にしなければなりません。
ユーザーが明示的にこの機能を有効にしなければなりません。