Android之AppWidget桌面小部件开发

做需求中遇到AppWidget相关知识，所以学习了官方文档和网上中文材料，并简单学习做了一个相关的Demo。

• Widget了解
• Widget主要组件
• 创建自定义Widget

---

Widget了解

App Widget是应用程序窗口小部件（Widget）是微型的应用程序视图，它可以被嵌入到其它应用程序中（比如桌面）并接收周期性的更新。你可以通过一个App Widget Provider来发布一个Widget

Widget组成

• AppWidgetProviderInfo
  描述一个App Widget元数据，比如App Widget的布局，更新频率，这个应该在XML里定义

• AppWidgetProvider
  Android中提供的用于实现桌面小工具的类，其本质是一个广播，即BroadcastReceiver，用它来管理widget接收到广播后做出对应的响应处理

• widget_layout
  用来设置widget的相关布局，但是Widget并不支持所有的布局和控件，这点需要注意。

创建一个Widget

建立一个Widget示例，要求Widget能被添加到主屏中，widget包含3个成分：文本、按钮和图片。文本要求：显示提示信息；按钮要求：点击按钮，弹出一个Toast提示框；图片要求：每个5秒随机更新一张图片

1.在修改Manifest中配置，在Manifest中注册AppWidgetProvider和负责发送更新图片广播的Service

 <application        android:allowBackup="true"        android:icon="@drawable/ic_launcher"        android:label="@string/app_name"        android:theme="@style/AppTheme" >        <!-- 声明widget对应的AppWidgetProvider -->        <receiver android:name=".ExampleAppWidgetProvider" >            <intent-filter>                <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />                <action android:name="com.leeds.widget.UPDATE_ALL"/>            </intent-filter>            <meta-data android:name="android.appwidget.provider"                android:resource="@xml/example_appwidget_info" />        </receiver>        <service android:name=".ExampleAppWidgetService" >            <intent-filter>                <action android:name="android.appwidget.action.EXAMPLE_APP_WIDGET_SERVICE" />            </intent-filter>        </service>    </application>

android.appwidget.action.APPWIDGET_UPDATE，必须要显示声明的action！因为所有的widget的广播都是通过它来发送的；要接收widget的添加、删除等广播，就必须包含它。
com.leeds.widget.UPDATE_ALL，是自定义的action，是为了接收服务所发送的更新图片的广播。
ExampleAppWidgetService 是用于更新widget中的图片的服务。
android.appwidget.action.EXAMPLE_APP_WIDGET_SERVICE 用于启动服务的action

2.编辑AppWidgetProviderInfo对应的资源文件

<?xml version="1.0" encoding="utf-8"?><appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"    android:minWidth="180dp"    android:minHeight="180dp"    android:previewImage="@mipmap/ic_note"    android:initialLayout="@layout/activity_main"    android:resizeMode="horizontal|vertical"    android:widgetCategory="home_screen"></appwidget-provider>

文件中各个属性意义如下

• minWidth 和minHeight
  它们指定了App Widget布局需要的最小区域。缺省的App Widgets所在窗口的桌面位置基于有确定高度和宽度的单元网格（cell）中。如果App Widget的最小长度或宽度和这些网格单元的尺寸不匹配，那么这个App Widget将上舍入（上舍入即取比该值大的最接近的整数——译者注）到最接近的单元尺寸。
  注意：app widget的最小尺寸，不建议比 “4x4” 个单元格要大，基于适配性考虑
  

• minResizeWidth 和 minResizeHeight
  它们属性指定了 widget 的最小绝对尺寸。也就是说，如果 widget 小于该尺寸，便会因为变得模糊、看不清或不可用。 使用这两个属性，可以允许用户重新调整 widget 的大小，使 widget 的大小可以小于 minWidth 和 minHeight。
  Tip：
  当 minResizeWidth 的值比 minWidth 大时，minResizeWidth 无效；当 resizeMode 的取值不包括 horizontal 时，minResizeWidth 无效。minResizeHeight对应同理。

• updatePeriodMillis
  它定义了 widget 的更新频率。实际的更新时机不一定是精确的按照这个时间发生的。建议更新尽量不要太频繁，最好是低于1小时一次。 或者可以在配置 Activity 里面供用户对更新频率进行配置。 实际上，当updatePeriodMillis的值小于30分钟时，系统会自动将更新频率设为30分钟！

  这是出于对电池的保护，因为如果当更新时机到达时设备正在休眠，那么就会唤醒设备以执行更新，频繁唤醒对电池寿命有影响。因此当需要较频繁的更新时，可以使用基于alarm的更新来代替widget自身的刷新机制，将 alarm 类型设置为 ELAPSED_REALTIME 或 RTC，将不会唤醒休眠的设备，同时请将 updatePeriodMillis 设为 0。或者使用service，AlarmManager，Timer等方式。

• initialLayout
  指向 widget 的布局资源文件

• configure
  可选属性，定义了 widget 的配置 Activity。如果定义了该项，那么当 widget 创建时，会自动启动该 Activity。

• previewImage
  指定预览图，该预览图在用户选择 widget 时出现，如果没有提供，则会显示应用的图标。该字段对应在 AndroidManifest.xml 中 receiver 的 android:previewImage 字段。由 Android 3.0 引入。

• autoAdvanceViewId
  指定一个子view ID，表明该子 view 会自动更新。在 Android 3.0 中引入。

• resizeMode
  指定了 widget 的调整尺寸的规则。可取的值有: “horizontal”, “vertical”, “none”。”horizontal”意味着widget可以水平拉伸，“vertical”意味着widget可以竖值拉伸，“none”意味着widget不能拉伸；默认值是”none”。Android 3.1 引入。

• widgetCategory
  指定了 widget 能显示的地方：能否显示在 home Screen 或 lock screen 或 两者都可以。它的取值包括：”home_screen” 和 “keyguard”。Android 4.2 引入。
  tip：
  只有低于5.0的Android系统可以将widget添加到lock screen，5.0及5.0以上的系统规定widget只有添加到home screen有效。

• initialKeyguardLayout
  指向 widget 位于 lockscreen 中的布局资源文件。Android 4.2 引入。

3.编辑widget的布局文件

<LinearLayout    xmlns:android="http://schemas.android.com/apk/res/android"    android:layout_width="match_parent"    android:layout_height="match_parent"    android:orientation="vertical" >    <LinearLayout        android:layout_width="wrap_content"        android:layout_height="wrap_content"        android:layout_gravity="center"        android:orientation="horizontal" >        <TextView            android:layout_width="wrap_content"            android:layout_height="wrap_content"            android:text="HomeScreen Widget"            android:textColor="#242424"/>        <Button            android:id="@+id/btn_show"            android:layout_width="wrap_content"            android:layout_height="wrap_content"            android:text="Show" />    </LinearLayout>    <ImageView        android:id="@+id/iv_show"        android:layout_width="wrap_content"        android:layout_height="wrap_content"        android:layout_gravity="center"/></LinearLayout>

要注意的是widget并不支持所有的布局和控件，而是仅支持Android布局和控件的一个子集。具体支持的布局可以查看官方文档。

4.编辑AppWidgetProvider的实现类

当创建第一个widget到桌面时，执行onEnable，启动发送更新图片广播服务，当删除最后一个widget时，终止该服务；
每添加一个widget调用一次onUpdate，讲对应widget的id添加到widgetSet中；
onReceive()中，处理两个广播：
(1) 更新桌面的widget 以及 响应按钮点击广播。当收到ACTION_UPDATE_ALL广播时，调用updateAllAppWidgets()来更新所有的widget。
(2) 当收到的广播的categery为Intent.CATEGORY_ALTERNATIVE，并且scheme为BUTTON_SHOW时，对应是按钮点击事件。按钮的监听是在updateAllAppWidgets()中注册的。

public class ExampleAppWidgetProvider extends AppWidgetProvider {    private static final String TAG = "ExampleWidgetProvider";    private boolean DEBUG = false;    //启动service服务对应的action    private final Intent EXAMPLE_SERVICE_INTENT = new Intent("android.appwidget.action.EXAMPLE_APP_WIDGET_SERVICE");    //更新widget的广播对应的action    private final String ACTION_UPDATE_ALL = "com.example.user.widgettest.UPDATE_ALL";    //保存widget的id的hashset，每新建一个widget都会为该widget分配一个id    private static Set idsSet = new HashSet<>();    //按钮信息    private static final int BUTTON_SHOW = 1;    //图片数组    private static final int[] ARR_IMAGES = {            R.mipmap.sample_0,            R.mipmap.sample_1,            R.mipmap.sample_2,            R.mipmap.sample_3,            R.mipmap.sample_4,            R.mipmap.sample_5,            R.mipmap.sample_6,            R.mipmap.sample_7,};    @Override    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {        // 每次 widget 被创建时，对应的将widget的id添加到set中        for (int appWidgetId : appWidgetIds) {            idsSet.add(Integer.valueOf(appWidgetId));        }    }    @Override    public void onEnabled(Context context) {        // 在第一个 widget 被创建时，开启服务        context.startService(EXAMPLE_SERVICE_INTENT);        super.onEnabled(context);    }    @Override    public void onDisabled(Context context) {        // 在最后一个 widget 被删除时，终止服务        context.stopService(EXAMPLE_SERVICE_INTENT);        super.onDisabled(context);    }    /**     * widget被删除的时候调用     * @param context     * @param appWidgetIds     */    @Override    public void onDeleted(Context context, int[] appWidgetIds) {        // 当 widget 被删除时，对应的删除set中保存的widget的id        for (int appWidgetId : appWidgetIds) {            idsSet.remove(Integer.valueOf(appWidgetId));        }    }    @Override    public void onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager, int appWidgetId, Bundle newOptions) {        super.onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, newOptions);    }    @Override    public void onReceive(Context context, Intent intent) {        final String action = intent.getAction();        if (ACTION_UPDATE_ALL.equals(action)) {            // “更新”广播            updateAllAppWidgets(context, AppWidgetManager.getInstance(context), idsSet);        } else if (intent.hasCategory(Intent.CATEGORY_ALTERNATIVE)) {            // “按钮点击”广播            Uri data = intent.getData();            int buttonId = Integer.parseInt(data.getSchemeSpecificPart());            if (buttonId == BUTTON_SHOW) {                Toast.makeText(context, "Button Clicked", Toast.LENGTH_SHORT).show();            }        }        super.onReceive(context, intent);    }    private void updateAllAppWidgets(Context context, AppWidgetManager instance, Set idsSet) {        // widget 的id        int appID;        // 迭代器，用于遍历所有保存的widget的id        Iterator it = idsSet.iterator();        while (it.hasNext()) {            appID = ((Integer) it.next()).intValue();            // 随机获取一张图片            int index = (new java.util.Random().nextInt(ARR_IMAGES.length));            if (DEBUG) Log.d(TAG, "onUpdate(): index=" + index);            // 获取 example_appwidget.xml 对应的RemoteViews            RemoteViews remoteView = new RemoteViews(context.getPackageName(), R.layout.activity_main);            // 设置显示图片            remoteView.setImageViewResource(R.id.iv_show, ARR_IMAGES[index]);            // 设置点击按钮对应的PendingIntent：即点击按钮时，发送广播。                        remoteView.setOnClickPendingIntent(R.id.btn_show, getPendingIntent(context, BUTTON_SHOW));            // 更新 widget            instance.updateAppWidget(appID, remoteView);        }    }    /**     * 设置点击按钮对应的PendingIntent     * @param context     * @param buttonShowId     * @return     */    private PendingIntent getPendingIntent(Context context, int buttonShowId) {        Intent intent = new Intent();        intent.setClass(context, ExampleAppWidgetProvider.class);        intent.addCategory(Intent.CATEGORY_ALTERNATIVE);        intent.setData(Uri.parse("custom:" + buttonShowId));        PendingIntent pi = PendingIntent.getBroadcast(context, 0, intent, 0);        return pi;    }    }

AppWidgetProvider中的广播处理函数如下：

• onUpdate()

  当 widget 更新时被执行。同样，当用户首次添加 widget 时，onUpdate() 也会被调用，这样 widget 就能进行必要的设置工作(如果需要的话) 。但是，如果定义了 widget 的 configure属性，那么当用户首次添加 widget 时，onUpdate()不会被调用；之后更新 widget 时，onUpdate才会被调用。

• onAppWidgetOptionsChanged()

  当widget 被初次添加或者当widget的大小被改变时，执行onAppWidgetOptionsChanged()。你可以在该函数中，根据 widget 的大小来显示/隐藏某些内容。可以通过 getAppWidgetOptions() 来返回 Bundle 对象以读取 widget 的大小信息，Bundle中包括以下信息：
  OPTION_APPWIDGET_MIN_WIDTH – 包含 widget 当前宽度的下限，以dp为单位。
  OPTION_APPWIDGET_MIN_HEIGHT – 包含 widget 当前高度的下限，以dp为单位。
  OPTION_APPWIDGET_MAX_WIDTH – 包含 widget 当前宽度的上限，以dp为单位。
  OPTION_APPWIDGET_MAX_HEIGHT – 包含 widget 当前高度的上限，以dp为单位。
  onAppWidgetOptionsChanged() 是 Android 4.1 引入的。

• onDeleted(Context, int[])

  当 widget 被删除时被触发。

• onEnabled(Context)

  当第1个 widget 的实例被创建时触发。也就是说，如果用户对同一个 widget 增加了两次（两个实例），那么onEnabled()只会在第一次增加widget时触发。

• onDisabled(Context)

  当最后1个 widget 的实例被删除时触发。

• onReceive(Context, Intent)

  接收到任意广播时触发，并且会在上述的方法之前被调用。

总结:
AppWidgetProvider 继承于 BroadcastReceiver。实际上，App Widge中的onUpdate()、onEnabled()、onDisabled()等方法都是在 onReceive()中调用的，是onReceive()对特定事情的响应函数。

4.编辑发送更新图片广播的Service

public class ExampleAppWidgetService extends Service {    private static final String TAG="ExampleAppWidgetService";    //更新widget的广播对应的action    private final String ACTION_UPDATE_ALL ="com.example.user.widgettest.UPDATE_ALL";    //周期性更新widget的周期    private static final int UPDATE_TIME=5000;    //周期性更新widget的线程    private UpdateThread mUpdateThread;    private Context mContext;    //更新周期的计数    private int count=0;    @Override    public void onCreate() {        // 创建并开启线程UpdateThread        mUpdateThread = new UpdateThread();        mUpdateThread.start();        mContext = this.getApplicationContext();        super.onCreate();    }    @Override    public void onDestroy() {        // 中断线程，即结束线程。        if (mUpdateThread != null) {            mUpdateThread.interrupt();        }        super.onDestroy();    }    @Nullable    @Override    public IBinder onBind(Intent intent) {        return null;    }    /**     * 服务开始时，即调用startService     * @param intent     * @param flags     * @param startId     * @return     */    @Override    public int onStartCommand(Intent intent, int flags, int startId) {        Log.d(TAG, "onStartCommand");        super.onStartCommand(intent, flags, startId);        return START_STICKY;    }    private class UpdateThread extends Thread{        @Override        public void run() {            super.run();            try {                count=0;                while(true){                    Log.d(TAG,"run...count:"+count);                    count++;                    Intent updateIntent =new Intent(ACTION_UPDATE_ALL);                    mContext.sendBroadcast(updateIntent);                    Thread.sleep(UPDATE_TIME);                }            } catch (InterruptedException e) {                e.printStackTrace();            }        }    }}

服务UpdateThread 每隔5秒，发送1个广播ACTION_UPDATE_ALL。广播ACTION_UPDATE_ALL在ExampleAppWidgetProvider 被处理：用来更新widget中的图片。

完成后效果：

---

参考资料
[1] 官方文档
[2] Android 之窗口小部件详解–App Widget