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

ตัวอย่างวิดเจ็ตที่สร้างขึ้นช่วยให้คุณสร้างตัวอย่างแบบไดนามิกที่ปรับตามโปรไฟล์ของผู้ใช้สำหรับวิดเจ็ต ซึ่งแสดงให้เห็นอย่างถูกต้องว่าวิดเจ็ตจะปรากฏบนหน้าจอหลักของผู้ใช้ อย่างไร โดยจะแสดงผ่าน 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_pre>v<iew"
/appwidge>t-provider

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

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

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

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

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

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

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

ส่วนนี้จะอธิบายแนวทางที่แนะนำสำหรับการแสดงหลายรายการในตัวอย่างวิดเจ็ตสำหรับวิดเจ็ตที่มีมุมมองคอลเล็กชัน ซึ่งก็คือวิดเจ็ตที่ใช้ 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=&>quot;match_parent"
        android:layout_height="wrap_content" /

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

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

    TextView android:text="@string/fake_item2"
        android:layout_width=&q>uo<t;match_paren>t"
        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_h>eight=<"wrap_content"

    TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height="wr>ap_con<tent"
        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="widgetC>o<ntent">; format="string" /
/resources

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

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

    TextView android:id="@id/title"
        android:layout_width="match_parent"
        android:layout_height=&q>uot;wr<ap_content"
        android:text="?widgetTitle" /

    TextView android:id="@id/content"
        android:layout_width="match_parent&>q<uot;
        >android:layout_height="wrap_content"
        android:text="?widgetContent" /
/LinearLayout

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

    <resources>

    <style name="Theme.Widget.List>Item"<;
        item name=&qu><ot;wi>dgetTitle<"/item
        item ><name=>"<;widge>tCont<ent"/item
    /style
    style name=&q>uot;Theme<.Widget.ListItem.Previe>w1"
   <     >item name<="widgetTitle"F>ake Title 1/it<em
  >     < item >name=<"widgetContent"Fake content 1/ite>m
    /st<yle
    style name=&quo>t;Theme.Widg<et.Li>stItem.Pr<eview2"
        item> name="wi<dgetT>itle&<quot;F>ak<e 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_heigh>t=&quo<t;wrap_content" ...

    include layo>ut=&qu<ot;@layout/widget_view" ... /

    include layout="@layout/widget_list_item"
        andro>id:the<me="@style/Theme.Widget.ListItem.Preview1" /

    include layout="@layout/widget_list_item>&q<uot;
        >android:theme="@style/Theme.Widget.ListItem.Preview2" /

/LinearLayout
ก่อนหน้า
สร้างวิดเจ็ตแอปด้วย "ข้อมูลโดยย่อ"
ถัดไป
ปักหมุดวิดเจ็ต Glance ในแอป