【翻译】(87)复制与粘贴

【翻译】(87)复制与粘贴

 

see

http://developer.android.com/guide/topics/clipboard/copy-paste.html

 

原文见

http://developer.android.com/guide/topics/clipboard/copy-paste.html

 

-------------------------------

 

Copy and Paste

 

复制与粘贴

 

-------------------------------

 

Quickview

 

快速概览

 

* A clipboard-based framework for copying and pasting data.

 

* 一个基于剪贴板的框架，用于复制和粘贴数据。

 

* Supports both simple and complex data, including text strings, complex data structures, text and binary stream data, and application assets.

 

* 支持简单和复杂的数据，包括文本字符串，复杂数据结构，文本和二进制流数据，和应用程序资源。

 

* Copies and pastes simple text directly to and from the clipboard.

 

* 直接地复制和粘贴简单文本进出剪贴板。

 

* Copies and pastes complex data using a content provider.

 

* 使用一个内容提供者复制和粘贴复杂数据。

 

* Requires API 11.

 

* 需要API级别11（注：Android 3.0）。

 

In this document

 

本文目录

 

* The Clipboard Framework 剪贴板框架

* Clipboard Classes 剪贴板类

* ClipboardManager 

* ClipData, ClipDescription, and ClipData.Item ClipData，ClipDescription，与ClipData.Item

* ClipData convenience methods ClipData的便利方法

* Coercing the clipboard data to text 强制转换剪贴板数据为文本

* Copying to the Clipboard 复制到剪贴板

* Pasting from the Clipboard 从剪贴板中粘贴

* Pasting plain text 粘贴纯文本

* Pasting data from a content URI 从一个内容URI中粘贴数据

* Pasting an Intent 粘贴一个意图

* Using Content Providers to Copy Complex Data 使用内容提供者以复制复杂的数据

* Encoding an identifier on the URI 在URI上编码一个标识符

* Copying data structures 复制数据结构

* Copying data streams 复制数据流

* Designing Effective Copy/Paste Functionality 设计有效的复制/粘贴功能

 

Key classes

 

关键类

 

ClipboardManager

ClipData

ClipData.Item

ClipDescription

Uri

ContentProvider

Intent

 

Related Samples

 

相关示例

 

Note Pad sample application 记事本示例应用程序

 

See also

 

另见

 

Content Providers 内容提供者

 

-------------------------------

 

Android provides a powerful clipboard-based framework for copying and pasting. It supports both simple and complex data types, including text strings, complex data structures, text and binary stream data, and even application assets. Simple text data is stored directly in the clipboard, while complex data is stored as a reference that the pasting application resolves with a content provider. Copying and pasting works both within an application and between applications that implement the framework.

 

Android提供一个强大的基于剪贴板框架用于复制和粘贴。它支持简单和复杂的数据类型，包括文本字符串，复杂数据结构，文本和二进制流数据，甚至应用程序资源。简单文本数据被直接存储在剪贴板内，而复杂数据则被存储作为一个引用，粘贴的应用程序用一个内容提供者来解析它。复制和粘贴都能工作于实现该框架的一个应用程序内和多个应用程序之间。

 

Since a part of the framework uses content providers, this topic assumes some familiarity with the Android Content Provider API, which is described in the topic Content Providers.

 

因为框架的一部分使用内容提供者，所以这个主题假设你对Android的内容提供者API有一些认识，它在主题内容提供者中被描述。

 

-------------------------------

 

The Clipboard Framework

 

剪贴板框架

 

When you use the clipboard framework, you put data into a clip object, and then put the clip object on the system-wide clipboard. The clip object can take one of three forms:

 

当你使用剪贴板框架时，你放数据进一个剪辑对象中，然后放剪辑对象在系统范围的剪贴板上。剪辑对象可以具有三种形式的其中一种：

 

Text

 

文本

 

A text string. You put the string directly into the clip object, which you then put onto the clipboard. To paste the string, you get the clip object from the clipboard and copy the string to into your application's storage.

 

一个文本字符串，你直接地放置字符串进剪辑对象中，然后你把它放在剪贴板上。为了粘贴该字符串，你从剪贴板中获得剪辑对象并复制字符串以放进你的应用程序的存储中。

 

URI

 

URI（注：统一资源标识符）

 

A Uri object representing any form of URI. This is primarily for copying complex data from a content provider. To copy data, you put a Uri object into a clip object and put the clip object onto the clipboard. To paste the data, you get the clip object, get the Uri object, resolve it to a data source such as a content provider, and copy the data from the source into your application's storage.

 

一个Uri对象代表任意形式的URI。它主要用于从一个内容提供者中复制复杂数据。为了复制数据，你放一个Uri对象进一个剪辑对象并方剪辑对象到剪贴板上。为了粘贴数据，你获得剪辑对象，获得Uri对象，解析它为一个数据源诸如一个内容提供者，并且从源中复制数据进你的应用程序的存储中。

 

Intent

 

意图

 

An Intent. This supports copying application shortcuts. To copy data, you create an Intent, put it into a clip object, and put the clip object onto the clipboard. To paste the data, you get the clip object and then copy the Intent object into your application's memory area.

 

一个Intent。它支持复制应用程序快捷方式。为了复制数据，你创建一个Intent，放置它进一个剪辑对象，并且放置剪辑对象到剪贴板上。为了粘贴数据，你获得剪辑对象，然后复制Intent对象进你的应用程序的内存区中。

 

The clipboard holds only one clip object at a time. When an application puts a clip object on the clipboard, the previous clip object disappears.

 

剪贴板在一段时间内只持有一个剪辑对象。当一个应用程序放置一个剪辑对象在剪贴板上时，前一个剪辑对象消失。

 

If you want to allow users to paste data into your application, you don't have to handle all types of data. You can examine the data on the clipboard before you give users the option to paste it. Besides having a certain data form, the clip object also contains metadata that tells you what MIME type or types are available. This metadata helps you decide if your application can do something useful with the clipboard data. For example, if you have an application that primarily handles text you may want to ignore clip objects that contain a URI or Intent.

 

如果你希望允许用户粘贴数据进你的应用程序，那么你不必处理所有类型的数据。你可以在你给用户选项来粘贴它之前检查剪贴板上的数据。除了拥有某种数据形式，剪辑对象还包含元数据，告诉你哪种或哪些MIME类型是可用的。这个元数据帮助你决定你的应用程序是否可以做一些有助于处理剪贴板数据的事情。例如，如果你有一个应用程序，它主要处理文本，那么你可能希望忽略包含一个URI或Intent的剪辑对象。

 

You may also want to allow users to paste text regardless of the form of data on the clipboard. To do this, you can force the clipboard data into a text representation, and then paste this text. This is described in the section Coercing the clipboard to text.

 

你也可能希望允许用户粘贴文本，不管剪贴板上的数据形式。为了做到这一点，你可以强制剪贴板数据转换为一个文本表现，然后粘贴这个文本。这在章节强制转换剪贴板为文本中被描述。

 

-------------------------------

 

Clipboard Classes

 

剪贴板类

 

This section describes the classes used by the clipboard framework.

 

这个章节描述被剪贴板框架使用的类

 

ClipboardManager

 

In the Android system, the system clipboard is represented by the global ClipboardManager class. You do not instantiate this class directly; instead, you get a reference to it by invoking getSystemService(CLIPBOARD_SERVICE).

 

在Android系统中，系统剪贴板由全局ClipboardManager类表示。你不直接实例化这个类：取而代之，你通过调用getSystemService(CLIPBOARD_SERVICE)获得一个指向它的引用。

 

ClipData, ClipData.Item, and ClipDescription

 

ClipData，ClipData.Item，与ClipDescription

 

To add data to the clipboard, you create a ClipData object that contains both a description of the data and the data itself. The clipboard holds only one ClipData at a time. A ClipData contains a ClipDescription object and one or more ClipData.Item objects.

 

为了添加数据到剪贴板，你创建一个ClipData对象，它包含数据的描述和数据自身。剪贴板在一段时间内只持有一个ClipData。一个ClipData包含一个ClipDescription对象和一个或多个ClipData.Item对象。

 

A ClipDescription object contains metadata about the clip. In particular, it contains an array of available MIME types for the clip's data. When you put a clip on the clipboard, this array is available to pasting applications, which can examine it to see if they can handle any of available the MIME types.

 

一个ClipDescription对象包含关于剪辑的元数据。特别地，它包含剪辑数据的可用MIME类型的数组。当你放置一个剪辑在剪贴板上时，这个数组对于粘贴应用程序来说是可用的，它们可以检查它以了解它们是否可以处理任意可用的MIME类型。

 

A ClipData.Item object contains the text, URI, or Intent data:

 

一个ClipData.Item对象包含文本，URI，或Intent数据：

 

Text

 

文本

 

A CharSequence.

 

一个CharSequence。

 

URI

 

URI

 

A Uri. This usually contains a content provider URI, although any URI is allowed. The application that provides the data puts the URI on the clipboard. Applications that want to paste the data get the URI from the clipboard and use it to access the content provider (or other data source) and retrieve the data.

 

一个Uri。这通常包含一个内容提供者的URI，虽然允许是任意URI。提供数据的应用程序放置URI在剪贴板上。想要粘贴数据的应用程序从剪贴板中获得URI并且使用它来访问内容提供者（或其它数据源）并取出数据。

 

Intent

 

意图

 

An Intent. This data type allows you to copy an application shortcut to the clipboard. Users can then paste the shortcut into their applications for later use.

 

一个Intent。这个对象类型允许你复制一个应用程序快捷方式到剪贴板。然后用户可以粘贴快捷方式进他们的应用程序供稍后的使用。

 

You can add more than one ClipData.Item object to a clip. This allows users to copy and paste multiple selections as a single clip. For example, if you have a list widget that allows the user to select more than one item at a time, you can copy all the items to the clipboard at once. To do this, you create a separate ClipData.Item for each list item, and then you add the ClipData.Item objects to the ClipData object.

 

你可以添加多于一个ClipData.Item对象到一个剪辑。这允许用户复制和粘贴多个选择作为一个单一剪辑。例如，如果你有一个列表部件，它允许用户一次选择多于一个条目，你可以马上复制所有条目到剪贴板。为了做到这点，你为每个列表项创建一个单独的ClipData.Item，然后你添加ClipData.Item对象到ClipData对象。

 

ClipData convenience methods

 

ClipData的便利方法

 

The ClipData class provides static convenience methods for creating a ClipData object with a single ClipData.Item object and a simple ClipDescription object:

 

ClipData类提供静态便利方法用于创建一个带单一ClipData.Item对象和简单ClipDescription对象的ClipData对象：

 

newPlainText(label, text)

 

Returns a ClipData object whose single ClipData.Item object contains a text string. The ClipDescription object's label is set to label. The single MIME type in ClipDescription is MIMETYPE_TEXT_PLAIN.

 

返回一个ClipData对象，它的单一ClipData.Item对象包含一个文本字符串。ClipDescription对象的标签被设置为label。在ClipDescription中单一MIME类型是MIMETYPE_TEXT_PLAIN。

 

Use newPlainText() to create a clip from a text string.

 

使用newPlainText()以从一个文本字符串中创建一个剪辑。

 

newUri(resolver, label, URI)

 

Returns a ClipData object whose single ClipData.Item object contains a URI. The ClipDescription object's label is set to label. If the URI is a content URI (Uri.getScheme() returns content:), the method uses the ContentResolver object provided in resolver to retrieve the available MIME types from the content provider and store them in ClipDescription. For a URI that is not a content: URI, the method sets the MIME type to MIMETYPE_TEXT_URILIST.

 

返回一个ClipData对象，它的单一ClipData.Item对象包含一个URI。ClipDescription对象的标签被设置为label。如果URI是一个内容URI（Uri.getScheme()返回content:），那么该方法使用在resolver中提供的ContentResolver对象以从内容提供者中取出可用的MIME类型，并且存储它们在ClipDescription中。对于一个不是content: URI的URI，该方法设置MIME类型为MIMETYPE_TEXT_URILIST。

 

Use newUri() to create a clip from a URI, particularly a content: URI.

 

使用newUri()以从一个URI中创建一个剪辑，特别地是一个content: URI。

 

newIntent(label, intent)

 

Returns a ClipData object whose single ClipData.Item object contains an Intent. The ClipDescription object's label is set to label. The MIME type is set to MIMETYPE_TEXT_INTENT.

 

返回一个ClipData对象，它的单一ClipData.Item对象包含一个Intent。ClipDescription对象的标签被设置为label。MIME类型被设置为MIMETYPE_TEXT_INTENT。

 

Use newIntent() to create a clip from an Intent object.

 

使用newIntent()以从一个Intent对象中创建一个剪辑。

 

Coercing the clipboard data to text

 

强制转换剪贴板至文本

 

Even if your application only handles text, you can copy non-text data from the clipboard by converting it with the method ClipData.Item.coerceToText().

 

即便你的应用程序只处理文本，你也可以通过用方法ClipData.Item.coerceToText()转换它，从剪贴板中复制非文本数据。

 

This method converts the data in ClipData.Item to text and returns a CharSequence. The value that ClipData.Item.coerceToText() returns is based on the form of data in ClipData.Item:

 

这个方法转换ClipData.Item中的数据至文本，并且返回一个CharSequence。ClipData.Item.coerceToText()返回的值基于ClipData.Item中的数据的形式。

 

Text

 

文本

 

If ClipData.Item is text (getText() is not null), coerceToText() returns the text.

 

如果ClipData.Item是文本（getText()不是null），那么coerceToText()返回该文本。

 

URI

 

URI

 

If ClipData.Item is a URI (getUri() is not null), coerceToText() tries to use it as a content URI:

 

如果ClipData.Item是一个URI（getUri()是非空）。coerceToText()尝试使用它作为一个内容URI：

 

* If the URI is a content URI and the provider can return a text stream, coerceToText() returns a text stream.

 

* 如果URI是一个内容URI而且提供者可以返回一个文本流，那么coerceToText()返回一个文本流。

 

* If the URI is a content URI but the provider does not offer a text stream, coerceToText() returns a representation of the URI. The representation is the same as that returned by Uri.toString().

 

* 如果URI是一个内容URI但提供者不提供一个文本流，那么coerceToText()返回URI的表现。表现和Uri.toString()所返回的相同。

 

* If the URI is not a content URI, coerceToText() returns a representation of the URI. The representation is the same as that returned by Uri.toString().

 

* 如果URI不是一个内容URI，那么coerceToText()返回一个URI的表现。表现和Uri.toString()所返回的相同。

 

Intent

 

意图

 

If ClipData.Item is an Intent (getIntent() is not null), coerceToText() converts it to an Intent URI and returns it. The representation is the same as that returned by Intent.toUri(URI_INTENT_SCHEME).

 

如果ClipData.Item是一个Intent（getIntent()不是null），那么coerceToText()转换它为一个意图URI并且返回它。该表现和Intent.toUri(URI_INTENT_SCHEME)所返回的相同。

 

The clipboard framework is summarized in Figure 1. To copy data, an application puts a ClipData object on the ClipboardManager global clipboard. The ClipData contains one or more ClipData.Item objects and one ClipDescription object. To paste data, an application gets the ClipData, gets its MIME type from the ClipDescription, and gets the data either from the ClipData.Item or from the content provider referred to by ClipData.Item.

 

剪贴板框架在图1中被总结。为了复制数据，一个应用程序放置一个ClipData对象在ClipboardManager全局剪贴板上。ClipData包含一个或多个ClipData.Item对象和一个ClipDescription对象。为了粘贴数据，一个应用程序获得ClipData，从ClipDescription中获得它的MIME类型，并且从ClipData.Item或从被内容提供者ClipData.Item引用的内容提供者中获得数据。

 

（图1略：

Android系统：

Android系统->（复制方应用程序）

Android系统<->（剪贴板）

Android系统->（粘贴方应用程序）

复制方应用程序

（包含）内容提供者

->要粘贴的数据->（粘贴方应用程序）

<-（MIME类型 / URI）

->（剪辑元数据）

->（数据项）

->（灰色）（数据项）

剪贴板 ClipboardManager

（包含）剪辑 ClipData

（包含）剪辑元数据 ClipDescription

（包含）（多个）MIME类型

（包含）数据项 ClipData.Item

（包含）文本 URI 意图

（包含）（灰色）数据项 ClipData.Item

（包含）文本 URI 意图

粘贴方应用程序

（ClipData）->

（ClipDescription）->

（ClipData.Item）->

->（虚线）Mime类型->（复制方应用程序）

（文本 URI 意图）->（虚线）URI->（复制方应用程序）

（要粘贴的数据）->

）

 

Figure 1. The Android clipboard framework

 

图1. Android剪贴板框架

 

-------------------------------

 

Copying to the Clipboard

 

复制至剪贴板

 

As described previously, to copy data to the clipboard you get a handle to the global ClipboardManager object, create a ClipData object, add a ClipDescription and one or more ClipData.Item objects to it, and add the finished ClipData object to the ClipboardManager object. This is described in detail in the following procedure:

 

正如前面所描述的那样，为了复制数据到剪贴板，你获得一个指向全局ClipboardManager对象的句柄，创建一个ClipData对象，添加一个ClipDescription和一个或多个ClipData.Item对象到它，并且添加已完成的ClipData对象到ClipboardManager对象。这在以下过程中被详细地描述：

 

1. If you are copying data using a content URI, set up a content provider.

 

1. 如果你正在使用一个内容URI复制数据，请配置一个内容提供者。

 

The Note Pad sample application is an example of using a content provider for copying and pasting. The NotePadProvider class implements the content provider. The NotePad class defines a contract between the provider and other applications, including the supported MIME types.

 

记事本示例应用程序是把内容提供者用于复制和粘贴的一个示例。NotePadProvider类实现内容提供者。NotePad类在提供者和其它应用程序之间定义一个契约，包括被支持的MIME类型。

 

2. Get the system clipboard:

 

2. 获得系统剪贴板：

 

-------------------------------

 

...

 

// 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. Copy the data to a new ClipData object:

 

3. 复制数据至一个新的ClipData对象：

 

* For text

 

* 对于文本

 

-------------------------------

 

// Creates a new text clip to put on the clipboard

// 创建一个新的文本剪辑以放在剪贴板上

ClipData clip = ClipData.newPlainText("simple text","Hello, World!");

 

-------------------------------

 

* For a URI

 

* 对于一个URI

 

This snippet constructs a URI by encoding a record ID onto the content URI for the provider. This technique is covered in more detail in the section Encoding an identifier on the URI:

 

这段代码片段构造一个URI，通过编码一个记录ID到提供者的内容URI上。这项技术在章节编码一个标识符在URI上中被更详细地涵盖。

 

-------------------------------

 

// Creates a Uri based on a base Uri and a record ID based on the contact's last name

// Declares the base URI string

// 基于一个基Uri创建一个Uri和基于电话簿的姓创建一个记录ID

// 声明基URI字符串

private static final String CONTACTS = "content://com.example.contacts";

 

// Declares a path string for URIs that you use to copy data

// 声明你用于复制数据的URI的路径字符串

private static final String COPY_PATH = "/copy";

 

// Declares the Uri to paste to the clipboard

// 声明Uri以粘贴到剪贴板

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.

// 创建一个新的URI剪辑对象。系统使用匿名getContentResolver()对象以从提供者中获得MIME类型。

// 剪辑对象的标签是"URI"，而它的数据是之前被创建的Uri。

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

 

-------------------------------

 

* For an Intent

 

* 对于一个Intent

 

This snippet constructs an Intent for an application and then puts it in the clip object:

 

这段代码片段为一个应用程序构造一个Intent，然后放置它进剪辑对象中：

 

-------------------------------

 

// Creates the Intent

// 创建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

// 创建一个剪辑对象，里面带着该Intent。它的标签是"Intent"而它的数据是之前被创建

// 的Intent对象

ClipData clip = ClipData.newIntent("Intent",appIntent);

 

-------------------------------

 

4. Put the new clip object on the clipboard:

 

4. 放置新的剪辑对象在剪贴板上：

 

-------------------------------

 

// Set the clipboard's primary clip.

// 设置剪贴板的主剪辑。

clipboard.setPrimaryClip(clip);

 

-------------------------------

 

-------------------------------

 

Pasting from the Clipboard

 

从剪贴板中粘贴

 

As described previously, you paste data from the clipboard by getting the global clipboard object, getting the clip object, looking at its data, and if possible copying the data from the clip object to your own storage. This section describes in detail how to do this for the three forms of clipboard data.

 

正如前面所描述的那样，你通过获得全局剪贴板对象从剪贴板中粘贴数据，获得剪辑对象，查看它的数据，并且在可能的时候从剪辑对象中复制数据到你自己的存储。这个章节详细地描述如何为三种形式的剪贴板数据执行这件事。

 

Pasting plain text

 

粘贴纯文本

 

To paste plain text, first get the global clipboard and verify that it can return plain text. Then get the clip object and copy its text to your own storage using getText(), as described in the following procedure:

 

为了粘贴纯文本，首先要获得全局剪贴板和验证它可以返回纯文本。然后获得剪辑对象并使用getText()复制它的文本到你自己的存储，正如以下过程中所描述的那样：

 

1. Get the global ClipboardManager object using getSystemService(CLIPBOARD_SERVICE). Also declare a global variable to contain the pasted text:

 

1. 使用getSystemService(CLIPBOARD_SERVICE)获得全局ClipboardManager对象。还要声明一个全局变量以包含被粘贴的文本：

 

-------------------------------

 

ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);

 

String pasteData = "";

 

-------------------------------

 

2. Next, determine if you should enable or disable the "paste" option in the current Activity. You should verify that the clipboard contains a clip and that you can handle the type of data represented by the clip:

 

2. 接下来，决定你是否应该在当前Activity中使能或屏蔽“粘贴”选项。你应该验证剪贴板包含一个剪辑以及你可以处理被剪辑代表的数据类型。

 

-------------------------------

 

// Gets the ID of the "paste" menu item

// 获得“粘贴”菜单条目的ID。

MenuItem mPasteItem = 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())) {

 

    mPasteItem.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

        // 这里屏蔽粘贴菜单条目，因为剪贴板有数据但它不是纯文本

        mPasteItem.setEnabled(false);

    } else {

 

        // This enables the paste menu item, since the clipboard contains plain text.

        // 这里使能粘贴菜单条目，因为剪贴板包含纯文本。

        mPasteItem.setEnabled(true);

    }

}

 

-------------------------------

 

3. Copy the data from the clipboard. This point in the program is only reachable if the "paste" menu item is enabled, so you can assume that the clipboard contains plain text. You do not yet know if it contains a text string or a URI that points to plain text. The following snippet tests this, but it only shows the code for handling plain text:

 

3. 从剪贴板中复制数据。在程序中这一点只是可触及的，如果“粘贴”菜单条目被使能，所以你可以假设剪贴板包含纯文本。你还未知道它是否包含一个文本字符串或一个指向纯文本的URI。以下代码片段测试这一点，但它只展示用于处理纯文本的代码：

 

-------------------------------

 

// 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.

// 检查剪贴板上的条目。如果getText()不返回null，那么剪辑条目包含该文本。

// 假设这个应用程序一次只可以处理一个条目。

 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;

 

// The clipboard does not contain text. If it contains a URI, attempts to get data from it

// 剪贴板不包含文本。如果它包含一个URI，尝试从它获得数据

} else {

    Uri pasteUri = item.getUri();

 

    // If the URI contains something, try to get text from it

    // 如果URI包含一些东西，请尝试从它中获得文本

    if (pasteUri != null) {

 

        // calls a routine to resolve the URI and get data from it. This routine is not

        // presented here.

        // 调用一个例程以解析URI并从其中获得数据。

        // 这个例程在这里没有出现。

        pasteData = resolveUri(Uri);

        return;

    } else {

 

    // Something is wrong. The MIME type was plain text, but the clipboard does not contain either

    // text or a Uri. Report an error.

    // 有些东西出错。MIME类型是纯文本，但剪贴板既不包含文本也不包含一个Uri。报告一个错误。

    Log.e("Clipboard contains an invalid data type");

    return;

    }

}

 

-------------------------------

 

Pasting data from a content URI

 

从一个内容URI中粘贴数据

 

If the ClipData.Item object contains a content URI and you have determined that you can handle one of its MIME types, create a ContentResolver and then call the appropriate content provider method to retrieve the data.

 

如果ClipData.Item object包含一个内容URI，而你已经确定你可以处理它的MIME类型中的一个，请创建一个ContentResolver，然后调用合适的提供者方法以取出数据。

 

The following procedure describes how to get data from a content provider based on a content URI on the clipboard. It checks that a MIME type that the application can use is available from the provider:

 

以下过程描述如何从一个内容提供者中获得数据，基于剪贴板上的一个内容URI。它检查应用程序可以使用的一个MIME类型是从提供者中可用：

 

1. Declare a global variable to contain the MIME type:

 

1. 声明一个全局变量以包含MIME类型：

 

-------------------------------

 

// Declares a MIME type constant to match against the MIME types offered by the provider

// 声明一个MIME类型常量以匹配提供者提供的MIME类型

public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"

 

-------------------------------

 

2. Get the global clipboard. Also get a content resolver so you can access the content provider:

 

2. 获得全局剪贴板。同时获得一个内容解析器，那样你可以访问那个内容提供者：

 

-------------------------------

 

// Gets a handle to the Clipboard Manager

// 获得一个指向剪贴板的句柄

ClipboardManager clipboard = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);

 

// Gets a content resolver instance

// 获得一个内容解析器实例

ContentResolver cr = getContentResolver();

 

-------------------------------

 

3. Get the primary clip from the clipboard, and get its contents as a URI:

 

3. 从剪贴板中获得主剪辑，并且获得它的内容作为一个URI：

 

-------------------------------

 

// 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

    Uri pasteUri = item.getUri();

 

-------------------------------

 

4. Test to see if the URI is a content URI by calling getType(Uri). This method returns null if Uri does not point to a valid content provider:

 

4. 通过调用getType(Uri)，测试以知道该URI是否为一个内容URI。这个方法返回null，如果Uri不指向一个可用的内容提供者：

 

-------------------------------

 

    // If the clipboard contains a URI reference

    // 如果剪贴板包含一个URI引用

    if (pasteUri != null) {

 

        // Is this a content URI?

        // 这是一个内容URI？

        String uriMimeType = cr.getType(pasteUri);

 

-------------------------------

 

5. Test to see if the content provider supports a MIME type that the current application understands. If it does, call ContentResolver.query() to get the data. The return value is a Cursor:

 

5. 测试以知道内容提供者是否支持当前应用程序了解的一个MIME类型。如果它支持，就调用ContentResolver.query()以获得数据。返回值是一个Cursor：

 

-------------------------------

 

        // If the return value is not null, the Uri is a content Uri

        // 如果返回值不是null，那么Uri是一个内容Uri

        if (uriMimeType != null) {

 

            // Does the content provider offer a MIME type that the current application can use?

            // 内容提供者是否提供一个当前应用程序可以使用的MIME类型？

            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

                // 如果Cursor包含数据，请移动到第一个记录

                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.

                    // 在这里从Cursor中获得数据。代码将根据数据模型的格式而不同。

                    }

                }

 

                // close the Cursor

                // 关闭Cursor

                pasteCursor.close();

             }

         }

     }

}

 

-------------------------------

 

Pasting an Intent

 

粘贴一个意图

 

To paste an Intent, first get the global clipboard. Examine the ClipData.Item object to see if it contains an Intent. Then call getIntent() to copy the Intent to your own storage. The following snippet demonstrates this:

 

为了粘贴一个Intent，首先获得全局剪贴板。检查ClipData.Item对象以了解它是否包含一个Intent。然后调用getIntent()来复制Intent到你自己的存储。以下代码片段演示这点：

 

-------------------------------

 

// 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，通过测试来知道getIntent()是否返回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

    // 忽略剪贴板，或者产生一个错误，如果你的应用程序正在期待一个Intent在剪贴板上

}

 

-------------------------------

 

-------------------------------

 

Using Content Providers to Copy Complex Data

 

使用内容提供者以复制复杂的数据

 

Content providers support copying complex data such as database records or file streams. To copy the data, you put a content URI on the clipboard. Pasting applications then get this URI from the clipboard and use it to retrieve database data or file stream descriptors.

 

内容提供者支持复制复杂数据诸如数据库记录或文件流。为了复制数据，你放置一个内容URI在剪贴板上。然后粘贴方应用程序从剪贴板中获得这个URI并使用它来去除数据库数据或文件流描述符。

 

Since the pasting application only has the content URI for your data, it needs to know which piece of data to retrieve. You can provide this information by encoding an identifier for the data on the URI itself, or you can provide a unique URI that will return the data you want to copy. Which technique you choose depends on the organization of your data.

 

因为粘贴方应用程序只有你的数据的内容URI，所以它需要知道要取出哪块数据。你可以通过编码数据的标识符在URI自身上来提供这个信息，或者你可以提供一个唯一URI，它将返回你想复制的数据。你选择哪种技术依赖于你的数据的结构（注：组织）。

 

The following sections describe how to set up URIs, how to provide complex data, and how to provide file streams. The descriptions assume that you are familiar with the general principles of content provider design.

 

以下章节描述如何配置URI，如何提供复杂的数据，以及如何提供文件流。那些描述假设你熟悉内容提供者设计的一般原则。

 

Encoding an identifier on the URI

 

在URI上编码一个标识符

 

A useful technique for copying data to the clipboard with a URI is to encode an identifier for the data on the URI itself. Your content provider can then get the identifier from the URI and use it to retrieve the data. The pasting application doesn't have to know that the identifier exists; all it has to do is get your "reference" (the URI plus the identifier) from the clipboard, give it your content provider, and get back the data.

 

用一个URI复制数据到剪贴板的一个有用的技术是编码数据的标识符在URI自身上。然后你的内容提供者可以从URI中获得标识符，并且使用它取出数据。粘贴方应用程序不必知道标识符存在；必须做的所有事情是从剪贴板中获得你的“引用”（URI加上标识符），给它你的内容提供者，并且取回数据。

 

You usually encode an identifier onto a content URI by concatenating it to the end of the URI. For example, suppose you define your provider URI as the following string:

 

你通常编码一个标识符到一个内容URI上，通过拼接它到URI的末尾。例如，想象你定义你的提供者URI为以下字符串：

 

-------------------------------

 

"content://com.example.contacts"

 

-------------------------------

 

If you want to encode a name onto this URI, you would use the following snippet:

 

如果你想编码一个名称到这个URI上，你将使用以下代码片段：

 

-------------------------------

 

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

 

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

// uriString现在包含content://com.example.contacts/Smith。

 

// Generates a uri object from the string representation

// 从字符串表现中生成一个Uri对象

Uri copyUri = Uri.parse(uriString);

 

-------------------------------

 

If you are already using a content provider, you may want to add a new URI path that indicates the URI is for copying. For example, suppose you already have the following URI paths:

 

如果你已经正在使用一个内容提供者，那么你可能希望添加一个新的URI路径，它指示URI是用于复制的。例如，想象你已经拥有以下URI路径：

 

-------------------------------

 

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

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

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

 

-------------------------------

 

You could add another path that is specific to copy URIs:

 

你可以添加另一个路径，它特定于复制URI：

 

-------------------------------

 

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

 

-------------------------------

 

You could then detect a "copy" URI by pattern-matching and handle it with code that is specific for copying and pasting.

 

然后你可以通过模式匹配检测一个“复制”URI，并且用特定于复制和粘贴的代码来处理它。

 

You normally use the encoding technique if you're already using a content provider, internal database, or internal table to organize your data. In these cases, you have multiple pieces of data you want to copy, and presumably a unique identifier for each piece. In response to a query from the pasting application, you can look up the data by its identifier and return it.

 

你通常使用编码技术，如果你已经在使用一个内容提供者，内部数据，或者内部表以组织你的数据。在这些情况下，你有你想复制的多块数据，以及可能（注：大概）用于每一块的唯一标识符。作为对来自粘贴方应用程序的查询的响应，你可以通过它的标识符查找数据并且返回它。

 

If you don't have multiple pieces of data, then you probably don't need to encode an identifier. You can simply use a URI that is unique to your provider. In response to a query, your provider would return the data it currently contains.

 

如果你没有多块数据，那么你可能不需要编码一个标识符。你可以简单地使用一个对于你的提供者是唯一的URI。作为对查询的响应，你的提供者将返回它当前包含的数据。

 

Getting a single record by ID is used in the Note Pad sample application to open a note from the notes list. The sample uses the _id field from an SQL database, but you can have any numeric or character identifier you want.

 

通过ID获得一个单一记录，被用在记事本示例应用程序中，以从便签列表中打开一个便签。该示例使用了一个SQL数据库中的_id字段，但你可以拥有你想要的任意数字型或字符型标识符。

 

Copying data structures

 

复制数据结构

 

You set up a content provider for copying and pasting complex data as a subclass of the ContentProvider component. You should also encode the URI you put on the clipboard so that it points to the exact record you want to provide. In addition, you have to consider the existing state of your application:

 

你为复制和粘贴复制数据配置一个内容提供者作为ContentProvider组件一个子类。你还应该编码你放在剪贴板上的URI，使它指向你希望提供的具体记录。额外地，你必须考虑你的应用程序的现存状态：

 

* If you already have a content provider, you can add to its functionality. You may only need to modify its query() method to handle URIs coming from applications that want to paste data. You will probably want to modify the method to handle a "copy" URI pattern.

 

* 如果你已经有一个内容提供者，那么你可以添加到它的功能。你可能值需要修改它的query()方法以处理来自想粘贴数据的应用程序的URI。你将很可能想修改方法以处理一个“复制”URI模式。

 

* If your application maintains an internal database, you may want to move this database into a content provider to facilitate copying from it.

 

* 如果你的应用程序维护一个内部数据库，那么你可能想移动这个数据库进一个内容提供者，使从它里面复制变得容易。

 

* If you are not currently using a database, you can implement a simple content provider whose sole purpose is to offer data to applications that are pasting from the clipboard.

 

* 如果你当前不在使用一个数据库，那么你可以实现一个简单内容提供者，它的唯一目的是提供数据给正在从剪贴板中粘贴的应用程序。

 

In the content provider, you will want to override at least the following methods:

 

在内容提供者中，你将至少希望覆盖以下方法：

 

query()

 

Pasting applications will assume that they can get your data by using this method with the URI you put on the clipboard. To support copying, you should have this method detect URIs that contain a special "copy" path. Your application can then create a "copy" URI to put on the clipboard, containing the copy path and a pointer to the exact record you want to copy.

 

粘贴方应用程序将假设它们可以通过用你放在剪贴板上的URI使用这个方法获得你的数据。为了支持复制，你应该让这个方法检测包含一个特殊“复制”路径的URI。然后你的应用程序可以创建一个“复制”URI以放置在剪贴板上，包含复制路径和一个指向你想复制的具体记录的指针。

 

getType()

 

This method should return the MIME type or types for the data you intend to copy. The method newUri() calls getType() in order to put the MIME types into the new ClipData object.

 

这个方法应该返回你倾向于复制的数据的一个或多个MIME类型。方法newUri()调用getType()以放置MIME类型进新的ClipData对象中。

 

MIME types for complex data are described in the topic Content Providers.

 

用于复杂数据的MIME类型在主题内容提供者中被描述。

 

Notice that you don't have to have any of the other content provider methods such as insert() or update(). A pasting application only needs to get your supported MIME types and copy data from your provider. If you already have these methods, they won't interfere with copy operations.

 

注意你不必拥有其它任意内容提供者方法诸如insert()或update()。一个粘贴方应用程序只需要获得你支持的MIME类型并且从你的提供者中复制数据。如果你已经拥有这些方法，那么它们不干扰复制操作。

 

The following snippets demonsrate how to set up your application to copy complex data:

 

以下代码片段演示如何配置你的应用程序以复制复杂的数据：

 

1. In the global constants for your application, declare a base URI string and a path that identifies URI strings you are using to copy data. Also declare a MIME type for the copied data:

 

1. 在你的应用程序的全局常量中，声明一个基URI字符串和一个标识你正在用于复制数据的URI字符串的路径。还要为被复制的数据声明一个MIME类型：

 

-------------------------------

 

// Declares the base URI string

// 声明基URI字符串

private static final String CONTACTS = "content://com.example.contacts";

 

// Declares a path string for URIs that you use to copy data

// 声明你用来复制数据的URI的路径字符串

private static final String COPY_PATH = "/copy";

 

// Declares a MIME type for the copied data

// 为被复制的数据声明一个MIME类型

public static final String MIME_TYPE_CONTACT = "vnd.android.cursor.item/vnd.example.contact"

 

-------------------------------

 

2. In the Activity from which users copy data, set up the code to copy data to the clipboard. In response to a copy request, put the URI on the clipboard:

 

2. 在用户从其中复制数据的Activity中，配置代码以复制数据到剪贴板。请放置URI在剪贴板上，以响应一个复制请求。

 

-------------------------------

 

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"

    // 尾加姓到基URI

    // 名称被存储在"lastName"中

    uriString = CONTACTS + COPY_PATH + "/" + lastName;

 

    // Parses the string into a URI

    // 解析字符串为一个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. In the global scope of your content provider, create a URI matcher and add a URI pattern that will match URIs you put on the clipboard:

 

3. 在你的内容提供者的全局作用域内，创建一个URI匹配器，并添加一个URI模式，它将匹配你放在剪贴板上的URI。

 

-------------------------------

 

public class MyCopyProvider extends ContentProvider {

 

    ...

 

// A Uri Match object that simplifies matching content URIs to patterns.

// 一个Uri匹配对象，它简化内容URI与模式的匹配。

private static final UriMatcher sURIMatcher = new UriMatcher(UriMatcher.NO_MATCH);

 

// An integer to use in switching based on the incoming URI pattern

// 一个整数，在基于传入URI模式的switch跳转中使用

private static final int GET_SINGLE_CONTACT = 0;

 

...

 

// Adds a matcher for the content URI. It matches

// "content://com.example.contacts/copy/*"

// 为内容URI添加一个匹配器。

// 它匹配"content://com.example.contacts/copy/*"

sUriMatcher.addURI(CONTACTS, "names/*", GET_SINGLE_CONTACT);

 

-------------------------------

 

4. Set up the query() method. This method can handle different URI patterns, depending on how you code it, but only the pattern for the clipboard copying operation is shown:

 

4. 配置query()方法。这个方法可以处理不同的URI模式，依赖于你如何编码它，但只展示用于剪贴板复制操作的模式：

 

-------------------------------

 

// Sets up your provider's query() method.

// 配置你的提供者的query()方法

public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,

    String sortOrder) {

 

    ...

 

    // Switch based on the incoming content URI

    // 基于传入的内容URI的switch跳转

    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.

        // 查询并返回被请求名称的电话簿。这里你将编码

        // 传入的URI，基于姓查询数据模型，并且返回结果作为一个Cursor。

 

    ...

 

}

 

-------------------------------

 

5. Set up the getType() method to return an appropriate MIME type for copied data:

 

5. 配置getType()方法以返回用于被复制数据的一个合适的MIME类型。

 

-------------------------------

 

// Sets up your provider's getType() method.

// 配置你的提供者的getType()方法

public String getType(Uri uri) {

 

    ...

 

    switch (sUriMatcher.match(uri)) {

 

    case GET_SINGLE_CONTACT:

 

            return (MIME_TYPE_CONTACT);

 

-------------------------------

 

The section Pasting data from a content URI describes how to get a content URI from the clipboard and use it to get and paste data.

 

章节从一个内容URI中粘贴数据描述如何从剪贴板中获得一个内容URI，并且使用它来获得和粘贴数据。

 

Copying data streams

 

复制数据流

 

You can copy and paste large amounts of text and binary data as streams. The data can have forms such as the following:

 

你可以复制和粘贴大数量文本和二进制数据作为流。数据可以拥有一些形式中诸如以下：

 

* Files stored on the actual device.

 

* 存储在实际设备上的文件。

 

* Streams from sockets.

 

* 来自套接字的流。

 

* Large amounts of data stored in a provider's underlying database system.

 

* 大数量数据存储在提供者的底层数据库系统中。

 

A content provider for data streams provides access to its data with a file descriptor object such as AssetFileDescriptor instead of a Cursor object. The pasting application reads the data stream using this file descriptor.

 

一个数据流的内容提供者提供使用一个文件描述符对象诸如AssetFileDescriptor而非一个Cursor对象，对它的数据的访问权（注：待考）。粘贴方应用程序使用这个文件描述符读取数据流。

 

To set up your application to copy a data stream with a provider, follow these steps:

 

为了配置你的应用程序以用一个提供者复制一个数据流，请遵循这些步骤：

 

1. Set up a content URI for the data stream you are putting on the clipboard. Options for doing this include the following:

 

1. 为你正在放置在剪贴板上的数据流配置一个内容URI。做这件事的选择包括以下：

 

* Encode an identifier for the data stream onto the URI, as described in the section Encoding an identifier on the URI, and then maintain a table in your provider that contains identifiers and the corresponding stream name.

 

* 编码数据流的标识符到URI上。正如章节编码一个标识符在URI上所描述的那样，然后在你包含标识符和相应流名称的提供者中维护一个表。

 

* Encode the stream name directly on the URI.

 

* 直接在URI上编码流的名称。

 

* Use a unique URI that always returns the current stream from the provider. If you use this option, you have to remember to update your provider to point to a different stream whenever you copy the stream to the clipboard via the URI.

 

* 使用一个唯一URI，它总是从提供者中返回当前流。如果你使用这个选项，你不得不记得更新你的提供者以指向一个不同的流，不管你何时通过URI复制流到剪贴板。

 

2. Provide a MIME type for each type of data stream you plan to offer. Pasting applications need this information to determine if they can paste the data on the clipboard.

 

2. 为你计划提供的每种类型的数据流提供一个MIME类型。粘贴应用程序需要这个信息以确定它们是否可以粘贴剪贴板上的数据。

 

3. Implement one of the ContentProvider methods that returns a file descriptor for a stream. If you encode identifiers on the content URI, use this method to determine which stream to open.

 

3. 实现ContentProvider的方法的其中一个，它返回一个流的文件描述符。如果你编码标识符在内容URI上，请使用这个方法来确定要打开哪个流。

 

4. To copy the data stream to the clipboard, construct the content URI and place it on the clipboard.

 

4. 为了复制数据流到剪贴板，请构造内容URI并放置它在剪贴板上。

 

To paste a data stream, an application gets the clip from the clipboard, gets the URI, and uses it in a call to a ContentResolver file descriptor method that opens the stream. The ContentResolver method calls the corresponding ContentProvider method, passing it the content URI. Your provider returns the file descriptor to ContentResolver method. The pasting application then has the responsibility to read the data from the stream.

 

为了粘贴数据流，一个应用程序从剪贴板上获得剪辑，并且在对打开该流的一个ContentResolver文件描述符方法的调用中使用它。ContentResolver方法调用对应的ContentProvider方法，传递它内容URI。你的提供者返回文件描述符给ContentResolver的方法。然后粘贴方应用程序有责任从流中读取数据。

 

The following list shows the most important file descriptor methods for a content provider. Each of these has a corresponding ContentResolver method with the string "Descriptor" appended to the method name; for example, the ContentResolver analog of openAssetFile() is openAssetFileDescriptor():

 

以下列表展示用于一个内容提供者的最重要的文件描述符方法。它们中每个拥有一个对应的ContentResolver方法，有字符串"Descriptor"尾加在方法名后面；例如openAssetFile()的ContentResolver类似物是openAssetFileDescriptor()：

 

openTypedAssetFile()

 

This method should return an asset file descriptor, but only if the provided MIME type is supported by the provider. The caller (the application doing the pasting) provides a MIME type pattern. The content provider (of the application that has copied a URI to the clipboard) returns an AssetFileDescriptor file handle if it can provide that MIME type, or throws an exception if it can not.

 

这个方法应该返回一个资源文件描述符，但仅当提供的MIME类型被提供者支持。调用方（执行粘贴的应用程序）提供一个MIME类型模式。（已经复制一个URI到剪贴板的应用程序的）内容提供者返回一个AssetFileDescriptor文件句柄如果它可以提供那个MIME类型，或者抛出一个异常如果它不可以。

 

This method handles subsections of files. You can use it to read assets that the content provider has copied to the clipboard.

 

这个方法处理文件的小部分。你可以使用它来读取内容提供者已经复制到剪贴板的资源。

 

openAssetFile()

 

This method is a more general form of openTypedAssetFile(). It does not filter for allowed MIME types, but it can read subsections of files.

 

这个方法是openTypedAssetFile()的更一般形式。它不针对被允许的MIME类型来过滤，但它可以读取文件的一些小部分。

 

openFile()

 

This is a more general form of openAssetFile(). It can't read subsections of files.

 

这是openAssetFile()的更一般形式。它不能读取文件的小部分。

 

You can optionally use the openPipeHelper() method with your file descriptor method. This allows the pasting application to read the stream data in a background thread using a pipe. To use this method, you need to implement the ContentProvider.PipeDataWriter interface. An example of doing this is given in the Note Pad sample application, in the openTypedAssetFile() method of NotePadProvider.java.

 

你可以可选地使用openPipeHelper()方法伴随你的文件描述符方法。这允许粘贴方的应用程序在一个后台线程中使用管道读取流数据。为了使用此方法，你需要实现ContentProvider.PipeDataWriter接口。做这件事的一个示例在记事本示例应用程序中被给出，在NotePadProvider.java的openTypedAssetFile()方法中。

 

-------------------------------

 

Designing Effective Copy/Paste Functionality

 

设计有效的复制/粘贴功能

 

To design effective copy and paste functionality for your application, remember these points:

 

为了为你的应用程序设计有效的复制和粘贴功能，请记住这些要点：

 

* At any time, there is only one clip on the clipboard. A new copy operation by any application in the system overwrites the previous clip. Since the user may navigate away from your application and do a copy before returning, you can't assume that the clipboard contains the clip that the user previously copied in your application.

 

* 在任何时候，在剪贴板上只有一个剪辑。在系统中任意应用程序作出的一个新的复制操作覆写前一个剪辑。因为用户可能从你的应用程序中导航离开并且在返回之前执行一次复制，所以你不能假设剪贴板包含用户之前在你的应用程序中复制的剪辑。

 

* The intended purpose of multiple ClipData.Item objects per clip is to support copying and pasting of multiple selections rather than different forms of reference to a single selection. You usually want all of the ClipData.Item objects in a clip to have the same form, that is, they should all be simple text, content URI, or Intent, but not a mixture.

 

* 每个剪辑有多个ClipData.Item对象的预期目的是为了支持复制和粘贴多个选择，而非指向一个单一选择的不同形式的引用。你通常希望在一个剪辑中的所有ClipData.Item对象拥有相同的形式，就是说，它们应该都是简单文本，内容URI，或Intent，但不是一个混合。

 

* When you provide data, you can offer different MIME representations. Add the MIME types you support to the ClipDescription, and then implement the MIME types in your content provider.

 

* 当你提供数据时，你可以提供不同MIME表现。添加你支持的MIME类型到ClipDescription，然后在你的内容提供者中实现MIME类型。

 

* When you get data from the clipboard, your application is responsible for checking the available MIME types and then deciding which one, if any, to use. Even if there is a clip on the clipboard and the user requests a paste, your application is not required to do the paste. You should do the paste if the MIME type is compatible. You may choose to coerce the data on the clipboard to text using coerceToText() if you choose. If your application supports more than one of the available MIME types, you can allow the user to choose which one to use.

 

* 当你从剪贴板中获得数据时，你的应用程序有责任检查可用的MIME类型，然后决定要使用哪一个，如果有的话。即便在剪贴板上有一个剪辑而且用户请求一次粘贴，你的应用程序并不必须执行粘贴。你应该执行粘贴，如果MIME类型是兼容的。你可能选择使用coerceToText()强制转换剪贴板上的数据为文本，如果你选择这样做。如果你的应用程序支持多于一种可用MIME类型，那么你可以允许用户选择要使用哪一种。

 

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

 

除特别说明外，本文在Apache 2.0下许可。细节和限制请参考内容许可证。

 

Android 4.0 r1 - 09 May 2012 23:46

 

-------------------------------

 

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

 

此页部分内容，是基于Android开源项目所创建和共享的工作，并且根据知识共享2.5署名许可证描述的条款来使用的修改版。

 

（本人翻译质量欠佳，请以官方最新内容为准，或者参考其它翻译版本：

* ソフトウェア技術ドキュメントを勝手に翻訳

http://www.techdoctranslator.com/android

* 微风的网络日志

http://leybreeze.com/blog/

* 农民伯伯

http://www.cnblogs.com/over140/

* Android中文翻译组

http://androidbox.sinaapp.com/

）