เพิ่มตัวอย่างลงในเครื่องมือเลือกวิดเจ็ต

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

ตัวอย่างวิดเจ็ตที่สร้างขึ้นช่วยให้คุณสร้างตัวอย่างแบบไดนามิกที่ปรับเปลี่ยนในแบบของคุณสำหรับวิดเจ็ต ซึ่งแสดงลักษณะที่วิดเจ็ตจะปรากฏบนหน้าจอหลักของผู้ใช้อย่างถูกต้อง สำหรับ Android 15 ขึ้นไป ระบบจะแสดงตัวอย่างผ่าน Push API ซึ่งหมายความว่าแอปจะแสดงตัวอย่าง ณ จุดใดก็ได้ในวงจรโดยไม่ต้องรับคำขอที่ชัดเจนจากโฮสต์วิดเจ็ต

ดูข้อมูลเพิ่มเติมได้ที่เพิ่มประสิทธิภาพแอปด้วยข้อมูลอัปเดตแบบเรียลไทม์และวิดเจ็ตใน YouTube

เพิ่มตัวอย่างที่สร้างขึ้น

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

แอปสามารถใช้ setWidgetPreview ใน AppWidgetManager ได้ setWidgetPreview เป็น API ที่จำกัดอัตราคำขอเพื่อป้องกันการละเมิดและลดความกังวลเกี่ยวกับประสิทธิภาพของระบบ ขีดจำกัดเริ่มต้นคือประมาณ 2 ครั้งต่อชั่วโมง

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

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

ตัวอย่างต่อไปนี้จะโหลดทรัพยากรเลย์เอาต์วิดเจ็ต 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

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

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

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

นอกจากนี้ แอตทริบิวต์นี้ยังใช้เป็นตัวสำรองสำหรับตัวอย่างที่สร้างขึ้นหากคุณไม่ได้ตั้งค่าไว้โดยใช้ setWidgetPreview

สร้างตัวอย่างที่ถูกต้องซึ่งมีรายการแบบไดนามิก

รูปที่ 1: ตัวอย่างวิดเจ็ตที่ไม่แสดงรายการใดๆ

ส่วนนี้จะอธิบายแนวทางที่แนะนำสำหรับการแสดงหลายรายการในตัวอย่างวิดเจ็ตสำหรับวิดเจ็ตที่มีมุมมองคอลเล็กชัน ซึ่งก็คือวิดเจ็ตที่ใช้ ListView, GridView หรือ StackView ซึ่งจะมีผลกับตัวอย่างวิดเจ็ตที่ปรับขนาดได้ ไม่ใช่ตัวอย่างที่สร้างขึ้น

หากวิดเจ็ตใช้มุมมองใดมุมมองหนึ่งเหล่านี้ การสร้างตัวอย่างที่ปรับขนาดได้โดยระบุเลย์เอาต์วิดเจ็ตจริงใน previewLayout โดยตรงอาจทำให้ประสบการณ์การใช้งานแย่ลงเมื่อตัวอย่างวิดเจ็ตไม่แสดงรายการใดๆ กรณีนี้เกิดขึ้นเนื่องจากระบบจะตั้งค่าข้อมูลมุมมองคอลเล็กชันแบบไดนามิกที่รันไทม์ และจะมีลักษณะคล้ายกับรูปภาพที่แสดงในรูปที่ 1

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

• เลย์เอาต์วิดเจ็ตจริง
• มุมมองคอลเล็กชันตัวยึดตำแหน่งที่มีรายการจำลอง เช่น คุณสามารถจำลอง ListView โดยระบุตัวยึดตำแหน่ง LinearLayout ที่มีรายการปลอมหลายรายการ

หากต้องการแสดงตัวอย่างสำหรับ ListView ให้เริ่มด้วยไฟล์เลย์เอาต์แยกต่างหาก ดังนี้

// res/layout/widget_preview.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:background="@drawable/widget_background"
   android:orientation="vertical">

    // Include the actual widget layout that contains ListView.
    <include
        layout="@layout/widget_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content" />

    // The number of fake items you include depends on the values you provide
    // for minHeight or targetCellHeight in the AppWidgetProviderInfo
    // definition.

    <TextView android:text="@string/fake_item1"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

    <TextView android:text="@string/fake_item2"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginVertical="?attr/appWidgetInternalPadding" />

</LinearLayout>

ระบุไฟล์เลย์เอาต์ตัวอย่างเมื่อระบุแอตทริบิวต์ previewLayout ของข้อมูลเมตา AppWidgetProviderInfo คุณยังคงระบุเลย์เอาต์วิดเจ็ตจริงสำหรับแอตทริบิวต์ initialLayout และใช้เลย์เอาต์วิดเจ็ตจริงเมื่อสร้าง RemoteViews ขณะรันไทม์

<appwidget-provider
    previewLayout="@layout/widget_preview"
    initialLayout="@layout/widget_view" />

รายการที่ซับซ้อน

ตัวอย่างในส่วนก่อนหน้าแสดงรายการปลอม เนื่องจากรายการเป็นออบเจ็กต์ TextView การระบุรายการปลอมอาจซับซ้อนกว่าหากรายการมีเลย์เอาต์ที่ซับซ้อน

พิจารณารายการลิสต์ที่กำหนดไว้ใน widget_list_item.xml และประกอบด้วยออบเจ็กต์ TextView 2 รายการ ดังนี้

<LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

    <TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_title" />

    <TextView android:id="@id/content"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="@string/fake_content" />
</LinearLayout>

หากต้องการระบุรายการจำลอง คุณสามารถใส่เลย์เอาต์หลายครั้ง แต่จะทำให้รายการแต่ละรายการเหมือนกัน หากต้องการระบุรายการที่ไม่ซ้ำกัน ให้ทำตามขั้นตอนต่อไปนี้

1. สร้างชุดแอตทริบิวต์สำหรับค่าข้อความดังนี้

   <resources>
       <attr name="widgetTitle" format="string" />
       <attr name="widgetContent" format="string" />
   </resources>
   

2. ใช้แอตทริบิวต์เหล่านี้เพื่อตั้งค่าข้อความ

   <LinearLayout  xmlns:android="http://schemas.android.com/apk/res/android"
           android:layout_width="match_parent"
           android:layout_height="wrap_content">
   
       <TextView android:id="@id/title"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetTitle" />
   
       <TextView android:id="@id/content"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:text="?widgetContent" />
   </LinearLayout>
   

3. สร้างสไตล์ได้มากเท่าที่จำเป็นสำหรับการแสดงตัวอย่าง กำหนดค่าใหม่ในแต่ละสไตล์ดังนี้

   <resources>
   
       <style name="Theme.Widget.ListItem">
           <item name="widgetTitle"></item>
           <item name="widgetContent"></item>
       </style>
       <style name="Theme.Widget.ListItem.Preview1">
           <item name="widgetTitle">Fake Title 1</item>
           <item name="widgetContent">Fake content 1</item>
       </style>
       <style name="Theme.Widget.ListItem.Preview2">
           <item name="widgetTitle">Fake title 2</item>
           <item name="widgetContent">Fake content 2</item>
       </style>
   
   </resources>
   

4. ใช้สไตล์กับรายการจำลองในเลย์เอาต์ตัวอย่าง ดังนี้

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
      android:layout_width="match_parent"
      android:layout_height="wrap_content" ...>
   
       <include layout="@layout/widget_view" ... />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview1" />
   
       <include layout="@layout/widget_list_item"
           android:theme="@style/Theme.Widget.ListItem.Preview2" />
   
   </LinearLayout>