【翻译】(16)动作栏

【翻译】(16)动作栏

 

see

http://developer.android.com/guide/topics/ui/actionbar.html

 

原文见

http://developer.android.com/guide/topics/ui/actionbar.html

 

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

 

Action Bar

 

动作栏

 

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

 

Quickview

 

快速概览

 

* A title bar that includes the application icon and activity title

 

* 一个标题栏，包括应用程序图标和活动标题

 

* Provides access to menu items and navigation modes such as tabs

 

* 提供对菜单条目的访问和导航模式诸如标签页

 

* Requires API level 11 or greater 

 

* 需要API级别11或更高的API

 

In this document

 

本文目录

 

* Adding the Action Bar 添加动作栏

* Removing the action bar 移除动作栏

* Adding Action Items 添加动作条目

* Choosing your action items 选择你的动作条目

* Using split action bar 使用分割动作栏

* Using the App Icon for Navigation 使用应用图标进行导航

* Navigating up 导航向上

* Adding an Action View 添加动作视图

* Handling collapsible action views 处理可折叠的动作视图

* Adding an Action Provider 添加动作提供者

* Using the ShareActionProvider 使用ShareActionProvider

* Creating a custom action provider 创建自定义的动作提供者

* Adding Navigation Tabs 添加导航标签页

* Adding Drop-down Navigation 添加下拉导航

* Styling the Action Bar 风格化动作栏

* General appearance 通用外观

* Action items 动作条目

* Navigation tabs 导航标签页

* Drop-down lists 下拉列表

* Advanced styling 高级风格化

 

Key classes 

 

关键类

 

ActionBar

Menu

ActionProvider

 

Related samples

 

相关示例

 

Honeycomb Gallery 蜂巢画廊

Action Bar Compatibility 动作栏兼容性

API Demos API演示

 

See also

 

另见

 

item 条目

Menus 菜单

Supporting Tablets and Handsets 支持平板和手机

 

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

 

The action bar is a window feature that identifies the application and user location, and provides user actions and navigation modes. You should use the action bar in most activities that need to prominently present user actions or global navigation, because the action bar offers users a consistent interface across applications and the system gracefully adapts the action bar's appearance for different screen configurations. You can control the behaviors and visibility of the action bar with the ActionBar APIs, which were added in Android 3.0 (API level 11).

 

动作栏是一种标识应用程序和用户位置，以及提供用户动作和导航模式的窗口特性。你应该在大多数需要突出呈现给用户动作或全局导航的活动中使用动作栏，因为动作栏向用户提供一个跨应用程序的一致界面，而系统优雅地为不同屏幕配置调整动作栏的外观。你可以用ActionBar API控制动作栏的行为和可见性，它在Android 3.0（API级别11）中添加。

 

The primary goals of the action bar are to:

 

动作栏的主要目的是：

 

* Provide a dedicated space for identifying the application brand and user location.

 

* 提供一个专用空间用于标识应用程序品牌和用户位置。

 

This is accomplished with the app icon or logo on the left side and the activity title. You might choose to remove the activity title, however, if the current view is identified by a navigation label, such as the currently selected tab.

 

它由左端的应用图标或徽记和活动标题组成。然而，你可以选择移除活动标题，如果当前活动被一个导航标签标识，诸如当前被选择的标签页。

 

* Provide consistent navigation and view refinement across different applications.

 

* 提供跨应用程序的一致的导航和视图优雅性。

 

The action bar provides built-in tab navigation for switching between fragments. It also offers a drop-down list you can use as an alternative navigation mode or to refine the current view (such as to sort a list by different criteria).

 

活动栏提供内建的标签页导航，用于在片段间切换。它还提供一个下拉列表，你可以用它作为一个可替换的导航模式或精简当前视图（诸如通过不同的标准排序一个列表）

 

* Make key actions for the activity (such as "search", "create", "share", etc.) prominent and accessible to the user in a predictable way.

 

* 以可预测的方式让活动的关键动作（诸如“搜索”，“创建”，“共享”，等。）对用户来说突出且可访问。

 

You can provide instant access to key user actions by placing items from the options menu directly in the action bar, as "action items." Action items can also provide an "action view," which provides an embedded widget for even more immediate action behaviors. Menu items that are not promoted to an action item are available in the overflow menu, revealed by either the device MENU button (when available) or by an "overflow menu" button in the action bar (when the device does not include a MENU button).

 

你可以通过把条目从选项菜单直接放置进动作栏作为“动作条目”，为关键的用户动作提供即时访问。动作条目还可以提供一个“动作视图”，它提供一个内嵌部件以获得更为即时的动作行为。没有被提升至动作条目的菜单条目在溢出菜单中可用，通过设备的MENU按钮（当它可用时）或通过动作栏中的“溢出菜单”按钮（当设备没有包含MENU按钮时）来显示。

 

（图1略）

 

Figure 1. Action bar from the Honeycomb Gallery app (on a landscape handset), showing the logo on the left, navigation tabs, and an action item on the right (plus the overflow menu button).

 

图1. 出自Honeycomb画廊应用的动作栏（在宽屏手机上），在左边显示徽记，导航标签页，而右边是一个动作条目（加上溢出菜单按钮）。

 

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

 

Remaining backward-compatible

 

保留向后兼容性

 

If you want to provide an action bar in your application and remain compatible with versions of Android older than 3.0, you need to create the action bar in your activity's layout (because the ActionBar class is not available on older versions).

 

如果你希望在你的应用程序中提供一个动作栏并维持对低于3.0的Android版本的兼容性，那么你需要在你的活动布局中创建动作栏（因为ActionBar类在旧版本中不可用）。

 

To help you, the Action Bar Compatibility sample app provides an API layer and action bar layout that allows your app to use some of the ActionBar APIs and also support older versions of Android by replacing the traditional title bar with a custom action bar layout.

 

为了帮助你，动作栏兼容性示例应用提供一个API层和动作栏布局，允许你的应用使用一些ActionBar API，而且还支持旧版本的Android，通过用一个自定义的活动栏布局替换传统标题栏。

 

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

 

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

 

Adding the Action Bar

 

添加动作栏

 

Beginning with Android 3.0 (API level 11), the action bar is included in all activities that use the Theme.Holo theme (or one of its descendants), which is the default theme when either the targetSdkVersion or minSdkVersion attribute is set to "11" or greater. For example:

 

从Android 3.0（API级别11）开始，动作栏被包含在所有使用Theme.Holo主题的活动（或它的后代类之一）中，它是当targetSdkVersion或minSdkVersion的属性设置为"11"或更高时的默认主题。例如：（注：下文提到的holo都是指Theme.Holo主题，holo是holographic的缩写，意思是全息、半透明）

 

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

 

<manifest ... >

    <uses-sdk android:minSdkVersion="4"

              android:targetSdkVersion="11" />

    ...

</manifest>

 

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

 

In this example, the application requires a minimum version of API Level 4 (Android 1.6), but it also targets API level 11 (Android 3.0). This way, when the application runs on Android 3.0 or greater, the system applies the holographic theme to each activity, and thus, each activity includes the action bar.

 

在这个示例中，应用程序需要最小版本为API级别4（Android 1.6），但是它还把目标平台设为API级别11（Android 3.0）。这样，当应用程序运行在Android 3.0或更高时，系统应用全息主题到每个活动，因此，每个活动都包含动作栏。

 

If you want to use ActionBar APIs, such as to add navigation modes and modify action bar styles, you should set the minSdkVersion to "11" or greater. If you want your app to support older versions of Android, there are ways to use a limited set of ActionBar APIs on devices that support API level 11 or higher, while still running on older versions. See the sidebox for information about remaining backward-compatible.

 

如果你希望使用ActionBar API，诸如为了添加导航模式和修改动作栏风格，那么你应该设置minSdkVersion为11或更高。如果你希望你的应用支持较旧版本的Android，那么有一些方法让支持API级别11或更高，但仍在运行较旧版本系统的设备上使用一个受限ActionBar API集合。参见边框的注释以获取关于保持向后兼容的信息。

 

Removing the action bar

 

移除动作栏

 

If you don't want the action bar for a particular activity, set the activity theme to Theme.Holo.NoActionBar. For example:

 

如果你不希望特定动作拥有动作栏，那么请设置活动的主题为Theme.Holo.NoActionBar。例如：

 

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

 

<activity android:theme="@android:style/Theme.Holo.NoActionBar">

 

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

 

You can also hide the action bar at runtime by calling hide(). For example:

 

你还可以通过调用hide()在运行时隐藏动作栏。例如：

 

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

 

ActionBar actionBar = getActionBar();

actionBar.hide();

 

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

 

When the action bar hides, the system adjusts your activity layout to fill all the screen space now available. You can bring the action bar back with show().

 

当动作栏隐藏时，系统调整你的活动布局以填充现在可用的所有屏幕空间。你可以用show()恢复动作栏。

 

Beware that hiding and removing the action bar causes your activity to re-layout in order to account for the space consumed by the action bar. If your activity regularly hides and shows the action bar (such as in the Android Gallery app), you might want to use overlay mode. Overlay mode draws the action bar on top of your activity layout rather than in its own area of the screen. This way, your layout remains fixed when the action bar hides and re-appears. To enable overlay mode, create a theme for your activity and set android:windowActionBarOverlay to true. For more information, see the section about Styling the Action Bar.

 

请意识到隐藏和移除动作栏会导致你的活动重新布局以占据动作栏使用的空间。如果你的活动经常隐藏和显示动作栏（诸如在Android画廊应用中），你可能希望使用叠加模式。叠加模式在你的活动布局的上方绘画动作栏而非在它自己的屏幕区域中。这样的话，你的布局在动作栏隐藏和重新显示时保持固定。为了开启叠加模式，为你的活动创建一个主题并设置android:windowActionBarOverlay为true。想获取更多信息，请参见关于风格化动作栏的章节。

 

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

 

Tip: If you have a custom activity theme in which you'd like to remove the action bar, set the android:windowActionBar style property to false. However, if you remove the action bar using a theme, then the window will not allow the action bar at all, so you cannot add it later—calling getActionBar() will return null.

 

提示：如果你有一个自定义活动主题，你希望移除使用这种主题的动作栏，请设置android:windowActionBar样式属性为false。然而，如果你移除使用主题的动作栏，那么窗口将完全不允许出现动作栏，那样稍后你不能再添加它——调用getActionBar()将返回null。

 

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

 

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

 

Adding Action Items

 

添加动作条目

 

Sometimes you might want to give users immediate access to an item from the options menu. To do this, you can declare that the menu item should appear in the action bar as an "action item." An action item can include an icon and/or a text title. If a menu item does not appear as an action item, then the system places it in the overflow menu. The overflow menu is revealed either by the device MENU button (if provided by the device) or an additional button in the action bar (if the device does not provide the MENU button).

 

有时你可能想向用户提供选项菜单中条目的即时访问。为了做到这点，你可以声明菜单条目应该显示在动作栏中作为“动作条目”。一个动作条目可以包含一个图标和/或一个文本标题。如果菜单条目不显示为一个动作条目，那么系统把它放置在溢出菜单中。溢出菜单通过设备的MENU按钮（如果设备提供了的话）或动作栏的额外按钮（如果设备没有提供MENU按钮的话）来显示。

 

（图2略）

 

Figure 2. Two action items with icon and text titles, and the overflow menu button.

 

图2. 两个带有图标和文本标题的动作条目，以及溢出菜单按钮。

 

When the activity first starts, the system populates the action bar and overflow menu by calling onCreateOptionsMenu() for your activity. As discussed in the Menus developer guide, it's in this callback method that you should inflate an XML menu resource that defines the menu items. For example:

 

当活动第一次开始时，系统通过调用你的活动的onCreateOptionsMenu()生成动作栏和溢出菜单。正如菜单开发者指引中讨论的那样，你应该在这个回调方法中解压定义了菜单条目的XML菜单资源。例如：

 

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

 

@Override

public boolean onCreateOptionsMenu(Menu menu) {

    MenuInflater inflater = getMenuInflater();

    inflater.inflate(R.menu.main_activity, menu);

    return true;

}

 

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

 

In the XML file, you can request a menu item to appear as an action item by declaring android:showAsAction="ifRoom" for the <item> element. This way, the menu item appears in the action bar for quick access only if there is room available. If there's not enough room, the item appears in the overflow menu.

 

在XML文件中，你可以通过为<item>元素声明android:showAsAction="ifRoom"来请求一个菜单条目显示为一个动作条目。用这种方式，菜单条目显示在动作栏以方便快速显示，仅当有可用的空间的时候。如果没有足够的空间，该条目出现在溢出菜单中。

 

If your menu item supplies both a title and an icon—with the android:title and android:icon attributes—then the action item shows only the icon by default. If you want to display the text title, add "withText" to the android:showAsAction attribute. For example:

 

如果你的菜单条目同时提供标题和图标——用android:title和android:icon属性——那么动作条目默认只显示图标。如果你希望显示文本标题，请添加"withText"到android:showAsAction属性。例如：

 

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

 

<?xml version="1.0" encoding="utf-8"?>

<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item android:id="@+id/menu_save"

          android:icon="@drawable/ic_menu_save"

          android:title="@string/menu_save"

          android:showAsAction="ifRoom|withText" />

</menu>

 

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

 

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

 

Note: The "withText" value is a hint to the action bar that the text title should appear. The action bar will show the title when possible, but might not if an icon is available and the action bar is constrained for space.

 

注意："withText"值是对动作栏建议应该显示文本标题。动作栏将在可能的情况下显示标题，但如果图标可用而且动作栏被拘束以节省空间时可能不显示标题。

 

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

 

When the user selects an action item, your activity receives a call to onOptionsItemSelected(), passing the ID supplied by the android:id attribute—the same callback received for all items in the options menu.

 

当用户选择一个动作条目时，你的活动接收到对onOptionsItemSelected()的调用，传入由android:id属性提供的ID——选项菜单中的所有条目接收相同的回调。

 

It's important that you always define android:title for each menu item—even if you don't declare that the title appear with the action item—for three reasons:

 

重要的是你总是要为每个菜单条目定义android:title——即便你没有声明标题要和动作条目一起显示——理由有三：

 

* If there's not enough room in the action bar for the action item, the menu item appears in the overflow menu and only the title appears.

 

* 如果动作栏中没有足够的空间给动作条目，那么菜单条目出现在溢出菜单，而且只显示标题。

 

* Screen readers for sight-impaired users read the menu item's title.

 

* 视障用户使用的屏幕阅读器读取菜单条目的标题。

 

* If the action item appears with only the icon, a user can long-press the item to reveal a tool-tip that displays the action item's title.

 

* 如果动作条目只显示图标，那么用户可以长按条目以展开一个工具提示，显示动作条目的标题。

 

The android:icon is always optional, but recommended. For icon design recommendations, see the Action Bar Icon design guidelines.

 

android:icon总是可选的，但建议设置。想获取图标设计的建议，请参见动作栏图标设计指引。

 

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

 

Note: If you added the menu item from a fragment, via the Fragment class's onCreateOptionsMenu callback, then the system calls the respective onOptionsItemSelected() method for that fragment when the user selects one of the fragment's items. However the activity gets a chance to handle the event first, so the system calls onOptionsItemSelected() on the activity before calling the same callback for the fragment.

 

注意：如果你通过Fragment类的onCreateOptionsMenu回调，从一个片段中添加菜单条目，那么当用户选择其中一个片段的条目时，系统为那个片段调用相应的onOptionsItemSelected()方法。然而活动有机会最先处理该事件，所以系统在为片段调用相同的回调前调用活动上的onOptionsItemSelected()。

 

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

 

You can also declare an item to "always" appear as an action item, instead of being placed in the overflow menu when space is limited. In most cases, you should not force an item to appear in the action bar by using the "always" value. However, you might need an item to always appear when it provides an action view that does not offer a default action for the overflow menu. Beware that too many action items can create a cluttered UI and cause layout problems on devices with a narrow screen. It's best to instead use "ifRoom" to request that an item appear in the action bar, but allow the system to move it into the overflow menu when there's not enough room.

 

你还可以声明一个条目“总是”显示为一个动作条目，而非在空间有限时放置在溢出菜单中。在大多数情况下，你不应该通过使用always值强迫一个条目显示在动作栏中。然而，你可能需要一个条目总是出现，当它提供一个没有为溢出菜单提供默认动作的动作视图时。请意识到太多动作条目会造成一个混乱的用户界面并导致窄屏设备上的布局问题。最好改为使用ifRoom以请求一个条目显示在动作栏，但允许系统在不够空间的时候把它移进溢出菜单。

 

For more information about creating the options menu that defines your action items, see the Menus developer guide.

 

想获取关于创建定义动作条目的选项菜单的更多信息，请参见菜单开发者指引。

 

Choosing your action items

 

选择你的动作条目

 

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

 

Menu items vs. other app controls

 

菜单条目对比其它应用控件

 

As a general rule, all items in the options menu (let alone action items) should have a global impact on the app, rather than affect only a small portion of the interface. For example, if you have a multi-pane layout and one pane shows a video while another lists all videos, the video player controls should appear within the pane containing the video (not in the action bar), while the action bar might provide action items to share the video or save the video to a favorites list.

 

作为普遍的规则，选项菜单中的所有条目（更不用说动作条目）应该在应用上具有全局的影响力，而非只影响界面上一小部分。例如，如果你有一个多窗格的布局并且一个窗格显示视频而另一个列举所有视频，视频播放器的控制应该显示在包含视频的窗格中（而非动作栏），而动作栏可以提供动作条目来分享视频或保存视频到收藏列表。

 

So, even before deciding whether a menu item should appear as an action item, be sure that the item has a global scope for the current activity. If it doesn't, then you should place it as a button in the appropriate context of the activity layout.

 

所以，即使在决定一个菜单条目是否应该作为一个动作条目出现之前，也要确保条目拥有当前活动的全局作用域。如果它没有，那么你应该放置它作为活动布局的合适上下文中的一个按钮。

 

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

 

You should carefully choose which items from your options menu should appear as action items by assessing a few key traits. In general, each action item should be at least one of the following:

 

你应该通过评估一些关键特征，小心选择你的选项菜单中的哪个条目应该显示作为动作条目。通常，每个动作条目应该至少具有以下其中一个特点：

 

1. Frequently used: It's an action that your users need seven out of ten visits or they use it several times in a row.

 

1. 经常使用：动作是你的用户需要十分之七的情况访问或者他们连续多次使用它。

 

Example frequent actions: "New message" in the Messaging app and "Search" in Android Market.

 

示例的频繁动作：在短信应用中的“新短信”和在Android市场中的“搜索”。

 

2. Important: It's an action that you need users to easily discover or, if it's not frequently used, it's important that it be effortless to perform in the few cases that users do need it.

 

2. 重要的：动作是你需要用户很容易发现，或者，如果它不是经常被使用，重要的是它要在用户需要它的极少情况下需要毫不费力地执行。

 

Example important actions: "Add network" in Wi-Fi settings and "Switch to camera" in the Gallery app.

 

示例的重要动作：在Wi-Fi（注：一种创建在IEEE 802.11标准上的无线局域网络设备）设置中的“添加网络”和画廊应用的“切换到照相机”。

 

3. Typical: It's an action that is typically provided in the action bar in similar apps, so your users expect to find it in yours.

 

3. 惯常的：动作在相似应用的动作栏中惯常提供。所以你的用户期待在你的应用中能找到它。

 

Example typical actions: "Refresh" in an email or social app, and "New contact" in the People app.

 

示例的惯常动作：电子邮件或社交应用中的“刷新”，和联系人应用中的“新电话簿”。

 

If you believe that more than four of your menu items can be justified as action items, then you should carefully consider their relative level of importance and try to set no more than four as action items (and do so using the "ifRoom" value to allow the system to put some back in the overflow menu when space is limited on smaller screens). Even if space is available on a wide screen, you should not create a long stream of action items that clutter the UI and appear like a desktop toolbar, so keep the number of action items to a minimum.

 

如果你确信你有多于四个菜单条目可以被正式化为动作条目，那么你应该小心地考虑它们的相对重要级别并尝试设置不多于四个条目作为动作条目（并且使用ifRoom值来做到这点以允许系统在空间被限制在更小的屏幕时把一些条目放回到溢出菜单中）。即便在宽屏上有可用的空间，你也不应该创建一长串动作条目弄乱用户界面并且显得像桌面工具栏，所以要保持动作条目的数量至最小值。

 

Additionally, the following actions should never appear as action items: Settings, Help, Feedback, or similar. Always keep them in the overflow menu.

 

另外，以下动作应该从不显示为动作条目：设置，帮助，反馈或类似。总是把它们保持在溢出菜单中。

 

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

 

Note: Remember that not all devices provide a dedicated hardware button for Search, so if it's an important feature in your app, it should always appear as an action item (and usually as the first item, especially if you offer it with an action view).

 

注意：记住不是所有设备提供一个专用于搜索的硬件按键，所以如果它在你的应用中是重要的特性，那么它应该总是作为一个动作条目来显示（并总是作为第一个条目，特别是如果你用动作视图来提供它）。

 

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

 

Using split action bar

 

使用分割动作栏

 

When your application is running on Android 4.0 (API level 14) and higher, there's an extra mode available for the action bar called "split action bar." When you enable split action bar, a separate bar appears at the bottom of the screen to display all action items when the activity is running on a narrow screen (such as a portrait-oriented handset). Splitting the action bar to separate the action items ensures that a reasonable amount of space is available to display all your action items on a narrow screen, while leaving room for navigation and title elements at the top.

 

当你的用于程序正在运行于Android 4.0（API级别14）和更高时，动作栏有一个可用的额外模式被称为“分割动作栏”。当你使能分割动作栏时，一个分隔栏显示在屏幕的底部以在活动运行于一个狭窄屏幕时（诸如一个竖屏方向的手机）显示所有动作条目。分割动作栏以分隔动作条目，确保在一个窄屏上有合理数量的空间可用于显示你的所有动作条目，同时在顶部保留空间用于导航和标题元素。

 

To enable split action bar, simply add uiOptions="splitActionBarWhenNarrow" to your <activity> or <application> manifest element.

 

为了使能分割动作栏，简单地添加uiOptions="splitActionBarWhenNarrow"到你的<activity>或<application>清单元素。

 

Be aware that Android adjusts the action bar's appearance in a variety of ways, based on the current screen size. Using split action bar is just one option that you can enable to allow the action bar to further optimize the user experience for different screen sizes. In doing so, you may also allow the action bar to collapse navigation tabs into the main action bar. That is, if you use navigation tabs in your action bar, once the action items are separated on a narrow screen, the navigation tabs may be able to fit into the main action bar rather than be separated into the "stacked action bar." Specifically, if you've disabled the action bar icon and title (with setDisplayShowHomeEnabled(false) and setDisplayShowTitleEnabled(false)), then the navigation tabs collapse into the main action bar, as shown by the second device in figure 3.

 

请意识到Android以不同的方式调整动作栏的外观，基于当前的屏幕大小。使用分割动作栏只是其中一种选择，你用它使能以允许动作栏进一步优化不同屏幕大小的用户体验。这样做的时候，你还可以允许动作栏折叠导航标签页进主动作栏。就是说，如果你在你的动作栏中使用导航标签页，一旦动作条目在窄屏中被分隔，导航标签页可以有能力适应主动作栏的大小而非被分隔进“被堆叠的动作栏”。特别地，如果你已经屏蔽动作栏图标和标题（用setDisplayShowHomeEnabled(false)和setDisplayShowTitleEnabled(false)），那么导航标签页折叠进主动作栏，正如图3中第二个设备中所示。

 

（图3略）

 

Figure 3. Mock-ups of split action bar with navigation tabs on the left; with the app icon and title disabled on the right.

 

图3. 左图是带导航标签页的分割动作栏模型（注：Mockup，意思是样机，木型）；而右图的应用图标和标题被屏蔽。

 

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

 

Note: Although the android:uiOptions attribute was added in Android 4.0 (API level 14), you can safely include it in your application even if your minSdkVersion is set to a value lower than "14" to remain compatible with older versions of Android. When running on older versions, the system simply ignores the XML attribute because it doesn't understand it. The only condition to including it in your manifest is that you must compile your application against a platform version that supports API level 14 or higher. Just be sure that you don't openly use other APIs in your application code that aren't supported by the version declared by your minSdkVersion attribute—only XML attributes are safely ignored by older platforms.

 

注意：虽然android:uiOptions属性在Android 4.0（API级别14）中被添加，但是你可以安全地包含它在你的应用程序中，即便你的minSdkVersion被设置为一个低于14的值以保持对旧版本Android的兼容性。当运行在旧版本上时，系统简单地忽略该XML属性因为它并不了解。在你的清单中包含它的唯一条件是你必须编译你的应用程序对应支持API级别14或更高的平台。只要确保你在你的应用程序代码中不要公开使用其它不被你的minSdkVersion属性所声明版本不支持的API——只有XML的属性能被旧平台安全地忽略。

 

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

 

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

 

Using the App Icon for Navigation

 

使用应用图标进行导航

 

Using a logo instead of icon

 

使用徽记代替图标

 

By default, the system uses your application icon in the action bar, as specified by the android:icon attribute in the <application> or <activity> element. However, if you also specify the android:logo attribute, then the action bar uses the logo image instead of the icon.

 

默认，系统在动作栏中使用你的应用程序图标，正如<application>或<activity>元素中指定的android:icon属性。然而，如果你还指定android:logo属性，那么动作栏使用徽记图片代替图标。

 

A logo should usually be wider than the icon, but should not include unnecessary text. You should generally use a logo only when it represents your brand in a traditional format that users recognize. A good example is the YouTube app's logo—the logo represents the expected user brand, whereas the app's icon is a modified version that conforms to the square requirement.

 

徽记通常应该比图标宽，但不应该包含不必要的文本。你通常应该使用徽记，仅当它以用户认识的传统格式代表你的品牌。一个好的例子是YouTube应用的徽记——该徽记代表期待的用户品牌，然而应用的图标是一个符合正方形需要的修改版。

 

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

 

By default, your application icon appears in the action bar on the left side. If you'd like, you can enable the icon to behave as an action item. In response to user action on the icon, your application should do one of two things:

 

默认，你的应用程序图标出现在动作栏的左侧。如果你喜欢的话，你可以使图标的行为像一个动作条目。作为图标上的用户动作的响应，你的应用程序应该做两件事情的其中之一：

 

* Go to the application "home" activity, or

 

* 转至应用程序的“主页”活动，或

 

* Navigate "up" the application's structural hierarchy

 

* 在应用的结构层级中导航“向上”

 

When the user touches the icon, the system calls your activity's onOptionsItemSelected() method with the android.R.id.home ID. In response, you should either start the home activity or take the user one step up in your application's structural hierarchy.

 

当用户触碰图标时，系统用android.R.id.home的ID值调用你的活动的onOptionsItemSelected()方法。作为响应，你应该启动主页活动或带用户在你的应用的结构层级中向上走一步。

 

If you respond to the application icon by returning to the home activity, you should include the FLAG_ACTIVITY_CLEAR_TOP flag in the Intent. With this flag, if the activity you're starting already exists in the current task, then all activities on top of it are destroyed and it is brought to the front. Adding this flag is often important because going "home" is an action that's equivalent to "going back" and you should usually not create a new instance of the home activity. Otherwise, you might end up with a long stack of activities in the current task with multiple instances of the home activity.

 

如果你通过返回主页活动来响应应用程序图标，你应该包含FLAG_ACTIVITY_CLEAR_TOP在Intent中。使用这个标志，如果你正在启动的活动已经存在于当前任务重，那么所有在它上方的活动被销毁，而它被带到前方。添加这个标志总是重要的，因为转至“主页”是一个相当于“后退”的动作，而你通常不应该创建主页活动的新实例。否则，最终你在当前任务中得到一个长的活动堆栈，带有多个主页活动的实例。

 

For example, here's an implementation of onOptionsItemSelected() that returns to the application's "home" activity:

 

例如，这里有一个onOptionsItemSelected()的实现，返回到应用程序的“主页”活动：

 

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

 

@Override

public boolean onOptionsItemSelected(MenuItem item) {

    switch (item.getItemId()) {

        case android.R.id.home:

            // app icon in action bar clicked; go home

            // 动作栏的应用图标被点击；转到桌面

            Intent intent = new Intent(this, HomeActivity.class);

            intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);

            startActivity(intent);

            return true;

        default:

            return super.onOptionsItemSelected(item);

    }

}

 

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

 

In case the user can enter the current activity from another application, you might also want to add the FLAG_ACTIVITY_NEW_TASK flag. This flag ensures that, when the user navigates either "home" or "up", the new activity is not added to the current task, but instead started in a task that belongs to your application. For example, if the user starts an activity in your application through an intent invoked by another application, then selects the action bar icon to navigate home or up, the FLAG_ACTIVITY_CLEAR_TOP flag starts the activity in a task that belongs to your application (not the current task). The system either starts a new task with your new activity as the root activity or, if an existing task exists in the background with an instance of that activity, then that task is brought forward and the target activity receives onNewIntent(). So if your activity accepts intents from other applications (it declares any generic intent filters), you should usually add the FLAG_ACTIVITY_NEW_TASK flag to the intent:

 

如果用户可以从另一个应用程序进入当前活动，你还可能希望添加FLAG_ACTIVITY_NEW_TASK标志。这个标志确保，当用户导航“去主页”或“向上”时，新的活动不被添加到当前任务，但改为在属于你的应用程序的任务中启动。例如，如果用户通过被另一个程序调用的意图，在你的应用程序中启动一个活动，然后选择动作栏图标导航到主页或向上，那么FLAG_ACTIVITY_CLEAR_TOP标志在属于你的应用程序的任务（不是当前任务）中启动活动。系统或者启动一个新任务，以你的新活动作为根活动，或者，如果一个现在存在于后台的现存任务带有那个活动的实例，那么那个活动被带到前面而目标活动接收到onNewIntent()。所以如果你的活动从其它应用程序接收意图（它声明了任意常规的意图过滤器），那么你通常应该添加FLAG_ACTIVITY_NEW_TASK标志到该意图：

 

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

 

intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK);

 

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

 

For more information about these flags and other back stack behaviors, read the Tasks and Back Stack developer guide.

 

想获取关于这些标志和其它后退堆栈行为的更多信息，请阅读任务和后退堆栈开发者指引。

 

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

 

Note: If you're using the icon to navigate to the home activity, beware that beginning with Android 4.0 (API level 14), you must explicitly enable the icon as an action item by calling setHomeButtonEnabled(true) (in previous versions, the icon was enabled as an action item by default).

 

注意：如果你正在使用图标导航到主页活动，请意识到从Android 4.0（API级别14）开始，你必须通过调用setHomeButtonEnabled(true)显式地使图标成为一个动作条目（在之前的版本中，图标默认被使能为动作条目）。

 

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

 

Navigating up

 

导航向上

 

（图4略）

 

Figure 4. The Email app's standard icon (left) and the "navigate up" icon (right). The system automatically adds the "up" indicator.

 

图4. 电子邮件的标准图标（左图）和“导航向上”图标（右图）。系统自动地添加“向上”指示符。

 

As a supplement to traditional "back" navigation—which takes the user to the previous screen in the task history—you can enable the action bar icon to offer "up" navigation, which should take the user one step up in your application's structural hierarchy. For instance, if the current screen is somewhere deep in the hierarchy of the application, touching the app icon should navigate upward one level, to the parent of the current screen.

 

作为对传统的“后退”导航的补充——它把用户带到堆栈层级中的前一个屏幕——你可以使能动作栏图标以提供“向上”导航，它应该会带用户在你的应用的结构层级中向上走一步。例如，如果当前屏幕在应用的层级中较深的地方，那么触碰应用图标应该导航向上走一层，转到当前屏幕的父屏幕。

 

For example, figure 5 illustrates how the BACK button behaves when the user navigates from one application to an activity belonging to a different application (specifically, when composing an email to a person selected from the People app).

 

例如，图5描绘当用户从一个应用程序导航到属于一个不同的应用程序的活动时，后退键的行为是怎样的（特别地，当撰写邮件给从联系人应用中选中的联系人时）。

 

（图5略：

联系人任务：

电话簿->电话簿明细->撰写电子邮件->BACK（->电话簿明细）

）

 

Figure 5. The BACK button behavior after entering the Email app from the People (or Contacts) app.

 

图5. 在从联系人（或电话簿）应用进入电子右键应用后，后退键的行为。

 

However, if the user wants to stay within the email application after composing the email, up navigation allows the user to navigate upward in the email application, rather than go back to the previous activity. Figure 6 illustrates this scenario, in which the user again comes into the email application, but presses the action bar icon to navigate up, rather than back.

 

然而，如果用户希望在撰写电子邮件后停留在电子邮件应用，那么向上导航允许用户导航向上进电子邮件应用，而非返回前一个活动。图6描绘在这种场景下，用户再次回到电子邮件应用，但按下动作栏图标会导航向上，而非返回。

 

（图6略：

联系人任务：

联系人->联系人明细->撰写电子邮件->UP（->电子邮件收件箱）

电子邮件任务：

电子邮件收件箱

）

 

Figure 6. Example behavior for UP navigation after entering the Email app from the People app.

 

图6. 从联系人应用进入电子邮件应用后，向上导航的示例行为。

 

To enable the icon for up navigation (which displays the "up" indicator next to the icon), call setDisplayHomeAsUpEnabled(true) on your ActionBar:

 

为了使图标能向上导航（它在图标旁边显示“向上”指示符），请在你的ActionBar上调用setDisplayHomeAsUpEnabled(true)：

 

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

 

protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);

 

    setContentView(R.layout.main);

    ActionBar actionBar = getActionBar();

    actionBar.setDisplayHomeAsUpEnabled(true);

    ...

}

 

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

 

When the user touches the icon, the system calls your activity's onOptionsItemSelected() method with the android.R.id.home ID, as shown in the above section about Using the App Icon for Navigation.

 

当用户触碰图标时，系统用android.R.id.home的ID值调用你的活动的onOptionsItemSelected()方法，正如上面关于使用应用图标进行导航的章节中展示的那样。

 

Remember to use the FLAG_ACTIVITY_CLEAR_TOP flag in the Intent, so that you don't create a new instance of the parent activity if one already exists. For instance, if you don't use the FLAG_ACTIVITY_CLEAR_TOP flag, then after navigating up, the BACK button will actually take the user "forward", with respect to the application structure, which would be strange.

 

请记得在Intent中使用FLAG_ACTIVITY_CLEAR_TOP标志，使你不会创建父活动的新实例，如果它已经存在。例如，如果你不使用FLAG_ACTIVITY_CLEAR_TOP标志，然后在导航向上后，事实上后退键是根据应用程序的结构，带用户“向前”，这会变得很怪。

 

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

 

Note: If there are many paths that the user could have taken to reach the current activity within your application, the up icon should navigate backward along the path the user actually followed to get to the current activity.

 

注意：如果用户在你的应用程序中可以有很多路径到达当前活动时，那么向上图标应该沿着用户实际到达当前活动所跟随的路径导航后退。

 

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

 

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

 

Adding an Action View

 

添加动作视图

 

（图7略）

 

Figure 7. An action bar with a collapsed action view for Search (top), then expanded action view with the SearchView widget (bottom).

 

图7. 带有一个用于搜索的被折叠的动作视图的动作栏（上图），然后是带有SearchView部件的展开动作视图（下图）。

 

An action view is a widget that appears in the action bar as a substitute for an action item's button. For example, if you have an item in the options menu for "Search," you can add an action view that replaces the button with a SearchView widget, as shown in figure 7.

 

动作视图是一种显示在动作栏中的部件，作为动作条目的按钮的替代物。例如，如果你在选项菜单中有一个条目用于“搜索”，你可以添加动作视图，代替带有SearchView部件的按钮，正如图7中展示的那样。

 

To declare an action view for an item in your menu resource, use either the android:actionLayout or android:actionViewClass attribute to specify either a layout resource or widget class to use, respectively. For example:

 

为了在你的菜单资源中把一个条目声明为一个动作视图，请使用android:actionLayout或android:actionViewClass属性以指出要使用的相应的布局资源或部件类。例如：

 

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

 

<?xml version="1.0" encoding="utf-8"?>

<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item android:id="@+id/menu_search"

          android:title="@string/menu_search"

          android:icon="@drawable/ic_menu_search"

          android:showAsAction="ifRoom|collapseActionView"

          android:actionViewClass="android.widget.SearchView" />

</menu>

 

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

 

Notice that the android:showAsAction attribute also includes "collapseActionView". This is optional and declares that the action view should be collapsed into a button. When the user selects the button, the action view expands. Otherwise, the action view is visible by default and might consume valuable action bar space even when the user is not using it. For more information, see the next section about Handling collapsible action views.

 

注意android:showAsAction还包含collapseActionView。这是可选的并且声明动作视图应该被折叠进一个按钮中。当用户选择该按钮时，动作视图会展开。否则，动作视图默认是可见的并且可能占用宝贵的动作栏空间，即便当用户不在使用它。想获取更多信息，请参见下一个关于处理可折叠动作视图的章节。

 

If you need to add some event hooks to your action view, you can do so during the onCreateOptionsMenu() callback. You can acquire elements in an action view by calling findItem() with the ID of the menu item, then call getActionView(). For example, the search widget from the above sample is acquired like this:

 

如果你需要添加一些事件钩子到你的动作视图，那么你可以在onCreateOptionsMenu()回调期间做这些事情。你可以通过用菜单条目的ID调用findItem()来获取动作视图中的元素。例如，上面例子中的搜索部件像这样来获取：

 

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

 

@Override

public boolean onCreateOptionsMenu(Menu menu) {

    getMenuInflater().inflate(R.menu.options, menu);

    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();

    // Configure the search info and add any event listeners

    // 配置搜索信息并添加任意事件监听器

    ...

    return super.onCreateOptionsMenu(menu);

}

 

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

 

For more information about using the search widget, see Creating a Search Interface.

 

想获取关于使用搜索部件的更多信息，请参见创建搜索界面。

 

Handling collapsible action views

 

处理可折叠的动作视图

 

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

 

Supporting Android 3.0 with an action view

 

用动作视图支持Android 3.0

 

The "collapseActionView" option was added with Android 4.0 (API level 14). However, if your application supports older versions, you should still declare "collapseActionView" in order to better support smaller screens. Devices running Android 4.0 and higher will show the action view collapsed, while older versions work as designed otherwise.

 

collapseActionView选项随Android 4.0（API级别14）被添加。然而，如果你的应用程序支持较老的版本，你仍然应该声明collapseActionView以便更好地支持较小的屏幕。运行Android 4.0和更高的设备将显示被折叠的动作视图，相反，较老的版本如同设想的那样工作。

 

Adding this value requires that you set your build target to Android 4.0 or higher in order to compile. Older versions of Android ignore the "collapseActionView" value because they don't understand it. Just be sure not to use other APIs in your source code that are not supported in the version declared by your minSdkVersion, unless you add the appropriate version check at runtime.

 

添加这个值需要你设置你的构建目标为Android 4.0或更高以便于编译。较旧版本的Android忽略collapseActionView值，因为它们不知道它。只要确保不要在源代码中使用你的minSdkVersion声明的版本中不支持的其它API，除非你在运行时添加合适的版本检查。

 

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

 

Action views allow you to provide fast access to rich actions without changing activities or fragments, or replacing the action bar. However, it might not be appropriate to make an action view visible by default. To preserve the action bar space (especially when running on smaller screens), you can collapse your action view into an action item button. When the user selects the button, the action view appears in the action bar. When collapsed, the system might place the item into the overflow menu if you've defined android:showAsAction with "ifRoom", but the action view still appears in the action bar when the user selects the item. You can make your action view collapsible by adding "collapseActionView" to the android:showAsAction attribute, as shown in the XML above.

 

动作视图允许你提供连接富动作的快速访问而不改变活动或片段，或取代动作栏。然而，让动作视图默认可视可能不太合适。为了节省动作栏空间（特别地当运行在较小屏幕上时），你可以折叠你的动作视图进一个动作条目按钮。当用户选择该按钮时，动作视图出现在动作栏中。当被折叠时，如果你已经用ifRoom定义android:showAsAction，系统可以把条目放进溢出菜单中，但是当用户选择条目时动作视图仍然显示在动作栏中。你可以通过添加collapseActionView到android:showAsAction属性，让你的动作视图可折叠，正如上面的XML中所示。

 

Because the system will expand the action view when the user selects the item, so you do not need to respond to the item in the onOptionsItemSelected callback. The system still calls onOptionsItemSelected() when the user selects it, but the system will always expand the action view unless you return true (indicating you've handled the event instead).

 

因为系统在用户选择条目时会展开动作视图，所以你不需要在onOptionsItemSelected回调中响应条目。当用户选择它时，系统仍调用onOptionsItemSelected()，但系统将总是展开动作视图除非你返回true（指示你已经代替系统处理了事件）

 

The system also collapses your action view when the user selects the "up" icon in the action bar or presses the BACK button.

 

当用户在动作栏中选择“向上”图标或按下后退键时，系统也会折叠你的动作视图。

 

If necessary, you can expand or collapse the action view in your own code by calling expandActionView() and collapseActionView() on the MenuItem.

 

如果有必要的话，你可以通过调用MenuItem上的expandActionView()和collapseActionView()，在你自己的代码中展开或折叠动作视图。

 

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

 

Note: Although collapsing your action view is optional, we recommend that you always collapse your action view if it includes SearchView. Also be aware that some devices provide a dedicated SEARCH button and you should expand your search action view if the user presses the SEARCH button. Simply override your activity's onKeyUp() callback method, listen for the KEYCODE_SEARCH event, then call expandActionView().

 

注意：虽然折叠你的动作视图是可选的，但是我们建议你总是折叠你的动作视图如果它包含SearchView。同时要意识到一些设备提供专用的搜索按钮，如果用户按下搜索按钮，你应该展开你的搜索动作视图。简单地覆盖你的活动的onKeyUp()回调方法，监听KEYCODE_SEARCH事件，然后调用expandActionView()。

 

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

 

If you need to update your activity based on the visibility of your action view, you can receive callbacks when it's expanded and collapsed by defining an OnActionExpandListener and registering it with setOnActionExpandListener(). For example:

 

如果你需要基于动作视图的可见性来更新你的活动，那么你可以通过定义OnActionExpandListener和用setOnActionExpandListener()注册它，在视图被展开和折叠时接收回调。

 

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

 

@Override

public boolean onCreateOptionsMenu(Menu menu) {

    getMenuInflater().inflate(R.menu.options, menu);

    MenuItem menuItem = menu.findItem(R.id.actionItem);

    ...

 

    menuItem.setOnActionExpandListener(new OnActionExpandListener() {

        @Override

        public boolean onMenuItemActionCollapse(MenuItem item) {

            // Do something when collapsed 当折叠时做某些事情

            return true;  // Return true to collapse action view 返回true给折叠的动作视图

        }

 

        @Override

        public boolean onMenuItemActionExpand(MenuItem item) {

            // Do something when expanded 当展开时做某些事情

            return true;  // Return true to expand action view 返回true给展开动作视图

        }

    });

}

 

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

 

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

 

Adding an Action Provider

 

添加动作提供者

 

（图8略）

 

Figure 8. Screenshot from the Gallery app, with the ShareActionProvider submenu expanded to show share targets.

 

图8. 来自画廊应用的截屏，使用展开的ShareActionProvider子菜单显示共享部件。

 

Similar to an action view, an action provider (defined by the ActionProvider class) replaces an action item with a customized layout, but it also takes control of all the item's behaviors. When you declare an action provider for a menu item in the action bar, it not only controls the appearance of the item in the action bar with a custom layout, but also handles the default event for the menu item when it appears in the overflow menu. It can also provide a submenu from either the action bar or the overflow menu.

 

类似于一个动作视图，一个动作提供者（由ActionProvider类定义）不仅用一个定制布局代替一个动作条目，而且还控制所有条目的行为。当你把动作栏中一个菜单条目声明为一个动作提供者时，它不仅仅用自定义的布局控制动作栏中条目的外观，而且处理菜单条目在它出现在溢出菜单中时的默认事件。它还从动作栏或溢出菜单中提供一个子菜单。

 

For example, the ShareActionProvider is an extension of ActionProvider that facilitates a “share" action by showing a list of available share targets from the action bar. Instead of using a traditional action item that invokes the ACTION_SEND intent, you can declare an instance of ShareActionProvider to handle an action item. This action provider presents an action view with a drop-down list of applications that handle the ACTION_SEND intent, even when the menu item appears in the overflow menu. Hence, when you use an action provider such as this one, you don't have to handle user events on the menu item.

 

例如，ShareActionProvider是一个ActionProvider的扩展类，方便通过在动作栏中显示一列可用的共享目标来实现一个“共享”动作。不使用一个传统的调用ACTION_SEND意图的动作条目，你可以声明一个ShareActionProvider实例以处理一个动作条目。这个动作提供者用一个处理ACTION_SEND意图的应用程序的下拉列表呈现一个动作视图，即便当菜单条目出现在溢出菜单中。因此，当你使用一个动作提供者诸如这个类时，你不必处理菜单条目上的用户事件。

 

To declare an action provider for an action item, define the android:actionProviderClass attribute for the appropriate the <item> element in your menu resource, using the fully-qualified class name of the action provider. For example:

 

为了声明动作条目的动作提供者，请为你的菜单资源中合适的<item>元素，使用动作提供者的完全标准类名定义android:actionProviderClass属性。例如：

 

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

 

<?xml version="1.0" encoding="utf-8"?>

<menu xmlns:android="http://schemas.android.com/apk/res/android">

    <item android:id="@+id/menu_share"

          android:title="@string/share"

          android:showAsAction="ifRoom"

          android:actionProviderClass="android.widget.ShareActionProvider" />

    ...

</menu>

 

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

 

In this example, the ShareActionProvider is used as the action provider. At this point, the action provider officially takes control of the menu item and handles both its appearance and behavior in the action bar and its behavior in the overflow menu. You must still provide a text title for the item to be used in the overflow menu.

 

在这个示例中，使用ShareActionProvider作为动作提供者。在这一点上，动作提供者正式地控制菜单条目和处理它在动作栏中的外观与行为以及它在溢出菜单中的行为。你仍必须为条目提供一个在溢出菜单中使用的文本标题。

 

Although the action provider can perform the default action for the menu item when it appears in the overflow menu, your activity (or fragment) can override that behavior by also handling the click event from the onOptionsItemSelected() callback method. If you do not handle the event in that callback, then the action provider receives the onPerformDefaultAction() callback to handle the event. However, if the action provider provides a submenu, then your activity will not receive the onOptionsItemSelected() callback, because the submenu is shown instead of invoking the default menu item behavior when selected.

 

虽然动作提供者可以在菜单条目出现在溢出菜单时为它执行默认动作，但是你的活动（或片段）可以同样地通过从onOptionsItemSelected()回调方法中处理点击事件，覆盖那个行为。如果你不在那个回调中处理该事件，那么动作提供者接收onPerformDefaultAction()回调以处理事件。然而，如果动作提供者提供一个子菜单，那么你的活动将不会接收到onOptionsItemSelected()回调，因为在选中的时候显示子菜单而非调用默认的菜单条目行为。

 

Using the ShareActionProvider

 

使用ShareActionProvider

 

If you want to provide a "share" action in your action bar by leveraging other applications installed on the device (for example, to share a photo using a messaging or social app), then using ShareActionProvider is an effective way to do so, rather than adding an action item that invokes the ACTION_SEND intent. When you use ShareActionProvider for an action item, it presents an action view with a drop-down list of applications that handle the ACTION_SEND intent (as shown in figure 8).

 

如果你希望通过利用其它已安装在设备上的其它应用程序，在你的动作栏中提供一个“共享”动作（例如，使用短信分享图片或社交应用），那么使用ShareActionProvider是做这种事情的高效方式，而非添加调用ACTION_SEND意图的动作条目。当你为一个动作条目使用ShareActionProvider时，它呈现一个动作视图，带有一个下拉列表的应用程序处理ACTION_SEND意图（正如图8所示）。

 

All the logic for creating the submenu, populating it with share targets, and handling click events (including when the item appears in the overflow menu) is implemented by the ShareActionProvider—the only code you need to write is to declare the action provider for the menu item and specify the share intent.

 

所有用于创建子菜单的逻辑，用共享的目标填充它，并且处理点击事件（包括当条目出现在溢出菜单中时）是由ShareActionProvider实现的——你需要书写的唯一代码是为菜单条目声明动作提供者并指定共享意图。

 

By default, the ShareActionProvider retains a ranking for each share target based on how often the user selects each one. The share targets used more frequently appear at the top of the drop-down list and the target used most often appears directly in the action bar as the default share target. By default, the ranking information is saved in a private file with a name specified by DEFAULT_SHARE_HISTORY_FILE_NAME. If you use the ShareActionProvider or an extension of it for only one type of action, then you should continue to use this default history file and there's nothing you need to do. However, if you use ShareActionProvider or an extension of it for multiple actions with semantically different meanings, then each ShareActionProvider should specify its own history file in order to maintain its own history. To specify a different history file for the ShareActionProvider, call setShareHistoryFileName() and provide an XML file name (for example, "custom_share_history.xml").

 

默认，ShareActionProvider保留每个共享目标的排行，基于用户选择它们中每一个的频繁程度。使用较频繁的共享目标出现在下拉列表的顶部，而使用最频繁的目标直接出现在动作栏中作为默认的共享目标。默认，排行信息被保存在一个私有文件，它的名字由DEFAULT_SHARE_HISTORY_FILE_NAME指定。如果你使用ShareActionProvider或它的一个扩展做一种类型的动作，那么你应该继续使用这个默认历史文件，并且你不需要做任何事情。然而，如果你使用ShareActionProvider或它的一个扩展做多种带有语义上不同含义的动作，那么每个ShareActionProvider应该指定它自己的历史文件以便维护它自己的历史。要想为ShareActionProvider指定一个不同的历史文件，请调用setShareHistoryFileName()并提供一个XML文件名（例如，"custom_share_history.xml"）。

 

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

 

Note: Although the ShareActionProvider ranks share targets based on frequency of use, the behavior is extensible and extensions of ShareActionProvider can perform different behaviors and ranking based on the history file (if appropriate).

 

注意：虽然ShareActionProvider基于使用频率排序共享目标，但是这个行为是可扩展的，而且ShareActionProvider的扩展可以执行不同的行为并基于历史文件排序（如果合适的话）。

 

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

 

To add ShareActionProvider, simply define the android:actionProviderClass attribute with "android.widget.ShareActionProvider", as shown in the XML example above. The only thing left to do is define the Intent you want to use for sharing. To do so, you must call getActionProvider() to retrieve the ShareActionProvider that's associated with a MenuItem, then call setShareIntent().

 

为了添加ShareActionProvider，简单地用android.widget.ShareActionProvider定义android:actionProviderClass属性，正如上面示例的XML中展示的那样。余下要做的唯一事情是定义你要用来共享的Intent。为了做到那一点，你必须调用getActionProvider()获取与一个MenuItem关联的ShareActionProvider，然后调用setShareIntent()。

 

If the format for the share intent depends on the selected item or other variables that change during the activity lifecycle, you should save the ShareActionProvider in a member field and update it by calling setShareIntent() as necessary. For example:

 

如果用于共享意图的格式依赖于选中的条目或其它在活动生命周期期间改变的变量，那么你应该保存ShareActionProvider在一个成员域并在需要时通过调用setShareIntent()更新它。例如：

 

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

 

private ShareActionProvider mShareActionProvider;

...

 

@Override

public boolean onCreateOptionsMenu(Menu menu) {

    mShareActionProvider = (ShareActionProvider) menu.findItem(R.id.menu_share).getActionProvider();

 

    // If you use more than one ShareActionProvider, each for a different action,

    // use the following line to specify a unique history file for each one.

    // 如果你使用多于一个ShareActionProvider时，每个用于不同的动作，

    // 那么请使用以下代码行来为每个对象指定一个唯一的历史文件

    // mShareActionProvider.setShareHistoryFileName("custom_share_history.xml");

 

    // Set the default share intent

    // 设置默认共享意图

    mShareActionProvider.setShareIntent(getDefaultShareIntent());

 

    return true;

}

// When you need to update the share intent somewhere else in the app, call

// mShareActionProvider.setShareIntent()

// 当你需要在应用的其它地方更新共享意图时，

// 请调用mShareActionProvider.setShareIntent()

 

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

 

The ShareActionProvider now handles all user interaction with the item and you do not need to handle click events from the onOptionsItemSelected() callback method.

 

ShareActionProvider现在处理对该条目的所有用户交互，而你不需要从onOptionsItemSelected()回调方法中处理点击事件。

 

For a sample using the share action provider, see ActionBarActionProviderActivity.

 

想获取使用共享动作提供者的示例，请参见ActionBarActionProviderActivity。

 

Creating a custom action provider

 

创建一个自定义动作提供者

 

When you want to create an action view that has dynamic behaviors and a default action in the overflow menu, extending ActionProvider to define those behaviors is a good solution. Creating your own action provider offers you an organized and reusable component, rather than handling the various action item transformations and behaviors in your fragment or activity code. As shown in the previous section, Android provides one implementation of ActionProvider for share actions: the ShareActionProvider.

 

当你希望创建一个拥有动态行为的动作视图，并在溢出菜单中有一个默认动作时，扩展ActionProvider以定义那些行为是一个好的解决方案。创建你自己的动作提供者会为你提供一个有组织的和可重用的组件，而非在你的片段或活动代码中处理不同动作条目的转换和行为。正如前面章节中展示的那样，Android提供一个ActionProvider的实现用于共享的动作：ShareActionProvider。

 

To create your own, simply extend the ActionProvider class and implement its callback methods as appropriate. Most importantly, you should implement the following:

 

为了创建你自己的，简单地扩展ActionProvider类并合理的实现它的回调方法。最重要的是，你应该实现以下方法：

 

* ActionProvider()

 

This constructor passes you the application Context, which you should save in a member field to use in the other callback methods.

 

这个构造函数传给你应用程序的Context，你可以保存它作为成员字段并在其它回调方法中使用它。

 

* onCreateActionView()

 

This is where you define the action view for the item. Use the Context acquired from the constructor to instantiate a LayoutInflater and inflate your action view layout from an XML resource, then hook up event listeners. For example:

 

这里你定义条目的动作视图。使用从构造函数中取出的Context对象以实例化LayoutInflater并从XML资源中解压你的动作视图布局，然后挂钩事件监听器。例如：

 

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

 

public View onCreateActionView() {

    // Inflate the action view to be shown on the action bar.

    // 解压动作视图以显示在动作栏上。

    LayoutInflater layoutInflater = LayoutInflater.from(mContext);

    View view = layoutInflater.inflate(R.layout.action_provider, null);

    ImageButton button = (ImageButton) view.findViewById(R.id.button);

    button.setOnClickListener(new View.OnClickListener() {

        @Override

        public void onClick(View v) {

            // Do something...

            // 做一些事情……

        }

    });

    return view;

}

 

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

 

* onPerformDefaultAction()

 

The system calls this when the menu item is selected from the overflow menu and the action provider should perform a default action for the menu item.

 

当溢出菜单中的菜单条目被选中时系统调用它，而动作提供者应该为菜单条目执行默认动作。

 

However, if your action provider provides a submenu, through the onPrepareSubMenu() callback, then the submenu appears even when the menu item is in the overflow menu. Thus, onPerformDefaultAction() is never called when there is a submenu.

 

然而，如果你的动作提供者通过onPrepareSubMenu()回调提供一个子菜单时，那么子菜单会出现，即便菜单条目是在溢出菜单中。因此，当存在子菜单时onPerformDefaultAction()从不被调用。

 

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

 

Note: An activity or a fragment that implements onOptionsItemSelected() can override the action provider's default behavior by handling the item-selected event (and returning true), in which case, the system does not call onPerformDefaultAction().

 

注意：一个实现onOptionsItemSelected()的活动或片段可以通过处理条目选择事件（并且返回true）来覆盖动作提供者的默认行为，在那种情况下，系统不调用onPerformDefaultAction()。

 

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

 

For an example extension of ActionProvider, see ActionBarSettingsActionProviderActivity.

 

想获取ActionProvider的示例扩展，请参见ActionBarSettingsActionProviderActivity。

 

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

 

Adding Navigation Tabs

 

添加导航标签页

 

（图9略）

 

Figure 9. Screenshot of action bar tabs from the Honeycomb Gallery app.

 

图9. 出自Honeycomb画廊应用的动作栏标签页的截屏。

 

（图10略）

 

Figure 10. Screenshot of tabs in the stacked action bar on a narrow screen.

 

图10. 窄屏下堆叠的动作栏标签页的截屏。

 

When you want to provide navigation tabs in an activity, using the action bar's tabs is a great option (instead of using TabWidget), because the system adapts the action bar tabs for different screen sizes—placing them in the main action bar when the screen is sufficiently wide, or in a separate bar (known as the "stacked action bar") when the screen is too narrow, as shown in figures 9 and 10.

 

当你希望在一个活动中提供导航标签页时，使用动作栏的标签页是一个很好的选择（取代使用TabWidget），因为系统为不同的屏幕大小调整动作栏标签页——当屏幕足够宽时放置它们在主动作栏中，或当屏幕太狭窄时放在一个单独的栏中（被称为“被堆叠的动作栏”），正如图9和10中所示。

 

To switch between fragments using the tabs, you must perform a fragment transaction each time a tab is selected. If you're not familiar with how to change fragments using FragmentTransaction, first read the Fragments developer guide.

 

为了使用标签页在片段间切换，你必须在每次标签选中时执行片段过渡。如果你不熟悉如何使用FragmentTransaction改变片段，请先阅读片段开发者指引。

 

To get started, your layout must include a ViewGroup in which you place each Fragment associated with a tab. Be sure the ViewGroup has a resource ID so you can reference it from your tab-swapping code. Alternatively, if the tab content will fill the activity layout (excluding the action bar), then your activity doesn't need a layout at all (you don't even need to call setContentView()). Instead, you can place each fragment in the default root ViewGroup, which you can refer to with the android.R.id.content ID (you can see this ID used in the sample code below, during fragment transactions).

 

为了方便入门，你的布局必须包含一个ViewGroup，在它里面放置每个与标签页关联的Fragment对象。确保ViewGroup拥有一个资源ID使你可以从你的标签页交换代码中引用它。可选地，如果标签页内容将填充活动布局（不包括动作栏），那么你的活动完全不需要一个布局（你甚至不需要调用setContentView()）。取而代之的是，你可以在默认的根ViewGroup中放置每个片段，你可以用android.R.id.content的ID引用它（你可以看到下面的示例代码中在片段事务期间使用这个ID）。

 

Once you determine where the fragments appear in the layout, the basic procedure to add tabs is:

 

一旦你决定好片段出现在布局中的什么地方，添加标签页的基本过程是：

 

1. Implement the ActionBar.TabListener interface. Callbacks in this interface respond to user events on the tabs so you can swap fragments.

 

1. 实现ActionBar.TabListener接口。在这个接口中回调响应标签页上的用户事件，使你可以交换片段。

 

2. For each tab you want to add, instantiate an ActionBar.Tab and set the ActionBar.TabListener by calling setTabListener(). Also set the tab's title and/or icon with setText() and/or setIcon().

 

2. 对于你要添加的每个标签页，通过调用setTabListener()来实例化ActionBar.Tab和设置ActionBar.TabListener。还可以用setText()和/或setIcon()设置标签页的标题和/或图标。

 

3. Add each tab to the action bar by calling addTab().

 

3. 通过调用addTab()添加每个标签页到动作栏。

 

When looking at the ActionBar.TabListener interface, notice that the callback methods provide only the ActionBar.Tab that was selected and a FragmentTransaction for you to perform fragment transactions—it doesn't say anything about what fragment you should swap in or out. Thus, you must define your own association between each ActionBar.Tab and the appropriate Fragment that it represents (in order to perform the appropriate fragment transaction). There are several ways you can define the association, depending on your design. In the example below, the ActionBar.TabListener implementation provides a constructor such that each new tab uses its own instance of the listener. Each instance of the listener defines several fields that are necessary to later perform a transaction on the appropriate fragment.

 

当你看ActionBar.TabListener接口时，请注意回调方法只提供给被选中的ActionBar.Tab和FragmentTransaction给你以执行片段事务——它并不会说关于你应该交换进出什么片段的任何事情。因此，你必须定义你自己对每个ActionBar.Tab和它代表的正确Fragment之间的关联（以便执行正确的片段事务）。你可以有一些方法定义这种关联，依赖于你的设计。在下面的示例中，ActionBar.TabListener的实现提供一个构造函数，使每个新的标签页使用它自己的监听器实例。每个监听器实例定义一些域，它们对于后面要在合适的片段上执行事务是必要的。

 

For example, here's how you might implement the ActionBar.TabListener such that each tab uses its own instance of the listener:

 

例如，这里的代码描述你如何可以实现ActionBar.TabListener，致使每个标签页使用它自己的监听器实例：

 

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

 

public static class TabListener<T extends Fragment> implements ActionBar.TabListener {

    private Fragment mFragment;

    private final Activity mActivity;

    private final String mTag;

    private final Class<T> mClass;

 

    /** Constructor used each time a new tab is created.

      * 每当新标签页被创建时使用的构造函数

      * @param activity  The host Activity, used to instantiate the fragment 宿主Activity，用于实例化片段

      * @param tag  The identifier tag for the fragment 用于片段的标识符标签

      * @param clz  The fragment's Class, used to instantiate the fragment 片段的类，用于实例化片段

      */

    public TabListener(Activity activity, String tag, Class<T> clz) {

        mActivity = activity;

        mTag = tag;

        mClass = clz;

    }

 

    /* The following are each of the ActionBar.TabListener callbacks */

/* 以下内容是每个ActionBar.TabListener回调 */

    public void onTabSelected(Tab tab, FragmentTransaction ft) {

        // Check if the fragment is already initialized

        // 检查片段是否已经被初始化

        if (mFragment == null) {

            // If not, instantiate and add it to the activity

            // 如果没有，实例化并添加它到活动

            mFragment = Fragment.instantiate(mActivity, mClass.getName());

            ft.add(android.R.id.content, mFragment, mTag);

        } else {

            // If it exists, simply attach it in order to show it

            // 如果它已经存在，简单地依附它以便于显示它

            ft.attach(mFragment);

        }

    }

 

    public void onTabUnselected(Tab tab, FragmentTransaction ft) {

        if (mFragment != null) {

            // Detach the fragment, because another one is being attached

            // 解除依附片段，因为依附了另一个片段

            ft.detach(mFragment);

        }

    }

 

    public void onTabReselected(Tab tab, FragmentTransaction ft) {

        // User selected the already selected tab. Usually do nothing.

        // 用户选中了已经被选择的标签。通常不做任何事情。

    }

}

 

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

 

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

 

Caution: You must not call commit() for the fragment transaction in each of these callbacks—the system calls it for you and it may throw an exception if you call it yourself. You also cannot add these fragment transactions to the back stack.

 

警告：你不能为了片段事务而在这里的每个回调中调用commit()——系统为你调用它，如果你自己调用它，它可能会抛出一个异常。你也不能添加这些片段事务到后退堆栈。

 

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

 

In this example, the listener simply attaches (attach()) a fragment to the activity layout—or if not instantiated, creates the fragment and adds (add()) it to the layout (as a child of the android.R.id.content view group)—when the respective tab is selected, and detaches (detach()) it when the tab is unselected.

 

在这个示例中，监听器简单地依附（attach()）一个片段到活动的布局——或如果没有被实例化，那么创建片段并添加（add()）它到布局（作为android.R.id.content视图组的子对象）——当相应的标签被选中，并在标签页没有被选中时解除依附（detach()）它。

 

The ActionBar.TabListener implementation is the bulk of the work. All that remains is to create each ActionBar.Tab and add it to the ActionBar. Additionally, you must call setNavigationMode(NAVIGATION_MODE_TABS) to make the tabs visible. You might also want to disable the activity title by calling setDisplayShowTitleEnabled(false) if the tab titles actually indicate the current view.

 

ActionBar.TabListener的实现是工作的绝大部分。余下的所有工作是创建每个ActionBar.Tab并添加它到ActionBar。另外，你必须调用setNavigationMode(NAVIGATION_MODE_TABS)使标签页可见。你还可能希望通过调用setDisplayShowTitleEnabled(false)屏蔽活动标题，如果标签页标题实际上指示当前视图。

 

For example, the following code adds two tabs using the listener defined above:

 

例如，以下代码使用上面定义的监听器添加两个标签页：

 

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

 

@Override

protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);

    // Notice that setContentView() is not used, because we use the root

    // android.R.id.content as the container for each fragment

    // 注意没有使用setContentView()，因为我们使用根

    // android.R.id.content作为每个片段的容器

 

    // setup action bar for tabs

    // 为标签页配置动作栏

    ActionBar actionBar = getActionBar();

    actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);

    actionBar.setDisplayShowTitleEnabled(false);

 

    Tab tab = actionBar.newTab()

            .setText(R.string.artist)

            .setTabListener(new TabListener<ArtistFragment>(

                    this, "artist", ArtistFragment.class));

    actionBar.addTab(tab);

 

    tab = actionBar.newTab()

        .setText(R.string.album)

        .setTabListener(new TabListener<AlbumFragment>(

                this, "album", AlbumFragment.class));

    actionBar.addTab(tab);

}

 

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

 

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

 

Note: The above implementation for ActionBar.TabListener is one of several possible techniques. You can see more of this style in the API Demos app.

 

注意：上面对ActionBar.TabListener的实现是几种可能技术之一。你可以在API示例应用中看到这种样式的更多内容。

 

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

 

If your activity stops, you should retain the currently selected tab with the saved instance state so you can open the appropriate tab when the user returns. When it's time to save the state, you can query the currently selected tab with getSelectedNavigationIndex(). This returns the index position of the selected tab.

 

如果你的活动停止，你应该用保存的实例状态保持当前选中的标签页，使你在用户返回时，可以打开合适的标签页。当到了保存状态的时候，你可以用getSelectedNavigationIndex()查询当前选中的标签页。它返回选中标签页的索引位置。

 

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

 

Caution: It's important that you save the state of each fragment as necessary, so that when users switch fragments with the tabs and then return to a previous fragment, it looks the way it did when they left. For information about saving the state of your fragment, see the Fragments developer guide.

 

警告：重要的是在必要时你要保存每个片段的状态，致使当用户用标签页切换片段然后返回到前一个片段时，它看起来如同你离开时那样。想获取关于保存你的片段状态的信息，请参见片段开发者指引。

 

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

 

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

 

Note: In some cases, the Android system will show your action bar tabs as a drop-down list in order to ensure the best fit in the action bar.

 

注意：有些情况下，Android系统将向你显示你的动作栏标签页作为一个下拉列表以确保对动作栏的最佳适合。

 

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

 

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

 

Adding Drop-down Navigation

 

添加下拉导航

 

As another mode of navigation (or filtering) within your activity, the action bar offers a built in drop-down list. For example, the drop-down list can offer different modes by which content in the activity is sorted.

 

作为活动中导航（或过滤）的另一种模式，动作栏提供一个内建的下拉列表。例如，下拉列表可以提供活动中内容排序的不同模式。

 

The basic procedure to enable drop-down navigation is:

 

开启下拉导航的基本过程是：

 

1. Create a SpinnerAdapter that provides the list of selectable items for the drop-down and the layout to use when drawing each item in the list.

 

1. 创建一个SpinnerAdapter，为下拉提供可选择条目的列表以及当绘画列表中每个条目时使用的布局。

 

2. Implement ActionBar.OnNavigationListener to define the behavior that occurs when the user selects an item from the list.

 

2. 实现ActionBar.OnNavigationListener以定义在用户从列表中选中一个条目时所发生的行为。

 

3. Enable navigation mode for the action bar with setNavigationMode(). For example:

 

3. 使用setNavigationMode()为动作栏开启导航模式。例如：

 

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

 

ActionBar actionBar = getActionBar();

actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST);

 

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

 

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

 

Note: You should perform this during your activity's onCreate() method.

 

注意：你应该在你的活动的onCreate()方法中执行这个方法。

 

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

 

4. Set the callback for the drop-down list with setListNavigationCallbacks(). For example:

 

4. 用setListNavigationCallbacks()设置下拉列表的回调。例如：

 

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

 

actionBar.setListNavigationCallbacks(mSpinnerAdapter, mNavigationCallback);

 

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

 

This method takes your SpinnerAdapter and ActionBar.OnNavigationListener.

That's the basic setup. However, implementing the SpinnerAdapter and ActionBar.OnNavigationListener is where most of the work is done. There are many ways you can implement these to define the functionality for your drop-down navigation and implementing various types of SpinnerAdapter is beyond the scope of this document (you should refer to the SpinnerAdapter class reference for more information). However, below is a simple example for a SpinnerAdapter and ActionBar.OnNavigationListener to get you started (click the title to reveal the sample).

 

这个方法传入你的SpinnerAdapter和ActionBar.OnNavigationListener。那是基本设置。然而，实现SpinnerAdapter和ActionBar.OnNavigationListener是大多数工作完成的地方。你可以有很多方法实现这些类定义你的下拉导航的功能，而实现不同的SpinnerAdapter类型已经超出本文的范围（你应该查看SpinnerAdapter类的参考文档以获取更多信息）。然而，下面是一个SpinnerAdapter和ActionBar.OnNavigationListener的简单例子可以让你入门（单击这个标题以显示该示例）

 

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

 

  Example SpinnerAdapter and OnNavigationListener

 

  示例 SpinnerAdapter和OnNavigationListener（注：原文中此处为折叠内容）

 

SpinnerAdapter is an adapter that provides data for a spinner widget, such as the drop-down list in the action bar. SpinnerAdapter is an interface that you can implement, but Android includes some useful implementations that you can extend, such as ArrayAdapter and SimpleCursorAdapter. For example, here's an easy way to create a SpinnerAdapter by using ArrayAdapter implementation, which uses a string array as the data source:

 

SpinnerAdapter是一个适配器，提供微调部件诸如动作栏中的下拉列表的数据。SpinnerAdapter是一个接口类，你可以实现它，但Android包含一些有用的你可以扩展的实现，诸如ArrayAdapter和SimpleCursorAdapter。例如，这里有一个简单的方法，通过使用ArrayAdapter实现创建一个SpinnerAdapter，它使用一个字符串数组作为数据源。

 

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

 

SpinnerAdapter mSpinnerAdapter = ArrayAdapter.createFromResource(this, R.array.action_list,

          android.R.layout.simple_spinner_dropdown_item);

 

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

 

The createFromResource() method takes three parameters: the application Context, the resource ID for the string array, and the layout to use for each list item.

 

createFromResource()方法携带三个参数：应用程序的Context，字符串数组的资源ID，以及用于每个列表条目的布局。

 

A string array defined in a resource looks like this:

 

定义在资源中的字符串数组看起来像这样：

 

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

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <string-array name="action_list">

        <item>Mercury</item>

        <item>Venus</item>

        <item>Earth</item>

    </string-array>

</pre>

 

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

 

The ArrayAdapter returned by createFromResource() is complete and ready for you to pass it to setListNavigationCallbacks() (in step 4 from above). Before you do, though, you need to create the OnNavigationListener.

 

被createFromResource()返回的ArrayAdapter是完整的并且准备好让你传递它到setListNavigationCallbacks()（在上文中的步骤4）。虽然，在你这样做之前，你需要创建OnNavigationListener。

 

Your implementation of ActionBar.OnNavigationListener is where you handle fragment changes or other modifications to your activity when the user selects an item from the drop-down list. There's only one callback method to implement in the listener: onNavigationItemSelected().

 

在你的ActionBar.OnNavigationListener实现中你处理片段的改变或其它对你的活动的修改，当用户从下拉列表中选择一个条目。在监听器中只有一个回调方法要实现：onNavigationItemSelected()。

 

The onNavigationItemSelected() method receives the position of the item in the list and a unique item ID provided by the SpinnerAdapter.

 

onNavigationItemSelected()方法接收列表中条目的位置以及由SpinnerAdapter提供的一个唯一的条目ID。

 

Here's an example that instantiates an anonymous implementation of OnNavigationListener, which inserts a Fragment into the layout container identified by R.id.fragment_container:

 

这里有一个示例，它实例化一个OnNavigationListener的匿名实现，它把一个Fragment插入被R.id.fragment_container标识的布局容器中。

 

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

 

mOnNavigationListener = new OnNavigationListener() {

  // Get the same strings provided for the drop-down's ArrayAdapter

  // 获取给下拉的ArrayAdapter提供的相同字符串

  String[] strings = getResources().getStringArray(R.array.action_list);

 

  @Override

  public boolean onNavigationItemSelected(int position, long itemId) {

    // Create new fragment from our own Fragment class

    // 从我们自己的Fragment类中创建新的片段

    ListContentFragment newFragment = new ListContentFragment();

    FragmentTransaction ft = openFragmentTransaction();

    // Replace whatever is in the fragment container with this fragment

    //  and give the fragment a tag name equal to the string at the position selected

    // 把片段容器中的任何东西替换为这个片段

    // 并且给片段一个标签名称，与选中位置上的字符串相等。

    ft.replace(R.id.fragment_container, newFragment, strings[position]);

    // Apply changes

    // 应用改变

    ft.commit();

    return true;

  }

};

 

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

 

This instance of OnNavigationListener is complete and you can now call setListNavigationCallbacks() (in step 4), passing the ArrayAdapter and this OnNavigationListener.

 

这个OnNavigationListener实例是完整的，而你现在可以调用setListNavigationCallbacks()（在步骤4），传进ArrayAdapter以及这个OnNavigationListener。

 

In this example, when the user selects an item from the drop-down list, a fragment is added to the layout (replacing the current fragment in the R.id.fragment_container view). The fragment added is given a tag that uniquely identifies it, which is the same string used to identify the fragment in the drop-down list.

 

在这个示例中，当用户从下拉列表中选择一个条目时，一个片段被添加到布局（代替R.id.fragment_container视图内的当前片段）。添加的片段被给予一个唯一标识它的标签，它和用于在下拉列表中标识片段所使用的字符串相同。

 

Here's a look at the ListContentFragment class that defines each fragment in this example:

 

这里可以看一下在这个示例中定义每个片段的ListContentFragment类：

 

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

 

public class ListContentFragment extends Fragment {

    private String mText;

 

    @Override

    public void onAttach(Activity activity) {

      // This is the first callback received; here we can set the text for

      // the fragment as defined by the tag specified during the fragment transaction

      // 这是首先接收到的回调；这里我们可以设置

      // 片段的文本为通过在片段事务期间指定的标签定义的那样

      super.onAttach(activity);

      mText = getTag();

    }

 

    @Override

    public View onCreateView(LayoutInflater inflater, ViewGroup container,

            Bundle savedInstanceState) {

        // This is called to define the layout for the fragment;

        // we just create a TextView and set its text to be the fragment tag

        // 它被调用以定义片段的布局；

        // 我们只是创建一个TextView并设置它的文本为片段的标签

        TextView text = new TextView(getActivity());

        text.setText(mText);

        return text;

    }

}

 

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

 

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

 

Styling the Action Bar

 

风格化动作栏

 

If you've implemented a custom design for the widgets in your application, you might also want to redesign some of the action bar to match your app design. To do so, you need to use Android's style and theme framework to restyle the action bar using special style properties.

 

如果你在你的应用程序中为部件实现了一个自定义设计，那么你还可能希望重新设计一些动作栏以匹配你的应用设计。为了做到那样，你需要使用Android的风格和主题框架以使用特定风格属性重新风格化动作栏。

 

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

 

Note: In order for background images to change appearance depending on the current button state (selected, pressed, unselected), the drawable resource you use must be a state list drawable.

 

注意：为了让背景图片根据当前的按钮状态（选择，按下，不选择）改变外观，你使用的可绘画对象资源必须是一个状态列表可绘画对象。

 

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

 

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

 

Caution: For all background drawables you provide, be sure to use Nine-Patch drawables to allow stretching. The Nine-Patch image should be smaller than 40px tall and 30px wide (for the mdpi asset).

 

警告：对于你提供的所有背景可绘画对象，请确保使用九宫格绘画对象以允许拉伸。九宫格图片应该小于40px高和30px宽（对于mdpi资源）（注：px是pixel的缩写，即像素，mdpi是medium dots per inch的缩写，即中等密度）

 

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

 

General appearance

 

通用外观

 

* android:windowActionBarOverlay

 

Declares whether the action bar should overlay the activity layout rather than offset the activity's layout position (for example, the Gallery app uses overlay mode). This is false by default.

 

声明动作栏是否应该叠加活动布局而非偏移活动的布局位置（例如，画廊应用使用叠加模式）。默认为false。

 

Normally, the action bar requires its own space on the screen and your activity layout fills in what's left over. When the action bar is in overlay mode, your activity layout uses all the available space and the system draws the action bar on top. Overlay mode can be useful if you want your content to keep a fixed size and position when the action bar is hidden and shown. You might also like to use it purely as a visual effect, because you can use a semi-transparent background for the action bar so the user can still see some of your activity layout behind the action bar.

 

通常，动作栏在屏幕上需要它自己的空间而你的活动布局填充余下的所有地方。当动作栏处于叠加模式时，你的活动布局使用所有可用的空间而系统在上方绘画动作栏。叠加模式可能是有用的，如果你希望你的内容在动作栏被隐藏和显示时保持固定的大小和位置，你还可能喜欢使用它单纯作为一种可视化效果，因为你可以为动作栏使用一种半透明背景使用户仍旧可以看到动作栏后面你的活动布局的一些东西。

 

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

 

Note: The Holo theme families draw the action bar with a semi-transparent background by default. However, you can modify it with your own styles and the DeviceDefault theme on different devices might use an opaque background by default.

 

注意：Holo主题族默认用半透明背景绘画动作栏。然而，你可以用你自己的样式主题修改它，而不同设备上的DeviceDefault主题默认使用一种不透明的背景。

 

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

 

When overlay mode is enabled, your activity layout has no awareness of the action bar laying on top of it. So, you must be careful not to place any important information or UI components in the area overlayed by the action bar. If appropriate, you can refer to the platform's value for actionBarSize to determine the height of the action bar, by referencing it in your XML layout. For example:

 

当叠加模式开启时，你的活动布局还没有意识到动作栏位于它上方。所以，你必须小心不要放置任何重要信息或用户界面组件在被动作栏叠加的区域。如果合适的话，你可以通过在你的XML布局中引用平台的actionBarSize值，确定动作栏的高度。例如：

 

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

 

<SomeView

    ...

    android:layout_marginTop="?android:attr/actionBarSize" />

 

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

 

You can also retrieve the action bar height at runtime with getHeight(). This reflects the height of the action bar at the time it's called, which might not include the stacked action bar (due to navigation tabs) if called during early activity lifecycle methods. To see how you can determine the total height at runtime, including the stacked action bar, see the TitlesFragment class in the Honeycomb Gallery sample app.

 

你还可以在运行时用getHeight()取得动作栏的高度。它反映它被调用时动作栏的高度，可能不包括堆叠的动作栏（由导航标签页引起），如果它在早期的活动生命周期方法期间被调用。如果想看看你可以如何在运行时决定总体高度，包括被堆叠的动作栏在内，请参见Honeycomb画廊示例应用中的TitlesFragment类。

 

Action items

 

动作条目

 

* android:actionButtonStyle

 

Defines a style resource for the action item buttons.

 

为动作条目按钮定义一个风格资源。

 

* android:actionBarItemBackground

 

Defines a drawable resource for each action item's background. (Added in API level 14.)

 

为每个动作条目的背景定义一个可绘画资源。（在API级别14中添加。）

 

* android:itemBackground

 

Defines a drawable resource for each overflow menu item's background.

 

为每个溢出菜单条目的背景定义一个可绘画资源。

 

* android:actionBarDivider

 

Defines a drawable resource for the divider between action items. (Added in API level 14.)

 

为动作条目之间的分割器定义一个可绘画资源（在API级别14中添加。）

 

* android:actionMenuTextColor

 

Defines a color for text that appears in an action item.

 

为显示在动作条目的文本定义一种颜色。

 

* android:actionMenuTextAppearance

 

Defines a style resource for text that appears in an action item.

 

为显示在动作条目中的文本定义一个样式资源。

 

* android:actionBarWidgetTheme

 

Defines a theme resource for widgets that are inflated into the action bar as action views. (Added in API level 14.)

 

为解压进动作栏作为动作视图的部件定义一个主题资源。（在API级别14中添加。）

 

Navigation tabs

 

导航标签页

 

* android:actionBarTabStyle

 

Defines a style resource for tabs in the action bar.

 

为动作栏内的标签页定义一个风格资源。

 

* android:actionBarTabBarStyle

 

Defines a style resource for the thin bar that appears below the navigation tabs.

 

为显示在导航标签页下的薄栏定义一个风格资源。

 

* android:actionBarTabTextStyle

 

Defines a style resource for text in the navigation tabs.

 

为导航标签页中的文本定义一个风格资源

 

Drop-down lists

 

下拉列表

 

* android:actionDropDownStyle

 

Defines a style for the drop-down navigation (such as the background and text styles).

 

为下拉导航定义一个样式（诸如背景和文本风格）。

 

For example, here's a file that defines a few custom styles for the action bar:

 

例如，这里有一个文件，为动作栏定义一些自定义样式：

 

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

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <!-- the theme applied to the application or activity -->

    <!-- 应用到应用程序或活动的主题 -->

    <style name="CustomActivityTheme" parent="@android:style/Theme.Holo">

        <item name="android:actionBarTabTextStyle">@style/CustomTabTextStyle</item>

        <item name="android:actionBarDivider">@drawable/ab_divider</item>

        <item name="android:actionBarItemBackground">@drawable/ab_item_background</item>

    </style>

 

    <!-- style for the action bar tab text -->

    <!-- 动作栏标签文本的样式 -->

    <style name="CustomTabTextStyle">

        <item name="android:textColor">#2456c2</item>

    </style>

</resources>

 

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

 

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

 

Note: Be certain that your theme declares a parent theme in the <style> tag, from which it inherits all styles not explicitly declared by your theme. When modifying the action bar, using a parent theme is important so that you can simply override the action bar styles you want to change without re-implementing the styles you want to leave alone (such as text appearance or padding in action items).

 

注意：请确定你的主题在<style>标签中声明一个父主题，从这里它继承所有没有显式被你的主题声明的风格。当修改动作栏时，使用一个父主题是很重要的，它使你可以简单地覆盖你想改变的动作栏风格而不必重新实现你希望单独保留的风格（诸如文本外观或动作条目中的内边距）。

 

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

 

You can apply your custom theme to the entire application or to individual activities in your manifest file like this:

 

你可以在你的清单文件中应用你的自定义主题到整个应用程序或单个活动，就像这样：

 

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

 

<application android:theme="@style/CustomActivityTheme"

             ... />

 

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

 

For more information about using style and theme resources in your application, read Styles and Themes.

 

想获取更多关于在你的应用程序内使用风格和主题资源的信息，请阅读风格和主题。

 

Advanced styling

 

高级风格化

 

If you need more advanced styling for the action bar than is available with the properties above, you can include android:actionBarStyle and android:actionBarSplitStyle in your activity's theme. Each of these specifies another style that can define various properties for the action bar, including different backgrounds with android:background, android:backgroundSplit, and android:backgroundStacked. If you override these action bar styles, be sure that you define a parent action bar style such as Widget.Holo.ActionBar.

 

如果你需要比起上面使用的可用属性更多的动作栏高级风格化，你可以在你的活动的主题中包含android:actionBarStyle和android:actionBarSplitStyle。它们各自指定另一种风格，可以为动作栏定义不同的属性，包括带有android:background，android:backgroundSplit和android:backgroundStacked的不同背景。如果你覆盖这些动作栏风格，请确保你定义一个父动作栏风格诸如Widget.Holo.ActionBar。

 

For example, if you want to change the action bar's background, you could use the following styles:

 

例如，如果你希望改变动作栏的背景，那么你应该使用如下风格：

 

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

 

<?xml version="1.0" encoding="utf-8"?>

<resources>

    <!-- the theme applied to the application or activity -->

    <!-- 应用到应用程序或活动的主题 -->

    <style name="CustomActivityTheme" parent="@android:style/Theme.Holo">

        <item name="android:actionBarTabTextStyle">@style/customTabTextStyle</item>

        <!-- other activity and action bar styles here -->

        <!-- 这里是其它活动和动作栏的样式 -->

    </style>

 

    <!-- style for the action bar, simply to change the background -->

    <!-- 动作栏的样式，简单地改变背景 -->

    <style parent="@android:style/Widget.Holo.ActionBar">

        <item name="android:background">@drawable/ab_background</item>

        <item name="android:backgroundSplit">@drawable/ab_background</item>

    </style>

</resources>

 

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

 

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 - 17 Nov 2011 21:59

 

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

 

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来源许可证描述的条款进行修改）