@rescript-tauri/plugin-clipboard-manager

Tauri 2.x クリップボードプラグイン の ReScript バインディングです。テキスト、HTML、画像の読み書きを提供します。

注釈

本パッケージは main で機能完備済みです。初回 npm 公開は他のパッケージと合わせて予定されています。それまでは、ソースリポジトリ経由かワークスペースリンクで利用してください。

Tip

画像 API (writeImage / readImage) は @rescript-tauri/core の Image モジュールを直接再利用しており、本パッケージ独自の画像型は持ちません。Core.Image.fromPath か Core.Image.fromBytes で Image.t を構築して writeImage に渡し、クリップボード上の画像バイト列は Core.Image.rgba で参照してください。

インストール

pnpm add @rescript-tauri/plugin-clipboard-manager @tauri-apps/plugin-clipboard-manager

@rescript-tauri/plugin-clipboard-manager は @rescript-tauri/core と @tauri-apps/plugin-clipboard-manager の両方を peerDependencies として宣言しているため、上流側の各バージョンを利用者側で制御できます。

rescript.json の dependencies にパッケージを追加します:

{
  "dependencies": [
    "@rescript-tauri/core",
    "@rescript-tauri/plugin-clipboard-manager"
  ]
}

Rust 側では、プラグイン crate を追加して builder に登録します:

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-clipboard-manager = "2"

// src-tauri/src/main.rs
fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_clipboard_manager::init())
        .run(tauri::generate_context!())
        .expect("error while running app");
}

Capability 設定

Tauri 2.x では、すべてのクリップボード操作に capability を付与する必要があります。最小構成は以下のとおりです:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "clipboard-manager:default"
  ]
}

clipboard-manager:default は本バインディングが公開するすべての読み書き API をカバーします。一部のみ許可したい場合は、プラグインが提供するより限定的なエイリアスに置き換えてください (リファレンス)。例えば、ペースト専用ユーティリティであれば clipboard-manager:allow-write-text と clipboard-manager:allow-read-text を組み合わせます。

最小サンプル

module Cb = RescriptTauriPluginClipboardManager.PluginClipboardManager

let copyAndPaste = async () => {
  await Cb.writeText("Tauri is awesome!")
  let text = await Cb.readText()
  Console.log2("clipboard:", text)
}

公開 API

6 つの公開関数と writeTextOptions record で、@tauri-apps/plugin-clipboard-manager v2.3.x の上流 API 表面全体をカバーします。

シンボル	用途
writeText(text, ~opts=?)	プレーンテキストを書き込む。opts.label は Android 用のエンティティ名を付与
readText()	プレーンテキストを読み取る
writeImage('image)	生の RGBA バッファ / Image.t / Uint8Array / array<int> / ファイルパスを書き込む
readImage()	RescriptTauriCore.Image.t として読み取る (Image.rgba で参照)
writeHtml(html, ~altText=?)	プレーンテキストの fallback (省略可) と併せて HTML を書き込む
clear()	クリップボードをクリアする
writeTextOptions	{label?: string}

テキスト API

writeText と readText は最も一般的なエントリポイントです。writeText は省略可能な writeTextOptions record を受け取ります。唯一のフィールド label は Android のクリップボード履歴ピッカーで クリップボードエンティティ名 として表示されます (デスクトップでは no-op):

await Cb.writeText(
  "Public address: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  ~opts={label: "Wallet address"},
)

let copied = await Cb.readText()
Console.log("clipboard now contains: " ++ copied)

readText() は string を返します。クリップボードにテキストが含まれていない場合は、内部の Rust 呼び出しがエラーを返します。「空のクリップボード」と実際の失敗を区別したい場合は、呼び出しを try { ... } catch で包んでください。

画像 API

画像 API は @rescript-tauri/core と Image.t を共有しており、本パッケージは独自の画像型を定義しません。peer dependency 経由で Core.Image を取り込み、クリップボード画像の入出力にはそのコンストラクタ / アクセサを使用してください。

writeImage は上流の union 型 string | Image | Uint8Array | ArrayBuffer | number[] を反映するため、polymorphic な 'image パラメータで意図的に型付けされています。これらの形式のいずれかを渡せます。推論される型が曖昧な場合は、呼び出し側で型注釈を付けてください。

(a) ファイルパスから構築した Core.Image.t を書き込む:

module Cb = RescriptTauriPluginClipboardManager.PluginClipboardManager
module Image = RescriptTauriCore.Image

let icon = await Image.fromPath("./assets/icon.png")
await Cb.writeImage(icon)

(b) 生の RGBA バイト列を直接書き込む:

// 1×1 red pixel: R G B A
let bytes = Uint8Array.fromArray([255, 0, 0, 255])
await Cb.writeImage(bytes)

readImage() は RescriptTauriCore.Image.t リソースハンドルを返します。ピクセルバッファは Core.Image.rgba で、寸法は Core.Image.size で参照できます:

let img = await Cb.readImage()
let bytes = await Image.rgba(img)
let {width, height} = await Image.size(img)
Console.log4(
  "clipboard image:",
  Int.toString(TypedArray.length(bytes)) ++ " bytes,",
  Float.toString(width) ++ "x",
  Float.toString(height),
)

注釈

writeImage / readImage は上流で Android / iOS では未サポートです。デスクトップでは、capability セットで clipboard-manager:allow-write-image と clipboard-manager:allow-read-image が実際に付与されていることを確認してください (どちらも前述の clipboard-manager:default エイリアスに含まれます)。

注意点 — 画像の RGBA レイアウト

Core.Image.rgba および Core.Image.new_ が受け取るバイト列は、行優先・上から下・RGBA8 (各チャンネル 1 バイト、alpha が最後) です。BGRA、下から上のスキャンライン、premultiplied alpha を返す画像ライブラリの場合は、クリップボードに渡す前に変換が必要です。変換しないと、ペーストした画像でチャンネルの入れ替わりや上下反転が発生します。

HTML API

writeHtml(html, ~altText=?) は OS ネイティブの HTML フォーマットで、クリップボードにリッチテキストを格納します。典型的な用途は、書式付きテキスト (太字、色、リンク、テーブルなど) を HTML クリップボードデータを尊重するアプリ (ワープロ、メールエディタ、リッチテキストエディタ) に貼り付け可能にすることです。省略可能な ~altText 引数は、HTML ペイロードを受け付けないクライアントに渡されるプレーンテキストの fallback です。リッチコンテンツに意味のあるテキスト相当がある場合は常に渡してください。

await Cb.writeHtml(
  "<p>Visit <a href=\"https://tauri.app\">Tauri</a> for docs.</p>",
  ~altText="Visit https://tauri.app for docs.",
)

~altText を省略するとプレーンテキストスロットが空になり、HTML を受け付けないコンシューマでは何も貼り付けられない可能性があります。

クリア

clear() はクリップボードを空にします。Android の SDK < 28 では基盤となるプラットフォーム API が利用できないため、本バインディングは空文字列の書き込みに fallback します。これらのバージョンでは、本当の意味で空にはならず、長さ 0 のテキスト項目がクリップボードに残ることに注意してください。

await Cb.clear()

互換性

項目	対応バージョン
上流 @tauri-apps/plugin-clipboard-manager	^2.0.0 (peer)
Rust tauri-plugin-clipboard-manager	2.x
@rescript-tauri/core	^0.1.0 (peer)
ReScript	>=12.0.0
@rescript/core	>=1.6.0
対応 OS	Linux / macOS / Windows (画像 / HTML API は Android / iOS では未サポート)

関連リンク

• ライブデモ: examples/plugin-clipboard-manager-demo

• ソース: packages/plugin-clipboard-manager

• パッケージ README: packages/plugin-clipboard-manager/README.md

• 画像型 (peer-dep 再利用): packages/core/src/Image.resi

• 上流ドキュメント: Tauri 2.x クリップボードプラグイン