با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
صفحه اصلی 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 را در مانیفست میزبان اعلام کند:
اما این فقط اولین قدم است. در زمان اجرا، کاربر باید به صراحت به برنامه شما اجازه دهد تا ویجت را به هاست اضافه کند. برای آزمایش اینکه آیا برنامه شما مجوز اضافه کردن ویجت را دارد یا خیر، از روش bindAppWidgetIdIfAllowed() استفاده کنید. اگر bindAppWidgetIdIfAllowed()false را برگرداند، برنامه شما باید دیالوگی را نمایش دهد که از کاربر می خواهد اجازه دهد: "اجازه دادن" برای افزودن ویجت فعلی، یا "همیشه اجازه می دهد" برای پوشش تمام افزوده های ویجت در آینده.
این قطعه نمونه ای از نحوه نمایش دیالوگ را ارائه می دهد:
کاتلین
valintent=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)
جاوا
Intentintent=newIntent(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 معرفی می‌کند. توصیه می‌کنیم ویجتی که از حداقل یکی از این ویژگی‌ها استفاده می‌کند، از اندازه مشخص‌شده توسط ویژگی‌ها تجاوز نکند.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی."],[],[],null,["The Android home screen, available on most Android-powered devices, lets the\nuser embed [app widgets](/guide/topics/appwidgets/overview) (or *widgets* ) for\nquick access to content. If you're building a home screen replacement or a\nsimilar app, you can also let the user embed widgets by implementing\n[`AppWidgetHost`](/reference/android/appwidget/AppWidgetHost). This isn't\nsomething that most apps need to do, but if you are creating your own host, it's\nimportant to understand the contractual obligations a host implicitly agrees to. \n\nThis page focuses on the responsibilities involved in implementing a custom\n`AppWidgetHost`. For a specific example of how to implement an `AppWidgetHost`,\nlook at the source code for the Android home screen\n[`LauncherAppWidgetHost`](https://cs.android.com/android/platform/superproject/+/master:packages/apps/Launcher3/src/com/android/launcher3/widget/LauncherAppWidgetHost.java;l=57?q=LauncherAppWidgetHost).\n\nHere is an overview of key classes and concepts involved in implementing a\ncustom `AppWidgetHost`:\n\n- **App widget host** : the `AppWidgetHost` provides the interaction with the\n AppWidget service for apps that embed widgets in their UI. An `AppWidgetHost`\n must have an ID that is unique within the host's own package. This ID persists\n across all uses of the host. The ID is typically a hardcoded value that you\n assign in your app.\n\n- **App widget ID** : each widget instance is assigned a unique ID at the time\n of binding. See\n [`bindAppWidgetIdIfAllowed()`](/reference/android/appwidget/AppWidgetManager#bindAppWidgetIdIfAllowed(int,%20android.content.ComponentName))\n and, for more detail, the [Binding widgets](#bind) section that follows. The\n host obtains the unique ID using\n [`allocateAppWidgetId()`](/reference/android/appwidget/AppWidgetHost#allocateAppWidgetId()).\n This ID persists across the lifetime of the widget until it is deleted from the\n host. Any host-specific state---such as the size and location of the\n widget---must be persisted by the hosting package and associated with the\n app widget ID.\n\n- **App widget host view** : think of\n [`AppWidgetHostView`](/reference/android/appwidget/AppWidgetHostView) as a frame\n that the widget is wrapped in whenever it needs to be displayed. A widget is\n associated with an `AppWidgetHostView` every time the widget is inflated by the\n host.\n\n - By default, the system creates an `AppWidgetHostView`, but the host can create its own subclass of `AppWidgetHostView` by extending it.\n - Starting in Android 12 (API level 31), `AppWidgetHostView` introduces the the [`setColorResources()`](/reference/android/appwidget/AppWidgetHostView#setColorResources(android.util.SparseIntArray)) and [`resetColorResources()`](/reference/android/appwidget/AppWidgetHostView#resetColorResources()) methods for handling dynamically overloaded colors. The host is responsible for providing the colors to these methods.\n- **Options bundle** : the `AppWidgetHost` uses the options bundle to\n communicate information to the\n [`AppWidgetProvider`](/reference/android/appwidget/AppWidgetProvider)\n about how the widget is displayed---for example, the\n [list of size ranges](/guide/topics/appwidgets/layouts#provide-exact-layouts)---and whether the\n widget is on a lockscreen or the home screen. This information lets the\n `AppWidgetProvider` tailor the widget's contents and appearance based on how and\n where it is displayed. You can use\n [`updateAppWidgetOptions()`](/reference/android/appwidget/AppWidgetHostView#updateAppWidgetOptions(android.os.Bundle))\n and\n [`updateAppWidgetSize()`](/reference/android/appwidget/AppWidgetHostView#updateAppWidgetSize(android.os.Bundle,%20java.util.List%3Candroid.util.SizeF%3E))\n to modify a widget's bundle. Both of these methods trigger the\n [`onAppWidgetOptionsChanged()`](/reference/android/appwidget/AppWidgetProvider#onAppWidgetOptionsChanged(android.content.Context,%20android.appwidget.AppWidgetManager,%20int,%20android.os.Bundle))\n callback to the `AppWidgetProvider`.\n\nBinding widgets\n\nWhen a user adds a widget to a host, a process called *binding* occurs. Binding\nrefers to associating a particular app widget ID with a specific host and a\nspecific `AppWidgetProvider`.\n\nBinding APIs also make it possible for a host to provide a custom UI for\nbinding. To use this process, your app must declare the\n[`BIND_APPWIDGET`](/reference/android/Manifest.permission#BIND_APPWIDGET)\npermission in the host's manifest: \n\n \u003cuses-permission android:name=\"android.permission.BIND_APPWIDGET\" /\u003e\n\nBut this is just the first step. At runtime, the user must explicitly grant\npermission to your app to let it add a widget to the host. To test whether your\napp has permission to add the widget, use the\n[`bindAppWidgetIdIfAllowed()`](/reference/android/appwidget/AppWidgetManager#bindAppWidgetIdIfAllowed(int,%20android.content.ComponentName))\nmethod. If `bindAppWidgetIdIfAllowed()` returns `false`, your app must display a\ndialog prompting the user to grant permission: \"allow\" for the current widget\naddition, or \"always allow\" to cover all future widget additions.\n\nThis snippet gives an example of how to display the dialog: \n\nKotlin \n\n```kotlin\nval intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply {\n putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)\n putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName)\n // This is the options bundle described in the preceding section.\n putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options)\n}\nstartActivityForResult(intent, REQUEST_BIND_APPWIDGET)\n```\n\nJava \n\n```java\nIntent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND);\nintent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);\nintent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName);\n// This is the options bundle described in the preceding section.\nintent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);\nstartActivityForResult(intent, REQUEST_BIND_APPWIDGET);\n```\n\nThe host must check whether the widget that a user adds needs configuration. For\nmore information, see [Enable users to configure app\nwidgets](/guide/topics/appwidgets/configuration).\n\nHost responsibilities\n\nYou can specify a number of configuration settings for widgets using the\n[`AppWidgetProviderInfo` metadata](/develop/ui/views/appwidgets#components).\nYou can retrieve these configuration options, covered in more detail in the\nfollowing sections, from the\n[`AppWidgetProviderInfo`](/reference/android/appwidget/AppWidgetProviderInfo)\nobject associated with a widget provider.\n\nRegardless of the version of Android you are targeting, all hosts have the\nfollowing responsibilities:\n\n- When adding a widget, allocate the widget ID as described earlier. When a\n widget is removed from the host, call\n [`deleteAppWidgetId()`](/reference/android/appwidget/AppWidgetHost#deleteAppWidgetId(int))\n to deallocate the widget ID.\n\n- When adding a widget, check whether the configuration activity needs to be\n launched. Typically, the host needs to launch the widget's configuration\n activity if it exists and isn't marked as optional by specifying both the\n `configuration_optional` and `reconfigurable` flags. See\n [Update the widget from the configuration activity](/guide/topics/appwidgets/configuration#update)\n for details. This is a necessary step for many widgets before they can display.\n\n | **Note:** Handle irregular cases where the configuration activity doesn't return or finishes with errors.\n- Widgets specify a default width and height in the `AppWidgetProviderInfo`\n metadata. These values are defined in cells---starting in\n Android 12, if `targetCellWidth` and `targetCellHeight` are\n specified---or dps if only `minWidth` and `minHeight` are specified. See\n [Widget sizing attributes](/guide/topics/appwidgets#widget-sizing-attributes).\n\n Make sure that the widget is laid out with at least this many dps. For\n example, many hosts align icons and widgets in a grid. In this scenario, by\n default the host adds the a widget using the minimum number of cells that\n satisfy the `minWidth` and `minHeight` constraints.\n\nIn addition to the requirements listed in the preceding section, specific\nplatform versions introduce features that place new responsibilities on the\nhost.\n\nDetermine your approach based on the targeted Android version\n\nAndroid 12\n\nAndroid 12 (API level 31) bundles an extra `List\u003cSizeF\u003e` that contains the list\nof possible sizes in dps that a widget instance can take in the options bundle.\nThe number of sizes provided depends on the host implementation. Hosts typically\nprovide two sizes for phones---portrait and landscape---and four sizes\nfor foldables.\n\nThere is a limit of `MAX_INIT_VIEW_COUNT` (16) on the number of different\n`RemoteViews` that an `AppWidgetProvider` can provide to\n[`RemoteViews`](/reference/android/widget/RemoteViews#RemoteViews(java.util.Map%3Candroid.util.SizeF,%20android.widget.RemoteViews%3E)).\nSince `AppWidgetProvider` objects map a `RemoteViews` object to each size in the\n`List\u003cSizeF\u003e`, don't provide more than `MAX_INIT_VIEW_COUNT` sizes.\n\nAndroid 12 also introduces the\n[`maxResizeWidth`](/reference/android/appwidget/AppWidgetProviderInfo#maxResizeWidth)\nand\n[`maxResizeHeight`](/reference/android/appwidget/AppWidgetProviderInfo#maxResizeHeight)\nattributes in dps. We recommend that a widget that uses at least one of these\nattributes doesn't exceed the size specified by the attributes.\n\nAdditional resources\n\n- See the [`Glance`](/jetpack/androidx/releases/glance) reference documentation."]]
