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

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

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

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

ตั้งค่าแอปสำหรับการแสดงตัวอย่างวิดเจ็ตที่สร้างขึ้น

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

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

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

สำหรับวิดเจ็ตที่สร้างด้วย Jetpack Glance ให้ทำดังนี้

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

2. โทรหา GlanceAppWidgetManager.setWidgetPreviews เพื่อสร้างและเผยแพร่ ตัวอย่าง

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

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

การแก้ปัญหาตัวอย่างที่สร้างขึ้น

ปัญหาที่พบบ่อยคือหลังจากสร้างตัวอย่างแล้ว รูปภาพ ไอคอน หรือ Composable อื่นๆ อาจหายไปจากรูปภาพตัวอย่างเมื่อเทียบกับขนาดการวางของวิดเจ็ต ขนาดการวางนี้กำหนดโดย targetCellWidth และ targetCellHeight หากระบุ หรือโดย minWidth และ minHeight ใน ไฟล์ข้อมูลผู้ให้บริการวิดเจ็ตแอป

ซึ่งเกิดขึ้นเนื่องจาก Android จะแสดงผลเฉพาะ Composable ที่มองเห็นได้ที่ขนาดขั้นต่ำของวิดเจ็ตโดยค่าเริ่มต้น กล่าวคือ Android จะตั้งค่า previewSizeMode เป็น SizeMode.Single โดยค่าเริ่มต้น โดยจะใช้ android:minHeight และ android:minWidth ใน XML ข้อมูลผู้ให้บริการวิดเจ็ตแอปเพื่อกำหนด Composable ที่จะวาด

หากต้องการแก้ไขปัญหานี้ ให้ลบล้าง previewSizeMode ใน GlanceAppWidget และตั้งค่าเป็น SizeMode.Responsive โดยระบุชุดค่า DpSize ซึ่งจะบอก Android ถึงขนาดเลย์เอาต์ทั้งหมดที่ต้องแสดงตัวอย่าง เพื่อให้มั่นใจว่าองค์ประกอบทั้งหมด จะแสดงอย่างถูกต้อง

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

สร้างตัวอย่างที่อัปเดตแล้วโดยไม่ต้องใช้ 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

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

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

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

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

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

หากวิดเจ็ตใช้มุมมองใดมุมมองหนึ่งเหล่านี้ การสร้างตัวอย่างที่ปรับขนาดได้โดยระบุเลย์เอาต์วิดเจ็ตจริงโดยตรงจะทำให้ประสบการณ์การใช้งานแย่ลงเมื่อตัวอย่างวิดเจ็ตไม่แสดงรายการใดๆ ซึ่งเกิดขึ้นเนื่องจากมีการตั้งค่าข้อมูลมุมมองคอลเล็กชัน แบบไดนามิกในขณะรันไทม์ และมีลักษณะคล้ายกับรูปภาพที่แสดงในรูปที่ 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_previe"
    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>