Sao chép và dán

Android cung cấp một khung toàn diện về bảng nhớ tạm cho thao tác sao chép và dán. Khung này hỗ trợ cả loại dữ liệu đơn giản và phức tạp, bao gồm cả chuỗi văn bản, cấu trúc dữ liệu phức tạp, dữ liệu văn bản, dữ liệu trong luồng tệp nhị phân và thậm chí là tài sản của ứng dụng. Dữ liệu văn bản đơn giản được lưu trữ trực tiếp trong bảng nhớ tạm, còn dữ liệu phức tạp được lưu trữ dưới dạng tệp đối chiếu mà ứng dụng dán phân giải thông qua nhà cung cấp nội dung. Việc sao chép và dán diễn ra cả trong một ứng dụng và giữa các ứng dụng cài đặt khung.

Vì một phần của khung này sử dụng các nhà cung cấp nội dung, nên chủ đề này giả định rằng nhà phát triển biết về ndroid Content Provider API theo mô tả trong chủ đề Nhà cung cấp nội dung.

Khung bảng nhớ tạm

Khi sử dụng khung bảng nhớ tạm (clipboard framework), bạn đặt dữ liệu vào một đối tượng cắt (clip), sau đó đặt đối tượng clip đó vào bảng nhớ tạm trên toàn hệ thống. Đối tượng clip có ba dạng sau:

Văn bản
Chuỗi văn bản. Bạn đặt trực tiếp chuỗi vào đối tượng clip mà sau đó được đặt vào bảng nhớ tạm. Để dán chuỗi, bạn lấy đối tượng clip từ bảng nhớ tạm và sao chép chuỗi vào bộ nhớ của ứng dụng.
URI
Đối tượng Uri đại diện cho bất kỳ dạng URI nào. Việc này chủ yếu để sao chép dữ liệu phức tạp từ một nhà cung cấp nội dung. Để sao chép dữ liệu, bạn đặt một đối tượng Uri vào một đối tượng clip và đặt đối tượng clip đó vào bảng nhớ tạm. Để dán dữ liệu, bạn sẽ lấy đối tượng clip, lấy đối tượng Uri, phân giải đối tượng đó thành một nguồn dữ liệu như nhà cung cấp nội dung, rồi sao chép dữ liệu từ nguồn đó vào bộ nhớ của ứng dụng.
Intent
Một Intent (ý định). Dạng đối tượng này hỗ trợ sao chép lối tắt ứng dụng. Để sao chép dữ liệu, bạn tạo một Intent, đặt vào một đối tượng clip rồi đặt đối tượng clip vào bảng nhớ tạm. Để dán dữ liệu, bạn sẽ lấy đối tượng clip rồi sao chép đối tượng Intent vào vùng bộ nhớ của ứng dụng.

Bảng nhớ tạm chỉ chứa một đối tượng clip tại mỗi thời điểm. Khi ứng dụng đặt đối tượng clip trên bảng nhớ tạm, đối tượng clip trước đó sẽ biến mất.

Nếu muốn cho phép người dùng dán dữ liệu vào ứng dụng của mình, bạn không cần phải xử lý tất cả các loại dữ liệu. Bạn có thể kiểm tra dữ liệu trên bảng nhớ tạm trước khi cho phép người dùng dán dữ liệu đó. Ngoài việc có một số loại dữ liệu nhất định, đối tượng clip còn chứa siêu dữ liệu cho bạn biết loại hoặc loại MIME nào có sẵn. Siêu dữ liệu này giúp bạn quyết định liệu ứng dụng của mình có thể làm điều gì đó hữu ích với dữ liệu trong bảng nhớ tạm hay không. Chẳng hạn, nếu có một ứng dụng chủ yếu xử lý văn bản, bạn có thể cần bỏ qua các đối tượng clip chứa URI hoặc Intent.

Bạn cũng có thể cho phép người dùng dán văn bản bất kể dạng dữ liệu nào trên bảng nhớ tạm. Để làm điều này, bạn có thể biểu diễn dữ liệu bảng nhớ tạm dưới dạng văn bản, sau đó dán văn bản này. Phần này được mô tả trong nội dung Chuyển đổi dữ liệu bảng nhớ tạm thành văn bản.

Các lớp bảng nhớ tạm

Phần này mô tả các lớp mà khung bảng nhớ tạm sử dụng.

ClipboardManager

Trong hệ thống Android, bảng nhớ tạm của hệ thống được biểu thị bằng lớp ClipboardManager toàn cục. Bạn không trực tiếp tạo một thực thể của lớp này; thay vào đó, bạn phải tham chiếu đến lớp này bằng cách gọi getSystemService(CLIPBOARD_SERVICE).

ClipData, ClipData.Item và ClipDescription

Để thêm dữ liệu vào bảng nhớ tạm, bạn tạo một đối tượng ClipData chứa cả phần mô tả dữ liệu và chính dữ liệu đó. Bảng nhớ tạm chỉ chứa một ClipData tại mỗi thời điểm. ClipData chứa một đối tượng ClipDescription và một hoặc nhiều đối tượng ClipData.Item.

Đối tượng ClipDescription chứa siêu dữ liệu về đối tượng clip. Đặc biệt, đối tượng này chứa một mảng các loại MIME có sẵn cho dữ liệu của đối tượng clip. Ngoài ra, trên Android 12 (API cấp độ 31) trở lên, siêu dữ liệu bao gồm thông tin về việc đối tượng có chứa văn bản cách điệu hay không và về loại văn bản trong đối tượng. Khi bạn đặt một đối tượng clip vào bảng nhớ tạm, thông tin này sẽ có sẵn cho các ứng dụng dán. Những ứng dụng này có thể kiểm tra xem liệu có thể xử lý dữ liệu đối tượng clip hay không.

Đối tượng ClipData.Item chứa dữ liệu văn bản, URI hoặc Intent:

Văn bản
Một CharSequence.
URI
Một Uri. Đối tượng này thường chứa một URI của nhà cung cấp nội dung, mặc dù bất kỳ URI nào cũng đều được. Ứng dụng cung cấp dữ liệu sẽ đặt URI trên bảng nhớ tạm. Các ứng dụng muốn dán dữ liệu sẽ lấy URI từ bảng nhớ tạm và dùng URI đó để truy cập nhà cung cấp nội dung (hoặc nguồn dữ liệu khác) và truy xuất dữ liệu đó.
Intent
Một Intent. Loại dữ liệu này cho phép bạn sao chép lối tắt ứng dụng vào bảng nhớ tạm. Sau đó, người dùng có thể dán lối tắt vào ứng dụng để sử dụng sau.

Bạn có thể thêm nhiều đối tượng ClipData.Item vào một clip. Việc này cho phép người dùng sao chép và dán nhiều lựa chọn dưới dạng một đối tượng clip duy nhất. Ví dụ: nếu có một tiện ích danh sách cho phép người dùng chọn nhiều mục cùng lúc, bạn có thể sao chép tất cả các mục vào bảng nhớ tạm cùng một lúc. Để thực hiện việc này, bạn tạo một ClipData.Item riêng cho từng mục trong danh sách, sau đó thêm các đối tượng ClipData.Item vào đối tượng ClipData.

Phương thức ClipData thuận tiện

Lớp ClipData cung cấp các phương thức tĩnh thuận tiện để tạo đối tượng ClipData bằng một đối tượng ClipData.Itemvà đối tượng ClipDescription đơn giản:

newPlainText(label, text)
Trả về đối tượng ClipData, trong đó mỗi đối tượng ClipData.Item chứa một chuỗi văn bản. Nhãn của đối tượng ClipDescription được thiết lập thành label. Loại MIME duy nhất trong ClipDescriptionMIMETYPE_TEXT_PLAIN.

Sử dụng newPlainText() để tạo một đối tượng clip từ một chuỗi văn bản.

newUri(resolver, label, URI)
Trả về đối tượng ClipData, trong đó mỗi ClipData.Item chứa một URI. Nhãn của đối tượng ClipDescription được thiết lập thành label. Nếu URI là một URI nội dung (Uri.getScheme() trả về content:), phương thức sử dụngContentResolver đối tượng được cung cấp trong resolver để truy xuất các loại MIME có sẵn từ nhà cung cấp nội dung và lưu trữ các loại đó bằng ClipDescription. Đối với URI không phải là URI content:, phương thức này sẽ thiết lập loại MIME thành MIMETYPE_TEXT_URILIST.

Sử dụng newUri() để tạo một đối tượng clip từ một URI, đặc biệt là URI content:.

newIntent(label, intent)
Trả về đối tượng ClipData, trong đó mỗi ClipData.Item chứa một Intent. Nhãn của đối tượng ClipDescription được thiết lập thành label. Loại MIME được thiết lập thành MIMETYPE_TEXT_INTENT.

Sử dụng newIntent() để tạo một đối tượng clip từ một đối tượng Intent.

Chuyển đổi dữ liệu bảng nhớ tạm thành văn bản

Ngay cả khi ứng dụng của bạn chỉ xử lý văn bản, bạn vẫn có thể sao chép dữ liệu không phải văn bản từ bảng nhớ tạm bằng cách chuyển đổi chúng bằng phương thức ClipData.Item.coerceToText().

Phương thức này chuyển đổi dữ liệu trong ClipData.Item thành văn bản và trả về CharSequence. Giá trị mà ClipData.Item.coerceToText() trả về sẽ dựa trên dạng dữ liệu trong ClipData.Item:

Văn bản
Nếu ClipData.Item là văn bản (getText() không mang giá trị rỗng), coerceToText() sẽ trả về văn bản (text).
URI
Nếu ClipData.Item là một URI (getUri() không mang giá trị rỗng), coerceToText() sẽ cố gắng sử dụng URI đó làm một URI nội dung:
  • Nếu URI là một URI nội dung và nhà cung cấp có thể trả về một dòng văn bản thì coerceToText() sẽ trả về một dòng văn bản.
  • Nếu URI là một URI nội dung nhưng nhà cung cấp không cung cấp một dòng văn bản, thì coerceToText() sẽ trả về kết quả biểu diễn của URI. Kết quả biểu diễn giống với kết quả doUri.toString() trả về.
  • Nếu URI không phải là URI nội dung, thì coerceToText() sẽ trả về kết quả biểu diễn của URI. Kết quả biểu diễn giống với kết quả doUri.toString() trả về.
Intent
Nếu ClipData.Item là một Ý định (getIntent() không mang giá trị rỗng), coerceToText() sẽ chuyển đổi Ý định đó thành một URI Ý định và trả về URI Ý định này. Kết quả biểu diễn giống với kết quả do Intent.toUri(URI_INTENT_SCHEME) trả về.

Khung bảng nhớ tạm được tóm tắt trong Hình 1. Để sao chép dữ liệu, ứng dụng sẽ đặt đối tượng ClipData vào bảng nhớ tạm ClipboardManager toàn cục. ClipData chứa một hoặc nhiều đối tượng ClipData.Item và một đối tượng ClipDescription. Để dán dữ liệu, ứng dụng sẽ nhận ClipData, nhận loại MIME từ ClipDescription và nhận dữ liệu từ ClipData.Item hoặc từ nhà cung cấp nội dung do ClipData.Item tham chiếu đến.

Sơ đồ khối của khung sao chép và dán

Hình 1. Khung bảng nhớ tạm của Android

Sao chép vào Bảng nhớ tạm

Như trong phần mô tả trước, để sao chép dữ liệu vào bảng nhớ tạm mà bạn tham chiếu (handle) đến đối tượng ClipboardManager toàn cục, tạo đối tượng ClipData, thêm ClipDescription và một hoặc nhiều đối tượng ClipData.Item cho đối tượng này và thêm đối tượng ClipData đã hoàn chỉnh vào đối tượng ClipboardManager. Chi tiết từng bước được mô tả dưới đây:

  1. Nếu bạn đang sao chép dữ liệu bằng URI nội dung, hãy thiết lập nhà cung cấp nội dung.

    Ứng dụng mẫu NotePad là một ví dụ về cách sử dụng nhà cung cấp nội dung để sao chép và dán. Lớp NotePadProvider triển khai nhà cung cấp nội dung. Lớp NotePad định nghĩa contract (hợp đồng) giữa nhà cung cấp nội dung và các ứng dụng khác, bao gồm cả các loại MIME được hỗ trợ.

  2. Lấy bảng nhớ tạm thời của hệ thống:

    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);
    
  3. Sao chép dữ liệu vào đối tượng ClipData mới:

    • Đối với văn bản

      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!");
      
    • Đối với URI

      Đoạn mã này khởi tạo URI bằng cách mã hoá mã nhận dạng bản ghi vào URI nội dung cho nhà cung cấp. Kỹ thuật này được đề cập chi tiết hơn trong phần Mã hoá giá trị nhận dạng trên URI:

      Kotlin

      // Creates a Uri based on 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 that you use 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 based on 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 that you use 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);
      
    • Đối với Ý định

      Đoạn mã này khởi tạo một Ý định cho một ứng dụng, sau đó đặt nó vào đối tượng clip:

      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);
      
  4. Đặt đối tượng clip mới vào bảng nhớ tạm:

    Kotlin

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

    Java

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

Dán từ Bảng nhớ tạm

Như đã mô tả trước đó, bạn dán dữ liệu từ bảng nhớ tạm bằng cách lấy đối tượng bảng nhớ tạm toàn cục, lấy đối tượng clip, xem dữ liệu của đối tượng và nếu có thể, sao chép dữ liệu từ đối tượng clip vào bộ nhớ của riêng bạn. Phần này giải thích chi tiết cách dán 3 loại dữ liệu trên bảng nhớ tạm.

Dán văn bản thuần tuý

Để dán văn bản thuần tuý, trước tiên hãy lấy bảng nhớ tạm toàn cục và xác minh rằng bảng nhớ tạm có thể trả về văn bản thuần tuý. Sau đó, lấy đối tượng clip và sao chép văn bản của đối tượng đó vào bộ nhớ của riêng bạn bằng getText() theo cách như sau:

  1. Lấy đối tượng ClipboardManager toàn cục bằng getSystemService(CLIPBOARD_SERVICE). Ngoài ra, hãy khai báo một biến toàn cục để chứa văn bản được dán:

    Kotlin

    var clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    var pasteData: String = ""
    

    Java

    ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
    String pasteData = "";
    
  2. Tiếp theo, hãy xác định xem bạn nên bật hay tắt tuỳ chọn "dán" trong Hoạt động (activity) hiện tại. Bạn nên xác minh xem bảng nhớ tạm có chứa một đối tượng clip và bạn có thể xử lý loại dữ liệu do đối tượng clip đó biểu diễn hay không:

    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 if you can handle the data.
    pasteItem.isEnabled = when {
        !clipboard.hasPrimaryClip() -> {
            false
        }
        !(clipboard.primaryClipDescription.hasMimeType(MIMETYPE_TEXT_PLAIN)) -> {
            // This disables the paste menu item, since the clipboard has data but it is not plain text
            false
        }
        else -> {
            // This 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 if you can handle the data.
    if (!(clipboard.hasPrimaryClip())) {
    
        pasteItem.setEnabled(false);
    
    } else if (!(clipboard.getPrimaryClipDescription().hasMimeType(MIMETYPE_TEXT_PLAIN))) {
    
        // This disables the paste menu item, since the clipboard has data but it is not plain text
        pasteItem.setEnabled(false);
    } else {
    
        // This enables the paste menu item, since the clipboard contains plain text.
        pasteItem.setEnabled(true);
    }
    
  3. Sao chép dữ liệu từ bảng nhớ tạm. Bạn chỉ có thể thực hiện đến bước này nếu mục "dán" trong trình đơn được bật. Vì vậy bạn có thể giả định rằng bảng nhớ tạm hiện chứa văn bản thuần tuý. Bạn chưa biết liệu bảng nhớ tạm có chứa một chuỗi văn bản hoặc một URI trỏ đến văn bản thuần tuý hay không. Đoạn mã sau đây giúp kiểm thử điều này nhưng chỉ bao gồm mã để xử lý văn bản thuần tuý:

    Kotlin

    when (menuItem.itemId) {
        ...
        R.id.menu_paste -> {    // Responds to the user selecting "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.
            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 does not 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 is not
                    // presented here.
                    pasteData = resolveUri(pasteUri)
                    true
                } else {
    
                    // Something is wrong. The MIME type was plain text, but the clipboard does not
                    // contain either 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 does not 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 is not
            // presented here.
            pasteData = resolveUri(Uri);
            return true;
        } else {
    
            // Something is wrong. The MIME type was plain text, but the clipboard does not contain either
            // text or a Uri. Report an error.
            Log.e(TAG, "Clipboard contains an invalid data type");
            return false;
        }
    }
    

Dán dữ liệu từ URI nội dung

Nếu đối tượng ClipData.Item chứa một URI nội dung và bạn đã xác định rằng có thể xử lý một trong các loại MIME của đối tượng đó, hãy tạo một ContentResolver, sau đó gọi phương thức nhà cung cấp nội dung thích hợp để truy xuất dữ liệu.

Quy trình sau đây mô tả cách lấy dữ liệu từ nhà cung cấp nội dung dựa trên URI nội dung trên bảng nhớ tạm. Quy trình này kiểm tra xem nhà cung cấp có cung cấp loại MIME mà ứng dụng có thể sử dụng hay không:

  1. Khai báo biến toàn cục chứa loại 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";
    
  2. Lấy bảng nhớ tạm toàn cục. Ngoài ra, hãy sử dụng trình phân giải nội dung để bạn có thể truy cập vào nhà cung cấp nội dung:

    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();
    
  3. Lấy đối tượng clip chính từ bảng nhớ tạm và nội dung của nó dưới dạng 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();
    
  4. Kiểm tra xem URI đó có phải là URI nội dung hay không bằng cách gọi getType(Uri). Phương thức này trả về giá trị rỗng nếu Uri không trỏ đến một nhà cung cấp nội dung hợp lệ:

    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);
    
  5. Kiểm tra xem nhà cung cấp nội dung có hỗ trợ loại MIME mà ứng dụng hiện tại hiểu được hay không. Nếu có, gọi ContentResolver.query() để lấy dữ liệu. Giá trị trả về là Cursor:

    Kotlin

            // If the return value is not 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 will vary according to the
                        // format of the data model.
                    }
    
                    // Kotlin `use` will automatically close the Cursor
                }
            }
        }
    }
    

    Java

            // If the return value is not 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 will vary according to the
                        // format of the data model.
                        }
                    }
    
                    // close the Cursor
                    pasteCursor.close();
                 }
             }
         }
    }
    

Dán Ý định

Để dán một Ý định, trước tiên hãy lấy bảng nhớ tạm toàn cục. Kiểm tra đối tượng ClipData.Item để xem đối tượng đó có chứa Ý định hay không. Sau đó, gọi getIntent() để sao chép Ý định vào bộ nhớ của riêng bạn. Đoạn mã sau hướng dẫn cách thực hiện:

Kotlin

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

// Checks to see if the clip item contains an Intent, by testing to see if 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 your application was expecting an Intent to be
    // on the clipboard
}

Java

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

// Checks to see if the clip item contains an Intent, by testing to see if 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 your application was expecting an Intent to be
    // on the clipboard
}

Hệ thống hiển thị thông báo khi ứng dụng truy cập vào dữ liệu bảng nhớ tạm

Trên Android 12 (API cấp 31) trở lên, hệ thống thường hiển thị một thông báo nhanh bằng thông báo khi ứng dụng của bạn gọi getPrimaryClip(). Văn bản bên trong thông báo có định dạng sau:

APP pasted from your clipboard

Hệ thống không hiển thị thông báo nhanh khi ứng dụng của bạn:

  • Truy cập vào ClipData qua ứng dụng của bạn.
  • Liên tục truy cập vào ClipData từ một ứng dụng cụ thể. Thông báo nhanh chỉ xuất hiện khi ứng dụng của bạn truy cập dữ liệu của ứng dụng đó lần đầu tiên.
  • Truy xuất siêu dữ liệu cho đối tượng clip, chẳng hạn như bằng cách gọi getPrimaryClipDescription() thay vì getPrimaryClip().

Sử dụng nhà cung cấp nội dung để sao chép dữ liệu phức tạp

Nhà cung cấp nội dung hỗ trợ sao chép dữ liệu phức tạp như bản ghi cơ sở dữ liệu hoặc dòng tệp. Để sao chép dữ liệu, đặt một URI nội dung vào bảng nhớ tạm. Sau đó, các ứng dụng dán lấy URI này từ bảng nhớ tạm và dùng URI đó để truy xuất dữ liệu trong cơ sở dữ liệu hoặc trình mô tả dòng tệp.

Vì ứng dụng dán chỉ có URI nội dung cho dữ liệu nên ứng dụng này cần biết dữ liệu nào cần truy xuất. Bạn có thể cung cấp thông tin này bằng cách mã hoá một giá trị nhận dạng cho dữ liệu trên chính URI, hoặc bạn có thể cung cấp một URI độc nhất để trả về dữ liệu mà bạn muốn sao chép. Kỹ thuật bạn chọn phụ thuộc vào cách sắp xếp dữ liệu của bạn.

Các phần sau đây mô tả cách thiết lập URI, cách cung cấp dữ liệu phức tạp và cách cung cấp dòng tệp. Những nội dung sau đây giả định rằng bạn đã nắm rõ các nguyên tắc chung về thiết kế nhà cung cấp nội dung.

Mã hoá giá trị nhận dạng trên URI

Một kỹ thuật hữu ích để sao chép dữ liệu vào bảng nhớ tạm bằng URI là mã hoá giá trị nhận dạng cho chính dữ liệu đó trong URI. Nhà cung cấp nội dung của bạn có thể lấy giá trị nhận dạng từ URI và dùng giá trị đó để truy xuất dữ liệu. Ứng dụng dán không cần phải biết rằng có giá trị nhận dạng hay không mà chỉ cần lấy "tệp tham chiếu" (URI cộng với giá trị nhận dạng) từ bảng nhớ tạm, cung cấp tệp đó cho nhà cung cấp nội dung của bạn rồi tiến hành lấy lại dữ liệu.

Bạn thường mã hoá giá trị nhận dạng trên một URI nội dung bằng cách ghép nối giá trị nhận dạng đó vào cuối URI. Ví dụ: giả sử bạn định nghĩa URI nhà cung cấp như chuỗi sau:

"content://com.example.contacts"

Nếu muốn mã hoá tên vào URI này, bạn sẽ sử dụng đoạn mã sau:

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);

Nếu đang sử dụng một nhà cung cấp nội dung, bạn nên thêm một đường dẫn URI mới cho biết URI đó là để sao chép. Ví dụ: giả sử bạn đã có đường dẫn URI sau:

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

Bạn có thể thêm một đường dẫn khác dành riêng cho việc sao chép URI:

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

Sau đó, bạn có thể phát hiện URI "sao chép" đó bằng cách so khớp mẫu và xử lý URI bằng mã riêng cho việc sao chép và dán.

Bạn thường sử dụng kỹ thuật mã hoá nếu đã sử dụng nhà cung cấp nội dung, cơ sở dữ liệu nội bộ hoặc bảng nội bộ để sắp xếp dữ liệu. Trong những trường hợp này, bạn có nhiều dữ liệu muốn sao chép và có thể bạn có một giá trị nhận dạng độc nhất cho từng dữ liệu. Để phản hồi truy vấn từ ứng dụng dán, bạn có thể tra cứu dữ liệu theo giá trị nhận dạng và trả về dữ liệu đó.

Nếu bạn không có nhiều dữ liệu thì có thể không cần phải mã hoá giá trị nhận dạng. Bạn chỉ cần sử dụng một URI độc nhất dành riêng cho nhà cung cấp của mình. Để phản hồi một truy vấn, nhà cung cấp của bạn sẽ trả về dữ liệu hiện có.

Lấy một bản ghi theo ID được dùng trong ứng dụng mẫu Note Pad để mở ghi chú trong danh sách ghi chú. Mẫu này sử dụng trường _id từ cơ sở dữ liệu SQL, nhưng bạn có thể có bất kỳ giá trị nhận dạng kiểu số hoặc ký tự nào.

Sao chép cấu trúc dữ liệu

Bạn thiết lập một nhà cung cấp nội dung để sao chép và dán dữ liệu phức tạp làm một lớp con của thành phần ContentProvider. Bạn cũng nên mã hoá URI mà bạn đặt vào bảng nhớ tạm để URL đó trỏ đến đúng bản ghi bạn muốn cung cấp. Ngoài ra, bạn phải xem xét trạng thái hiện tại của ứng dụng:

  • Nếu đã có nhà cung cấp nội dung, bạn có thể thêm vào phần chức năng của nhà cung cấp đó. Bạn chỉ có thể cần chỉnh sửa phương thức query() để xử lý các URI đến từ các ứng dụng muốn dán dữ liệu. Bạn nên chỉnh sửa phương thức để xử lý mẫu URI "sao chép".
  • Nếu ứng dụng của bạn duy trì một cơ sở dữ liệu nội bộ, bạn nên di chuyển cơ sở dữ liệu này vào một nhà cung cấp nội dung để dễ dàng sao chép từ nhà cung cấp đó.
  • Nếu không sử dụng cơ sở dữ liệu, bạn có thể triển khai một nhà cung cấp nội dung đơn giản với mục đích duy nhất là cung cấp dữ liệu cho các ứng dụng mà dán dữ liệu từ bảng nhớ tạm.

Trong nhà cung cấp nội dung, ít nhất bạn sẽ cần ghi đè các phương thức sau:

query()
Các ứng dụng dán sẽ cho rằng các ứng dụng đó có thể lấy dữ liệu của bạn bằng cách sử dụng phương thức này qua URI mà bạn đặt trên bảng nhớ tạm. Để hỗ trợ sao chép, bạn nên dùng phương thức này để phát hiện các URI chứa đường dẫn "sao chép" đặc biệt. Sau đó, ứng dụng của bạn có thể tạo URI "sao chép" để đưa vào bảng nhớ tạm chứa đường dẫn sao chép và con trỏ đến bản ghi chính xác mà bạn muốn sao chép.
getType()
Phương thức này sẽ trả về loại MIME hoặc các loại MIME cho dữ liệu mà bạn định sao chép. Phương thức newUri() gọi getType() để đặt các loại MIME vào đối tượng ClipData mới.

Các loại MIME cho dữ liệu phức tạp được mô tả trong phầnNhà cung cấp nội dung.

Lưu ý rằng bạn không nhất thiết phải có bất kỳ phương thức nào khác dành cho nhà cung cấp nội dung, chẳng hạn như insert() hoặc update(). Một ứng dụng dán chỉ cần lấy các loại MIME được hỗ trợ và sao chép dữ liệu từ nhà cung cấp của bạn. Nếu bạn đã sử dụng các phương thức này, chúng sẽ không ảnh hưởng đến hoạt động sao chép.

Các đoạn mã sau hướng dẫn cách thiết lập ứng dụng của bạn để sao chép dữ liệu phức tạp:

  1. Trong các hằng số toàn cục của ứng dụng, khai báo chuỗi URI cơ sở và đường dẫn xác định chuỗi URI mà bạn sử dụng để sao chép dữ liệu. Ngoài ra, hãy khai báo loại MIME cho dữ liệu được sao chép:

    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";
    
  2. Trong Hoạt động mà người dùng sao chép dữ liệu, hãy thiết lập mã để sao chép dữ liệu vào bảng nhớ tạm. Để phản hồi lại một yêu cầu sao chép, đặt URI vào bảng nhớ tạm:

    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)
    
            // Set 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);
    
        // Set the clipboard's primary clip.
        clipboard.setPrimaryClip(clip);
    
  3. Trong tầm vực toàn cục của nhà cung cấp nội dung, tạo một trình so khớp URI và thêm một mẫu URI sẽ khớp với các URI mà bạn đặt trên bảng nhớ tạm:

    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);
    
  4. Thiết lập phương thức query(). Phương thức này có thể xử lý các mẫu URI khác nhau, tuỳ thuộc vào cách bạn mã hoá, nhưng chỉ mẫu dùng cho thao tác sao chép vào bảng nhớ tạm mới được hiển thị:

    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 -> {
    
                // query and return the contact for the requested name. Here you would decode
                // the incoming URI, query the data model based on the last name, and return 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:
    
            // query and return the contact for the requested name. Here you would decode
            // the incoming URI, query the data model based on the last name, and return the result
            // as a Cursor.
    
        ...
    
    }
    
  5. Thiết lập phương thức getType() để trả về một loại MIME thích hợp cho dữ liệu được sao chép:

    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);
        ...
        }
    }
    

Phần Dán dữ liệu từ URI nội dung mô tả cách lấy URI nội dung từ bảng nhớ tạm và sử dụng URI đó để lấy và dán dữ liệu.

Sao chép luồng dữ liệu

Bạn có thể sao chép và dán lượng lớn văn bản và dữ liệu tệp nhị phân dưới dạng luồng. Dữ liệu có thể có các dạng như sau:

  • Tệp được lưu trữ trên thiết bị thực tế.
  • Luồng từ socket.
  • Lượng dữ liệu lớn được lưu trữ trong hệ thống cơ sở dữ liệu cơ bản của nhà cung cấp.

Nhà cung cấp nội dung cho luồng dữ liệu sẽ cấp quyền truy cập dữ liệu bằng đối tượng chỉ số mô tả tệp, chẳng hạn như AssetFileDescriptor thay vì đối tượng Cursor. Ứng dụng dán sẽ đọc luồng dữ liệu bằng chỉ số mô tả tệp này.

Để thiết lập ứng dụng của bạn cho việc sao chép luồng dữ liệu với nhà cung cấp, hãy làm theo các bước sau:

  1. Thiết lập URI nội dung cho luồng dữ liệu mà bạn đang đặt vào bảng nhớ tạm. Các phương án để thực hiện việc này bao gồm:
    • Mã hoá giá trị nhận dạng cho luồng dữ liệu vào URI theo cách được mô tả trong phần Mã hoá giá trị nhận dạng trên URI, sau đó duy trì bảng trong nhà cung cấp chứa giá trị nhận dạng và tên luồng tương ứng.
    • Mã hoá tên luồng trực tiếp trên URI.
    • Sử dụng một URI độc nhất luôn trả về luồng hiện tại từ nhà cung cấp. Nếu sử dụng phương án này, bạn phải nhớ cập nhật nhà cung cấp của mình để trỏ đến một luồng khác bất cứ khi nào bạn sao chép luồng vào bảng nhớ tạm qua URI.
  2. Cung cấp một loại MIME cho mỗi loại luồng dữ liệu mà bạn định cung cấp. Các ứng dụng dán cần thông tin này để xác định xem có thể dán dữ liệu vào bảng nhớ tạm hay không.
  3. Triển khai một trong các phương thức ContentProvider mà trả về chỉ số mô tả tệp cho luồng. Nếu bạn mã hoá giá trị nhận dạng trên URI nội dung, sử dụng phương thức này để xác định luồng nào cần mở.
  4. Để sao chép luồng dữ liệu vào bảng nhớ tạm, khởi tạo URI nội dung và đặt URI đó vào bảng nhớ tạm.

Để dán luồng dữ liệu, ứng dụng sẽ lấy đối tượng clip từ bảng nhớ tạm và URI, sau đó sử dụng URI đó trong lệnh gọi phương thức chỉ số mô tả tệp ContentResolver mà mở luồng. Phương thức ContentResolver gọi phương thức ContentProvider tương ứng và truyền URI nội dung vào phương thức tương ứng đó. Nhà cung cấp của bạn trả về chỉ số mô tả tệp cho phương thức ContentResolver. Sau đó, ứng dụng dán có trách nhiệm đọc dữ liệu từ luồng.

Danh sách sau đây liệt kê các phương thức chỉ số mô tả tệp quan trọng nhất đối với nhà cung cấp nội dung. Mỗi phương thức đều có một phương thức ContentResolver tương ứng, trong đó có chuỗi "Mô tả" sẽ được thêm vào tên phương thức; ví dụ: phương thức tương tự ContentResolver của openAssetFile()openAssetFileDescriptor():

openTypedAssetFile()
Phương thức này sẽ trả về chỉ số mô tả tệp tài sản, nhưng chỉ khi nhà cung cấp hỗ trợ loại MIME đã cung cấp. Phương thức gọi (ứng dụng thực hiện thao tác dán) cung cấp một mẫu loại MIME. Nhà cung cấp nội dung (của ứng dụng đã sao chép URI vào bảng nhớ tạm) trả về một tham chiếu tệp (file handle) AssetFileDescriptor nếu có thể cung cấp loại MIME đó hoặc báo ngoại lệ nếu không thể.

Phương thức này xử lý các mục con trong tệp. Bạn có thể sử dụng phương thức này để đọc các tài sản mà nhà cung cấp nội dung đã sao chép vào bảng nhớ tạm.

openAssetFile()
Phương thức này là một phương thức chung của openTypedAssetFile(). Phương thức này không lọc các loại MIME được phép nhưng có thể đọc các mục con trong tệp.
openFile()
Phương thức này là một phương thức chung của openAssetFile(). Phương thức này không thể đọc các mục con trong tệp.

Bạn có thể chọn sử dụng phương thức openPipeHelper() cùng với phương thức chỉ số mô tả tệp. Cách này cho phép ứng dụng dán đọc chuỗi dữ liệu trong luồng trong luồng nền (background thread) thông qua một ống dẫn (pipe). Để sử dụng phương thức này, bạn cần triển khai giao diện ContentProvider.PipeDataWriter. Ví dụ về cách sử dụng phương thức này được mô tả trong phần ứng dụng mẫu Note Pad, trong phương thức openTypedAssetFile() của NotePadProvider.java.

Thiết kế chức năng sao chép/dán hiệu quả

Để thiết kế chức năng sao chép và dán hiệu quả cho ứng dụng của bạn, hãy lưu ý những điểm sau:

  • Tại bất kỳ thời điểm nào, bảng nhớ tạm chỉ chứa một đối tượng clip duy nhất. Thao tác sao chép mới của bất kỳ ứng dụng nào trong hệ thống cũng sẽ ghi đè đối tượng clip trước đó. Vì người dùng có thể thoát khỏi ứng dụng của bạn và sao chép trước khi trở lại ứng dụng nên bạn không thể giả định rằng bảng nhớ tạm chứa đối tượng clip mà người dùng đã sao chép trước đó trong ứng dụng của bạn.
  • Mục đích của nhiều đối tượng ClipData.Item cho mỗi đối tượng clip là hỗ trợ việc sao chép và dán khi nhiều mục được chọn thay vì có nhiều hình thức tham chiếu đến một mục được chọn. Thông thường, bạn muốn mọi đối tượng ClipData.Item trong một đối tượng clip đều có cùng dạng thức, nghĩa là tất cả đều phải là văn bản, URI nội dung hoặc Intent đơn giản, chứ không phải là kết hợp nhiều dạng.
  • Khi cung cấp dữ liệu, bạn có thể biểu diễn các loại MIME khác nhau. Thêm các loại MIME được hỗ trợ vào ClipDescription, sau đó triển khai các loại MIME trong nhà cung cấp nội dung của bạn.
  • Khi bạn nhận được dữ liệu từ bảng nhớ tạm, ứng dụng của bạn chịu trách nhiệm kiểm tra loại MIME có sẵn rồi quyết định sử dụng loại MIME nào (nếu có). Ngay cả khi có một đối tượng clip trên bảng nhớ tạm và người dùng yêu cầu dán, thì ứng dụng của bạn cũng không bắt buộc phải thực hiện thao tác dán đó. Bạn nên thực hiện thao tác dán nếu loại MIME đó tương thích. Bạn có thể chuyển đổi dữ liệu trên bảng nhớ tạm thành văn bản bằng cách sử dụng coerceToText() nếu muốn. Nếu ứng dụng của bạn hỗ trợ nhiều loại MIME hiện có, bạn có thể cho phép người dùng chọn loại MIME để sử dụng.