ساختن میزبان ابزاره

صفحه اصلی Android که در اکثر دستگاه‌های مجهز به Android دردسترس است به کاربر امکان می‌دهد ابزاره‌های برنامه (یا ابزاره‌ها) را برای دسترسی سریع به محتوا جاسازی کند. اگر درحال ساختن جایگزین صفحه اصلی یا برنامه مشابهی هستید، می‌توانید با پیاده‌سازی AppWidgetHost به کاربر اجازه دهید ابزاره‌ها را جاسازی کند. این چیزی نیست که اکثر برنامه‌ها نیاز به انجام آن داشته باشند، اما اگر میزبان خودتان را ایجاد می‌کنید، مهم است که تعهدات قراردادی که میزبان به‌طور ضمنی با آن موافقت می‌کند را درک کنید.

این صفحه بر مسئولیت‌های مربوط به پیاده‌سازی AppWidgetHost سفارشی تمرکز دارد. برای نمونه‌ای خاص از نحوه پیاده‌سازی AppWidgetHost، به کد منبع صفحه اصلی Android نگاه کنید LauncherAppWidgetHost.

در اینجا مروری بر کلاس‌ها و مفاهیم کلیدی درگیر در پیاده‌سازی AppWidgetHost سفارشی ارائه شده است:

• میزبان ابزاره برنامه: AppWidgetHost تعامل با سرویس AppWidget را برای برنامه‌هایی که ابزاره‌ها را در واسط کاربر خود جاسازی می‌کنند فراهم می‌کند. AppWidgetHost باید شناسه منحصربه‌فردی در بسته میزبان داشته باشد. این شناسه در همه موارد استفاده از میزبان حفظ می‌شود. شناسه معمولاً مقدار کدبندی‌شده‌ای است که در برنامه‌تان اختصاص می‌دهید.

• شناسه ابزاره برنامه: هر نمونه ابزاره در زمان پیونددهی شناسه یکتایی دریافت می‌کند. به bindAppWidgetIdIfAllowed() و برای جزئیات بیشتر، به بخش پیوند دادن ابزارک‌ها در ادامه مراجعه کنید. میزبان شناسه یکتا را بااستفاده از allocateAppWidgetId() دریافت می‌کند. این شناسه در طول عمر ابزاره تا زمانی که از میزبان حذف شود باقی می‌ماند. هر وضعیت خاص میزبان—مثل اندازه و مکان ابزارک—باید توسط بسته میزبانی حفظ شود و با شناسه ابزارک برنامه مرتبط شود.

• نمای میزبان ابزاره برنامه: آن را به‌عنوان چارچوبیAppWidgetHostView درنظر بگیرید که ابزاره در آن پیچیده می‌شود هرگاه نیاز باشد نمایش داده شود. هر بار که میزبان ابزارک را ازهم باز می‌کند، ابزارک با AppWidgetHostView مرتبط می‌شود.

  • به‌طور پیش‌فرض، سیستم AppWidgetHostView را ایجاد می‌کند، اما میزبان می‌تواند با گسترش آن، زیرکلاس خود را از AppWidgetHostView ایجاد کند.
  • از Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۱)، AppWidgetHostView روش‌های setColorResources() و resetColorResources() را برای مدیریت رنگ‌های سرریز پویا معرفی می‌کند. میزبان مسئول ارائه رنگ‌ها به این روش‌ها است.

• بسته گزینه‌ها: AppWidgetHost از بسته گزینه‌ها برای انتقال اطلاعات به AppWidgetProvider درباره نحوه نمایش ابزارک استفاده می‌کند—برای مثال، فهرست محدوده‌های اندازه—و اینکه ابزارک در صفحه قفل است یا صفحه اصلی. این اطلاعات به AppWidgetProvider امکان می‌دهد محتوا و ظاهر ابزارک را براساس نحوه و مکان نمایش آن سفارشی‌سازی کند. برای اصلاح کردن دسته‌ای از ابزاره‌ها می‌توانید از updateAppWidgetOptions() و updateAppWidgetSize() استفاده کنید. هر دو روش باعث راه‌اندازی onAppWidgetOptionsChanged() بازخوانی به AppWidgetProvider می‌شوند.

ابزاره‌های صحافی

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

میاناهای برنامه‌سازی کاربردی پیونددهنده همچنین به میزبان امکان می‌دهند واسط کاربر سفارشی برای پیونددهی ارائه دهد. برای استفاده از این فرایند، برنامه‌تان باید اجازه BIND_APPWIDGET را در مانیفست میزبان تعریف کند:

<uses-permission android:name="android.permission.BIND_APPWIDGET" />

اما این فقط اولین قدم است. در زمان اجرا، کاربر باید صریحاً به برنامه شما اجازه دهد ابزاره‌ای به میزبان اضافه کند. برای آزمایش اینکه آیا برنامه شما اجازه افزودن ابزاره را دارد یا نه، از روش bindAppWidgetIdIfAllowed() استفاده کنید. اگر bindAppWidgetIdIfAllowed() مقدار false را برگرداند، برنامه شما باید گفتگویی نمایش دهد که از کاربر بخواهد اجازه دهد: «اجازه دادن» برای افزودن ابزاره فعلی، یا «همیشه اجازه دادن» برای پوشش دادن همه افزوده‌های ابزاره آینده.

این تکه‌کد نمونه‌ای از نحوه نمایش دادن چارگوش گفتگو ارائه می‌دهد:

val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.provider)
    // This is the options bundle described in the preceding section.
    putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)
}
startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Host.kt

میزبان باید بررسی کند که آیا ابزارکی که کاربر اضافه می‌کند نیاز به پیکربندی دارد یا نه. برای اطلاعات بیشتر، فعال کردن کاربران برای پیکربندی ابزارک‌های برنامه را ببینید.

مسئولیت‌های میزبان

بااستفاده از فراداده AppWidgetProviderInfo می‌توانید تعدادی از تنظیمات پیکربندی را برای ابزاره‌ها مشخص کنید. گزینه‌های پیکربندی را که در بخش‌های زیر با جزئیات بیشتری پوشش داده شده است می‌توانید از AppWidgetProviderInfo شیء مرتبط با ارائه‌دهنده ابزارک بازیابی کنید.

همه میزبانان مسئولیت‌های زیر را دارند:

• هنگام افزودن ابزاره، شناسه ابزاره را همان‌طور که قبلاً توضیح داده شد اختصاص دهید. وقتی ابزاره‌ای از میزبان برداشته می‌شود، برای لغو تخصیص شناسه ابزاره، deleteAppWidgetId() را فراخوانی کنید.

• هنگام افزودن ابزاره، بررسی کنید که آیا فعالیت پیکربندی باید راه‌اندازی شود یا نه. معمولاً میزبان باید فعالیت پیکربندی ابزارک را راه‌اندازی کند، اگر وجود داشته باشد و با مشخص کردن پرچم‌های configuration_optional و reconfigurable به‌عنوان اختیاری علامت‌گذاری نشده باشد. برای جزئیات بیشتر، به‌روزرسانی ابزاره از فعالیت پیکربندی را ببینید. این مرحله برای بسیاری از ابزارک‌ها قبل‌از نمایش ضروری است.

• ابزارک‌ها عرض و ارتفاع پیش‌فرضی را در AppWidgetProviderInfo فراداده مشخص می‌کنند. این مقادیر در سلول‌ها تعریف می‌شوند—از Android 12، اگر targetCellWidth و targetCellHeight مشخص شده باشند—یا dps اگر فقط minWidth و minHeight مشخص شده باشند. مشخصه‌های اندازه ابزاره را ببینید.

  مطمئن شوید که چیدمان ابزارک حداقل این تعداد واحد پیکسل مستقل را داشته باشد. برای مثال، بسیاری از میزبان‌ها نمادها و ابزاره‌ها را در یک شبکه تراز می‌کنند. در این سناریو، میزبان به‌طور پیش‌فرض ابزارکی را بااستفاده از حداقل تعداد سلول‌هایی که محدودیت‌های minWidth و minHeight را برآورده می‌کنند اضافه می‌کند.

نکته‌هایی درباره رویکرد شما

علاوه‌بر الزامات ذکرشده در بخش قبلی، نکات زیر را درنظر داشته باشید:

بسته گزینه‌ها می‌تواند حاوی List<SizeF> باشد که فهرست اندازه‌های ممکن را در واحد پیکسل که نمونه ابزاره می‌تواند داشته باشد دربرمی‌گیرد. تعداد اندازه‌های ارائه‌شده به پیاده‌سازی میزبان بستگی دارد. معمولاً میزبان‌ها دو اندازه برای تلفن‌ها (عمودی و افقی) و چهار اندازه برای دستگاه‌های تاشو ارائه می‌دهند.

تعداد MAX_INIT_VIEW_COUNT (۱۶) محدودیت برای تعداد مختلف RemoteViews که AppWidgetProvider می‌تواند به RemoteViews ارائه دهد وجود دارد. ازآنجایی‌که AppWidgetProvider شیء، شیء RemoteViews را به هر اندازه در List<SizeF> نگاشت می‌کند، بیش‌از MAX_INIT_VIEW_COUNT اندازه ارائه نکنید.

وقتی ابزارک‌ها maxResizeWidth و maxResizeHeight مشخصه‌های dps را مشخص می‌کنند، توصیه می‌کنیم ابزارکی که از حداقل یکی از این مشخصه‌ها استفاده می‌کند از اندازه مشخص‌شده توسط مشخصه‌ها فراتر نرود.

منابع بیشتر

• اسناد مرجع Glance را ببینید.