Reactで画像をクリップボードにコピーするボタンを作る方法

​​React​Canvas,Clipboard API,Playwright,TypeScript

チャットや資料に貼り付けたいグラフや画像を、ボタン1つでクリップボードに入れられます。画像のコピーには、文字列の writeText() ではなく、ClipboardItem に画像の Blob を入れて navigator.clipboard.write() に渡します。

私は検証環境で、JPEG の画像、PNG の画像、canvas に描いたグラフの3つにコピーボタンを付けた画面を作りました。Chromium を Playwright で操作し、クリップボードに入った画像と、貼り付けた結果を確かめています。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。使ったのは react / react-dom 19.3.1、@types/react 19.3.0、TypeScript 7.0.2、esbuild 0.28.2 です。tsc で型チェックしてから esbuild の開発用ビルドで変換し、<StrictMode> で包んで動かしました。ブラウザは Playwright 1.63.0 で起動した Chromium 153(headless)で、ページは http://localhost:5173 から開いています。Firefox と Safari、スマホのブラウザ、SVG や複数の形式を1つの ClipboardItem に入れる書き方は試していません。貼り付けは同じページの貼り付け欄で確かめただけで、ほかのアプリへの貼り付けは試していません。

ポイント

クリップボードに書く画像は PNG にします。JPEG などは canvas で描き直してから渡します。navigator.clipboard.write() はクリックの直後に呼び、画像の取得や変換を待つ間は、Blob の代わりに「あとで Blob になる Promise」を ClipboardItem に入れておきます。

ClipboardItem で PNG を書く

いちばん短い形は、PNG の Blob を 'image/png' というキーで ClipboardItem に入れ、配列にして write() に渡すものです。ClipboardItem() コンストラクタの説明にあるとおり、値には Blob か文字列のほか、それらになる Promise も渡せます。

ts
// copyImage.ts
// 画像をクリップボードに書けるブラウザかどうか
export function canCopyImage(): boolean {
  return typeof ClipboardItem !== 'undefined' && typeof navigator.clipboard?.write === 'function';
}

// PNG の Blob(または、あとで PNG の Blob になる Promise)をクリップボードに書く
export function copyImage(png: Blob | Promise<Blob>): Promise<void> {
  return navigator.clipboard.write([new ClipboardItem({ 'image/png': png })]);
}

形式を PNG に決めているのは、どのブラウザでも書けるのが PNG だからです。MDN の Clipboard API の説明では、ブラウザが必ず対応する形式は text/plain、text/html、image/png の3つで、ほかの形式は任意です。

形式ごとに書けるかどうかは、ClipboardItem.supports() で調べられます。検証環境の Chromium 153 で試したところ、結果は次のとおりでした。

形式 supports() の結果
image/png true
image/svg+xml true
image/jpeg false
image/webp false
image/gif false

JPEG は canvas で PNG に描き直す

JPEG 形式の写真などは、そのまま write() に渡しても書けません。Chromium 153 で、クリックの処理の中で試すと、次のように NotAllowedError になりました。

渡したもの 結果(Chromium 153)
'image/jpeg' をキーにして JPEG の Blob NotAllowedError:Type image/jpeg not supported on write.
'image/png' をキーにして JPEG の Blob NotAllowedError:Type image/png does not match the blob's type image/jpeg
'image/png' をキーにして、type が空の Blob NotAllowedError:Type image/png does not match the blob's type

キーを 'image/png' にしても、Blob の type が合っていなければ書けません。new Blob([...]) のように type を付けずに作った Blob も同じです。そこで、PNG 以外の画像は一度 canvas に描き、toBlob() で PNG にします。

ts
// copyImage.ts(続き)
// canvas の中身を PNG の Blob にする
export function canvasToPng(canvas: HTMLCanvasElement): Promise<Blob> {
  return new Promise((resolve, reject) => {
    canvas.toBlob((blob) => {
      if (blob) resolve(blob);
      else reject(new Error('PNG に変換できませんでした'));
    }, 'image/png');
  });
}

// URL の画像を取得して、PNG の Blob にする。PNG 以外は canvas で描き直す
export async function fetchAsPng(url: string): Promise<Blob> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`画像を取得できませんでした(${res.status})`);
  const blob = await res.blob();
  if (blob.type === 'image/png') return blob;

  const bitmap = await createImageBitmap(blob);
  const canvas = document.createElement('canvas');
  canvas.width = bitmap.width;
  canvas.height = bitmap.height;
  canvas.getContext('2d')!.drawImage(bitmap, 0, 0);
  bitmap.close();
  return canvasToPng(canvas);
}

res.blob() で得た Blob の type は、サーバーが返した Content-Type になります。検証用のサーバーは .png を image/png、.jpg を image/jpeg で返すので、JPEG だけが canvas を通ります。この形で 240×120 の JPEG をコピーし、navigator.clipboard.read() で読み戻すと、中身は image/png の 240×120 の画像1つでした。

canvas に描いたグラフなら、fetch はいらず、canvasToPng() だけで済みます。

クリックのあと時間をおいて write を呼ぶと失敗する

fetchAsPng() は画像の取得や変換を待つので、すぐには終わりません。ここで気を付けたいのが、write() を呼ぶタイミングです。MDN の Clipboard API のセキュリティの説明によると、Chromium 系のブラウザでは、書き込みに clipboard-write の許可か、ユーザーが操作した直後であること(transient activation)が必要です。Firefox と Safari では、操作した直後であることが必要です。

検証環境で、ボタンを押してから PNG を取得し、さらに待ってから write() を呼ぶ書き方と、押してすぐ write() を呼んで、同じだけ待つ Promise を ClipboardItem に入れる書き方を比べました。Playwright で、クリップボードの許可を指定せずに作ったブラウザのコンテキストで試しています。fetchPng() は /sample.png を fetch して Blob を返す関数、wait(ms) は ms ミリ秒待つ関数です。

ts
// 待ってから write を呼ぶ
const blob = await fetchPng();
await wait(ms);
await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })]);

// すぐ write を呼び、待つのは ClipboardItem の中の Promise
await navigator.clipboard.write([
  new ClipboardItem({ 'image/png': fetchPng().then(async (b) => { await wait(ms); return b; }) }),
]);
押してから PNG ができるまで 待ってから write() Promise を渡して、すぐ write()
すぐ 成功 成功
1秒 成功 成功
6秒 NotAllowedError(Write permission denied.) 成功

6秒待ってから呼んだときだけ失敗しました。このコンテキストでは、navigator.permissions.query() で調べた clipboard-write は granted でした。MDN の説明では、許可があれば操作した直後でなくても書けることになっていますが、それでも失敗しています。Promise を渡した書き方では、6秒後に PNG ができてから書き込まれ、成功しています。仕様(Clipboard API and events の write() の手順)でも、書いてよいかの確認は write() を呼んだときに行い、Promise の結果はそのあとで受け取る順になっています。

画像の取得や変換にかかる時間は、画像の大きさや通信の状態で変わります。待ってから呼ぶ書き方は、ふだんは成功しても、遅いときだけ失敗することがあります。このあと作るフックでは、取得と変換を待たずに、その Promise を write() に渡します。

React のフックとコピーボタン

コピーの処理と、ボタンの表示の切り替えをフックにまとめます。getPng には、PNG の Blob を返す非同期関数を渡します。

ts
// useCopyImage.ts
import { useCallback, useState } from 'react';
import { canCopyImage, copyImage } from './copyImage';

type Status = 'idle' | 'copying' | 'copied' | 'error';

export function useCopyImage() {
  const [status, setStatus] = useState<Status>('idle');
  const [error, setError] = useState('');

  // getPng は PNG の Blob を返す非同期関数。終わるのを待たずに write に渡す
  const copy = useCallback(async (getPng: () => Promise<Blob>) => {
    if (!canCopyImage()) {
      setStatus('error');
      setError('このブラウザでは画像をコピーできません');
      return;
    }
    setStatus('copying');
    try {
      await copyImage(getPng());
      setStatus('copied');
    } catch (e) {
      setStatus('error');
      setError(e instanceof Error ? `${e.name}: ${e.message}` : String(e));
    }
  }, []);

  return { status, error, copy };
}

大事なのは await copyImage(getPng()) の1行です。getPng() は Promise をすぐに返すので、write() はクリックの処理の中で、何も待たずに呼ばれます。クリップボードの許可を指定しないコンテキストでも、このフックを使ったボタンは「コピーしました」に変わりました。

ボタンは、状態に合わせて文字を変えます。

tsx
// CopyImageButton.tsx
import { useCopyImage } from './useCopyImage';

const labels = {
  idle: '画像をコピー',
  copying: 'コピー中…',
  copied: 'コピーしました',
  error: 'コピーできませんでした',
} as const;

type Props = { getPng: () => Promise<Blob> };

export function CopyImageButton({ getPng }: Props) {
  const { status, error, copy } = useCopyImage();
  return (
    <div>
      <button type="button" onClick={() => copy(getPng)} disabled={status === 'copying'}>
        {labels[status]}
      </button>
      <p role="status" className="status">
        {status === 'error' ? error : ''}
      </p>
    </div>
  );
}

使う側では、画像の URL か canvas から PNG を作る関数を渡します。canvas は ref で受け取ります。

tsx
<img src="/sample.jpg" alt="JPEG のサンプル画像" width={240} height={120} />
<CopyImageButton getPng={() => fetchAsPng('/sample.jpg')} />

<canvas ref={canvasRef} width={240} height={120} />
<CopyImageButton getPng={() => canvasToPng(canvasRef.current!)} />

検証用の画面には、コピーできたかを目で確かめるために、paste イベントで受け取った画像を表示する欄も置きました。JPEG の画像の「画像をコピー」を押してから、その欄で Ctrl+V を押した様子です。

JPEG の画像の下にある「画像をコピー」ボタンを押すと「コピーしました」に変わり、下の貼り付け欄をクリックして Ctrl+V を押すと、同じ画像と「貼り付けた画像:image/png、240×120」が表示される様子
「画像をコピー」を押してから、貼り付け欄に Ctrl+V で貼り付けるまでの動き

PNG の画像と canvas のグラフでも、ボタンは「コピーしました」に変わりました。貼り付け欄には、どれも image/png の 240×120 の画像が入りました。

コピーできないときの表示

画像のコピーは、安全なコンテキストでしか使えません(write() の説明)。検証環境で、localhost ではないホスト名の http://example.com:5173 として同じ画面を開くと(ブラウザの起動オプションで、example.com を検証用サーバーに向けています)、isSecureContext が false になりました。navigator.clipboard も ClipboardItem も undefined です。このページでボタンを押すと、canCopyImage() が false を返すので、ボタンは「コピーできませんでした」になり、下に「このブラウザでは画像をコピーできません」と出ました。

ClipboardItem に渡した Promise が reject されたとき、つまり画像の取得や変換に失敗したときの扱いも確かめました。Chromium 153 では、write() は NotAllowedError ではなく、その Promise の reject の理由(ここでは new Error('取得に失敗'))で reject されました。仕様の write() の手順では、この場合は NotAllowedError になると書かれていますが、Chromium 153 の動きはこれとは違いました。フックでは e.name と e.message をそのまま出し、どちらの場合も表示できるようにしています。

ブラウザの対応状況

MDN の互換性データでは、ClipboardItem は Chrome 76、Firefox 127、Safari 13.1 から使えます。ただし Chrome は、97 までは値に Blob しか渡せず、Promise も渡せるようになったのは 98 からです。ClipboardItem.supports() は Chrome 121、Firefox 127、Safari 18.4 からです。

write() の互換性データには、Chrome と Firefox は ClipboardItem を1つしか受け付けず、2つ以上渡すと NotAllowedError になると書かれています。そのため、この2つのブラウザでは画像を何枚もまとめてコピーできません。1回のコピーで書く画像は1枚にします。

​Posted by 86