Launcher3 怎么创建一个Widget

网络卷毛

墨衍会员 · AI 创作全网分发码龄14年

关注

原创最新推荐文章于 2026-06-29 10:51:31 发布 994 阅读 AI 写同款· GEO 优化 ›

Launcher3 AppWidget挂件显示原理手机开机和重启过程中,有低概率机出现挂件不显示的情况,对整个显示流程和原理进行梳理. 阅读详情

参考博客https://www.cnblogs.com/skywang12345/p/3158310.html

Launcher中除了app，还有一些小部件作为各个app的延伸功能

1，创建Widget工程

2.编辑AndroidManifest.XML文件

     <receiver android:name=".widgets.desktop.SmallWidget" android:label="@string/widget_small">
            <intent-filter>
                <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
                <action android:name="com.naman14.timber.metachanged" />
                <action android:name="com.naman14.timber.playstatechanged" />
            </intent-filter>
            <meta-data android:name="android.appwidget.provider"
                android:resource="@xml/widget_small" />
        </receiver>

申明了SmallWidget，SmallWidget是一个广播接收者，说明Widget的功能实现本质上是通过Widget实现，同时需要初始化SmallWidget的布局，由widget_small来配置：

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="380dp"
    android:minHeight="40dp"
    android:updatePeriodMillis="86400000"
    android:previewImage="@drawable/widget_small"
    android:resizeMode="horizontal|vertical"
    android:initialLayout="@layout/widget_small" />

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

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

updatePeriodMillis
它定义了 widget 的更新频率。实际的更新时机不一定是精确的按照这个时间发生的。建议更新尽量不要太频繁，最好是低于1小时一次。或者可以在配置 Activity 里面供用户对更新频率进行配置。实际上，当updatePeriodMillis的值小于30分钟时，系统会自动将更新频率设为30分钟！关于这部分，后面会详细介绍。
注意: 当更新时机到达时，如果设备正在休眠，那么设备将会被唤醒以执行更新。如果更新频率不超过1小时一次，那么对电池寿命应该不会造成多大的影响。如果你需要比较频繁的更新，或者你不希望在设备休眠的时候执行更新，那么可以使用基于 alarm 的更新来替代 widget 自身的刷新机制。将 alarm 类型设置为 ELAPSED_REALTIME 或 RTC，将不会唤醒休眠的设备，同时请将 updatePeriodMillis 设为 0。

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 引入。

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

minWidth和minHeigth设置Widget在Launcher中至少要占的格子数，格子数怎么算

但最终格子数，还是由Widget的布局说了算

然后通过android:initialLayout="@layout/widget_small"配置widget的布局文件：

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="@color/black_translucent"
    android:padding="4dp">

    <ImageView
        android:id="@+id/imageView_cover"
        android:padding="4dp"
        android:layout_width="100dp"
        android:layout_height="100dp" />

    <ImageView
        android:id="@+id/image_playpause"
        android:layout_margin="25dp"
        android:layout_width="50dp"
        android:layout_height="50dp"
        android:scaleType="center"
        android:background="@drawable/selectable_item_background"
        android:src="@drawable/ic_play_white_36dp" />

    <TextView
        android:id="@+id/textView_title"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentEnd="true"
        android:layout_alignParentRight="true"
        android:layout_alignParentTop="true"
        android:layout_toEndOf="@id/imageView_cover"
        android:layout_toRightOf="@id/imageView_cover"
        android:ellipsize="end"
        android:lines="1"
        android:text="@string/tap_to_start"
        android:textColor="@android:color/white"
        android:textStyle="bold" />

    <TextView
        android:id="@+id/textView_subtitle"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentEnd="true"
        android:layout_alignParentRight="true"
        android:layout_below="@id/textView_title"
        android:layout_toEndOf="@id/imageView_cover"
        android:layout_toRightOf="@id/imageView_cover"
        android:lines="1"
        android:textColor="@android:color/white" />

    <LinearLayout
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true"
        android:layout_alignParentEnd="true"
        android:layout_alignParentRight="true"
        android:layout_below="@id/textView_subtitle"
        android:layout_toEndOf="@id/imageView_cover"
        android:layout_toRightOf="@id/imageView_cover"
        android:gravity="bottom"
        tools:ignore="Suspicious0dp">

        <TextView
            android:layout_width="match_parent"
            android:layout_height="0dp"
            android:layout_weight="1" />


        <ImageView
            android:id="@+id/image_next"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:background="@drawable/selectable_item_background"
            android:src="@drawable/ic_skip_next_white_36dp" />

        <TextView
            android:layout_width="match_parent"
            android:layout_height="0dp"
            android:layout_weight="1" />
    </LinearLayout>

</RelativeLayout>

Widget并不支持所有的布局和控件，而仅仅只是支持Android布局和控件的一个子集。
(01) App Widget支持的布局：
　　FrameLayout
　　LinearLayout
　　RelativeLayout
　　GridLayout
(02) App Widget支持的控件：
　　AnalogClock
　　Button
　　Chronometer
　　ImageButton
　　ImageView
　　ProgressBar
　　TextView
　　ViewFlipper
　　ListView
　　GridView
　　StackView
　　AdapterViewFlipper

三.SmallWidget实现功能原理

1.SmallWidget继承了AppWidgetProvider，AppWidgetProvider继承了BroadcastReceiver，AppWidgetProvider主要封装了onReceive方法，如下：

public void onReceive(Context context, Intent intent) {
        // Protect against rogue update broadcasts (not really a security issue,
        // just filter bad broacasts out so subclasses are less likely to crash).
        String action = intent.getAction();
        if (AppWidgetManager.ACTION_APPWIDGET_UPDATE.equals(action)) {
            Bundle extras = intent.getExtras();
            if (extras != null) {
                int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
                if (appWidgetIds != null && appWidgetIds.length > 0) {
                    this.onUpdate(context, AppWidgetManager.getInstance(context), appWidgetIds);
                }
            }
        } else if (AppWidgetManager.ACTION_APPWIDGET_DELETED.equals(action)) {
            Bundle extras = intent.getExtras();
            if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID)) {
                final int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID);
                this.onDeleted(context, new int[] { appWidgetId });
            }
        } else if (AppWidgetManager.ACTION_APPWIDGET_OPTIONS_CHANGED.equals(action)) {
            Bundle extras = intent.getExtras();
            if (extras != null && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_ID)
                    && extras.containsKey(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS)) {
                int appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID);
                Bundle widgetExtras = extras.getBundle(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS);
                this.onAppWidgetOptionsChanged(context, AppWidgetManager.getInstance(context),
                        appWidgetId, widgetExtras);
            }
        } else if (AppWidgetManager.ACTION_APPWIDGET_ENABLED.equals(action)) {
            this.onEnabled(context);
        } else if (AppWidgetManager.ACTION_APPWIDGET_DISABLED.equals(action)) {
            this.onDisabled(context);
        } else if (AppWidgetManager.ACTION_APPWIDGET_RESTORED.equals(action)) {
            Bundle extras = intent.getExtras();
            if (extras != null) {
                int[] oldIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_OLD_IDS);
                int[] newIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
                if (oldIds != null && oldIds.length > 0) {
                    this.onRestored(context, oldIds, newIds);
                    this.onUpdate(context, AppWidgetManager.getInstance(context), newIds);
                }
            }
        }
    }

onUpdate()
当 widget 更新时被执行。
同样，当用户首次添加 widget 时，onUpdate() 也会被调用，这样 widget 就能进行必要的设置工作(如果需要的话) 。但是，如果定义了 widget 的 configure属性(即android:config，后面会介绍)，那么当用户首次添加 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)
接收到任意广播时触发，并且会在上述的方法之前被调用

2.onReceive是如何判断触发的是哪个Widget控件的呢？

Bundle extras = intent.getExtras();
            if (extras != null) {
                int[] appWidgetIds = extras.getIntArray(AppWidgetManager.EXTRA_APPWIDGET_IDS);
                if (appWidgetIds != null && appWidgetIds.length > 0) {
                    this.onUpdate(context, AppWidgetManager.getInstance(context), appWidgetIds);
                }
            }

通过intent获取到appWidgetIds触发更新

2.建立了BroadcastReceiver后，一般UI和功能的初始化绑定可在onUpdate（）完成，通过RemoteView完成，RemotView详解请看

https://blog.youkuaiyun.com/yuemingxingxing/article/details/86234811.

3.RemoteView初始化完后，调用 appWidgetManager.updateAppWidget(appWidgetIds, remoteViews)，更新Widget

这样，整个SmallWidget功能就实现了！！！

收录于