このページは Cloud Translation API によって翻訳されました。

コピーして貼り付け

Android は、コピー＆ペースト用の強力なクリップボードベースフレームワークを備えています。このフレームワークは、テキスト文字列、複雑なデータ構造、テキストおよびバイナリのストリームデータ、アプリアセットなど、シンプルなデータ型と複雑なデータ型の両方をサポートします。シンプルなテキストデータはクリップボード内に直接保存されます。複雑なデータは参照として保存され、貼り付け側アプリがコンテンツプロバイダを使用して解決します。コピー＆ペーストは、単一のアプリ内でも、フレームワークを実装している複数のアプリ間でも機能します。

フレームワークの一部でコンテンツプロバイダが使用されるため、このドキュメントは、ある程度 Android Content Provider API に精通していることを前提としています。詳細については、コンテンツプロバイダをご覧ください。

ユーザーがクリップボードにコンテンツをコピーする際にはフィードバックが期待されるため、Android 13（API レベル 33）以降では、コピー＆ペーストを強化するフレームワークに加えて、デフォルトの UI がユーザーに表示されます。この機能により、通知が重複するリスクがあります。このエッジケースについて詳しくは、重複する通知を回避するをご覧ください。

Android 13 のクリップボード通知を示すアニメーション — **図 1.** Android 13 以降でコンテンツがクリップボードに入ると表示される UI。

Android 12L（API レベル 32）以前でコピーする場合は、手動でフィードバックを提供します。このドキュメントの推奨事項をご覧ください。

クリップボードフレームワーク

クリップボードフレームワークを使用する場合は、データをクリップオブジェクトに配置して、そのクリップオブジェクトをシステムレベルのクリップボードに配置します。クリップオブジェクトには、次の 3 つの形式があります。

テキスト: テキスト文字列。文字列をコピーするには、文字列を直接クリップオブジェクトに配置して、そのクリップオブジェクトをクリップボードに配置します。文字列を貼り付けるには、クリップボードからクリップオブジェクトを取得して、その文字列をアプリのストレージにコピーします。
URI: 任意の形式の URI を示す Uri オブジェクト。主に、コンテンツプロバイダから複雑なデータをコピーする場合に使用します。データをコピーするには、Uri オブジェクトをクリップオブジェクトに配置し、そのクリップオブジェクトをクリップボードに配置します。データを貼り付けるには、クリップオブジェクトを取得して、Uri オブジェクトを取得し、それをコンテンツプロバイダなどのデータソースに変換して、そのソースからアプリのストレージにデータをコピーします。
インテント: Intent。アプリショートカットのコピーをサポートします。データをコピーするには、Intent を作成してクリップオブジェクトに配置し、そのクリップオブジェクトをクリップボードに配置します。データを貼り付けるには、クリップオブジェクトを取得して、Intent オブジェクトをアプリのメモリ領域にコピーします。

クリップボードは、一度に 1 つのクリップオブジェクトしか保持できません。アプリがクリップオブジェクトをクリップボードに配置すると、以前のクリップオブジェクトは消去されます。

ユーザーがアプリにデータを貼り付けられるようにする場合でも、すべてのタイプのデータを処理する必要はありません。ユーザーに貼り付けのオプションを付与する前に、クリップボード上のデータを調べることができます。クリップオブジェクト内には、特定のデータ形式のほかに、利用可能な MIME タイプを伝えるメタデータも含まれています。このメタデータは、アプリがクリップボードデータを使用して何か有用なことができるかどうかを判断する際に役立ちます。たとえば、主にテキストを処理するアプリの場合は、URI やインテントを含むクリップオブジェクトを無視することができます。

また、クリップボード上のデータの形式に関係なく、ユーザーがテキストを貼り付けられるようにすることもできます。この場合、クリップボードデータをテキスト表現に強制変換したうえで、テキストを貼り付けます。詳細については、クリップボードをテキストに強制変換するをご覧ください。

クリップボードクラス

このセクションでは、クリップボードフレームワークが使用するクラスについて説明します。

ClipboardManager

Android システムクリップボードは、グローバル ClipboardManager クラスで表されます。このクラスを直接インスタンス化しないでください。代わりに、getSystemService(CLIPBOARD_SERVICE) を呼び出して、その参照を取得します。

ClipData、ClipData.Item、ClipDescription

クリップボードにデータを追加するには、データの説明とデータ自体を含む ClipData オブジェクトを作成します。クリップボードは、一度に 1 つの ClipData しか保持できません。ClipData には、ClipDescription オブジェクトと 1 つ以上の ClipData.Item オブジェクトが含まれます。

ClipDescription オブジェクトには、クリップに関するメタデータが含まれます。特に、クリップのデータに対して利用可能な MIME タイプの配列が含まれています。さらに、Android 12（API レベル 31）以降では、スタイル設定されたテキストがオブジェクトに含まれているかどうかと、オブジェクトに含まれるテキストのタイプに関する情報が、メタデータに含まれます。クリップボードにクリップを配置すると、貼り付け側アプリがこの情報を利用できるようになります。貼り付け側アプリは、この配列を調べることで、クリップデータが処理可能かどうかを確認できます。

ClipData.Item オブジェクトには、テキスト、URI、インテントのいずれかのデータが含まれます。

テキスト: CharSequence。
URI: Uri。通常はコンテンツプロバイダ URI が格納されますが、どのような URI でも可能です。データ提供側のアプリは、URI をクリップボード上に配置します。データ貼り付け側のアプリは、クリップボードから URI を取得し、それを使用してコンテンツプロバイダ（または他のデータソース）にアクセスし、データを取得します。
インテント: Intent。このデータ型を使用すると、アプリのショートカットをクリップボードにコピーできます。ユーザーは、後でそのショートカットを別のアプリに貼り付けて使用できます。

1 つのクリップに複数の ClipData.Item オブジェクトを追加できます。これにより、複数の選択内容を単一のクリップとしてコピー＆ペーストすることができます。たとえば、一度に複数のアイテムを選択できるリストウィジェットがある場合に、すべてのアイテムを一度にクリップボードにコピーすることができます。そのためには、リストアイテムごとに個別の ClipData.Item を作成し、ClipData.Item オブジェクトを ClipData オブジェクトに追加します。

ClipData コンビニエンスメソッド

ClipData クラスには、単一の ClipData.Item オブジェクトとシンプルな ClipDescription オブジェクトを使用して ClipData オブジェクトを作成するための静的コンビニエンスメソッドが用意されています。

newPlainText(label, text): 単一の ClipData.Item オブジェクトがテキスト文字列を格納している ClipData オブジェクトを返します。ClipDescription オブジェクトのラベルは label に設定されています。ClipDescription 内の単一の MIME タイプは MIMETYPE_TEXT_PLAIN です。
newPlainText() を使用して、テキスト文字列からクリップを作成します。
newUri(resolver, label, URI): 単一の ClipData.Item オブジェクトが URI を格納している ClipData オブジェクトを返します。ClipDescription オブジェクトのラベルは label に設定されています。URI がコンテンツ URI の場合（Uri.getScheme() が content: を返す場合）、このメソッドは、resolver 内で提供される ContentResolver オブジェクトを使用して、コンテンツプロバイダから利用可能な MIME タイプを取得します。その後、ClipDescription に保存します。URI が content: URI ではない場合、このメソッドは、MIME タイプを MIMETYPE_TEXT_URILIST に設定します。
newUri() を使用すると、URI（特に content: URI）からクリップを作成できます。
newIntent(label, intent): 単一の ClipData.Item オブジェクトが Intent を格納している ClipData オブジェクトを返します。ClipDescription オブジェクトのラベルは label に設定されています。MIME タイプは MIMETYPE_TEXT_INTENT に設定されています。
newIntent() を使用して、Intent オブジェクトからクリップを作成します。

クリップボードデータをテキストに強制変換する

テキストだけを処理するアプリの場合でも、ClipData.Item.coerceToText() メソッドを使用して変換することで、クリップボードから非テキストデータをコピーすることができます。

このメソッドは、ClipData.Item 内のデータをテキストに変換して、CharSequence を返します。ClipData.Item.coerceToText() が返す値は、ClipData.Item 内のデータの形式に基づきます。

テキスト

ClipData.Item がテキストの場合（getText() が null でない場合）、coerceToText() はテキストを返します。

URI

ClipData.Item が URI の場合（getUri() が null でない場合）、coerceToText() はそれをコンテンツ URI として使用するように試みます。

URI がコンテンツ URI で、プロバイダがテキストストリームを返すことができる場合、coerceToText() はテキストストリームを返します。
URI がコンテンツ URI で、プロバイダがテキストストリームを提供しない場合、coerceToText() は URI のテキスト表現を返します。このテキスト表現は、Uri.toString() によって返されるものと同じです。
URI がコンテンツ URI でない場合、coerceToText() は URI の表現を返します。このテキスト表現は、Uri.toString() によって返されるものと同じです。

インテント

ClipData.Item が Intent の場合（つまり、getIntent() が null でない場合）、coerceToText() はそれをインテント URI に変換して返します。このテキスト表現は、Intent.toUri(URI_INTENT_SCHEME) によって返されるものと同じです。

クリップボードフレームワークの概要を図 2 に示します。データをコピーする場合、アプリは、ClipData オブジェクトを ClipboardManager グローバルクリップボードに配置します。ClipData には、1 つ以上の ClipData.Item オブジェクトと、1 つの ClipDescription オブジェクトが含まれます。データを貼り付ける場合、アプリは、ClipData を取得して、ClipDescription から MIME タイプを取得し、ClipData.Item から、あるいは ClipData.Item が参照しているコンテンツプロバイダから、データを取得します。

コピー＆ペーストフレームワークのブロック図を示す画像 — **図 2.** Android クリップボードフレームワーク。

クリップボードにコピーする

クリップボードにデータをコピーするには、グローバル ClipboardManager オブジェクトのハンドルを取得して、ClipData オブジェクトを作成し、1 つの ClipDescription オブジェクトと 1 つまたは複数の ClipData.Item オブジェクトを追加します。次に、完成した ClipData オブジェクトを ClipboardManager オブジェクトに追加します。詳細な手順について、以下で説明します。

コンテンツ URI を使用してデータをコピーする場合は、コンテンツプロバイダをセットアップします。

システムクリップボードを取得します。

Kotlin

when(menuItem.itemId) {
    ...
    R.id.menu_copy -> { // if the user selects copy
        // Gets a handle to the clipboard service.
        val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    }
}

Java

...
// If the user selects copy.
case R.id.menu_copy:

// Gets a handle to the clipboard service.
ClipboardManager clipboard = (ClipboardManager)
        getSystemService(Context.CLIPBOARD_SERVICE);

新しい ClipData オブジェクトにデータをコピーします。

テキストの場合

Kotlin

// Creates a new text clip to put on the clipboard.
val clip: ClipData = ClipData.newPlainText("simple text", "Hello, World!")

Java

// Creates a new text clip to put on the clipboard.
ClipData clip = ClipData.newPlainText("simple text", "Hello, World!");

URI の場合

下記のスニペットは、プロバイダのコンテンツ URI に対してレコード ID をエンコードすることによって URI を作成しています。この手法の詳細については、URI に対して識別子をエンコードするをご覧ください。

Kotlin

// Creates a Uri using a base Uri and a record ID based on the contact's last
// name. Declares the base URI string.
const val CONTACTS = "content://com.example.contacts"

// Declares a path string for URIs, used to copy data.
const val COPY_PATH = "/copy"

// Declares the Uri to paste to the clipboard.
val copyUri: Uri = Uri.parse("$CONTACTS$COPY_PATH/$lastName")
...
// Creates a new URI clip object. The system uses the anonymous
// getContentResolver() object to get MIME types from provider. The clip object's
// label is "URI", and its data is the Uri previously created.
val clip: ClipData = ClipData.newUri(contentResolver, "URI", copyUri)

Java

// Creates a Uri using a base Uri and a record ID based on the contact's last
// name. Declares the base URI string.
private static final String CONTACTS = "content://com.example.contacts";

// Declares a path string for URIs, used to copy data.
private static final String COPY_PATH = "/copy";

// Declares the Uri to paste to the clipboard.
Uri copyUri = Uri.parse(CONTACTS + COPY_PATH + "/" + lastName);
...
// Creates a new URI clip object. The system uses the anonymous
// getContentResolver() object to get MIME types from provider. The clip object's
// label is "URI", and its data is the Uri previously created.
ClipData clip = ClipData.newUri(getContentResolver(), "URI", copyUri);

インテントの場合

下記のスニペットは、アプリの Intent を作成して、クリップオブジェクト内に配置しています。

Kotlin

// Creates the Intent.
val appIntent = Intent(this, com.example.demo.myapplication::class.java)
...
// Creates a clip object with the Intent in it. Its label is "Intent"
// and its data is the Intent object created previously.
val clip: ClipData = ClipData.newIntent("Intent", appIntent)

Java

// Creates the Intent.
Intent appIntent = new Intent(this, com.example.demo.myapplication.class);
...
// Creates a clip object with the Intent in it. Its label is "Intent"
// and its data is the Intent object created previously.
ClipData clip = ClipData.newIntent("Intent", appIntent);

新しいクリップオブジェクトをクリップボード上に配置します。

Kotlin

// Set the clipboard's primary clip.
clipboard.setPrimaryClip(clip)

Java

// Set the clipboard's primary clip.
clipboard.setPrimaryClip(clip);

クリップボードにコピーする際のフィードバックの提供

ユーザーは、アプリがコンテンツをクリップボードにコピーするときに、視覚的なフィードバックを期待します。この処理は、Android 13 以降では自動的に行われますが、それより前のバージョンでは手動で実装する必要があります。

Android 13 以降では、クリップボードにコンテンツが追加されると、そのことをユーザーが視覚的に確認できるよう、標準のポップアップが表示されます。この新しい通知機能により、次のことが可能になります。

コンテンツが正常にコピーされたことをユーザーに知らせる。
コピーされたコンテンツのプレビューを表示する。

Android 12L（API レベル 32）以前では、コンテンツが正常にコピーされたかどうか、また何をコピーしたかをユーザーが確認できない場合があります。この機能により、コピー後にアプリに表示されるさまざまな通知が標準化され、ユーザーがクリップボードを細かく制御できるようになります。

通知の重複を避ける

Android 12L（API レベル 32）以前の場合、コピー後に Toast や Snackbar などのウィジェットを使用して、視覚的なアプリ内フィードバックを表示して、正常にコピーされたことをユーザーに知らせることをおすすめします。

情報が重複して表示されないように、Android 13 以降では、アプリ内コピーの後に表示されるトーストやスナックバーは削除することを強くおすすめします。

アプリ内コピーの後にスナックバーを表示する — **図 4.** Android 13 でコピー確認スナックバーを表示させると、ユーザーにはメッセージが重複して表示されます。

アプリ内コピーの後にトーストを表示する — **図 5.** Android 13 でコピー確認トーストを表示させると、ユーザーにはメッセージが重複して表示されます。

実装例を次に示します。

fun textCopyThenPost(textCopied:String) {
    val clipboardManager = getSystemService(CLIPBOARD_SERVICE) as ClipboardManager
    // When setting the clipboard text.
    clipboardManager.setPrimaryClip(ClipData.newPlainText   ("", textCopied))
    // Only show a toast for Android 12 and lower.
    if (Build.VERSION.SDK_INT <= Build.VERSION_CODES.S_V2)
        Toast.makeText(context, “Copied”, Toast.LENGTH_SHORT).show()
}

機密コンテンツをクリップボードに追加する

パスワードやクレジットカード情報などの機密コンテンツを、アプリ内でクリップボードにコピーできるようにする場合は、ClipboardManager.setPrimaryClip() を呼び出す前に、ClipData の ClipDescription にフラグを追加する必要があります。このフラグを追加すると、Android 13 以降で、コピーされたコンテンツの視覚的確認に機密コンテンツが表示されなくなります。

**図 6.** 機密コンテンツのフラグを設定せずにコピーされたテキストのプレビュー。

機密コンテンツのフラグを設定してコピーされたテキストのプレビュー — **図 7.** 機密コンテンツのフラグが設定されたコピーされたテキストのプレビュー。

機密コンテンツのフラグを設定するには、ClipDescription にブール型のエクストラを追加します。対象 API レベルにかかわらず、すべてのアプリでこれを行う必要があります。

// If your app is compiled with the API level 33 SDK or higher.
clipData.apply {
    description.extras = PersistableBundle().apply {
        putBoolean(ClipDescription.EXTRA_IS_SENSITIVE, true)
    }
}

// If your app is compiled with a lower SDK.
clipData.apply {
    description.extras = PersistableBundle().apply {
        putBoolean("android.content.extra.IS_SENSITIVE", true)
    }
}

クリップボードから貼り付ける

上記で説明したとおり、クリップボードからデータを貼り付けるには、グローバルクリップボードオブジェクトを取得して、クリップオブジェクトを取得し、データを参照して、可能であればクリップオブジェクトから独自のストレージにデータをコピーします。このセクションでは、3 つの形式のクリップボードデータを貼り付ける方法について詳しく説明します。

重要: 編集可能な TextView オブジェクトについては、リッチコンテンツを受信するドキュメントに沿って、任意のタイプのコンテンツの貼り付けのサポートを追加します。次のセクションでは、コンテンツを貼り付けるためのカスタム UI を開発する方法について説明します。

プレーンテキストを貼り付ける

プレーンテキストを貼り付けるには、グローバルクリップボードを取得して、プレーンテキストを返すことができるか検証します。次に、getText() を使用して、クリップオブジェクトを取得し、そのテキストを独自のストレージにコピーします。手順は次のとおりです。

getSystemService(CLIPBOARD_SERVICE) を使用して、グローバル ClipboardManager オブジェクトを取得します。また、貼り付けたテキストを格納するグローバル変数を宣言します。
Kotlin
```
var clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
var pasteData: String = ""
```
Java
```
ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
String pasteData = "";
```

現在のアクティビティで「貼り付け」オプションを有効にするか無効にするかを決定します。クリップボードがクリップを含んでいるかどうか、クリップのデータタイプを処理できるかどうかを検証します。

Kotlin

// Gets the ID of the "paste" menu item.
val pasteItem: MenuItem = menu.findItem(R.id.menu_paste)

// If the clipboard doesn't contain data, disable the paste menu item.
// If it does contain data, decide whether you can handle the data.
pasteItem.isEnabled = when {
    !clipboard.hasPrimaryClip() -> {
        false
    }
    !(clipboard.primaryClipDescription.hasMimeType(MIMETYPE_TEXT_PLAIN)) -> {
        // Disables the paste menu item, since the clipboard has data but it
        // isn't plain text.
        false
    }
    else -> {
        // Enables the paste menu item, since the clipboard contains plain text.
        true
    }
}

Java

// Gets the ID of the "paste" menu item.
MenuItem pasteItem = menu.findItem(R.id.menu_paste);

// If the clipboard doesn't contain data, disable the paste menu item.
// If it does contain data, decide whether you can handle the data.
if (!(clipboard.hasPrimaryClip())) {

    pasteItem.setEnabled(false);

} else if (!(clipboard.getPrimaryClipDescription().hasMimeType(MIMETYPE_TEXT_PLAIN))) {

    // Disables the paste menu item, since the clipboard has data but
    // it isn't plain text.
    pasteItem.setEnabled(false);
} else {

    // Enables the paste menu item, since the clipboard contains plain text.
    pasteItem.setEnabled(true);
}

クリップボードからデータをコピーします。コード内のこのポイントに到達できるのは、「貼り付け」メニュー項目が有効な場合に限られます。そのため、クリップボード内にプレーンテキストが格納されていると想定できます。ただし、格納されているプレーンテキストがテキスト文字列であるのか URI であるのかは、まだわかりません。これをテストするコードスニペットを以下に示します。ただし、プレーンテキストを処理するコードだけを表示しています。

Kotlin

when (menuItem.itemId) {
    ...
    R.id.menu_paste -> {    // Responds to the user selecting "paste".
        // Examines the item on the clipboard. If getText() doesn't return null,
        // the clip item contains the text. Assumes that this application can only
        // handle one item at a time.
        val item = clipboard.primaryClip.getItemAt(0)

        // Gets the clipboard as text.
        pasteData = item.text

        return if (pasteData != null) {
            // If the string contains data, then the paste operation is done.
            true
        } else {
            // The clipboard doesn't contain text. If it contains a URI,
            // attempts to get data from it.
            val pasteUri: Uri? = item.uri

            if (pasteUri != null) {
                // If the URI contains something, try to get text from it.

                // Calls a routine to resolve the URI and get data from it.
                // This routine isn't presented here.
                pasteData = resolveUri(pasteUri)
                true
            } else {

                // Something is wrong. The MIME type was plain text, but the
                // clipboard doesn't contain text or a Uri. Report an error.
                Log.e(TAG,"Clipboard contains an invalid data type")
                false
            }
        }
    }
}

Java

// Responds to the user selecting "paste".
case R.id.menu_paste:

// Examines the item on the clipboard. If getText() does not return null,
// the clip item contains the text. Assumes that this application can only
// handle one item at a time.
 ClipData.Item item = clipboard.getPrimaryClip().getItemAt(0);

// Gets the clipboard as text.
pasteData = item.getText();

// If the string contains data, then the paste operation is done.
if (pasteData != null) {
    return true;

// The clipboard doesn't contain text. If it contains a URI, attempts to get
// data from it.
} else {
    Uri pasteUri = item.getUri();

    // If the URI contains something, try to get text from it.
    if (pasteUri != null) {

        // Calls a routine to resolve the URI and get data from it.
        // This routine isn't presented here.
        pasteData = resolveUri(Uri);
        return true;
    } else {

        // Something is wrong. The MIME type is plain text, but the
        // clipboard doesn't contain text or a Uri. Report an error.
        Log.e(TAG, "Clipboard contains an invalid data type");
        return false;
    }
}

コンテンツ URI からデータを貼り付ける

ClipData.Item オブジェクトがコンテンツ URI を格納していて、その MIME タイプの 1 つを処理できると判断した場合は、ContentResolver を作成し、適切なコンテンツプロバイダメソッドを呼び出してデータを取得します。

以下では、クリップボード上のコンテンツ URI に基づいてコンテンツプロバイダからデータを取得する手順について説明します。アプリが使用できる MIME タイプがプロバイダから利用可能かどうかを確認します。

MIME タイプを格納するグローバル変数を宣言します。

Kotlin

// Declares a MIME type constant to match against the MIME types offered
// by the provider.
const val MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"

Java

// Declares a MIME type constant to match against the MIME types offered by
// the provider.
public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact";

グローバルクリップボードを取得します。また、コンテンツリゾルバも取得します。これにより、コンテンツプロバイダにアクセスできるようになります。

Kotlin

// Gets a handle to the Clipboard Manager.
val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager

// Gets a content resolver instance.
val cr = contentResolver

Java

// Gets a handle to the Clipboard Manager.
ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);

// Gets a content resolver instance.
ContentResolver cr = getContentResolver();

クリップボードからメインクリップを取得し、そのコンテンツを URI として取得します。

Kotlin

// Gets the clipboard data from the clipboard.
val clip: ClipData? = clipboard.primaryClip

clip?.run {

    // Gets the first item from the clipboard data.
    val item: ClipData.Item = getItemAt(0)

    // Tries to get the item's contents as a URI.
    val pasteUri: Uri? = item.uri

Java

// Gets the clipboard data from the clipboard.
ClipData clip = clipboard.getPrimaryClip();

if (clip != null) {

    // Gets the first item from the clipboard data.
    ClipData.Item item = clip.getItemAt(0);

    // Tries to get the item's contents as a URI.
    Uri pasteUri = item.getUri();

getType(Uri) を呼び出して、URI がコンテンツ URI かどうかをテストします。Uri が有効なコンテンツプロバイダをポイントしていない場合、このメソッドは null を返します。

Kotlin

    // If the clipboard contains a URI reference...
    pasteUri?.let {

        // ...is this a content URI?
        val uriMimeType: String? = cr.getType(it)

Java

    // If the clipboard contains a URI reference...
    if (pasteUri != null) {

        // ...is this a content URI?
        String uriMimeType = cr.getType(pasteUri);

コンテンツプロバイダがアプリが認識できる MIME タイプをサポートしているかどうかをテストします。サポートしている場合は、ContentResolver.query() を呼び出してデータを取得します。戻り値は Cursor です。

Kotlin

        // If the return value isn't null, the Uri is a content Uri.
        uriMimeType?.takeIf {

            // Does the content provider offer a MIME type that the current
            // application can use?
            it == MIME_TYPE_CONTACT
        }?.apply {

            // Get the data from the content provider.
            cr.query(pasteUri, null, null, null, null)?.use { pasteCursor ->

                // If the Cursor contains data, move to the first record.
                if (pasteCursor.moveToFirst()) {

                    // Get the data from the Cursor here.
                    // The code varies according to the format of the data model.
                }

                // Kotlin `use` automatically closes the Cursor.
            }
        }
    }
}

Java

        // If the return value isn't null, the Uri is a content Uri.
        if (uriMimeType != null) {

            // Does the content provider offer a MIME type that the current
            // application can use?
            if (uriMimeType.equals(MIME_TYPE_CONTACT)) {

                // Get the data from the content provider.
                Cursor pasteCursor = cr.query(uri, null, null, null, null);

                // If the Cursor contains data, move to the first record.
                if (pasteCursor != null) {
                    if (pasteCursor.moveToFirst()) {

                    // Get the data from the Cursor here.
                    // The code varies according to the format of the data model.
                    }
                }

                // Close the Cursor.
                pasteCursor.close();
             }
         }
     }
}

インテントを貼り付ける

インテントを貼り付けるには、まず、グローバルクリップボードを取得します。ClipData.Item オブジェクトを調べて、Intent が含まれているかどうかを確認します。次に、getIntent() を呼び出して、インテントを独自のストレージにコピーします。この手順を行うスニペットは以下のとおりです。

Kotlin

// Gets a handle to the Clipboard Manager.
val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager

// Checks whether the clip item contains an Intent by testing whether
// getIntent() returns null.
val pasteIntent: Intent? = clipboard.primaryClip?.getItemAt(0)?.intent

if (pasteIntent != null) {

    // Handle the Intent.

} else {

    // Ignore the clipboard, or issue an error if
    // you expect an Intent to be on the clipboard.
}

Java

// Gets a handle to the Clipboard Manager.
ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);

// Checks whether the clip item contains an Intent, by testing whether
// getIntent() returns null.
Intent pasteIntent = clipboard.getPrimaryClip().getItemAt(0).getIntent();

if (pasteIntent != null) {

    // Handle the Intent.

} else {

    // Ignore the clipboard, or issue an error if
    // you expect an Intent to be on the clipboard.
}

アプリがクリップボードデータにアクセスしたときに表示されるシステム通知

Android 12（API レベル 31）以降では、アプリが getPrimaryClip() を呼び出すと、通常はシステムによってトーストメッセージが表示されます。このメッセージ内のテキストには、次の形式が含まれます。

APP pasted from your clipboard

アプリが次のいずれかの操作を行った場合は、トーストメッセージは表示されません。

独自のアプリから ClipData にアクセスする。
同じアプリから ClipData に繰り返しアクセスする。トーストは、アプリがそのデータに初めてアクセスしたときにのみ表示されます。
クリップオブジェクトのメタデータを取得する（getPrimaryClip() の代わりに getPrimaryClipDescription() を呼び出すなど）。

コンテンツプロバイダを使用して複雑なデータをコピーする

コンテンツプロバイダは、データベースレコードやファイルストリームなど、複雑なデータのコピーをサポートします。データをコピーするには、コンテンツ URI をクリップボードに配置します。次に、貼り付け側アプリが、クリップボードからこの URI を取得し、それを使用してデータベースデータ記述子やファイルストリーム記述子を取得します。

貼り付け側アプリが取得するのはデータのコンテンツ URI だけであるため、取得するデータについて認識する必要があります。そのためには、URI 自体に対してデータの識別子をエンコードしてこの情報を提供するか、コピー対象のデータを返す一意の URI を指定します。どちらの手法を選択するのかは、データの整理方法によって決まります。

以降のセクションでは、URI のセットアップ方法、複雑なデータの提供方法、ファイルストリームの提供方法について説明します。以下の説明は、コンテンツプロバイダ設計の一般原則に精通していることを前提としています。

URI に対して識別子をエンコードする

URI を使用してクリップボードにデータをコピーする場合、URI 自体に対してデータの識別子をエンコードすると便利です。これにより、コンテンツプロバイダが URI から識別子を取得し、それを使用してデータを取得できるようになります。貼り付け側アプリは、識別子が存在していることを認識する必要はありません。クリップボードから「参照」（URI と識別子）を取得して、コンテンツプロバイダに渡すだけで、データを取得できます。

コンテンツ URI に対して識別子をエンコードする場合は通常、URI の末尾に識別子を連結します。たとえば、プロバイダ URI を次の文字列として定義したとします。

"content://com.example.contacts"

この URI に名前をエンコードする場合は、次のコードスニペットを使用します。

Kotlin

val uriString = "content://com.example.contacts/Smith"

// uriString now contains content://com.example.contacts/Smith.

// Generates a uri object from the string representation.
val copyUri = Uri.parse(uriString)

Java

String uriString = "content://com.example.contacts" + "/" + "Smith";

// uriString now contains content://com.example.contacts/Smith.

// Generates a uri object from the string representation.
Uri copyUri = Uri.parse(uriString);

すでにコンテンツプロバイダを使用している場合は、URI がコピー用であることを示す新しい URI パスを追加することをおすすめします。たとえば、次の URI パスをすでに使用しているとします。

"content://com.example.contacts/people"
"content://com.example.contacts/people/detail"
"content://com.example.contacts/people/images"

URI をコピーするためのパスを新たに追加できます。

"content://com.example.contacts/copying"

これにより、パターンマッチングによって「コピー版」の URI を検出し、コピー＆ペースト専用のコードで処理できるようになります。

すでにコンテンツプロバイダ、内部データベース、内部テーブルを使用してデータを整理している場合は通常、このエンコード方式を使用します。このようなケースでは、コピーするデータが複数あり、データごとに一意の識別子が設定されていると考えられます。貼り付け側アプリからのクエリに応じて、識別子に基づいてデータを検索し、返すことができます。

データが複数ない場合は通常、識別子をエンコードする必要はありません。プロバイダ固有の URI を使用できます。クエリに応じて、プロバイダは現在格納しているデータを返します。

データ構造をコピーする

複雑なデータのコピー＆ペーストを行うコンテンツプロバイダは、ContentProvider コンポーネントのサブクラスとしてセットアップします。提供するレコードを正確にポイントするように、クリップボード上に配置した URI をエンコードします。また、アプリの既存の状態についても考慮してください。

すでにコンテンツプロバイダを使用している場合は、その機能に追加できます。query() メソッドを編集して、データ貼り付け側アプリから取得する URI を処理できるようにするだけで済みます。「コピー版」の URI パターンを処理できるようにメソッドを編集してください。
アプリが内部データベースを保持している場合は、このデータベースをコンテンツプロバイダに移動することで、データベースからのコピーを促進できます。
データベースを使用していない場合は、クリップボードから貼り付けを行うアプリにデータを提供することを唯一の目的とするシンプルなコンテンツプロバイダを実装してください。

コンテンツプロバイダで、少なくとも次のメソッドをオーバーライドします。

query(): 貼り付け側アプリは、このメソッドを使用し、クリップボード上に配置されている URI を指定することで、データを取得できるものと想定しています。コピーをサポートするには、このメソッドによって、特別な「コピー版」のパスを含む URI を検出します。これにより、アプリは「コピー版」の URI を作成して、クリップボード上に配置できるようになります。「コピー版」の URI には、コピーパスと、コピーするレコードを正確にポイントするポインタが含まれます。
getType(): このメソッドは、コピーするデータの MIME タイプを返す必要があります。newUri() メソッドは getType() を呼び出して、MIME タイプを新しい ClipData オブジェクトに配置します。
複雑なデータの MIME タイプについては、コンテンツプロバイダをご覧ください。

insert() や update() など、他のコンテンツプロバイダメソッドは必要ありません。貼り付け側アプリは、サポート対象の MIME タイプを取得して、プロバイダからデータをコピーするだけで済みます。上記のような別のメソッドをすでに使用していたとしても、コピー処理を妨げることはありません。

複雑なデータをコピーするようにアプリをセットアップする方法を次のスニペットに示します。

アプリのグローバル定数内で、ベース URI 文字列と、データをコピーする際に使用する URI 文字列を識別するパスを宣言します。また、コピーしたデータの MIME タイプも宣言します。

Kotlin

// Declares the base URI string.
private const val CONTACTS = "content://com.example.contacts"

// Declares a path string for URIs that you use to copy data.
private const val COPY_PATH = "/copy"

// Declares a MIME type for the copied data.
const val MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"

Java

// Declares the base URI string.
private static final String CONTACTS = "content://com.example.contacts";

// Declares a path string for URIs that you use to copy data.
private static final String COPY_PATH = "/copy";

// Declares a MIME type for the copied data.
public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact";

ユーザーがデータをコピーするアクティビティ内で、データをクリップボードにコピーするコードをセットアップします。コピーリクエストに応じて、URI をクリップボードに配置します。

Kotlin

class MyCopyActivity : Activity() {
    ...
when(item.itemId) {
    R.id.menu_copy -> { // The user has selected a name and is requesting a copy.
        // Appends the last name to the base URI.
        // The name is stored in "lastName".
        uriString = "$CONTACTS$COPY_PATH/$lastName"

        // Parses the string into a URI.
        val copyUri: Uri? = Uri.parse(uriString)

        // Gets a handle to the clipboard service.
        val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager

        val clip: ClipData = ClipData.newUri(contentResolver, "URI", copyUri)

        // Sets the clipboard's primary clip.
        clipboard.setPrimaryClip(clip)
    }
}

Java

public class MyCopyActivity extends Activity {
    ...
// The user has selected a name and is requesting a copy.
case R.id.menu_copy:

    // Appends the last name to the base URI.
    // The name is stored in "lastName".
    uriString = CONTACTS + COPY_PATH + "/" + lastName;

    // Parses the string into a URI.
    Uri copyUri = Uri.parse(uriString);

    // Gets a handle to the clipboard service.
    ClipboardManager clipboard = (ClipboardManager)
        getSystemService(Context.CLIPBOARD_SERVICE);

    ClipData clip = ClipData.newUri(getContentResolver(), "URI", copyUri);

    // Sets the clipboard's primary clip.
    clipboard.setPrimaryClip(clip);

コンテンツプロバイダのグローバルスコープで、URI マッチャーを作成して、クリップボード上に配置した URI にマッチする URI パターンを追加します。

Kotlin

// A Uri Match object that simplifies matching content URIs to patterns.
private val sUriMatcher = UriMatcher(UriMatcher.NO_MATCH).apply {

    // Adds a matcher for the content URI. It matches.
    // "content://com.example.contacts/copy/*"
    addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT)
}

// An integer to use in switching based on the incoming URI pattern.
private const val GET_SINGLE_CONTACT = 0
...
class MyCopyProvider : ContentProvider() {
    ...
}

Java

public class MyCopyProvider extends ContentProvider {
    ...
// A Uri Match object that simplifies matching content URIs to patterns.
private static final UriMatcher sURIMatcher = new UriMatcher(UriMatcher.NO_MATCH);

// An integer to use in switching based on the incoming URI pattern.
private static final int GET_SINGLE_CONTACT = 0;
...
// Adds a matcher for the content URI. It matches
// "content://com.example.contacts/copy/*"
sUriMatcher.addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT);

query() メソッドをセットアップします。このメソッドは、コーディング方法に応じて、さまざまな URI パターンを処理できます。ただし、以下では、クリップボードコピー処理用のパターンだけを表示しています。

Kotlin

// Sets up your provider's query() method.
override fun query(
        uri: Uri,
        projection: Array<out String>?,
        selection: String?,
        selectionArgs: Array<out String>?,
        sortOrder: String?
): Cursor? {
    ...
    // When based on the incoming content URI:
    when(sUriMatcher.match(uri)) {

        GET_SINGLE_CONTACT -> {

            // Queries and returns the contact for the requested name. Decodes
            // the incoming URI, queries the data model based on the last name,
            // and returns the result as a Cursor.
        }
    }
    ...
}

Java

// Sets up your provider's query() method.
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
    String sortOrder) {
    ...
    // Switch based on the incoming content URI.
    switch (sUriMatcher.match(uri)) {

    case GET_SINGLE_CONTACT:

        // Queries and returns the contact for the requested name. Decodes the
        // incoming URI, queries the data model based on the last name, and
        // returns the result as a Cursor.
    ...
}

コピーされたデータの適切な MIME タイプを返すように getType() メソッドをセットアップします。

Kotlin

// Sets up your provider's getType() method.
override fun getType(uri: Uri): String? {
    ...
    return when(sUriMatcher.match(uri)) {
        GET_SINGLE_CONTACT -> MIME_TYPE_CONTACT
        ...
    }
}

Java

// Sets up your provider's getType() method.
public String getType(Uri uri) {
    ...
    switch (sUriMatcher.match(uri)) {
    case GET_SINGLE_CONTACT:
        return (MIME_TYPE_CONTACT);
    ...
    }
}

クリップボードからコンテンツ URI を取得し、それを使用してデータを取得し貼り付ける方法については、コンテンツ URI からデータを貼り付けるをご覧ください。

データストリームをコピーする

大量のテキストデータやバイナリデータをストリームとしてコピー＆ペーストすることができます。データは次のような形式にできます。

実際のデバイス上に保存されているファイル
ソケットからのストリーム
プロバイダの基盤データベースシステム内に保存されている大量のデータ

データストリーム用のコンテンツプロバイダは、Cursor オブジェクトではなく、AssetFileDescriptor などのファイル記述子オブジェクトを使用して、データへのアクセスを提供します。貼り付け側アプリは、このファイル記述子を使用してデータストリームを読み取ります。

プロバイダを使用してデータストリームをコピーするようにアプリをセットアップする手順は次のとおりです。

クリップボード上に配置するデータストリームのコンテンツ URI をセットアップします。次のような方法があります。
- URI に対してデータストリームの識別子をエンコードして（URI に対して識別子をエンコードするを参照）、識別子とそれに対応するストリーム名を格納するテーブルをプロバイダ内で保持します。
- 直接 URI に対してストリーム名をエンコードします。
- プロバイダから現在のストリームを常に返す一意の URI を使用します。この方法を使用する場合は、URI を使用してストリームをクリップボードにコピーするたびに、そのストリームをポイントするようにプロバイダを更新する必要があります。
提供する予定のデータストリームのタイプごとに MIME タイプを指定します。貼り付け側アプリがクリップボード上のデータを貼り付けられるかどうかを判断する際、この情報が必要になります。
ストリームのファイル記述子を返す ContentProvider メソッドの 1 つを実装します。コンテンツ URI に対して識別子をエンコードする場合、このメソッドを使用して、開くストリームを判断します。
データストリームをクリップボードにコピーするには、コンテンツ URI を作成して、クリップボード上に配置します。

データストリームを貼り付ける場合、アプリは、クリップボードからクリップを取得して、URI を取得し、それを使用して、ストリームを開く ContentResolver ファイル記述子メソッドを呼び出します。ContentResolver メソッドは、対応する ContentProvider メソッドを呼び出して、コンテンツ URI を渡します。プロバイダが、ファイル記述子を ContentResolver メソッドに返します。その後、貼り付け側アプリがストリームからデータを読み取ります。

コンテンツプロバイダにとって最も重要なファイル記述子メソッドのリストを以下に示します。それぞれに、対応する ContentResolver メソッドが用意されており、メソッド名に文字列「Descriptor」が付加されます。たとえば、openAssetFile() の ContentResolver アナログは openAssetFileDescriptor() です。

openTypedAssetFile()

このメソッドは、指定された MIME タイプがプロバイダによってサポートされている場合に限り、アセットファイル記述子を返します。呼び出し元（貼り付け側アプリ）が、MIME タイプパターンを指定します。URI をクリップボードにコピーしたアプリのコンテンツプロバイダは、その MIME タイプを提供できる場合は AssetFileDescriptor ファイルハンドルを返し、提供できない場合は例外をスローします。

このメソッドは、ファイルのサブセクションを処理します。このメソッドを使用することで、コンテンツプロバイダがクリップボードにコピーしたアセットを読み取ることができます。

openAssetFile()

このメソッドは、openTypedAssetFile() の汎用的な形式です。可能な MIME タイプのフィルタリングは行いませんが、ファイルのサブセクションを読み取ることができます。

openFile()

このメソッドは、openAssetFile() の汎用的な形式です。ファイルのサブセクションを読み取ることはできません。

必要に応じて、ファイル記述子メソッドと一緒に openPipeHelper() メソッドを使用できます。これにより、貼り付け側アプリは、パイプを使用してバックグラウンドスレッド内でストリームデータを読み取ることができるようになります。このメソッドを使用するには、ContentProvider.PipeDataWriter インターフェースを実装します。

効果的なコピー＆ペースト機能を設計する

アプリにとって効果的なコピー＆ペースト機能を設計するうえで、次の点に注意する必要があります。

クリップボード上には常に 1 つのクリップしか存在できません。システム内のいずれかのアプリによって新しいコピー処理が行われると、以前のクリップは上書きされます。ユーザーは、アプリから離れた後、コピー操作を行ってから戻ってくることがあります。そのため、アプリ内でユーザーが以前コピーしたクリップをそのままクリップボードが保持していると想定することはできません。
クリップごとに複数の ClipData.Item オブジェクトを使用しているのは、単一の選択内容に対して複数の参照形式を使用するためではなく、複数の選択内容のコピー＆ペーストをサポートするためです。通常は、クリップ内の ClipData.Item オブジェクトはすべて同じ形式にします。つまり、すべてのオブジェクトの形式をシンプルテキストか、コンテンツ URI か、Intent で統一し、混合しないようにしてください。
データを提供するときに、さまざまな MIME 表現を指定できます。サポートする MIME タイプを ClipDescription に追加して、コンテンツプロバイダ内でその MIME タイプを実装します。
クリップボードからデータを取得した後、アプリは、利用可能な MIME タイプをチェックし、使用できる MIME タイプがあった場合はどの MIME タイプを使用するのかを決定します。クリップボード上にクリップがあり、ユーザーが貼り付けをリクエストした場合でも、必ずしもアプリは貼り付けを行う必要はありません。MIME タイプが対応している場合は、貼り付けを行います。coerceToText() を使用して、クリップボード上のデータをテキストに自動変換することもできます。利用可能な MIME タイプのうち、複数の MIME タイプをアプリがサポートしている場合、使用する MIME タイプをユーザーが選択できるように設定することもできます。

コピーして貼り付け

クリップボード フレームワーク

クリップボード クラス

ClipboardManager

ClipData、ClipData.Item、ClipDescription

ClipData コンビニエンス メソッド

クリップボード データをテキストに強制変換する

クリップボードにコピーする

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

クリップボードにコピーする際のフィードバックの提供

通知の重複を避ける

機密コンテンツをクリップボードに追加する

クリップボードから貼り付ける

プレーンテキストを貼り付ける

Kotlin

Java

Kotlin

Java

Kotlin

Java

コンテンツ URI からデータを貼り付ける

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

インテントを貼り付ける

Kotlin

Java

アプリがクリップボード データにアクセスしたときに表示されるシステム通知

コンテンツ プロバイダを使用して複雑なデータをコピーする

URI に対して識別子をエンコードする

Kotlin

Java

データ構造をコピーする

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

データ ストリームをコピーする

効果的なコピー＆ペースト機能を設計する

クリップボードフレームワーク

クリップボードクラス

ClipData コンビニエンスメソッド

クリップボードデータをテキストに強制変換する

アプリがクリップボードデータにアクセスしたときに表示されるシステム通知

コンテンツプロバイダを使用して複雑なデータをコピーする

データストリームをコピーする