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