ปรับปรุงวิดเจ็ต

ลองใช้ Compose

Jetpack Compose เป็นชุดเครื่องมือ UI ที่แนะนำสำหรับ Android ดูวิธีสร้างวิดเจ็ตโดยใช้ API รูปแบบ Compose

Jetpack Glance →

หน้านี้มีรายละเอียดเกี่ยวกับการเพิ่มประสิทธิภาพวิดเจ็ตที่ไม่บังคับซึ่งพร้อมใช้งาน ตั้งแต่ Android 12 (API ระดับ 31) เป็นต้นไป ฟีเจอร์เหล่านี้เป็นฟีเจอร์ที่ไม่บังคับ แต่ใช้งานได้ง่ายและช่วยปรับปรุงประสบการณ์การใช้งานวิดเจ็ตของผู้ใช้

ใช้สีแบบเปลี่ยนอัตโนมัติ

ตั้งแต่ Android 12 เป็นต้นไป วิดเจ็ตจะใช้สีของธีมอุปกรณ์ สำหรับปุ่ม พื้นหลัง และคอมโพเนนต์อื่นๆ ได้ ซึ่งจะช่วยให้การเปลี่ยนผ่านเป็นไปอย่างราบรื่นยิ่งขึ้น และช่วยให้วิดเจ็ตต่างๆ มีความสอดคล้องกัน

คุณใช้สีแบบไดนามิกได้ 2 วิธีดังนี้

• ใช้ธีมเริ่มต้นของระบบ (@android:style/Theme.DeviceDefault.DayNight) ในเลย์เอาต์ราก

• ใช้ธีม Material 3 (Theme.Material3.DynamicColors.DayNight) จากไลบรารี คอมโพเนนต์เนื้อหาสำหรับ Android ซึ่งพร้อมใช้งานตั้งแต่คอมโพเนนต์เนื้อหาสำหรับ Android v1.6.0 เป็นต้นไป

เมื่อตั้งค่าธีมในเลย์เอาต์รูทแล้ว คุณจะใช้แอตทริบิวต์สีทั่วไปใน รูทหรือองค์ประกอบย่อยใดก็ได้เพื่อเลือกสีแบบไดนามิก

ตัวอย่างแอตทริบิวต์สีที่คุณใช้ได้มีดังนี้

• ?attr/primary
• ?attr/primaryContainer
• ?attr/onPrimary
• ?attr/onPrimaryContainer

ในตัวอย่างต่อไปนี้ที่ใช้ธีม Material 3 สีธีมของอุปกรณ์คือ "ม่วง" สีที่ใช้เน้นและพื้นหลังของวิดเจ็ตจะปรับให้เข้ากับโหมดสว่างและโหมดมืด ดังแสดงในรูปที่ 1 และ 2

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:background="?attr/colorPrimaryContainer"
  android:theme="@style/Theme.Material3.DynamicColors.DayNight">

  <ImageView
    ...
    app:tint="?attr/colorPrimaryContainer"
    android:src="@drawable/ic_partly_cloudy" />

    <!-- Other widget content. -->

</LinearLayout>

ความเข้ากันได้แบบย้อนหลังสำหรับสีแบบไดนามิก

สีแบบไดนามิกใช้ได้ในอุปกรณ์ที่ใช้ Android 12 ขึ้นไปเท่านั้น หากต้องการระบุธีมที่กำหนดเองสำหรับเวอร์ชันที่ต่ำกว่า ให้สร้างธีมเริ่มต้น ด้วยสีที่กำหนดเองและตัวระบุใหม่ (values-v31) โดยใช้แอตทริบิวต์ธีมเริ่มต้น

ตัวอย่างการใช้ธีม Material 3 มีดังนี้

<resources>
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight">
    <!-- Override default colorBackground attribute with custom color. -->
    <item name="android:colorBackground">@color/my_background_color</item>

    <!-- Add other colors/attributes. -->

  </style>
</resources>

<resources>
  <!-- Do not override any color attribute. -->
  <style name="MyWidgetTheme" parent="Theme.Material3.DynamicColors.DayNight" />
</resources>

<resources>
  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:background="?android:attr/colorBackground"
    android:theme="@style/MyWidgetTheme" />
</resources>

เปิดใช้การรองรับเสียง

การดำเนินการของแอปช่วยให้ Google Assistant แสดงวิดเจ็ตได้เมื่อได้รับคำสั่งเสียงที่เกี่ยวข้องจากผู้ใช้ การกำหนดค่า วิดเจ็ตให้ตอบสนองต่อIntent ในตัว (BII) จะช่วยให้ แอปแสดงวิดเจ็ตในแพลตฟอร์มของ Assistant เช่น Android และ Android Auto ได้อย่างรวดเร็ว ผู้ใช้มีตัวเลือกในการปักหมุดวิดเจ็ตที่ Assistant แสดงไว้ใน Launcher เพื่อกระตุ้นการมีส่วนร่วมในอนาคต

เช่น คุณสามารถกำหนดค่าวิดเจ็ตสรุปการออกกำลังกายสำหรับแอปออกกำลังกาย เพื่อตอบสนองคำสั่งเสียงของผู้ใช้ที่ทริกเกอร์ GET_EXERCISE_OBSERVATION BII ได้ Assistant จะแสดงวิดเจ็ตของคุณอย่างกระตือรือร้นเมื่อผู้ใช้เรียกใช้ BII นี้โดย การส่งคำขอ เช่น "Ok Google ฉันวิ่งไปกี่กิโลเมตรในสัปดาห์นี้ใน ExampleApp"

BII มีอยู่หลายสิบรายการซึ่งครอบคลุมการโต้ตอบของผู้ใช้หลายหมวดหมู่ ทำให้แอป Android เกือบทุกแอปสามารถปรับปรุงวิดเจ็ตให้รองรับเสียงได้ หากต้องการเริ่มต้นใช้งาน โปรดดูผสานรวม App Actions กับวิดเจ็ต Android

ปรับปรุงประสบการณ์การใช้งานเครื่องมือเลือกวิดเจ็ตของแอป

Android 12 ให้คุณเพิ่มตัวอย่างวิดเจ็ตที่ปรับขนาดแล้วและคำอธิบายวิดเจ็ตได้ Android 15 ช่วยให้คุณปรับปรุงประสบการณ์ตัวเลือกวิดเจ็ต สำหรับแอปด้วยตัวอย่างวิดเจ็ตที่สร้างขึ้น

หากต้องการปรับปรุงประสบการณ์การใช้งานเครื่องมือเลือกวิดเจ็ตของแอป ให้ระบุตัวอย่างวิดเจ็ตที่สร้างขึ้น ในอุปกรณ์ Android 15 ขึ้นไป ตัวอย่างวิดเจ็ตที่ปรับขนาดแล้ว (โดยระบุ previewLayout) สำหรับอุปกรณ์ Android 12 ถึง Android 14 และ previewImage สำหรับเวอร์ชันก่อนหน้า

เพิ่มตัวอย่างวิดเจ็ตที่สร้างขึ้นไปยังเครื่องมือเลือกวิดเจ็ต

แอปต้องตั้งค่า compileSdk เป็น 35 ขึ้นไปในไฟล์ build.gradle ของโมดูลเพื่อให้สามารถระบุ RemoteViews ให้กับเครื่องมือเลือกวิดเจ็ตในอุปกรณ์ Android 15 ขึ้นไป ซึ่งหมายความว่าแอปสามารถ อัปเดตเนื้อหาในเครื่องมือเลือกให้แสดงถึงสิ่งที่ผู้ใช้ เห็นได้มากขึ้น

แอปสามารถใช้วิธีการ AppWidgetManager, setWidgetPreview และ getWidgetPreview เพื่ออัปเดตลักษณะที่ปรากฏของวิดเจ็ตด้วยข้อมูลล่าสุดและข้อมูลที่ปรับเปลี่ยนในแบบของคุณ

สร้างตัวอย่างที่อัปเดตแล้วด้วย Jetpack Glance

Glance.compose เรียกใช้การจัดองค์ประกอบ 1 รายการ จึงไม่มีการใช้ฟังก์ชันระงับ โฟลว์ หรือการเรียกแบบอะซิงโครนัสที่คล้ายกันในเนื้อหาของ Composable แต่คุณต้องใช้ข้อมูลคงที่แทน

ตัวอย่างต่อไปนี้ใช้ Jetpack Glance เพื่อสร้างตัวอย่างที่อัปเดตแล้ว ต้องมีcompileSdkการตั้งค่าบิลด์ 35 ขึ้นไปsetWidgetPreviewจึงจะแสดงเป็นวิธีการในข้อมูลโค้ดนี้ได้

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    ExampleAppWidget().compose(
        context = appContext
    ),
)
AppWidgetSnippets.kt

สร้างตัวอย่างที่อัปเดตแล้วโดยไม่ต้องใช้ Jetpack Glance

คุณใช้ RemoteViews ได้โดยไม่ต้องใช้ Glance ตัวอย่างต่อไปนี้จะโหลดทรัพยากรเลย์เอาต์วิดเจ็ต XML และตั้งค่าให้เป็นตัวอย่าง ต้องมีการตั้งค่าบิลด์ compileSdk เป็น 35 ขึ้นไป setWidgetPreview จึงจะแสดงเป็น เมธอดในข้อมูลโค้ดนี้

AppWidgetManager.getInstance(appContext).setWidgetPreview(
    ComponentName(
        appContext,
        ExampleAppWidgetReceiver::class.java
    ),
    AppWidgetProviderInfo.WIDGET_CATEGORY_HOME_SCREEN,
    RemoteViews("com.example", R.layout.widget_preview)
)
AppWidgetSnippets.kt

เพิ่มตัวอย่างวิดเจ็ตที่ปรับขนาดได้ลงในเครื่องมือเลือกวิดเจ็ต

ตั้งแต่ Android 12 เป็นต้นไป ตัวอย่างวิดเจ็ตที่แสดงใน เครื่องมือเลือกวิดเจ็ตจะปรับขนาดได้ คุณระบุเป็นเลย์เอาต์ XML ที่ตั้งค่าเป็นขนาดเริ่มต้นของวิดเจ็ต ก่อนหน้านี้ ตัวอย่างวิดเจ็ตเป็นทรัพยากรแบบวาดแบบคงที่ ซึ่งในบางกรณีทำให้ตัวอย่างแสดงลักษณะของวิดเจ็ตเมื่อเพิ่มลงในหน้าจอหลักไม่ถูกต้อง

หากต้องการใช้ตัวอย่างวิดเจ็ตที่ปรับขนาดได้ ให้ใช้แอตทริบิวต์ previewLayout ขององค์ประกอบ appwidget-provider เพื่อระบุเลย์เอาต์ XML แทน

<appwidget-provider
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

เราขอแนะนำให้ใช้เลย์เอาต์เดียวกันกับวิดเจ็ตจริง โดยใช้ค่าเริ่มต้นหรือค่าทดสอบที่สมจริง แอปส่วนใหญ่ใช้ previewLayout และ initialLayout เดียวกัน ดูคำแนะนำในการสร้างเลย์เอาต์ตัวอย่างที่ถูกต้องได้ในส่วนต่อไปนี้ของหน้านี้

เราขอแนะนำให้ระบุทั้งแอตทริบิวต์ previewLayout และ previewImage เพื่อให้แอปสามารถกลับไปใช้ previewImage ได้หากอุปกรณ์ของผู้ใช้ ไม่รองรับ previewLayout แอตทริบิวต์ previewLayout จะมีความสำคัญเหนือกว่า แอตทริบิวต์ previewImage

แนวทางที่แนะนำในการสร้างตัวอย่างที่แม่นยำ

หากต้องการใช้ตัวอย่างวิดเจ็ตที่ปรับขนาดได้ ให้ใช้แอตทริบิวต์ previewLayout ขององค์ประกอบ appwidget-provider เพื่อระบุเลย์เอาต์ XML ดังนี้

<appwidget-provider
    ...
    android:previewLayout="@layout/my_widget_preview">
</appwidget-provider>

หากต้องการแสดงตัวอย่างที่ถูกต้อง คุณสามารถระบุเลย์เอาต์วิดเจ็ตจริงโดยตรงพร้อมค่าเริ่มต้นได้โดยทำตามขั้นตอนต่อไปนี้

• การตั้งค่า android:text="@string/my_widget_item_fake_1" สำหรับองค์ประกอบ TextView

• การตั้งค่ารูปภาพหรือไอคอนเริ่มต้นหรือตัวยึดตำแหน่ง เช่น android:src="@drawable/my_widget_icon" สำหรับคอมโพเนนต์ ImageView

หากไม่มีค่าเริ่มต้น ตัวอย่างอาจแสดงค่าที่ไม่ถูกต้องหรือค่าว่าง ข้อดีที่สำคัญของแนวทางนี้คือคุณสามารถระบุเนื้อหาตัวอย่างที่แปลแล้วได้

ดูรายละเอียดเกี่ยวกับแนวทางที่แนะนำสำหรับตัวอย่างที่ซับซ้อนมากขึ้นซึ่งมี ListView, GridView หรือ StackView ได้ที่สร้างตัวอย่างที่แม่นยำซึ่งมีสินค้าแบบไดนามิก

ความเข้ากันได้แบบย้อนหลังพร้อมตัวอย่างวิดเจ็ตที่ปรับขนาดได้

หากต้องการให้ตัวเลือกวิดเจ็ตใน Android 11 (API ระดับ 30) หรือต่ำกว่าแสดงตัวอย่างวิดเจ็ต ให้ระบุแอตทริบิวต์ previewImage

หากเปลี่ยนลักษณะที่ปรากฏของวิดเจ็ต ให้อัปเดตรูปภาพตัวอย่าง

ตั้งชื่อวิดเจ็ต

วิดเจ็ตต้องมีชื่อที่ไม่ซ้ำกันเมื่อแสดงในเครื่องมือเลือกวิดเจ็ต

ระบบจะโหลดชื่อวิดเจ็ตจากแอตทริบิวต์ label ขององค์ประกอบ receiver ของวิดเจ็ตในไฟล์ AndroidManifest.xml

<receiver
    ….
   android:label="Memories">
     ….
</receiver>

เพิ่มคำอธิบายสำหรับวิดเจ็ต

ตั้งแต่ Android 12 เป็นต้นไป ให้ระบุคำอธิบายสำหรับเครื่องมือเลือกวิดเจ็ต เพื่อแสดงสำหรับวิดเจ็ต

ระบุคำอธิบายสำหรับวิดเจ็ตโดยใช้แอตทริบิวต์ description ขององค์ประกอบ <appwidget-provider> ดังนี้

<appwidget-provider
    android:description="@string/my_widget_description">
</appwidget-provider>

คุณใช้แอตทริบิวต์ descriptionRes ใน Android เวอร์ชันก่อนหน้าได้ แต่ตัวเลือกวิดเจ็ตจะไม่สนใจแอตทริบิวต์นี้

ช่วยให้การเปลี่ยนราบรื่นยิ่งขึ้น

ตั้งแต่ Android 12 เป็นต้นไป ตัวเรียกใช้จะช่วยให้การเปลี่ยนผ่านเป็นไปอย่างราบรื่นยิ่งขึ้น เมื่อผู้ใช้เปิดแอปจากวิดเจ็ต

หากต้องการเปิดใช้การเปลี่ยนฉากที่ปรับปรุงแล้วนี้ ให้ใช้ @android:id/background หรือ android.R.id.background เพื่อระบุองค์ประกอบพื้นหลัง

// Top-level layout of the widget.
<LinearLayout
    android:id="@android:id/background">
</LinearLayout>

แอปของคุณสามารถใช้ @android:id/background ใน Android เวอร์ชันก่อนหน้าได้โดยไม่เกิดข้อผิดพลาด แต่ระบบจะไม่สนใจ

ใช้การแก้ไข RemoteViews ที่รันไทม์

ตั้งแต่ Android 12 เป็นต้นไป คุณจะใช้ประโยชน์จาก RemoteViews วิธีการต่างๆ ที่อนุญาตให้แก้ไขแอตทริบิวต์ RemoteViews ในรันไทม์ได้ ดูรายการเมธอดทั้งหมดที่เพิ่มได้ในข้อมูลอ้างอิง RemoteViews API

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้เมธอดบางรายการ

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList())

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP)

// Set the colors of a progress bar at runtime.
remoteView.setColorStateList(R.id.progress, "setProgressTintList", createProgressColorStateList());

// Specify exact sizes for margins.
remoteView.setViewLayoutMargin(R.id.text, RemoteViews.MARGIN_END, 8f, TypedValue.COMPLEX_UNIT_DP);