クリップボード操作ライブラリの技術的比較：clipboard-copy から vue-clipboard2 まで

Webアプリで「コピー」ボタンを実装する際、多くの開発者は document.execCommand('copy') の複雑さやブラウザ間の差異に直面します。ここで紹介する5つのnpmパッケージは、その課題を解決するために設計されていますが、それぞれが異なるアプローチとトレードオフを持っています。以下では、実際のコード例を交えながら、技術的な違いと選定基準を詳しく見ていきます。

🧩 基本的な使い方：関数 vs コンポーネント vs ディレクティブ

clipboard-copy

このパッケージは、単一の関数をエクスポートする軽量モジュールです。引数として文字列を受け取り、Promiseを返します。

import copy from 'clipboard-copy';

async function handleCopy() {
  try {
    await copy('コピーしたいテキスト');
    console.log('コピー成功');
  } catch (err) {
    console.error('コピー失敗', err);
  }
}

内部で navigator.clipboard.writeText() を使用し、それが利用できない環境では一時的な <textarea> 要素を作成してフォールバックします。依存関係がなく、どのフレームワークでも使えます。

copy-to-clipboard

こちらも関数ベースですが、より詳細な制御が可能です。オプションでフォールバック動作を調整できます。

import copy from 'copy-to-clipboard';

// 成功/失敗をbooleanで返す（非Promise）
const success = copy('テキスト', {
  debug: true, // デバッグログ出力
  message: 'Cmd+C to copy' // フォールバック時のヒントメッセージ
});

if (success) {
  console.log('コピー成功');
}

Promiseを返すオプションはありませんが、navigator.clipboard の可用性に応じて自動的に最適な方法を選択します。

ngclipboard

Angular向けのディレクティブとして動作します。テンプレート内で属性として使用します。

// app.module.ts
import { NgClipboardModule } from 'ngclipboard';

@NgModule({
  imports: [NgClipboardModule]
})
export class AppModule {}

<!-- template.html -->
<button ngClipboard [cbContent]="'コピー対象の文字列'">コピー</button>

ただし、Angular 9以降では公式の @angular/cdk/clipboard が推奨されており、ngclipboard はメンテナンスが停滞している可能性があるため、新規プロジェクトでの使用は避けるべきです。

react-copy-to-clipboard

Reactコンポーネントとして提供され、子要素をラップして使用します。

import { CopyToClipboard } from 'react-copy-to-clipboard';

function App() {
  const [copied, setCopied] = useState(false);

  return (
    <CopyToClipboard text="コピーしたいテキスト" onCopy={() => setCopied(true)}>
      <button>{copied ? 'コピー済み' : 'コピー'}</button>
    </CopyToClipboard>
  );
}

内部で copy-to-clipboard を呼び出しているため、React特有の抽象レイヤーが追加されるだけです。シンプルな実装には便利ですが、パフォーマンスに極端に敏感なケースでは直接 copy-to-clipboard を使う方が効率的です。

vue-clipboard2

Vue 2向けのプラグインで、ディレクティブ経由で使用します。

// main.js
import Vue from 'vue';
import VueClipboard from 'vue-clipboard2';

Vue.use(VueClipboard);

<template>
  <button v-clipboard:copy="message" v-clipboard:success="onCopySuccess">
    コピー
  </button>
</template>

<script>
export default {
  data() {
    return { message: 'コピーしたいテキスト' };
  },
  methods: {
    onCopySuccess() {
      alert('コピー成功！');
    }
  }
};
</script>

Vue 3では動作しないため、Vue 3プロジェクトでは @vueuse/core の useClipboard を使用することを強く推奨します。

🔒 セキュリティと権限モデル

現代のブラウザでは、navigator.clipboard.writeText() はユーザーの明示的な操作（例：クリック）がトリガーである場合にのみ許可されます。すべてのライブラリがこの制約を尊重していますが、フォールバック動作の実装方法に違いがあります。

• clipboard-copy と copy-to-clipboard は、navigator.clipboard が利用可能であればそれを使用し、そうでなければ一時的な <textarea> を作成して select() + execCommand('copy') を実行します。これはセキュリティ上安全ですが、古いブラウザではユーザーに警告が表示される可能性があります。

• ngclipboard, react-copy-to-clipboard, vue-clipboard2 はそれぞれのフレームワークのイベントシステム内から呼び出されるため、ユーザー操作のコンテキストが保たれやすく、権限エラーが発生しにくい設計になっています。

🔄 非同期処理の扱い

コピー操作は本質的に非同期ですが、各ライブラリのハンドリング方法は異なります。

• clipboard-copy: Promiseを返すため、async/await で自然に扱えます。
• copy-to-clipboard: 同期的にbooleanを返しますが、内部で非同期APIを使用する場合でも即座に結果を返すため、実際のコピー完了を正確に検知できません。
• react-copy-to-clipboard: onCopy コールバックで結果を通知しますが、これは内部の copy-to-clipboard の戻り値に基づくため、Promiseのような正確な非同期制御はできません。
• ngclipboard と vue-clipboard2: イベント駆動で成功/失敗を通知しますが、非同期の詳細は隠蔽されています。

正確な非同期制御が必要な場合は、clipboard-copy が最も適しています。

⚠️ 非推奨と代替手段

• ngclipboard: Angular公式のCDK Clipboardが存在するため、新規プロジェクトではそちらを使用すべきです。ngclipboard はメンテナンスが活発でない可能性があります。
• vue-clipboard2: Vue 3非対応であり、Vue 2のサポート終了に伴い将来的に使用できなくなる可能性があります。Vue 3では @vueuse/core を推奨します。

📌 実践的な選定ガイド

💡 最終的なアドバイス

クリップボード操作は一見単純に見えますが、ブラウザのセキュリティモデルや非同期処理の扱いによって意外と複雑です。ライブラリを選ぶ際は、以下の点を確認してください：

1. フレームワークのバージョン — Vue 3やAngular最新版では、公式またはコミュニティ主導の新しい代替手段が存在します。
2. 非同期制御の必要性 — 正確な成功/失敗のハンドリングが必要なら、Promiseを返す clipboard-copy が最適です。
3. バンドルサイズ — 軽量さを重視するなら、依存関係のない clipboard-copy か copy-to-clipboard を選びましょう。

これらのポイントを踏まえて、プロジェクトの要件に最も合うライブラリを選んでください。