Android - Widgets 教程

封面图 • 2026-01-08 • Android开发

在 Android 开发中，**Widgets（小部件）** 是一种可以在主屏幕（Home Screen）上显示的组件。它们可以提供简化的功能或信息，比如天气、日历、音乐播放器等。用户可以通过长按主屏幕并选择“小部件”来添加这些小部件。

---

## 🧩 一、什么是 Android Widget？

Android 小部件是 **AppWidget** 的一种实现，它允许你创建一个轻量级的 UI 组件，嵌入到用户的主屏幕上。它们通常由以下几部分组成：

- **AppWidgetProvider**：负责处理小部件的生命周期事件（如更新、点击等）。
- **XML 布局文件**：定义小部件的 UI。
- **Metadata 文件（`appwidget-provider.xml`）**：定义小部件的元数据，如最小尺寸、更新频率等。

---

## 📌 二、创建一个简单的 Android Widget

### 步骤 1：创建 AppWidgetProvider 类

```java
public class MyWidgetProvider extends AppWidgetProvider {

@Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // 遍历所有小部件实例
        for (int appWidgetId : appWidgetIds) {
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);

// 设置点击动作（可选）
            Intent intent = new Intent(context, MyWidgetProvider.class);
            intent.setAction(AppWidgetManager.ACTION_APPWIDGET_UPDATE);
            PendingIntent pendingIntent = PendingIntent.getBroadcast(context, 0, intent, 0);

views.setOnClickPendingIntent(R.id.widget_button, pendingIntent);

// 更新小部件
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}
```

---

### 步骤 2：创建小部件布局文件 `res/layout/widget_layout.xml`

```xml
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:gravity="center">

<Button
        android:id="@+id/widget_button"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="点击我！" />
</LinearLayout>
```

---

### 步骤 3：创建 metadata 文件 `res/xml/appwidget_provider.xml`

```xml
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="144dp"
    android:minHeight="72dp"
    android:updatePeriodMillis="86400000"
    android:initialLayout="@layout/widget_layout"
    android:configure="com.example.myapp.ConfigureActivity">
</appwidget-provider>
```

> - `minWidth` 和 `minHeight` 定义小部件的最小尺寸（单位为 dp）。
> - `updatePeriodMillis` 表示小部件多久更新一次（单位为毫秒）。
> - `initialLayout` 指定小部件的初始布局。
> - `configure` 可选，用于指定配置 Activity。

---

### 步骤 4：在 `AndroidManifest.xml` 中注册 Widget

```xml
<receiver android:name=".MyWidgetProvider">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>

---

## 📱 三、使用 Widget

1. 长按主屏幕 → 选择 “小部件”。
2. 找到你的应用并选择小部件。
3. 点击“添加小部件”即可。

---

## ✅ 四、高级功能（可选）

### 1. 点击事件处理

你可以通过 `setOnClickPendingIntent()` 来绑定点击事件，例如打开一个 Activity 或发送广播。

### 2. 更新小部件内容

你可以使用 `AppWidgetManager` 来动态更新小部件的内容。

```java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
views.setTextViewText(R.id.widget_text, "Hello, Widget!");
appWidgetManager.updateAppWidget(appWidgetId, views);
```

### 3. 使用 Service 更新数据

如果你需要定时更新小部件，可以结合 `AlarmManager` 或 `WorkManager` 实现后台更新。

---

## 📚 五、参考文档

- [官方文档 - App Widgets](https://developer.android.com/guide/topics/appwidgets)
- [Android AppWidgetProvider Class](https://developer.android.com/reference/android/appwidget/AppWidgetProvider)

---

如果你有具体需求（比如带图片、进度条、列表等），我可以为你提供更详细的代码示例。是否需要？