ابزاره‌های برنامه نماهای مینیاتوری برنامه هستند که می‌توانید آن‌ها را در برنامه‌های دیگر (مثلاً صفحه اصلی) جاسازی کنید و به‌روزرسانی‌های دوره‌ای دریافت کنید. این نماها در میانای کاربر به‌عنوان ابزاره شناخته می‌شوند و می‌توانید یکی از آن‌ها را با ارائه‌دهنده ابزاره برنامه (یا ارائه‌دهنده ابزاره) منتشر کنید. به مؤلفه برنامه‌ای که ابزاره‌های دیگر را در خود جای می‌دهد، میزبان ابزاره برنامه (یا میزبان ابزاره) می‌گویند. شکل ۱ نمونه‌ای از ابزارک موسیقی را نشان می‌دهد:
این سند نحوه انتشار ابزاره بااستفاده از ارائه‌دهنده ابزاره را شرح می‌دهد. برای
جزئیات درباره ایجاد AppWidgetHost خودتان برای میزبانی
ابزاره‌های برنامه، به ساخت میزبان ابزاره مراجعه کنید.
برای کسب اطلاعات درباره نحوه طراحی ابزاره، به نمای کلی ابزاره‌های برنامه مراجعه کنید.
اجزای ابزاره
برای ایجاد ابزاره، به مؤلفه‌های اصلی زیر نیاز دارید:
- شیء
AppWidgetProviderInfo - فراداده ابزاره را شرح می‌دهد، مانند چیدمان ابزاره، فواصل تجدید نظر، و کلاس
AppWidgetProvider.AppWidgetProviderInfoدر XML تعریف شده است، همان‌طور که در این سند شرح داده شده است. - کلاس
AppWidgetProvider - روش‌های اصلی را تعریف می‌کند
که به شما امکان می‌دهد به‌صورت برنامه‌نویسی‌شده با ابزاره تعامل داشته باشید. ازطریق آن،
وقتی ابزاره به‌روزرسانی، فعال، غیرفعال، یا
حذف می‌شود، پخش‌های همگانی دریافت می‌کنید.
AppWidgetProviderرا در مانیفست اعلام می‌کنید و سپس همان‌طور که در این سند شرح داده شده است، آن را پیاده‌سازی می‌کنید. - مشاهده چیدمان
- طرح‌بندی اولیه ابزاره را تعریف می‌کند. چیدمان در XML تعریف شده است، همان‌طور که در این سند شرح داده شده است.
شکل ۲ نشان می‌دهد که این مؤلفه‌ها چگونه در جریان پردازش کلی ابزاره برنامه قرار می‌گیرند.
اگر ابزاره شما به پیکربندی کاربر نیاز دارد، فعالیت پیکربندی ابزاره برنامه را پیاده‌سازی کنید. این فعالیت به کاربران اجازه می‌دهد تنظیمات ابزاره را تغییر دهند—برای مثال، منطقه زمانی برای ابزاره ساعت.
- از Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۱)، می‌توانید پیکربندی پیش‌فرضی ارائه دهید و به کاربران اجازه دهید بعداً ابزاره را دوباره پیکربندی کنند. برای جزئیات بیشتر، به استفاده از پیکربندی پیش‌فرض ابزاره و فعال کردن کاربران برای پیکربندی مجدد ابزاره‌های قرار داده‌شده مراجعه کنید.
- در Android نسخه ۱۱ (سطح API ۳۰) یا پایین‌تر، این فعالیت هربار که کاربر ابزاره را به صفحه اصلی اضافه می‌کند راه‌اندازی می‌شود.
همچنین بهبودهای زیر را توصیه می‌کنیم: چیدمان‌های ابزاره انعطاف‌پذیر، بهبودهای متفرقه، ابزاره‌های پیشرفته، ابزاره‌های مجموعه، و ساختن میزبان ابزاره.
اعلام کردن AppWidgetProviderInfo XML
تعریف تنظیمات فراداده (مانند اندازه‌های پیش‌فرض سلول، محدودیت‌های تغییر اندازه، و فرکانس‌های به‌روزرسانی) در هر دو ابزاره‌های مبتنی بر Glance و «نماهای» سنتی دقیقاً یکسان است.
برای آشنایی با نحوه تعریف و پیکربندی فایل XML فراداده، به بخش Compose-first اعلام بخش XML AppWidgetProviderInfo در اسناد Glance مراجعه کنید.
از کلاس AppWidgetProvider برای مدیریت همه‌فرستی‌های ابزارک استفاده کنید
مکانیک‌های گیرنده رویداد ثبت‌شده پلاتفرم، فیلترهای اعلام مانیفست، و
حلقه‌های رویداد چرخه حیات در زیر پلاتفرم یکپارچه شده‌اند. در توسعه Compose-first، این همه‌فرستی‌ها بااستفاده از پوشاننده GlanceAppWidgetReceiver سازمان‌دهی می‌شوند.
برای درک نحوه ثبت گیرنده در مانیفست و پیاده‌سازی لغوهای چرخه حیات سازگار با Hilt، به بخش استفاده از کلاس AppWidgetProvider برای مدیریت همه‌فرستی‌ها در مستندات Glance مراجعه کنید.
ایجاد کردن چیدمان ابزاره
باید چیدمان اولیه‌ای برای ابزاره‌تان در XML تعریف کنید و آن را در دایرکتوری res/layout/ پروژه ذخیره کنید. برای جزئیات، به رهنمودهای طراحی مراجعه کنید.
اگر با چیدمان‌ها آشنا باشید، ایجاد چیدمان ابزاره ساده است. بااین‌حال، توجه داشته باشید که چیدمان‌های ابزاره براساس
RemoteViews است که از همه انواع چیدمان یا ابزاره نمایشی پشتیبانی نمی‌کند.
نمی‌توانید از نماهای سفارشی یا زیرکلاس‌های نماهایی که توسط
RemoteViews پشتیبانی می‌شوند استفاده کنید.
RemoteViews همچنین از ViewStub پشتیبانی می‌کند که یک
View نامرئی با اندازه صفر است که می‌توانید از آن برای گسترش تنبل منابع چیدمان در زمان اجرا استفاده کنید.
پشتیبانی از رفتار باحالت
Android 12 بااستفاده از مؤلفه‌های موجود زیر، پشتیبانی از رفتار باحالت را اضافه می‌کند:
ابزاره هنوز بدون حالت است. برنامه شما باید وضعیت را ذخیره کند و برای رویدادهای تغییر وضعیت ثبت‌نام کند.
نمونه کد زیر نحوه پیاده‌سازی این مؤلفه‌ها را نشان می‌دهد.
// 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.
پیاده‌سازی گوشه‌های گرد
محاسبه پس‌زمینه بیرونی و شعاع‌های متناسب داخلی استاندارد و مشترک است. در توسعه Compose-first، این مورد را می‌توان به‌صورت پویا در Kotlin درکنار منابع زمینه سفارشی تنظیم کرد.
برای پیاده‌سازی شعاع گوشه یا راه‌اندازی سبک‌های پویا برای دستگاه‌های Android قدیمی‌تر، به بخش پیاده‌سازی گوشه‌های گرد در Compose-first در اسناد Glance مراجعه کنید.