Android API Guides---App Widget Host

应用的Widget主机
大多数Android设备上可用的Andr​​oid主屏幕允许用户嵌入应用小工具，以便快速访问的内容。如果你正在构建一个家庭更换或类似的应用程序，也可以允许用户通过实现AppWidgetHost嵌入应用程序部件。这不是大多数应用程序都不会需要做的事情，但如果你正在创建您自己的主机，它了解合同义务的主机隐含同意是非常重要的。

本文件的重点参与实施定制AppWidgetHost的责任。对于如何实现一个AppWidgetHost示例，请参见为Android主屏幕启动的源代码。

这里是参与实施定制AppWidgetHost关键类和概念的概述：

应用的Widget HOST-的AppWidgetHost提供与AppWidget服务的应用程序，如主屏幕，希望嵌入应用小部件在其UI交互。一个AppWidgetHost必须有一个ID，它是主机自己的包中是唯一的。此ID在跨越主机的所有使用持久性。该ID通常是在应用程序中指定一个硬编码值。
应用小工具ID-每个应用插件实例是在结合的时间分配了一个唯一的ID（见bindAppWidgetIdIfAllowed（），更详细地在装订应用程序窗口小部件所讨论的）。唯一ID是通过使用allocateAppWidgetId（）主机获得。该ID是横跨插件，即的寿命持久，直到它从主机中删除。任何特定的主机的状态（例如大小和小部件的位置）应当由主机包被持久并与该应用微件ID相关联。
应用程式的widget主机取景AppWidgetHostView可以被认为是一帧，该插件是包裹在每当需要将其显示出来。应用程式插件每小部件是由主机充气时间分配给AppWidgetHostView。
选项​​Bundle-该AppWidgetHost使用选项束将信息传达给所述AppWidgetProvider如何正在显示微件（例如，尺寸范围，以及是否该窗口小部件上的锁定屏幕或主屏幕）。该信息允许AppWidgetProvider的基础上如何以及在哪里显示定制Widget的内容和外观。您可以使用updateAppWidgetOptions（）和updateAppWidgetSize（）来修改应用程序widget的包。这两种方法触发一个回调至AppWidgetProvider。
结合应用小工具


当用户将某个应用插件到主机时，发生所谓的装订处理。结合是指一种特定的应用微件ID，以一个特定的主机和一个特定AppWidgetProvider相关联。有实现这一目标，取决于什么版本的Andr​​oid您的应用程序上运行的不同方式。


在Android 4.0和更低的结合应用小工具

在运行Android 4.0版和更低的设备，用户通过系统的活动，允许用户选择一个小部件添加应用程序部件。这含蓄地做了权限检查，也就是说，通过将应用程序窗口小部件，用户被隐性授予权限，以您的应用程序小部件添加到主机。这里是示出该方法中，从原来的启动器所采取的示例。在这个片段中，一个事件处理程序调用startActivityForResult（）在响应用户操作的请求代码REQUEST_PICK_APPWIDGET：

private static final int REQUEST_CREATE_APPWIDGET = 5;private static final int REQUEST_PICK_APPWIDGET = 9;...public void onClick(DialogInterface dialog, int which) {    switch (which) {    ...        case AddAdapter.ITEM_APPWIDGET: {            ...            int appWidgetId =                     Launcher.this.mAppWidgetHost.allocateAppWidgetId();            Intent pickIntent =                     new Intent(AppWidgetManager.ACTION_APPWIDGET_PICK);            pickIntent.putExtra                    (AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);            ...            startActivityForResult(pickIntent, REQUEST_PICK_APPWIDGET);            break;    }    ...}

当系统活动结束时，它返回与用户选择的应用小工具，你的活动的结果。在下面的例子中，该活动通过调用广告AppWidget（）添加应用程序部件响应：

public final class Launcher extends Activity         implements View.OnClickListener, OnLongClickListener {    ...    @Override    protected void onActivityResult(int requestCode, int resultCode, Intent data) {        mWaitingForResult = false;        if (resultCode == RESULT_OK && mAddItemCellInfo != null) {            switch (requestCode) {                ...                case REQUEST_PICK_APPWIDGET:                    addAppWidget(data);                    break;                case REQUEST_CREATE_APPWIDGET:                    completeAddAppWidget(data, mAddItemCellInfo, !mDesktopLocked);                    break;                }        }         ...    }}

该方法添加AppWidget（）检查是否应用程序部件需要它添加之前配置：

void addAppWidget(Intent data) {    int appWidgetId = data.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, -1);    String customWidget = data.getStringExtra(EXTRA_CUSTOM_WIDGET);    AppWidgetProviderInfo appWidget =             mAppWidgetManager.getAppWidgetInfo(appWidgetId);    if (appWidget.configure != null) {        // Launch over to configure widget, if needed.        Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_CONFIGURE);        intent.setComponent(appWidget.configure);        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);        startActivityForResult(intent, REQUEST_CREATE_APPWIDGET);    } else {        // Otherwise, finish adding the widget.    }}

有关配置的详细讨论，请参阅创建应用程序窗口小部件配置活动。
一旦应用小工具已准备就绪，下一步就是做它添加到工作区的实际工作。原来发射使用的方法称为完全加AppWidget（）来做到这一点。
在Android4.1及更高的结合应用小工具
搭载Android 4.1增加了API，用于一个更精简的绑定过程。这些API也有可能使一台主机绑定提供自定义UI。要使用此改进方法，您的应用程序必须申报在其清单中BIND_APPWIDGET权限：

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

但是，这仅仅是第一步。在运行时，用户必须明确授予权限，您的应用程序，使其能够应用小部件添加到主机。要测试你的应用程序是否有权限新增的小工具，可以使用bindAppWidgetIdIfAllowed（）方法。如果bindAppWidgetIdIfAllowed（）返回false，您的应用程序必须显示一个对话框，提示用户授予权限（“允许”或“总是允许”，以涵盖所有未来的应用小工具添加）。这段代码提供了如何显示对话框的例子：

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);// This is the options bundle discussed aboveintent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

主机也必须检查用户是否补充说，需要配置一个应用程序部件。有关此主题的更多讨论，请参阅创建应用程序窗口小部件配置活动。
主持人职责
什么版本你定位？
您实现您的主机使用的方法应该取决于你的目标是什么Android版本。许多本节所述的功能在3.0或更高版本进行了介绍。例如：
Android 3.0的（API等级11）介绍了小部件自动推进的行为。
Android的3.1（API等级12）引入了调整部件的能力。
搭载Android 4.0（API等级15）引入该把责任在主机上管理填充填充政策的改变。
搭载Android 4.1（API等级16）增加了一个API，允许小部件供应商，以获取有关在其控件实例被托管环境的更多详细信息。
Android的4.2（API等级17）推出期权包和bindAppWidgetIdIfAllowed（）方法。还引入了锁屏小部件。
如果你的目标早期设备，参考原始启动作为一个例子。
插件开发者可以指定使用AppWidgetProviderInfo元数据窗口小部件的一些配置设置。这些配置选项，在下面更详细讨论的，可以通过从与小窗口提供者关联的AppWidgetProviderInfo对象主机进行检索。
无论你的目标了Android版本，所有主机具有以下职责：
当添加窗口小部件，则必须按照上述分配部件ID。您还必须确保当一个小部件从主机中删除，你可以调用deleteAppWidgetId（）来释放小部件ID。
当添加窗口小部件，可以肯定如果存在推出配置活动，如从配置活动更新应用程序窗口小部件描述。这是许多应用小部件的必要步骤可以正确显示前。
每一个应用程序窗口小部件指定的dps的最小宽度和高度，如AppWidgetProviderInfo定义元数据（采用了android：了minWidth和android：了minHeight）。确保小部件至少有这么多的dps布局。例如，许多主机对齐栅格图标和窗口小部件。在这种情况下，在默认情况下，主机应使用满足了minWidth和了minHeight约束单元的最小数量添加的应用部件。
除了上面列出的要求，具体版本的平台引入放置在主机上新的责任功能。这些将在以下各节中描述。
Android 3.0的
Android 3.0的（API等级11）介绍了一个小工具，指定autoAdvanceViewId（）的能力。此视图ID应指向一个可前进，如StackView或AdapterViewFlipper的一个实例。这表明主机应该呼吁这种观点提前（）的间隔认为适当的主机（考虑到是否有意义推进小部件，例如，主机可能不希望，如果它提前一个小部件是另一个页上，或如果屏幕被关闭）。
Android版3.1
Android的3.1（API等级12）引入了调整部件的能力。一个小部件可以指定它使用Android是可调整大小：在AppWidgetProviderInfo元resizeMode属性，并说明它是否支持水平和/或垂直大小调整。在Android 4.0的（API级别14）介绍，小部件也可以指定一个机器人：minResizeWidth和/或Android：minResizeHeight。
它是主机的责任，这使该插件被水平和/或垂直地调整，由插件规定的。这说明它是可以调整大小可以调整任意大，但不应该比大小由Android规定值小的部件：minResizeWidth和android：minResizeHeight。有关示例实现，请参阅AppWidgetResizeFrame中的launcher2。
Android 4.0的
搭载Android 4.0（API等级15）引入该把责任在主机上管理填充填充政策的改变。作为4.0，应用小部件不再包括自己的填充。相反，系统添加填充每个部件，基于当前屏幕的特性。这导致一个更均匀，在网格部件的一致呈现。为了帮助该主机的应用程序窗口小部件，该平台提供的方法getDefaultPaddingForWidget应用程序（）。计算细胞的数量分配给widget时应用程序可以调用此方法来获取系统定义的填充和解释它。
搭载Android 4.1
搭载Android 4.1（API等级16）增加了一个API，允许小部件供应商，以获取有关在其控件实例被托管环境的更多详细信息。具体地，主机暗示至约在正被显示的窗口小部件的尺寸小窗口提供者。这是主机的责任提供这种规模的信息。
主机通过updateAppWidgetSize提供该信息（）。的大小指定为在DPS的最小和最大宽度/高度。一个范围（而不是一个固定的大小）的原因是因为一个小窗口的宽度和高度可以与取向发生变化。你不希望主机必须更新其所有的旋转部件，因为这可能会导致严重的系统运行缓慢。这些值应从前的插件来更新被放置，所述插件被调整大小的任何时间，任何时间发射膨胀用于在给定引导在第一时间（作为值不跨越启动持续）的部件。
Android 4.2版
对于选择在捆绑绑定时指定的Andr​​oid 4.2（API等级17）增加的能力。这是指定的应用程序插件选项，包括大小的理想方法，因为它给了AppWidgetProvider直接访问数据的选项在第一次更新。这可以通过使用该方法bindAppWidgetIdIfAllowed（）来实现。有关此主题的更多讨论，请参阅绑定应用程序部件。
Android 4.2版还引入了锁屏小部件。当主机在锁定屏幕上的小部件，主机必须指定应用程序窗口小部件选项包内该信息（AppWidgetProvider可以使用这些信息来适当方式进行样式设置）。要指定一个widget作为锁屏插件，使用updateAppWidgetOptions（），并包括与价值WIDGET_CATEGORY_KEYGUARD领域OPTION_APPWIDGET_HOST_CATEGORY。此选项默认为WIDGET_CATEGORY_HOME_SCREEN，所以也没有明确要求，设置本作的主屏幕主机。
请确保您的主机只增加了应用小工具，适合你的应用程序，例如，如果你的主机是主屏幕，确保了android：在AppWidgetProviderInfo元widgetCategory属性包括旗WIDGET_CATEGORY_HOME_SCREEN。同样，对于锁屏，确保字段包括标志WIDGET_CATEGORY_KEYGUARD。有关此主题的更多讨论，请参阅锁屏启用应用程序的窗口小部件。