تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح الشاشة الرئيسية على Android، المتوفّرة على معظم الأجهزة التي تعمل بنظام Android، للمستخدم تضمين تطبيقات مصغّرة (أو تطبيقات مصغّرة) للوصول السريع إلى المحتوى. إذا كنت بصدد إنشاء تطبيق بديل للشاشة الرئيسية أو تطبيق مشابه، يمكنك أيضًا السماح للمستخدم بتضمين التطبيقات المصغّرة من خلال تنفيذ AppWidgetHost. لا تحتاج معظم التطبيقات إلى تنفيذ ذلك، ولكن إذا كنت بصدد إنشاء مضيف خاص بك، من المهم فهم الالتزامات التعاقدية التي يوافق عليها المضيف ضمنيًا.
تركّز هذه الصفحة على المسؤوليات التي ينطوي عليها تنفيذ
AppWidgetHost مخصّص. للاطّلاع على مثال محدّد حول كيفية تنفيذ AppWidgetHost،
راجِع رمز المصدر للشاشة الرئيسية في Android
LauncherAppWidgetHost.
في ما يلي نظرة عامة على الفئات والمفاهيم الرئيسية المتعلّقة بتنفيذ AppWidgetHost مخصّص:
مضيف أدوات التطبيق: يوفّر AppWidgetHost التفاعل مع خدمة AppWidget للتطبيقات التي تضمّن أدوات في واجهة المستخدم. يجب أن يتضمّن AppWidgetHost
معرّفًا فريدًا ضمن حزمة المضيف. ويظلّ هذا المعرّف ثابتًا
في جميع استخدامات المضيف. ويكون المعرّف عادةً قيمة مبرمَجة بشكل ثابت تحدّدها في تطبيقك.
معرّف التطبيق المصغّر: يتم تخصيص معرّف فريد لكل نسخة من التطبيق المصغّر عند الربط. اطّلِع على
bindAppWidgetIdIfAllowed()
ولمزيد من التفاصيل، راجِع القسم ربط التطبيقات المصغّرة أدناه. يحصل المضيف على المعرّف الفريد باستخدام allocateAppWidgetId().
يظلّ هذا المعرّف متاحًا طوال فترة استخدام التطبيق المصغّر إلى أن يتم حذفه من المضيف. يجب أن تحتفظ حزمة الاستضافة بأي حالة خاصة بالمضيف، مثل حجم وموقع الأداة، وأن تربطها بمعرّف أداة التطبيق.
طريقة عرض مضيف التطبيق المصغَّر: يمكنك اعتبار
AppWidgetHostView إطارًا
يتم تضمين التطبيق المصغَّر فيه كلما دعت الحاجة إلى عرضه. يرتبط التطبيق المصغّر بمعرّف AppWidgetHostView في كل مرة يوسّع فيها المضيف التطبيق المصغّر.
ينشئ النظام AppWidgetHostView تلقائيًا، ولكن يمكن للمضيف إنشاء فئة فرعية خاصة به من AppWidgetHostView من خلال توسيعها.
بدءًا من نظام التشغيل Android 12 (المستوى 31 من واجهة برمجة التطبيقات)، تقدّم AppWidgetHostView الطريقتَين
setColorResources()
و
resetColorResources()
للتعامل مع الألوان المحمّلة بشكل ديناميكي. يكون المضيف مسؤولاً عن توفير الألوان لهذه الطرق.
حزمة الخيارات: يستخدم AppWidgetHost حزمة الخيارات لنقل المعلومات إلى AppWidgetProvider حول طريقة عرض التطبيق المصغّر، مثل قائمة نطاقات الأحجام، وما إذا كان التطبيق المصغّر معروضًا على شاشة القفل أو الشاشة الرئيسية. تسمح هذه المعلومات
AppWidgetProvider بتخصيص محتوى التطبيق المصغّر ومظهره استنادًا إلى طريقة عرضه ومكانه. يمكنك استخدام
updateAppWidgetOptions()
و
updateAppWidgetSize()
لتعديل حِزمة أداة. تؤدي كلتا الطريقتَين إلى تشغيل
onAppWidgetOptionsChanged()
لإعادة الاتصال بـ AppWidgetProvider.
ربط التطبيقات المصغّرة
عندما يضيف المستخدم أداة إلى مضيف، تحدث عملية تُعرف باسم الربط. يشير الربط إلى ربط معرّف أداة تطبيق معيّن بمضيف معيّن وAppWidgetProvider معيّن.
تتيح واجهات برمجة التطبيقات الملزمة أيضًا للمضيف توفير واجهة مستخدم مخصّصة لعملية الربط. لاستخدام هذه العملية، يجب أن يوضّح تطبيقك الإذن
BIND_APPWIDGET
في ملف البيان الخاص بالتطبيق المضيف:
ولكن هذه هي الخطوة الأولى فقط. أثناء التشغيل، يجب أن يمنح المستخدم تطبيقك الإذن صراحةً للسماح له بإضافة أداة إلى التطبيق المضيف. لاختبار ما إذا كان تطبيقك لديه إذن بإضافة الأداة، استخدِم طريقة bindAppWidgetIdIfAllowed(). إذا عرضت الدالة bindAppWidgetIdIfAllowed() القيمة false، يجب أن يعرض تطبيقك مربع حوار يطلب من المستخدم منح الإذن: "السماح" بإضافة التطبيق المصغّر الحالي، أو "السماح دائمًا" لتغطية جميع عمليات إضافة التطبيقات المصغّرة المستقبلية.
يقدّم هذا المقتطف مثالاً على كيفية عرض مربّع الحوار:
Kotlin
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)
Java
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);
على المضيف التحقّق مما إذا كانت الأداة التي يضيفها المستخدم بحاجة إلى إعداد. لمزيد من المعلومات، يُرجى الاطّلاع على السماح للمستخدمين بضبط أدوات التطبيقات.
بغض النظر عن إصدار Android الذي تستهدفه، يتحمّل جميع المضيفين المسؤوليات التالية:
عند إضافة تطبيق مصغّر، خصِّص رقم تعريف التطبيق المصغّر كما هو موضّح سابقًا. عند إزالة تطبيق مصغّر من المضيف، يجب استدعاء deleteAppWidgetId() لإلغاء تخصيص معرّف التطبيق المصغّر.
عند إضافة تطبيق مصغّر، تحقَّق ممّا إذا كان يجب تشغيل نشاط الإعداد. عادةً، يحتاج التطبيق المضيف إلى تشغيل نشاط إعدادات التطبيق المصغّر إذا كان متوفّرًا ولم يتم وضع علامة على أنّه اختياري من خلال تحديد كل من العلامتَين configuration_optional وreconfigurable. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة
تعديل الأداة من نشاط الإعداد. هذه الخطوة ضرورية للعديد من الأدوات قبل أن تتمكّن من العرض.
تحدّد التطبيقات المصغّرة عرضًا وارتفاعًا تلقائيَين في بيانات AppWidgetProviderInfoالوصف. يتم تحديد هذه القيم في الخلايا، بدءًا من نظام التشغيل Android 12، إذا تم تحديد targetCellWidth وtargetCellHeight، أو في وحدات البكسل المستقلة عن الكثافة إذا تم تحديد minWidth وminHeight فقط. اطّلِع على
سمات تحديد حجم التطبيق المصغّر.
تأكَّد من أنّ تصميم التطبيق المصغّر يتضمّن هذا العدد من وحدات البكسل المستقلة الكثافة على الأقل. على سبيل المثال، يرتّب العديد من المضيفين الرموز والأدوات في شبكة. في هذا السيناريو، يضيف المضيف تلقائيًا تطبيقًا مصغّرًا باستخدام الحد الأدنى من الخلايا التي تستوفي القيود minWidth وminHeight.
بالإضافة إلى المتطلبات الواردة في القسم السابق، تتضمّن إصدارات محدّدة من النظام الأساسي ميزات تفرض مسؤوليات جديدة على الجهاز المضيف.
تحديد النهج استنادًا إلى إصدار Android المستهدَف
Android 12
تتضمّن حزمة Android 12 (المستوى 31 من واجهة برمجة التطبيقات) حزمة إضافية List<SizeF> تحتوي على قائمة بالأحجام المحتملة بوحدات بكسل مستقلة عن الكثافة التي يمكن أن يشغلها مثيل أداة في حزمة الخيارات.
يعتمد عدد الأحجام المتوفّرة على عملية التنفيذ التي يجريها المضيف. يوفّر المضيفون عادةً حجمَين للهواتف، وهما الوضعان العمودي والأفقي، وأربعة أحجام للأجهزة القابلة للطي.
يبلغ الحد الأقصى لعدد RemoteViews المختلفة التي يمكن أن يقدّمها AppWidgetProvider إلى RemoteViews، MAX_INIT_VIEW_COUNT (16).
بما أنّ عناصر AppWidgetProvider تربط عنصر RemoteViews بكل مقاس في List<SizeF>، لا تقدّم أكثر من MAX_INIT_VIEW_COUNT مقاسات.
يقدّم نظام التشغيل Android 12 أيضًا السمتَين
maxResizeWidth
و
maxResizeHeight
في dps. ننصح بأن لا يتجاوز حجم الأداة التي تستخدم سمة واحدة على الأقل من هذه السمات الحجم المحدّد بواسطة السمات.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-21 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Build a widget host\n\nThe 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---------------\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\n### Kotlin\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\n### Java\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---------------------\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\n### Determine your approach based on the targeted Android version\n\n#### Android 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\n- See the [`Glance`](/jetpack/androidx/releases/glance) reference documentation."]]
