یک میزبان ویجت بسازید

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

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

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

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

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

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

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

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

ابزارک‌های اتصال

وقتی کاربری یک ویجت را به یک میزبان اضافه می‌کند، فرآیندی به نام اتصال (binding) رخ می‌دهد. اتصال به مرتبط کردن یک شناسه ویجت برنامه خاص با یک میزبان خاص و یک AppWidgetProvider خاص اشاره دارد.

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

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

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

این قطعه کد مثالی از نحوه نمایش کادر محاوره‌ای ارائه می‌دهد:

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

Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);
// This is the options bundle described in the preceding section.
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);

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

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

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

صرف نظر از نسخه اندروید مورد نظر شما، همه میزبان‌ها مسئولیت‌های زیر را دارند:

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

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

• ویجت‌ها یک عرض و ارتفاع پیش‌فرض را در متادیتای AppWidgetProviderInfo مشخص می‌کنند. این مقادیر در سلول‌ها تعریف می‌شوند - از اندروید ۱۲، اگر targetCellWidth و targetCellHeight مشخص شده باشند - یا در dps اگر فقط minWidth و minHeight مشخص شده باشند. به ویژگی‌های اندازه‌گذاری ویجت مراجعه کنید.

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

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

رویکرد خود را بر اساس نسخه اندروید هدف تعیین کنید

اندروید ۱۲

اندروید ۱۲ (سطح API 31) یک List<SizeF> اضافی را در بسته‌ی options قرار می‌دهد که شامل فهرستی از اندازه‌های ممکن بر حسب dps است که یک نمونه‌ی ویجت می‌تواند در بسته‌ی options بپذیرد. تعداد اندازه‌های ارائه شده به پیاده‌سازی میزبان بستگی دارد. میزبان‌ها معمولاً دو اندازه برای تلفن‌ها - عمودی و افقی - و چهار اندازه برای گوشی‌های تاشو ارائه می‌دهند.

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

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

منابع اضافی

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