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

صفحه اصلی 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> باشد که حاوی فهرست اندازه‌های ممکن در dps است که نمونه ابزاره می‌تواند داشته باشد. تعداد اندازه‌های ارائه‌شده به پیاده‌سازی میزبان بستگی دارد. میزبان‌ها معمولاً دو اندازه برای تلفن‌ها (عمودی و افقی) و چهار اندازه برای دستگاه‌های تاشو ارائه می‌دهند.

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

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

منابع بیشتر

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