MIUI小部件技术规范与系统能力说明

版本更新说明

简介

MIUI小部件基于原生 Android Widget，开发一个 MIUI 小部件和开发一个原生 Android Widget 基本一致，部分区别如下：

• 为了保证整机系统用户体验，MIUI 小部件对开发者做了一些规范要求；
• 为了拓展小部件能力，丰富可玩性，MIUI 小部件额外提供了一些调用能力；

一、小部件技术规范和要求

开发者基于MIUI小部件体系开发 Widget 时，需要满足下面的技术要求：

1.MIUI Widget 使用独立进程

1.1.描述

为了方便管理 Widget，减少 Widget 更新对后台内存的占用，提升整机的用户体验。MIUI 小部件规定 Widget 需要使用独立后台进程（后简称：Widget进程）来进行内容更新。

1.2.Widget 进程限制说明

– Widget 进程名字为” :widgetProvider ” 

– Widget 进程不能拉起其他任意进程（包括 App 主进程），同时系统也会进行相应限制

– Widget 进程内存占用不能超过 35M，执行命令( adb shell dumpsys meminfo 进程名 ) 可获取进程所占内存

– Widget 进程严禁使用 native方法（fork）拉起进程

– Widget 进程只能运行 Widget内容准备和刷新相关的逻辑

1.3.Widget 进程配置说明

<receiver android:name="com.miui.ExampleWidgetProvider"
    android:process=":widgetProvider">
    ....
</receiver>

<service android:name="com.miui.ExampleWidgetService"
    android:process=":widgetProvider" >
    ....
</service>
<provider android:name="com.miui.demo.ExampleWidgetProvider"
    android:process=":widgetProvider">
    ...
</provider>

备注：Activity不需要放在 Widget 进程中

1.4.播放器小部件适配独立进程

播放器小部件存在后台播放音频以及拉起其他进程的情况，这种特殊小部件可以运行在非 Widget 进程，但必须关闭曝光刷新，必须使用前台Service，更新UI时使用主动刷新（详细可看“MIUI 小部件系统能力说明-App主动刷新小部件”）。

1.5.其他

Widget 进程系统分配的 adj 值较高，在系统资源不足时，容易被系统回收。

2.MIUI Widget 曝光刷新适配

2.1.描述

MIUI Widget 将会去掉系统原有的定时刷新。用户滑动到有 Widget 的页面，系统会判定需要触发一次刷新并通知应用。默认 MIUI Widget 曝光不刷新，有曝光刷新需求的 MIUI Widget 需在 AndroidManifest.xml 中申请，并设定曝光刷新间隔miuiWidgetRefreshMinInterval（在间隔时间内曝光多次只会触发一次），曝光刷新间隔最短为10秒。

2.2.适配方式

<receiver android:name="com.miui.ExampleWidgetProvider" >
    ...
    // 定义是否需要曝光刷新
    <meta-data                
    android:name="miuiWidgetRefresh"                
    android:value="exposure" />
    // 定义曝光刷新的时间间隔
    <meta-data
    android:name="miuiWidgetRefreshMinInterval" 
    // 时间单位为毫秒                    
    android:value="20000" />
    // MIUI Widget 标识
    <meta-data
    android:name="miuiWidget"
    android:value="true" />

    <intent-filter>   
         //系统定时刷新             
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> 
        //MIUI展现刷新
        <action android:name="miui.appwidget.action.APPWIDGET_UPDATE" />    </intent-filter>
</receiver>

public class ExampleWidgetProvider extends AppWidgetProvider {
    ...
    @Override
    public void onReceive(Context context, Intent intent) {
        if ("miui.appwidget.action.APPWIDGET_UPDATE".equals(intent.getAction())) {
            int[] appWidgets = intent.getIntArrayExtra(AppWidgetManager.EXTRA_APPWIDGET_IDS);
            onUpdate(context, AppWidgetManager.getInstance(context), appWidgets); //或者自定义刷新逻辑
        } else {
            super.onReceive(context, intent);
        }
    }
}

3.MIUI Widget 尺寸设置

3.1.描述

MIUI Widget支持 2*2、4*2、4*4三种尺寸，开发者可以根据组件信息和所需展示的功能选择合适的尺寸进行设计，并且在 resource 配置文件中指定具体的尺寸。

3.2.适配方式

每个小部件必须定义 minWidth 和 minHeight，表示默认情况下应占用的最小空间量。当用户向AppWidgetHost（如桌面，负一屏等）添加小部件时，小部件占用的宽度和高度通常会超过您指定的最小值。AppWidgetHost 为用户提供了一个可用空间网格，供用户放置小部件和图标，网格可能因设备而异。

添加小部件后，它将在水平和垂直方向进行拉伸，占用满足其 minWidth 和 minHeight 约束条件所需的最小单元格数。

虽然单元格的宽度和高度以及应用到小部件的自动外边距量可能会因设备而异，但您设置尺寸时可以参考下表中的建议大小。

3.3.示例

根据 Widget 尺寸大小在上表中选择对应的dp值，填到对应配置文件里的 minWidth/minHeight 属性。下面以2×2的 Widget 为例，说明尺寸适配过程。

// step1:在AndroidManifest.xml中声明widegt配置文件
<receiver android:name=".ExampleAppWidgetProvider" >
   ....
    <meta-data android:name="android.appwidget.provider"
    android:resource="@xml/example_appwidget_info" />
</receiver>

// step2: example_appwidget_info中设置尺寸属性
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="@dimen/widget_min_width"
    android:minHeight="@dimen/widget_min_height"
    ....    
</appwidget-provider>

// step3: values/dimens中定义尺寸值
<dimen name="widget_min_width">110dp</dimen>
<dimen name="widget_min_height">110dp</dimen>

4.MIUI Widget 标识

4.1.描述

在 AndroidManifest.xml文件中，MIUI Widget 的receiver组件需要添加 MIUI 标识，只有添加 MIUI 标识的Widget才享有MIUI Widget 能力。

4.2.示例

<receiver
    android:name="com.miui.widgetdemo.provider.ExampleWidgetProvider"
    android:process=":widgetProvider">
   <meta-data
    android:name="miuiWidget"
    android:value="true" />
    ....
</receiver>