Android---App Widget（一）

本文译自：http://developer.android.com/guide/topics/appwidgets/index.html

App Widgets是一些较小的应用程序窗口，它们能够被嵌入到其他的应用程序中（如主屏窗口），并且能够接受周期性的更新。这些小窗口可以作为用户界面中的一个可视部件，而且这些可视部件也可以带有自己的App Widget提供器。能够持有其他App Widgets的组件被叫做App Widget的持有者。以下截图是Music App Widget。

本文介绍如何发布一个使用App Widget提供器的App Widget。对于创建自己的AppWidgetHost来持有AppWidgets，请看AppWidget Host。

Widget设计

对于如何设计应用可视部件，请阅读Widget设计指南。

基础

以下是创建一个App Widget所要了解的基本内容：

1. AppWidgetProviderInfo对象

这个对象用于描述App Widget的元数据，如布局、更新周期以及AppWidgetProvider类等。它应该在XML文件中定义。

2. 实现AppWidgetProder类

这个类定义了一些App Widget所带有的基本的、基于广播事件的编程接口方法，通过这个类，当App Widget被更新、启用、禁用和删除时，你会收到广播事件。

3. 窗口布局

在XML中给App Widget定影初始化布局。

另外，你还可以实现一个用于App Widget配置的Activity。这是一个可选的Activity，它会在用户添加该App Widget时启动，并允许用户在创建是编辑App Widget的设置。

以下介绍如何创建App Widget。

在清单中声明一个AppWidget

首先，在你的应用程序的AndroidManifest.xml中声明AppWidgetProvider类，例如：

<receiverandroid:name="ExampleAppWidgetProvider">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

其中的<receiver>元素需要设置android:name属性，它会指定App Widget所使用的AppWidgetProvider类。

其中的<intent-filter>元素必须要包含一个带有android:name属性的<action>元素。这个属性指定AppWidgetProvider对象会接收ACTION_APPWIDGET_UPDATE类型的广播。这是需要你明确声明的唯一的广播。必要时，AppWidgetManager会自动的把所有其他的App Widget广播发送给AppWidgetProvider。

<meta-data>元素指定了AppWidgetProviderInfo对象所要求的资源，以及以下必要的属性：

android:name-指定元数据名称。使用android.appwidget.provider作为AppWidgetProviderInof的描述符来标识数据。

android:resource---指定AppWidgetProviderInfo资源的位置。

添加AppWidgetProviderInfo元数据

AppWidgetProviderInfo定义了App Widget的基本特点，例如它的最小布局尺寸、初始化布局资源、如何更新App Widget，以及创建时启动一个用于设置的Activity（可选）等。使用一个<appwidget-provider>元素在一个XML资源中定义AppWidgetProviderInfo对象，并把该资源保存在工程的res/xml文件夹中。

例如：

<appwidget-providerxmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:updatePeriodMillis="86400000"
    android:previewImage="@drawable/preview"
    android:initialLayout="@layout/example_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigure"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen|keyguard"
    android:initialKeyguardLayout="@layout/example_keyguard">
</appwidget-provider>

以下是<appwidget-provider>元素属性的概要介绍

minWidth和minHeight属性值指定了AppWidget默认所要占据的空间大小。位于主屏窗口中的App Widget的尺寸是基于主屏中一个网格所定义的高度和宽度。如果App Widget的最小宽度或高度值跟网格的尺寸不匹配，那么App Widget的尺寸会四舍五入到最接近的单元格尺寸。有关App Widget尺寸的更多信息，请看AppWidget 设计指南。

注意：如果要让你的App Widget适应更多的设备，那么它的最小尺寸就不应该大于4x4单元格。

minResizeWidth和minResizeHeight属性指定了AppWidget的绝对最小尺寸。这两个值应该在不能确定App Widget尺寸的情况下使用，或者不使用。这个两个属性会允许用户重新调整Widget的尺寸，它们的值可以比minWidth和minHeight属性定义的默认的Widget尺寸值小。它们在Android3.1中被引入。

关于调整App Widget尺寸的更多信息，请看App Widget设计指南。

updatePeriodMillis属性定义了AppWidget框架的更新频率，App Widget通过调用onUpdate()回调方法来请求来自AppWidgetProvider的更新。实际的更新并不保证准确的按照这个值所定义的时间周期发生，并且我们建议尽可能减少更新频率---1小时最好不要超过一次，以便节省电池电量。你也可以通过配置允许用户来调整更新频率。有些人可能想要每隔15分钟看一次股票报价，也可能一天只看四次。

注意：如果设备在休眠时发生了更新，那么为了执行更新，设备将会被唤醒。如果每小时的更新不多于1次，那么就不会对电池的寿命造成显著的影响。但是，如果你要频繁的并且（或者）在设备休眠时不需要更新，那么你可以使用闹钟来代替，它不会唤醒设备。使用AlarmManager对象，给闹钟设置一个你的AppWidgetProvider能够接收的Intent对象。设置的闹钟类型既可以是ELAPSED_REALTIME也可以是RTC，它们只会在设备清醒的时候发送闹钟。然后把updatePeriodMillis属性设置为0.

 

initialLayout属性指定了定义App Widget布局的布局资源。

configure属性定义了用户添加App Widget时要启动的Activity，以便用于设置AppWidget属性。这是可选的。

previewImage属性指定了配置以后的App Widget的外观的预览图片，这样用户在选择该App Widget时就可以先看到外观。如果没有设置这个属性，那么用户就只会看到应用程序的启动图标。这个属性对应了AndroidManifest.xml文件中<receiver>元素中的android:previewImage属性。更多的使用previewImage讨论，请看设置预览图片。这个属性在Android3.0中被引入。

autoAdvanceViewId属性指定了AppWidget的子View的ID，它应该是有Widget的持有者自动生成的，它在Android3.0中被引入。

resizeMode属性指定调整Widget尺寸的规则。使用这个属性使得主屏Widget 可以调整尺寸。用户按住一个Widget就会显示一个调整尺寸的手柄，然后水平或垂直拖动手柄来改变Widget的尺寸。这个属性值包括：horizontal、vertical、none。要同时调整水平和垂直的尺寸，可以把属性值设置为“horizontal|vertical”。这个属性在Android3.1中被引入。

minResizeHeight属性指定了Widget可以调整的最小的高度(单位：dps)。如果它的值比minHeight属性值大，或者垂直尺寸不可调整，那么这个属性无效。该属性在Android4.0中被引入。

minResizeWidth属性指定了Widget可以调整的最小的宽度（单位：dps）。如果它的值比minWidth属性值大，或者水平尺寸不可调整，那么这个属性无效。该属性在Android4.0中被引入。
widgetCategory属性声明了你的App Widget是否能够显示在主屏或锁定屏幕上，或者是在这两个屏幕上都显示。它属性值包括：home_screen、keyguard。要让Widget同时显示在这种屏幕上，就要确保Widget类遵守它们的设计指南。更多的信息，请看“让App Widget能够显示在锁屏上”。默认值是“home_screen”。该属性在Android4.2中被引入。

InitialKeyguardLayout属性指向一个布局资源，这个布局资源定义了锁屏的App Widget布局。这个属性的工作方式跟android:initialLayout属性一样，它提供了一个能够立即显示的布局，直到App Widget初始化完成，并能够更新布局。该属性在Android4.2中被引入。

有关<appwidget-provider>元素所能接收的更多属性信息，请看AppWidgetProviderInfo类。