Clipboard API：Reactでのコピーと貼り付け

navigator.clipboard.writeText(text)は文字列をシステムクリップボードへ書き込み、Promiseを返します。これは従来のexecCommand方式に代わる最新の方法です。ユーザーがクリップボードへのアクセスを拒否した場合など、拒否される可能性があるため、必ずPromiseをawaitし、エラーを処理してください。

navigator.clipboard.readText()は現在のクリップボードの内容を文字列として読み取り、同じくPromiseを返します。読み取りにはclipboard-read権限が必要で、ブラウザーはユーザーに許可を求めます。一般的なReactアプリケーションでは、実際にはクリップボードの読み取りより書き込みを使う場面のほうが多くなります。

ブラウザーでは、clipboard.writeTextをクリックやkeydownイベントなどのユーザー操作のハンドラー内でしか呼び出せないように制限しています。useEffect内や、ユーザー操作の後に非同期で呼び出すと、セキュリティエラーが発生します。書き込みは必ずonClickハンドラーから直接実行してください。

標準的なパターンは次のとおりです。ユーザーがコピー用ボタンをクリックし、ハンドラーがnavigator.clipboard.writeText(value)を呼び出し、成功したらcopied状態をtrueに設定します。ボタンには一時的にチェックマークや「コピーしました！」というラベルを表示します。短い時間が経過すると、ボタンは通常の状態に戻ります。

ロジックをuseCopyToClipboardフックにまとめ、タプル[copied, copyFn]を返すようにします。copiedの真偽値がUIのフィードバックを制御し、copyFnはコピーするテキストを受け取ります。フック内で非同期の書き込みとエラー処理を行うため、コンポーネントをシンプルに保てます。

フック内では、コピーに成功した後にsetCopied(true)を設定し、setTimeout(() => setCopied(false), 2000)でリセットを予約します。タイムアウトIDを保存し、アンマウント後のstate更新を防ぐためにuseEffectのクリーンアップで解除してください。これにより、「アンマウントされたコンポーネントのstateは更新できません」という警告を避けられます。

古いブラウザーやHTTPSではないページはClipboard APIに対応していません。従来のフォールバックでは、一時的なtextareaを作成して値を設定し、bodyへ追加してからdocument.execCommand('copy')を呼び出し、要素を削除します。この方法は同期的に動作してどこでも使えますが、非推奨です。

Clipboard APIを使用する前に、次を確認します: navigator.clipboard && typeof navigator.clipboard.writeText === 'function'。利用できない場合は、従来のexecCommand方式にフォールバックします。この防御的なチェックにより、APIに対応していない環境での実行時エラーを防げます。

クリップボードの読み取りには、Permissions APIを介したユーザーの許可が必要です。現在の状態は次のように確認できます: navigator.permissions.query({ name: 'clipboard-read' })は、stateがgranted、denied、またはpromptのいずれかであるPermissionStatusを返します。readText()を呼び出すと、ブラウザーが自動的に許可を求めます。

Clipboard APIはセキュアコンテキスト（HTTPSまたはlocalhost）でのみ利用できます。HTTPページではnavigator.clipboardはundefinedです。クリップボードの内容には機密情報が含まれる可能性があるため、これはセキュリティ上の制限です。メソッドを参照する前に、APIが利用可能か必ず確認してnull参照エラーを避けてください。

Jestで使用されるjsdomはClipboard APIを実装していません。テストセットアップでモックします：Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } })。これにより、実際のブラウザ環境がなくても、コンポーネントが正しい引数でwriteTextを呼び出すことをテストできます。

ブラウザでnavigator.clipboard.writeText()を安全に呼び出せるのはどのような場合ですか？

テキストをコピーするには、クリックハンドラー内でnavigator.clipboard.writeText()を使用します。一定時間後にリセットされる[copied, copyFn]を返すuseCopyToClipboardフックを作成します。必ずAPIが利用可能か確認し、古いブラウザ向けにexecCommandのフォールバックを用意し、Jestのテストではnavigator.clipboardをモックしてください。