یک ویجت ساده ایجاد کنید

ویجت‌های برنامه، نماهای مینیاتوری برنامه هستند که می‌توانید در برنامه‌های دیگر - مانند صفحه اصلی - جاسازی کنید و به‌روزرسانی‌های دوره‌ای را دریافت کنید. این نماها به عنوان ابزارک در رابط کاربری نامیده می‌شوند و می‌توانید یکی از آنها را با ارائه‌دهنده ابزارک برنامه (یا ارائه‌دهنده ویجت ) منتشر کنید. جزء برنامه ای که ویجت های دیگر را نگه می دارد، میزبان ویجت برنامه (یا میزبان ویجت ) نامیده می شود. شکل 1 نمونه ویجت موسیقی را نشان می دهد:

نمونه ای از ویجت موسیقی
شکل 1. نمونه ای از ویجت موسیقی.

این سند نحوه انتشار یک ویجت با استفاده از ارائه دهنده ویجت را توضیح می دهد. برای جزئیات در مورد ایجاد AppWidgetHost خود برای میزبانی ابزارک های برنامه، به ساخت میزبان ویجت مراجعه کنید.

برای کسب اطلاعات در مورد نحوه طراحی ویجت خود، به نمای کلی ابزارک های برنامه مراجعه کنید.

اجزای ویجت

برای ایجاد یک ویجت، به اجزای اصلی زیر نیاز دارید:

شی AppWidgetProviderInfo
فراداده یک ویجت را توصیف می کند، مانند طرح بندی ویجت، فرکانس به روز رسانی، و کلاس AppWidgetProvider . AppWidgetProviderInfo در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.
کلاس AppWidgetProvider
روش‌های اساسی را تعریف می‌کند که به شما امکان می‌دهد از طریق برنامه‌نویسی با ویجت ارتباط برقرار کنید. از طریق آن، هنگامی که ویجت به روز می شود، فعال می شود، غیرفعال می شود یا حذف می شود، پخش ها را دریافت می کنید. شما AppWidgetProvider در مانیفست اعلام می کنید و سپس آن را اجرا می کنید ، همانطور که در این سند توضیح داده شده است.
نمایش طرح
طرح اولیه ویجت را تعریف می کند. طرح در XML تعریف شده است، همانطور که در این سند توضیح داده شده است.

شکل 2 نشان می دهد که چگونه این مؤلفه ها در جریان کلی پردازش ویجت برنامه قرار می گیرند.

جریان پردازش ویجت برنامه
شکل 2. جریان پردازش ویجت برنامه.

اگر ویجت شما به پیکربندی کاربر نیاز دارد، فعالیت پیکربندی ویجت برنامه را اجرا کنید. این فعالیت به کاربران امکان می‌دهد تنظیمات ویجت را تغییر دهند - به عنوان مثال، منطقه زمانی ویجت ساعت.

ما همچنین پیشرفت‌های زیر را توصیه می‌کنیم: طرح‌بندی ویجت‌های انعطاف‌پذیر ، پیشرفت‌های متفرقه ، ویجت‌های پیشرفته ، ویجت‌های مجموعه ، و ساخت میزبان ویجت .

AppWidgetProviderInfo XML را اعلام کنید

شی AppWidgetProviderInfo کیفیت های اساسی یک ویجت را تعریف می کند. شی AppWidgetProviderInfo را در یک فایل منبع XML با استفاده از یک عنصر <appwidget-provider> تعریف کنید و آن را در پوشه res/xml/ پروژه ذخیره کنید.

این در مثال زیر نشان داده شده است:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

ویژگی های اندازه ویجت

صفحه اصلی پیش‌فرض، ویجت‌ها را بر اساس شبکه‌ای از سلول‌ها که ارتفاع و عرض مشخصی دارند، در پنجره خود قرار می‌دهد. بیشتر صفحه‌های اصلی تنها به ابزارک‌ها اجازه می‌دهند اندازه‌هایی را بگیرند که مضرب صحیح سلول‌های شبکه هستند - برای مثال، دو سلول به صورت افقی و سه سلول به صورت عمودی.

ویژگی‌های اندازه ویجت به شما امکان می‌دهند یک اندازه پیش‌فرض برای ویجت خود تعیین کنید و محدوده‌های پایین و بالایی را برای اندازه ویجت ارائه دهید. در این زمینه، اندازه پیش‌فرض یک ویجت، اندازه‌ای است که ویجت زمانی که برای اولین بار به صفحه اصلی اضافه می‌شود، می‌گیرد.

جدول زیر ویژگی های <appwidget-provider> مربوط به اندازه ویجت را شرح می دهد:

صفات و شرح
targetCellWidth و targetCellHeight (اندروید 12)، minWidth و minHeight
  • با شروع در اندروید 12، ویژگی‌های targetCellWidth و targetCellHeight اندازه پیش‌فرض ویجت را از نظر سلول‌های شبکه مشخص می‌کنند. این ویژگی‌ها در اندروید 11 و پایین‌تر نادیده گرفته می‌شوند و اگر صفحه اصلی از طرح‌بندی مبتنی بر شبکه پشتیبانی نمی‌کند، می‌توان آنها را نادیده گرفت.
  • ویژگی‌های minWidth و minHeight اندازه پیش‌فرض ویجت را در dp مشخص می‌کنند. اگر مقادیر حداقل عرض یا ارتفاع ویجت با ابعاد سلول‌ها مطابقت نداشته باشد، مقادیر به نزدیکترین اندازه سلول گرد می‌شوند.
توصیه می‌کنیم هر دو مجموعه از ویژگی‌ها - targetCellWidth و targetCellHeight ، و minWidth و minHeight - را مشخص کنید تا اگر دستگاه کاربر از targetCellWidth و targetCellHeight پشتیبانی نمی‌کند، برنامه شما بتواند به استفاده minWidth و minHeight بازگردد. در صورت پشتیبانی، ویژگی‌های targetCellWidth و targetCellHeight بر ویژگی‌های minWidth و minHeight اولویت دارند.
minResizeWidth و minResizeHeight حداقل اندازه مطلق ویجت را مشخص کنید. این مقادیر اندازه ای را که ویجت در آن ناخوانا یا غیرقابل استفاده است مشخص می کند. استفاده از این ویژگی ها به کاربر امکان می دهد اندازه ویجت را به اندازه ای کوچکتر از اندازه پیش فرض ویجت تغییر دهد. ویژگی minResizeWidth در صورتی که بزرگتر از minWidth باشد یا تغییر اندازه افقی فعال نباشد نادیده گرفته می شود. resizeMode ببینید. به همین ترتیب، ویژگی minResizeHeight در صورتی که بزرگتر از minHeight باشد یا تغییر اندازه عمودی فعال نباشد نادیده گرفته می شود.
maxResizeWidth و maxResizeHeight حداکثر اندازه توصیه شده ویجت را مشخص کنید. اگر مقادیر مضربی از ابعاد سلول شبکه نباشند، به نزدیکترین اندازه سلول گرد می شوند. مشخصه maxResizeWidth اگر کوچکتر از minWidth باشد یا تغییر اندازه افقی فعال نباشد نادیده گرفته می شود. resizeMode ببینید. به همین ترتیب، ویژگی maxResizeHeight در صورتی که بزرگتر از minHeight باشد یا تغییر اندازه عمودی فعال نباشد نادیده گرفته می شود. در اندروید 12 معرفی شد.
resizeMode قوانینی را مشخص می کند که با آن می توان اندازه یک ویجت را تغییر داد. می توانید از این ویژگی برای تغییر اندازه ویجت های صفحه اصلی به صورت افقی، عمودی یا در هر دو محور استفاده کنید. کاربران یک ویجت را لمس کرده و نگه می دارند تا دسته های تغییر اندازه آن را نشان دهند، سپس دستگیره های افقی یا عمودی را برای تغییر اندازه آن در شبکه طرح بندی بکشند. مقادیر برای ویژگی resizeMode شامل horizontal ، vertical ، و none است. برای اعلام یک ویجت به عنوان قابل تغییر اندازه افقی و عمودی، از horizontal|vertical استفاده کنید.

مثال

برای نشان دادن اینکه چگونه ویژگی های جدول قبل بر اندازه ویجت تأثیر می گذارد، مشخصات زیر را در نظر بگیرید:

  • یک سلول شبکه ای 30 dp عرض و 50 dp ارتفاع دارد.
  • مشخصات ویژگی زیر ارائه شده است:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

شروع با اندروید 12:

از ویژگی های targetCellWidth و targetCellHeight به عنوان اندازه پیش فرض ویجت استفاده کنید.

اندازه ویجت به طور پیش فرض 2x2 است. اندازه ویجت را می توان به 2x1 یا تا 4x3 تغییر داد.

اندروید 11 و پایین تر:

از ویژگی های minWidth و minHeight برای محاسبه اندازه پیش فرض ویجت استفاده کنید.

عرض پیش فرض = Math.ceil(80 / 30) = 3

ارتفاع پیش فرض = Math.ceil(80 / 50) = 2

اندازه ویجت به طور پیش فرض 3x2 است. اندازه ویجت را می توان به 2x1 یا تا تمام صفحه تغییر داد.

ویژگی های ویجت اضافی

جدول زیر ویژگی های <appwidget-provider> مربوط به کیفیت هایی غیر از اندازه ویجت را توضیح می دهد.

صفات و شرح
updatePeriodMillis تعیین می کند که فریم ورک ویجت هر چند وقت یکبار از AppWidgetProvider درخواست به روز رسانی می کند با فراخوانی متد onUpdate() callback. تضمین نمی‌شود که به‌روزرسانی واقعی با این مقدار دقیقاً به موقع انجام شود، و توصیه می‌کنیم تا حد امکان به ندرت - حداکثر یک بار در ساعت - برای صرفه‌جویی در باتری به‌روزرسانی کنید. برای فهرست کامل ملاحظات برای انتخاب دوره به‌روزرسانی مناسب، به بهینه‌سازی‌ها برای به‌روزرسانی محتوای ویجت مراجعه کنید.
initialLayout به منبع طرح‌بندی که طرح‌بندی ویجت را تعریف می‌کند، اشاره می‌کند.
configure فعالیتی را تعریف می‌کند که وقتی کاربر ویجت را اضافه می‌کند، راه‌اندازی می‌شود و به او اجازه می‌دهد خصوصیات ویجت را پیکربندی کند. به فعال کردن کاربران برای پیکربندی ابزارک ها مراجعه کنید. با شروع Android 12، برنامه شما می تواند از پیکربندی اولیه صرف نظر کند. برای جزئیات بیشتر به استفاده از پیکربندی پیش فرض ویجت مراجعه کنید.
description شرحی را برای انتخابگر ویجت برای نمایش ویجت شما مشخص می کند. در اندروید 12 معرفی شد.
previewLayout (اندروید 12) و previewImage (اندروید 11 و پایین تر)
  • با شروع در Android 12، ویژگی previewLayout یک پیش‌نمایش مقیاس‌پذیر را مشخص می‌کند که شما آن را به‌عنوان یک طرح‌بندی XML با اندازه پیش‌فرض ویجت ارائه می‌دهید. در حالت ایده آل، طرح XML مشخص شده به عنوان این ویژگی، همان طرح بندی XML به عنوان ویجت واقعی با مقادیر پیش فرض واقعی است.
  • در اندروید 11 یا پایین‌تر، ویژگی previewImage پیش‌نمایش ظاهری ویجت را پس از پیکربندی مشخص می‌کند که کاربر هنگام انتخاب ویجت برنامه می‌بیند. اگر ارائه نشده باشد، کاربر در عوض نماد راه‌انداز برنامه شما را می‌بیند. این فیلد مربوط به ویژگی android:previewImage در عنصر <receiver> در فایل AndroidManifest.xml است.
توجه: توصیه می‌کنیم هر دو ویژگی previewImage و previewLayout را مشخص کنید تا اگر دستگاه کاربر از previewLayout پشتیبانی نمی‌کند، برنامه شما بتواند به استفاده از previewImage بازگردد. برای جزئیات بیشتر، به سازگاری به عقب با پیش نمایش ویجت های مقیاس پذیر مراجعه کنید.
autoAdvanceViewId شناسه نمای زیرنمای ویجت را مشخص می کند که توسط میزبان ویجت به طور خودکار پیشرفته می شود.
widgetCategory اعلام می‌کند که آیا ویجت شما می‌تواند در صفحه اصلی ( home_screen )، صفحه قفل ( keyguard )، یا هر دو نمایش داده شود. برای Android نسخه 5.0 و بالاتر، فقط home_screen معتبر است.
widgetFeatures ویژگی های پشتیبانی شده توسط ویجت را اعلام می کند. به عنوان مثال، اگر می‌خواهید وقتی کاربر ویجت را اضافه می‌کند، از پیکربندی پیش‌فرض خود استفاده کند، هر دو پرچم configuration_optional و reconfigurable را مشخص کنید. این کار راه اندازی فعالیت پیکربندی را پس از افزودن ویجت توسط کاربر دور می زند. کاربر همچنان می تواند پس از آن ویجت را دوباره پیکربندی کند .

از کلاس AppWidgetProvider برای مدیریت پخش ویجت استفاده کنید

کلاس AppWidgetProvider پخش ویجت را مدیریت می کند و ویجت را در پاسخ به رویدادهای چرخه حیات ویجت به روز می کند. بخش های زیر نحوه اعلان AppWidgetProvider در مانیفست و سپس پیاده سازی آن را توضیح می دهد.

یک ویجت را در مانیفست اعلام کنید

ابتدا طبق مثال زیر، کلاس AppWidgetProvider در فایل AndroidManifest.xml برنامه خود اعلام کنید:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

عنصر <receiver> به ویژگی android:name نیاز دارد که AppWidgetProvider مورد استفاده ویجت را مشخص می کند. مؤلفه نباید صادر شود مگر اینکه یک فرآیند جداگانه به AppWidgetProvider شما ارسال شود، که معمولاً اینطور نیست.

عنصر <intent-filter> باید دارای عنصر <action> با ویژگی android:name باشد. این ویژگی مشخص می کند که AppWidgetProvider پخش ACTION_APPWIDGET_UPDATE را می پذیرد. این تنها پخشی است که باید به صراحت اعلام کنید. AppWidgetManager به طور خودکار سایر پخش‌های ویجت را در صورت لزوم به AppWidgetProvider ارسال می‌کند.

عنصر <meta-data> منبع AppWidgetProviderInfo را مشخص می کند و به ویژگی های زیر نیاز دارد:

  • android:name : نام ابرداده را مشخص می کند. از android.appwidget.provider برای شناسایی داده ها به عنوان توصیفگر AppWidgetProviderInfo استفاده کنید.
  • android:resource : محل منبع AppWidgetProviderInfo را مشخص می کند.

کلاس AppWidgetProvider را پیاده سازی کنید

کلاس AppWidgetProvider BroadcastReceiver به عنوان یک کلاس راحت برای مدیریت پخش ویجت گسترش می دهد. فقط پخش رویدادهایی را دریافت می کند که مربوط به ویجت هستند، مانند زمانی که ویجت به روز می شود، حذف می شود، فعال و غیرفعال می شود. هنگامی که این رویدادهای پخش رخ می دهند، متدهای AppWidgetProvider زیر فراخوانی می شوند:

onUpdate()
این برای به روز رسانی ویجت در فواصل زمانی مشخص شده توسط ویژگی updatePeriodMillis در AppWidgetProviderInfo نامیده می شود. برای اطلاعات بیشتر به جدولی که ویژگی‌های ویجت اضافی را در این صفحه توضیح می‌دهد، مراجعه کنید.
این روش زمانی که کاربر ویجت را اضافه می‌کند نیز نامیده می‌شود، بنابراین تنظیمات ضروری مانند تعریف کنترل‌کننده‌های رویداد برای View اشیاء یا شروع کارها برای بارگیری داده‌ها برای نمایش در ویجت را انجام می‌دهد. با این حال، اگر یک فعالیت پیکربندی را بدون پرچم configuration_optional اعلام کنید، این روش زمانی که کاربر ویجت را اضافه می کند فراخوانی نمی شود، اما برای به روز رسانی های بعدی فراخوانی می شود . این مسئولیت فعالیت پیکربندی است که پس از تکمیل پیکربندی، اولین به روز رسانی را انجام دهد. برای اطلاعات بیشتر به فعال کردن کاربران برای پیکربندی ابزارک‌های برنامه رجوع کنید.
مهم ترین callback onUpdate() است. برای اطلاعات بیشتر به Handle events با کلاس onUpdate() در این صفحه مراجعه کنید.
onAppWidgetOptionsChanged()

هنگامی که ویجت برای اولین بار قرار می گیرد و هر زمانی که اندازه ویجت تغییر می کند، این نام خوانده می شود. از این تماس برای نمایش یا پنهان کردن محتوا بر اساس محدوده اندازه ویجت استفاده کنید. با فراخوانی getAppWidgetOptions() که Bundle شامل موارد زیر را برمی‌گرداند، محدوده‌های اندازه را دریافت کنید - و با شروع Android 12، فهرستی از اندازه‌های احتمالی که یک نمونه ویجت می‌تواند بگیرد.

  • OPTION_APPWIDGET_MIN_WIDTH : شامل کران پایینی در عرض، به واحدهای dp، نمونه ویجت است.
  • OPTION_APPWIDGET_MIN_HEIGHT : شامل کران پایینی در ارتفاع، به واحدهای dp، نمونه ویجت است.
  • OPTION_APPWIDGET_MAX_WIDTH : شامل کران بالایی در عرض، به واحدهای dp، نمونه ویجت است.
  • OPTION_APPWIDGET_MAX_HEIGHT : شامل کران بالای ارتفاع، به واحدهای dp، نمونه ویجت است.
  • OPTION_APPWIDGET_SIZES : حاوی لیستی از اندازه های ممکن ( List<SizeF> ) در واحدهای dp است که یک نمونه ویجت می تواند بگیرد. در اندروید 12 معرفی شد.
onDeleted(Context, int[])

هر بار که یک ویجت از میزبان ویجت حذف می شود، این نام خوانده می شود.

onEnabled(Context)

هنگامی که یک نمونه از ویجت برای اولین بار ایجاد می شود، این نام خوانده می شود. به عنوان مثال، اگر کاربر دو نمونه از ویجت شما را اضافه کند، این تنها بار اول فراخوانی می شود. اگر نیاز به باز کردن یک پایگاه داده جدید یا انجام تنظیمات دیگری دارید که فقط باید یک بار برای همه نمونه های ویجت انجام شود، این مکان مناسبی برای انجام آن است.

onDisabled(Context)

این زمانی فراخوانی می شود که آخرین نمونه ویجت شما از میزبان ویجت حذف شود. این جایی است که شما هر کاری را که در onEnabled(Context) انجام می شود، مانند حذف یک پایگاه داده موقت، پاک می کنید.

onReceive(Context, Intent)

این برای هر پخش و قبل از هر یک از روش های برگشت تماس قبلی فراخوانی می شود. شما معمولاً نیازی به پیاده‌سازی این روش ندارید، زیرا اجرای پیش‌فرض AppWidgetProvider همه پخش‌های ویجت را فیلتر می‌کند و روش‌های قبلی را در صورت لزوم فراخوانی می‌کند.

شما باید پیاده سازی کلاس AppWidgetProvider خود را به عنوان گیرنده پخش با استفاده از عنصر <receiver> در AndroidManifest اعلام کنید. برای اطلاعات بیشتر به اعلام ویجت در مانیفست در این صفحه مراجعه کنید.

رویدادها را با کلاس onUpdate() مدیریت کنید

مهم ترین فراخوانی AppWidgetProvider ، onUpdate() است، زیرا زمانی که هر ویجت به یک میزبان اضافه می شود، فراخوانی می شود، مگر اینکه از یک فعالیت پیکربندی بدون پرچم configuration_optional استفاده کنید. اگر ویجت شما رویدادهای تعامل کاربر را می پذیرد، کنترل کننده های رویداد را در این پاسخ به تماس ثبت کنید. اگر ویجت شما فایل‌ها یا پایگاه داده‌های موقتی ایجاد نمی‌کند، یا کارهای دیگری که نیاز به پاکسازی دارند انجام نمی‌دهد، ممکن است onUpdate() تنها روشی باشد که باید تعریف کنید.

به عنوان مثال، اگر ویجتی با دکمه ای می خواهید که با ضربه زدن یک فعالیت را راه اندازی کند، می توانید از پیاده سازی زیر AppWidgetProvider استفاده کنید:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}
public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

این AppWidgetProvider تنها متد onUpdate() را تعریف می‌کند و از آن برای ایجاد یک PendingIntent استفاده می‌کند که یک Activity را راه‌اندازی می‌کند و آن را با استفاده از setOnClickPendingIntent(int, PendingIntent) به دکمه ویجت متصل می‌کند. این شامل یک حلقه است که از طریق هر ورودی در appWidgetIds تکرار می‌شود، که آرایه‌ای از شناسه‌ها است که هر ویجت ایجاد شده توسط این ارائه‌دهنده را شناسایی می‌کند. اگر کاربر بیش از یک نمونه از ویجت را ایجاد کند، همه آنها به طور همزمان به روز می شوند. با این حال، تنها یک برنامه updatePeriodMillis برای همه نمونه‌های ویجت مدیریت می‌شود. به عنوان مثال، اگر زمان‌بندی به‌روزرسانی هر دو ساعت یک بار تعریف شده باشد، و یک نمونه دوم از ویجت یک ساعت پس از اولین مورد اضافه شود، هر دو در دوره تعریف‌شده توسط دوره اول و دوم به‌روزرسانی می‌شوند. نادیده گرفته می شود. هر دوی آنها هر دو ساعت یک بار به روز می شوند، نه هر ساعت.

برای جزئیات بیشتر به کلاس نمونه ExampleAppWidgetProvider.java مراجعه کنید.

اهداف پخش ویجت را دریافت کنید

AppWidgetProvider یک کلاس راحتی است. اگر می‌خواهید پخش‌های ویجت را مستقیماً دریافت کنید، می‌توانید BroadcastReceiver خود را پیاده‌سازی کنید یا پاسخ تماس onReceive(Context,Intent) را لغو کنید. اهدافی که باید به آنها اهمیت دهید موارد زیر است:

طرح بندی ویجت را ایجاد کنید

شما باید یک طرح اولیه برای ویجت خود در XML تعریف کنید و آن را در دایرکتوری res/layout/ پروژه ذخیره کنید. برای جزئیات به دستورالعمل های طراحی مراجعه کنید.

اگر با طرح‌بندی‌ها آشنایی دارید، ایجاد طرح‌بندی ویجت ساده است. با این حال، توجه داشته باشید که طرح‌بندی ویجت‌ها بر اساس RemoteViews هستند که از هر نوع طرح‌بندی یا ویجت مشاهده پشتیبانی نمی‌کنند. شما نمی توانید از نماهای سفارشی یا زیر کلاس های نماهایی که توسط RemoteViews پشتیبانی می شوند استفاده کنید.

RemoteViews همچنین از ViewStub پشتیبانی می کند، که یک View نامرئی و با اندازه صفر است که می توانید از آن برای افزایش تنبلی منابع طرح در زمان اجرا استفاده کنید.

حمایت از رفتار دولتی

Android 12 با استفاده از مؤلفه‌های موجود زیر، از رفتار حالت‌پذیر پشتیبانی می‌کند:

ویجت هنوز بدون وضعیت است. برنامه شما باید وضعیت را ذخیره کند و برای رویدادهای تغییر وضعیت ثبت نام کند.

نمونه ای از ویجت لیست خرید که رفتار حالتی را نشان می دهد
شکل 3. نمونه ای از رفتار حالت دار.

مثال کد زیر نحوه پیاده سازی این کامپوننت ها را نشان می دهد.

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)
// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

دو طرح‌بندی ارائه دهید: یکی دستگاه‌های دارای Android 12 یا بالاتر در res/layout-v31 و دیگری هدف قرار دادن Android 11 یا پایین‌تر در پوشه res/layout پیش‌فرض.

گوشه های گرد را اجرا کنید

Android 12 پارامترهای سیستم زیر را برای تنظیم شعاع گوشه های گرد ویجت شما معرفی می کند:

  • system_app_widget_background_radius : شعاع گوشه پس‌زمینه ویجت، که هرگز بزرگ‌تر از 28 dp نیست.

  • system_app_widget_inner_radius : شعاع گوشه هر نمای داخل ویجت. این دقیقاً 8 dp کمتر از شعاع پس‌زمینه است تا در هنگام استفاده از یک لایه‌بندی 8 dp به خوبی تراز شود.

مثال زیر ویجتی را نشان می دهد که از system_app_widget_background_radius برای گوشه ویجت و system_app_widget_inner_radius برای نماهای داخل ویجت استفاده می کند.

ویجتی که شعاع پس‌زمینه ویجت و نماهای داخل ویجت را نشان می‌دهد
شکل 4. گوشه های گرد.

1 گوشه ویجت.

2 گوشه نما در داخل ویجت.

ملاحظات مهم برای گوشه های گرد

  • راه‌اندازهای شخص ثالث و سازندگان دستگاه می‌توانند پارامتر system_app_widget_background_radius را نادیده بگیرند تا کمتر از 28 dp باشد. پارامتر system_app_widget_inner_radius همیشه 8 dp کمتر از مقدار system_app_widget_background_radius است.
  • اگر ویجت شما از @android:id/background استفاده نمی‌کند یا پس‌زمینه‌ای را تعریف نمی‌کند که محتوای آن را بر اساس طرح کلی برش می‌دهد - با تنظیم android:clipToOutline روی true - راه‌انداز به‌طور خودکار پس‌زمینه را شناسایی می‌کند و ویجت را با استفاده از یک مستطیل با گوشه‌های گرد برش می‌دهد. تا 16 dp اطمینان حاصل کنید که ویجت شما با Android 12 سازگار است .

برای سازگاری ویجت با نسخه‌های قبلی Android، توصیه می‌کنیم ویژگی‌های سفارشی را تعریف کنید و از یک تم سفارشی برای لغو آنها برای Android 12 استفاده کنید، همانطور که در فایل‌های XML نمونه زیر نشان داده شده است:

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>
<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>
<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />