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

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

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

در اینجا یک نمای کلی از کلاس ها و مفاهیم کلیدی درگیر در اجرای یک AppWidgetHost سفارشی آمده است:

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

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

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

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

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

ویجت های صحافی

هنگامی که کاربر یک ویجت را به هاست اضافه می کند، فرآیندی به نام binding رخ می دهد. Binding به ارتباط یک شناسه ویجت برنامه خاص با یک میزبان خاص و یک AppWidgetProvider خاص اشاره دارد.

Binding API ها همچنین این امکان را برای میزبان فراهم می کند که یک رابط کاربری سفارشی برای اتصال ارائه کند. برای استفاده از این فرآیند، برنامه شما باید مجوز 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.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 به عنوان اختیاری علامت گذاری نشود. برای جزئیات به به روز رسانی ویجت از فعالیت پیکربندی مراجعه کنید. این یک مرحله ضروری برای بسیاری از ویجت ها قبل از نمایش آنها است.

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

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

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

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

اندروید 12

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

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

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

منابع اضافی

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