flutter-adding-home-screen-widgets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Flutter Home Screen Widgets

实现Flutter主屏幕小组件

Architecture & Data Flow

架构与数据流

Home Screen Widgets require native UI implementation (SwiftUI for iOS, XML/Kotlin for Android). The Flutter app communicates with these native widgets via shared local storage (

UserDefaults

on iOS,

SharedPreferences

on Android) using the

home_widget

package.

Data Write: Flutter app writes key-value pairs or renders images to a shared container.
Trigger: Flutter app signals the native OS to update the widget.
Data Read: Native widget wakes up, reads the key-value pairs or images from the shared container, and updates its UI.

主屏幕小组件需要原生UI实现（iOS使用SwiftUI，Android使用XML/Kotlin）。Flutter应用通过

home_widget

包，借助共享本地存储（iOS为

UserDefaults

，Android为

SharedPreferences

）与这些原生小组件进行通信。

数据写入：Flutter应用将键值对或渲染后的图片写入共享容器。
触发更新：Flutter应用通知原生系统更新小组件。
数据读取：原生小组件唤醒后，从共享容器读取键值对或图片，更新其UI。

Flutter Integration Workflow

Flutter集成流程

Use this checklist to implement the Dart side of the Home Screen Widget integration.

Step 1: Initialize the App Group. Call

HomeWidget.setAppGroupId('<YOUR_APP_GROUP>')

initState()

or app startup.

Step 2: Save Data. Use
```
HomeWidget.saveWidgetData<T>('key', value)
```
to write data to shared storage.

Step 3: Trigger Update. Call

HomeWidget.updateWidget(iOSName: 'YourIOSWidget', androidName: 'YourAndroidWidget')

to notify the OS.

Step 4: Validate. Run Flutter build -> review console for missing plugin registrations -> fix.

使用以下清单完成Home Screen Widget集成的Dart端实现。

步骤1：初始化App Group。在
```
initState()
```
或应用启动时调用
```
HomeWidget.setAppGroupId('<YOUR_APP_GROUP>')
```
。
步骤2：保存数据。使用
```
HomeWidget.saveWidgetData<T>('key', value)
```
将数据写入共享存储。

步骤3：触发更新。调用

HomeWidget.updateWidget(iOSName: 'YourIOSWidget', androidName: 'YourAndroidWidget')

通知系统。

步骤4：验证。运行Flutter构建 -> 检查控制台是否有插件注册缺失问题 -> 修复。

iOS Implementation Workflow

iOS实现流程

If targeting iOS, implement the widget using Xcode and SwiftUI.

Step 1: Create Target. Open
```
ios/Runner.xcworkspace
```
in Xcode. Add a new Widget Extension target. Disable "Include Live Activity" and "Include Configuration Intent" unless explicitly required.
Step 2: Configure App Groups. Add the App Groups capability to both the Runner target and the Widget Extension target. Ensure the App Group ID matches the one used in Dart.
Step 3: Define TimelineEntry. Create a struct conforming to
```
TimelineEntry
```
to hold the data passed from shared storage.

Step 4: Implement TimelineProvider.

getSnapshot

and

getTimeline

, instantiate

UserDefaults(suiteName: "<YOUR_APP_GROUP>")

Extract values using

userDefaults?.string(forKey: "your_key")

Return the populated
```
TimelineEntry
```
.

Step 5: Build UI. Implement the SwiftUI
```
View
```
to display the data from the
```
TimelineEntry
```
.
Step 6: Validate. Run Xcode build for the Widget Extension -> review provisioning/App Group errors -> fix.

如果面向iOS平台，使用Xcode和SwiftUI实现小组件。

步骤1：创建Target。在Xcode中打开
```
ios/Runner.xcworkspace
```
。添加新的Widget Extension目标。除非明确需要，否则禁用"Include Live Activity"和"Include Configuration Intent"。
步骤2：配置App Groups。为Runner目标和Widget Extension目标都添加App Groups能力。确保App Group ID与Dart代码中使用的一致。
步骤3：定义TimelineEntry。创建一个符合
```
TimelineEntry
```
协议的结构体，用于存储从共享存储传递的数据。

步骤4：实现TimelineProvider。

在

getSnapshot

和

getTimeline

方法中，实例化

UserDefaults(suiteName: "<YOUR_APP_GROUP>")

。

使用

userDefaults?.string(forKey: "your_key")

提取值。

返回填充好数据的
```
TimelineEntry
```
。

步骤5：构建UI。实现SwiftUI
```
View
```
以显示
```
TimelineEntry
```
中的数据。
步骤6：验证。为Widget Extension运行Xcode构建 -> 检查配置文件/App Group错误 -> 修复。

Android Implementation Workflow

Android实现流程

If targeting Android, implement the widget using Android Studio and XML/Kotlin.

Step 1: Create App Widget. Open the
```
android
```
folder in Android Studio. Right-click the app directory -> New -> Widget -> App Widget.
Step 2: Define Layout. Edit
```
res/layout/<widget_name>.xml
```
to define the UI using standard Android XML layouts (e.g.,
```
RelativeLayout
```
,
```
TextView
```
,
```
ImageView
```
).

Step 3: Implement AppWidgetProvider.

Open the generated Kotlin class extending
```
AppWidgetProvider
```
.

In the

onUpdate

method, retrieve shared data using

HomeWidgetPlugin.getData(context)

Extract values using
```
widgetData.getString("your_key", null)
```
.

Update the UI using

RemoteViews

and

setTextViewText

setImageViewBitmap

Call

appWidgetManager.updateAppWidget(appWidgetId, views)

Step 4: Validate. Run Android build -> review Manifest registration errors -> fix.

如果面向Android平台，使用Android Studio和XML/Kotlin实现小组件。

步骤1：创建App Widget。在Android Studio中打开
```
android
```
文件夹。右键点击应用目录 -> New -> Widget -> App Widget。
步骤2：定义布局。编辑
```
res/layout/<widget_name>.xml
```
，使用标准Android XML布局（如
```
RelativeLayout
```
、
```
TextView
```
、
```
ImageView
```
）定义UI。

步骤3：实现AppWidgetProvider。

打开生成的继承自
```
AppWidgetProvider
```
的Kotlin类。
在
```
onUpdate
```
方法中，使用
```
HomeWidgetPlugin.getData(context)
```
获取共享数据。
使用
```
widgetData.getString("your_key", null)
```
提取值。

使用

RemoteViews

和

setTextViewText

或

setImageViewBitmap

更新UI。

调用

appWidgetManager.updateAppWidget(appWidgetId, views)

。

步骤4：验证。运行Android构建 -> 检查Manifest注册错误 -> 修复。

Advanced Techniques

进阶技巧

Rendering Flutter Widgets as Images

将Flutter Widget渲染为图片

If the UI is too complex to recreate natively (e.g., custom charts), render the Flutter widget to an image and display the image in the native widget.

Wrap the target Flutter widget with a
```
GlobalKey
```
.
Call
```
HomeWidget.renderFlutterWidget()
```
, passing the widget, a filename, and the key.
iOS: Read the file path from
```
UserDefaults
```
and render using
```
UIImage(contentsOfFile:)
```
inside a SwiftUI
```
Image
```
.
Android: Read the file path from
```
SharedPreferences
```
, decode using
```
BitmapFactory.decodeFile()
```
, and render using
```
setImageViewBitmap()
```
.

如果UI过于复杂无法原生重建（如自定义图表），可将Flutter Widget渲染为图片，在原生小组件中显示。

用
```
GlobalKey
```
包裹目标Flutter Widget。
调用
```
HomeWidget.renderFlutterWidget()
```
，传入Widget、文件名和Key。
iOS：从
```
UserDefaults
```
读取文件路径，在SwiftUI
```
Image
```
中使用
```
UIImage(contentsOfFile:)
```
渲染。
Android：从
```
SharedPreferences
```
读取文件路径，使用
```
BitmapFactory.decodeFile()
```
解码，再用
```
setImageViewBitmap()
```
渲染。

Using Custom Flutter Fonts (iOS Only)

使用自定义Flutter字体（仅iOS）

If utilizing custom fonts defined in Flutter on iOS Home Screen Widgets:

Extract the Flutter asset bundle path in Swift.
Register the font using
```
CTFontManagerRegisterFontsForURL
```
.
Apply the font in SwiftUI using
```
Font.custom()
```
.

如果在iOS主屏幕小组件中使用Flutter定义的自定义字体：

在Swift中提取Flutter资源包路径。
使用
```
CTFontManagerRegisterFontsForURL
```
注册字体。
在SwiftUI中使用
```
Font.custom()
```
应用字体。

Examples

示例

Example: Flutter Data Update

示例：Flutter数据更新

dart

import 'package:home_widget/home_widget.dart';

const String appGroupId = 'group.com.example.app';
const String iOSWidgetName = 'NewsWidgets';
const String androidWidgetName = 'NewsWidget';

Future<void> updateWidgetData(String title, String description) async {
  await HomeWidget.setAppGroupId(appGroupId);
  await HomeWidget.saveWidgetData<String>('headline_title', title);
  await HomeWidget.saveWidgetData<String>('headline_description', description);
  await HomeWidget.updateWidget(
    iOSName: iOSWidgetName,
    androidName: androidWidgetName,
  );
}

dart

import 'package:home_widget/home_widget.dart';

const String appGroupId = 'group.com.example.app';
const String iOSWidgetName = 'NewsWidgets';
const String androidWidgetName = 'NewsWidget';

Future<void> updateWidgetData(String title, String description) async {
  await HomeWidget.setAppGroupId(appGroupId);
  await HomeWidget.saveWidgetData<String>('headline_title', title);
  await HomeWidget.saveWidgetData<String>('headline_description', description);
  await HomeWidget.updateWidget(
    iOSName: iOSWidgetName,
    androidName: androidWidgetName,
  );
}

Example: iOS SwiftUI Provider & View

示例：iOS SwiftUI Provider & View

swift

import WidgetKit
import SwiftUI

struct NewsArticleEntry: TimelineEntry {
    let date: Date
    let title: String
    let description: String
}

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> NewsArticleEntry {
        NewsArticleEntry(date: Date(), title: "Loading...", description: "Loading...")
    }

    func getSnapshot(in context: Context, completion: @escaping (NewsArticleEntry) -> ()) {
        let userDefaults = UserDefaults(suiteName: "group.com.example.app")
        let title = userDefaults?.string(forKey: "headline_title") ?? "No Title"
        let description = userDefaults?.string(forKey: "headline_description") ?? "No Description"
        
        let entry = NewsArticleEntry(date: Date(), title: title, description: description)
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        getSnapshot(in: context) { (entry) in
            let timeline = Timeline(entries: [entry], policy: .atEnd)
            completion(timeline)
        }
    }
}

struct NewsWidgetsEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack(alignment: .leading) {
            Text(entry.title).font(.headline)
            Text(entry.description).font(.subheadline)
        }
    }
}

swift

import WidgetKit
import SwiftUI

struct NewsArticleEntry: TimelineEntry {
    let date: Date
    let title: String
    let description: String
}

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> NewsArticleEntry {
        NewsArticleEntry(date: Date(), title: "Loading...", description: "Loading...")
    }

    func getSnapshot(in context: Context, completion: @escaping (NewsArticleEntry) -> ()) {
        let userDefaults = UserDefaults(suiteName: "group.com.example.app")
        let title = userDefaults?.string(forKey: "headline_title") ?? "No Title"
        let description = userDefaults?.string(forKey: "headline_description") ?? "No Description"
        
        let entry = NewsArticleEntry(date: Date(), title: title, description: description)
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        getSnapshot(in: context) { (entry) in
            let timeline = Timeline(entries: [entry], policy: .atEnd)
            completion(timeline)
        }
    }
}

struct NewsWidgetsEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack(alignment: .leading) {
            Text(entry.title).font(.headline)
            Text(entry.description).font(.subheadline)
        }
    }
}

Example: Android Kotlin Provider

示例：Android Kotlin Provider

kotlin

package com.example.app.widgets

import android.appwidget.AppWidgetManager
import android.appwidget.AppWidgetProvider
import android.content.Context
import android.widget.RemoteViews
import es.antonborri.home_widget.HomeWidgetPlugin
import com.example.app.R

class NewsWidget : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray,
    ) {
        for (appWidgetId in appWidgetIds) {
            val widgetData = HomeWidgetPlugin.getData(context)
            val views = RemoteViews(context.packageName, R.layout.news_widget).apply {
                val title = widgetData.getString("headline_title", "No Title")
                setTextViewText(R.id.headline_title, title)

                val description = widgetData.getString("headline_description", "No Description")
                setTextViewText(R.id.headline_description, description)
            }
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

<details> <summary>Example: iOS Custom Font Registration Helper</summary>

swift

// Add this to your SwiftUI View struct
var bundle: URL {
    let bundle = Bundle.main
    if bundle.bundleURL.pathExtension == "appex" {
        var url = bundle.bundleURL.deletingLastPathComponent().deletingLastPathComponent()
        url.append(component: "Frameworks/App.framework/flutter_assets")
        return url
    }
    return bundle.bundleURL
}

init(entry: Provider.Entry) {
    self.entry = entry
    CTFontManagerRegisterFontsForURL(
        bundle.appending(path: "/fonts/YourCustomFont.ttf") as CFURL, 
        CTFontManagerScope.process, 
        nil
    )
}

</details>

kotlin

package com.example.app.widgets

import android.appwidget.AppWidgetManager
import android.appwidget.AppWidgetProvider
import android.content.Context
import android.widget.RemoteViews
import es.antonborri.home_widget.HomeWidgetPlugin
import com.example.app.R

class NewsWidget : AppWidgetProvider() {
    override fun onUpdate(
        context: Context,
        appWidgetManager: AppWidgetManager,
        appWidgetIds: IntArray,
    ) {
        for (appWidgetId in appWidgetIds) {
            val widgetData = HomeWidgetPlugin.getData(context)
            val views = RemoteViews(context.packageName, R.layout.news_widget).apply {
                val title = widgetData.getString("headline_title", "No Title")
                setTextViewText(R.id.headline_title, title)

                val description = widgetData.getString("headline_description", "No Description")
                setTextViewText(R.id.headline_description, description)
            }
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

<details> <summary>示例：iOS自定义字体注册助手</summary>

swift

// Add this to your SwiftUI View struct
var bundle: URL {
    let bundle = Bundle.main
    if bundle.bundleURL.pathExtension == "appex" {
        var url = bundle.bundleURL.deletingLastPathComponent().deletingLastPathComponent()
        url.append(component: "Frameworks/App.framework/flutter_assets")
        return url
    }
    return bundle.bundleURL
}

init(entry: Provider.Entry) {
    self.entry = entry
    CTFontManagerRegisterFontsForURL(
        bundle.appending(path: "/fonts/YourCustomFont.ttf") as CFURL, 
        CTFontManagerScope.process, 
        nil
    )
}

</details>

flutter-adding-home-screen-widgets

Original

Translation

Implementing Flutter Home Screen Widgets

实现Flutter主屏幕小组件

Contents

目录

Architecture & Data Flow

架构与数据流

Flutter Integration Workflow

Flutter集成流程

iOS Implementation Workflow

iOS实现流程

Android Implementation Workflow

Android实现流程

Advanced Techniques

进阶技巧

Rendering Flutter Widgets as Images

将Flutter Widget渲染为图片

Using Custom Flutter Fonts (iOS Only)

使用自定义Flutter字体（仅iOS）

Examples

示例

Example: Flutter Data Update

示例：Flutter数据更新

Example: iOS SwiftUI Provider & View

示例：iOS SwiftUI Provider & View

Example: Android Kotlin Provider

示例：Android Kotlin Provider