الحاجيات التطبيق App Widgets

الحاجيات التطبيق App Widgets

في هذه الوثيقة
أساسيات
إعلان القطعة التطبيقات في البيان
إضافة البيانات الوصفية أبويدجيتبروفيدرينفو
إنشاء التطبيق القطعة تخطيط
استخدام فئة أبويدجيتبروفيدر
تلقي التطبيق القطعة بث النوايا
تعلق التطبيقات الحاجيات
إنشاء نشاط تكوين أداة تطبيق
تحديث أداة التطبيقات من نشاط التهيئة
تعيين صورة المعاينة
باستخدام التطبيقات الحاجيات مع مجموعات
تطبيق العينة
تنفيذ الحاجيات التطبيق مع مجموعات
حفظ البيانات الطازجة
الطبقات الرئيسية
AppWidgetProvider
AppWidgetProviderInfo
AppWidgetManager


تطبيقات الحاجيات هي آراء التطبيق مصغرة التي يمكن أن تكون جزءا لا يتجزأ من تطبيقات أخرى (مثل الشاشة الرئيسية) وتلقي التحديثات الدورية. يشار إلى هذه الآراء على الحاجيات في واجهة المستخدم، ويمكنك نشر واحد مع مزود التطبيق القطعة. ويسمى عنصر التطبيق القادر على عقد تطبيقات الحاجيات الأخرى مضيف التطبيقات القطعة. تظهر لقطة الشاشة أدناه تطبيق ميوزك أب ويدجيت.


تصف هذه الوثيقة كيفية نشر تطبيق القطعة باستخدام موفر التطبيق القطعة. للحصول على مناقشة حول إنشاء AppWidgetHost الخاص بك لاستضافة الحاجيات التطبيق، راجع التطبيقات القطعة المضيف .

تصميم القطعة
للحصول على معلومات حول كيفية تصميم تطبيقك، اقرأ دليل تصميم الأدوات .
أساسيات
لإنشاء تطبيق القطعة، تحتاج إلى ما يلي:

كائن AppWidgetProviderInfo
يصف البيانات الوصفية لأداة التطبيق، مثل تخطيط التطبيق القطعة، تردد التحديث، والطبقة أبويدجيتبروفيدر. يجب تعريف هذا في شمل.
تطبيق فئة AppWidgetProvider
يحدد الأساليب الأساسية التي تسمح لك واجهة برمجيا مع التطبيق القطعة، استنادا إلى أحداث البث. من خلال ذلك، سوف تتلقى البث عندما يتم تحديث التطبيق القطعة، تمكين، تعطيل وحذف.
عرض التخطيط
يحدد التخطيط الأولي للتطبيق القطعة، المعرفة في شمل.
بالإضافة إلى ذلك، يمكنك تنفيذ نشاط تكوين تطبيق القطعة. هذا هو Activity الاختياري الذي تطلق عندما يضيف المستخدم التطبيق الخاص بك القطعة ويسمح له أو لها لتعديل إعدادات التطبيق القطعة في خلق الوقت.

تصف الأقسام التالية كيفية إعداد كل من هذه المكونات.

إعلان القطعة التطبيقات في البيان
أولا، أعلن فئة AppWidgetProvider في ملف AndroidManifest.xml للتطبيق الخاص بك. فمثلا:


<receiver android:name="ExampleAppWidgetProvider" >
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

<receiver> عنصر يتطلب android:name السمة، الذي يحدد AppWidgetProvider المستخدمة من قبل التطبيق القطعة.

يجب أن يتضمن عنصر <intent-filter> عنصرا <action> مع السمة android:name نيم. تحدد هذه السمة أن AppWidgetProvider يقبل البث ACTION_APPWIDGET_UPDATE . هذا هو البث الوحيد الذي يجب أن تعلن صراحة. و AppWidgetManager يرسل تلقائيا جميع التطبيقات الأخرى لبث القطعة إلى أبويدجيتبروفيدر حسب الضرورة.

يحدد العنصر <meta-data> AppWidgetProviderInfo المورد AppWidgetProviderInfo ويتطلب السمات التالية:

android:name - يحدد اسم البيانات الوصفية. استخدام android.appwidget.provider لتحديد البيانات كما وصف AppWidgetProviderInfo .
android:resource AppWidgetProviderInfo - يحدد موقع مورد AppWidgetProviderInfo .
إضافة البيانات الوصفية أبويدجيتبروفيدرينفو
و AppWidgetProviderInfo يحدد الصفات الأساسية AppWidgetProviderInfo التطبيق، مثل الحد الأدنى من أبعاد التخطيط، والموارد تخطيط الأولية، ومدى تحديث القطعة التطبيق، و (اختياريا) نشاط التكوين لإطلاق في خلق الوقت. حدد الكائن أبويدجيتبروفيدرينفو في مورد شمل باستخدام عنصر واحد <appwidget-provider> وحفظه في المجلد res/xml/ .

فمثلا:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:updatePeriodMillis="86400000"
    android:previewImage="@drawable/preview"
    android:initialLayout="@layout/example_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigure"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen">
</appwidget-provider

في ما يلي ملخص <appwidget-provider> :

القيم ل minWidth و minHeight سمات تحديد الحد الأدنى من مساحة التطبيق القطعة يستهلك بشكل افتراضي . مواقف الشاشة الرئيسية الافتراضية التطبيقات الحاجيات في إطارها على أساس شبكة من الخلايا التي لها ارتفاع وعرض محدد. إذا كانت قيم الحد الأدنى للعرض أو الارتفاع لأداة تطبيق أب لا تتطابق مع أبعاد الخلايا، فسيتم بعدها قياس أبعاد أداة التطبيقات إلى أقرب حجم خلية.
انظر المبادئ التوجيهية تصميم التطبيق القطعة لمزيد من المعلومات حول تحجيم الحاجيات التطبيق الخاص بك.
ملاحظة: لجعل التطبيق الخاص بك القطعة المحمولة عبر الأجهزة، يجب أن يكون الحد الأدنى لحجم القطعة التطبيق الخاص بك أبدا أكبر من 4 × 4 خلايا.

و minResizeWidth و minResizeHeight السمات تحديد الحد الأدنى المطلق أب القطعة القطعة. يجب أن تحدد هذه القيم الحجم الذي تكون فيه أداة التطبيق غير مقروءة أو غير صالحة للاستخدام. يتيح استخدام هذه السمات للمستخدم تغيير حجم الأداة إلى حجم قد يكون أصغر من حجم القطعة الافتراضي المحدد بواسطة minWidth و minHeight سمات. قدم في الروبوت 3.1.
انظر المبادئ التوجيهية تصميم التطبيق القطعة لمزيد من المعلومات حول تحجيم الحاجيات التطبيق الخاص بك.
تحدد السمة updatePeriodMillis عدد المرات التي يجب أن يطلب إطار عمل التطبيق تحديث من AppWidgetProvider عن طريق استدعاء الأسلوب استدعاء onUpdate() . التحديث الفعلي ليس مضمونا أن يحدث بالضبط في الوقت المحدد مع هذه القيمة، ونحن نقترح تحديث كما نادرا قدر الإمكان، ربما لا أكثر من مرة واحدة ساعة للحفاظ على البطارية. قد تسمح أيضا للمستخدم لضبط التردد في تكوين بعض الناس قد ترغب في شريط الأسهم لتحديث كل 15 دقيقة، أو ربما أربع مرات فقط في اليوم.
ملاحظة: إذا كان الجهاز نائما عندما حان الوقت لإجراء تحديث (كما هو محدد بواسطة updatePeriodMillis )، ثم الجهاز سوف يستيقظ من أجل إجراء التحديث. إذا لم تقم بتحديث أكثر من مرة واحدة في الساعة، وهذا ربما لن يسبب مشاكل كبيرة للبطارية. إذا، ومع ذلك، تحتاج إلى تحديث أكثر في كثير من الأحيان و / أو لا تحتاج إلى تحديث أثناء الجهاز نائما، ثم يمكنك بدلا من ذلك إجراء التحديثات على أساس إنذار لن يستيقظ الجهاز. للقيام بذلك، تعيين منبه مع نية أن يتلقى أبويدجيتبروفيدر الخاص بك، وذلك باستخدام ألارماناجر. تعيين نوع التنبيه إما ELAPSED_REALTIME أو RTC ، والتي سوف فقط تسليم ناقوس الخطر عندما يكون الجهاز مستيقظا. ثم قم بتعيين updatePeriodMillis إلى صفر ( "0" ).

initialLayout السمة initialLayout إلى مورد التخطيط الذي يحدد تخطيط التطبيق القطعة.
تحدد السمة configure Activity لإطلاق عندما يضيف المستخدم التطبيق القطعة، من أجل له أو لها لتكوين خصائص القطعة التطبيق. هذا اختياري (اقرأ إنشاء نشاط تكوين أداة تطبيق أدناه).
تحدد السمة previewImage معاينة لما ستبدو عليه أداة تطبيق التطبيق بعد تهيئتها، والتي يراها المستخدم عند تحديد أداة التطبيق. إذا لم يتم توفيرها، فسيشاهد المستخدم رمز قاذفة التطبيق. يتوافق هذا الحقل مع السمة android:previewImage في العنصر <receiver> في ملف AndroidManifest.xml . لمزيد من المناقشة حول استخدام previewImage ، راجع تعيين صورة معاينة .

 قدم في الروبوت 3.0.
تحدد السمة autoAdvanceViewId معرف المشاهدة autoAdvanceViewId التطبيق التي يجب أن تكون متقدمة تلقائيا بواسطة مضيف الأداة. قدم في الروبوت 3.0.
تحدد السمة resizeMode القواعد التي يمكن تغيير حجم الأداة. يمكنك استخدام هذه السمة لجعل الحاجيات الشاشة الرئيسية ريزيزيبل أفقيا، رأسيا، أو على كلا المحاور. للمستخدمين اللمس عقد القطعة لإظهار مقابض تغيير الحجم، ثم اسحب مقابض أفقية و / أو عمودية لتغيير حجم على شبكة تخطيط. تتضمن قيم السمة resizeMode "أفقي" و " resizeMode " و "نون". أن تعلن القطعة كما ريزيزيبل أفقيا وعموديا، وتوفير قيمة "الأفقي | الرأسي". 

قدم في الروبوت 3.1.
تحدد السمة minResizeHeight الحد الأدنى للارتفاع (في دبس) الذي يمكن تغيير حجم الأداة. هذا الحقل ليس له أي تأثير إذا كان أكبر من minHeight أو إذا لم يتم تمكين تغيير حجم العمودي (انظر resizeMode ). 

قدم في الروبوت 4.0.
تحدد السمة minResizeWidth الحد الأدنى للعرض (في دبس) التي يمكن تغيير حجم الأداة. هذا الحقل ليس له أي تأثير إذا كان أكبر من minWidth أو إذا لم يتم تمكين تغيير حجم أفقي (انظر resizeMode ). 


قدم في الروبوت 4.0.
سمة widgetCategory يعلن ما إذا كان يمكن عرض التطبيق الخاص بك القطعة على الشاشة الرئيسية ( home_screen )، وشاشة القفل ( keyguard )، أو كليهما. فقط إصدارات أندرويد أقل من 5.0 دعم الحاجيات شاشة القفل. بالنسبة إلى الإصدار 5.0 من نظام التشغيل أندرويد والإصدارات الأحدث، فإن home_screen صالحة فقط.
راجع فئة AppWidgetProviderInfo لمزيد من المعلومات حول السمات المقبولة من قبل <appwidget-provider> .

إنشاء التطبيق القطعة تخطيط
يجب عليك تحديد تخطيط مبدئي لقطعة التطبيقات الخاصة بك في شمل وحفظه في الدليل res/layout/ المشروع. يمكنك تصميم التطبيق الخاص بك القطعة باستخدام كائنات مشاهدة المدرجة أدناه، ولكن قبل أن تبدأ في تصميم التطبيق الخاص بك القطعة، يرجى قراءة وفهم المبادئ التوجيهية تصميم التطبيق القطعة .

إنشاء تخطيط التطبيق القطعة بسيطة إذا كنت على دراية التخطيطات . ومع ذلك، يجب أن تكون على علم بأن تخطيطات التطبيق القطعة تستند على RemoteViews ، والتي لا تدعم كل نوع من تخطيط أو عرض القطعة.

كائن ريموتيفيوس (و، وبالتالي، التطبيق القطعة) يمكن أن تدعم الطبقات تخطيط التالية:

FrameLayout
LinearLayout
RelativeLayout
GridLayout
وفئات القطعة التالية:

AnalogClock
Button
Chronometer
ImageButton
ImageView
ProgressBar
TextView
ViewFlipper
ListView
GridView
StackView
AdapterViewFlipper
لا يتم دعم أحفاد هذه الفئات.

ريموتفيوس كما يدعم ViewStub ، وهو غير مرئية، صفر الحجم عرض يمكنك استخدامها لتضخيم موارد التخطيط تضخيم في وقت التشغيل.

إضافة هوامش إلى تطبيقات الحاجيات
يجب أن الحاجيات لا تمتد عموما إلى حواف الشاشة، وينبغي أن لا يكون بصريا تدفق مع الحاجيات الأخرى، لذلك يجب إضافة هوامش على جميع الجوانب حول إطار القطعة الخاصة بك.

اعتبارا من أندرويد 4.0، يتم إعطاء الحاجيات التطبيق تلقائيا الحشو بين إطار القطعة والمربع حدود القطعة التطبيق لتوفير أفضل محاذاة مع الحاجيات الأخرى والرموز على الشاشة الرئيسية للمستخدم. للاستفادة من هذا السلوك الموصى به بشدة، قم بتعيين تارجيتدكفرزيون للتطبيق إلى 14 أو أكبر.

من السهل كتابة تخطيط واحد يحتوي على هوامش مخصصة يتم تطبيقها على الإصدارات السابقة من النظام الأساسي، وليس له هوامش إضافية لنظام التشغيل أندرويد 4.0 والإصدارات الأحدث:

تعيين targetSdkVersion التطبيق الخاص بك إلى 14 أو أكبر.
أنشئ تنسيقا مثل التخطيط أدناه، والذي يشير إلى مورد البعد لهوامشه:

<FrameLayout
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:padding="@dimen/widget_margin">

  <LinearLayout
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="horizontal"
    android:background="@drawable/my_widget_background">
    …
  </LinearLayout>

</FrameLayout>


نشاء الموارد اثنين من الأبعاد، واحدة في res/values/ لتوفير ما قبل الروبوت 4.0 هوامش مخصصة، وواحدة في res/values-v14/ لتوفير أي حشو إضافية لالروبوت 4.0 الحاجيات:
ريس / فالويس / dimens.xml :



<dimen name="widget_margin">8dp</dimen>
res/values-v14/dimens.xml:
<dimen name="widget_margin">0dp</dimen>


وهناك خيار آخر هو ببساطة بناء هوامش إضافية في الأصول الخلفية تسعة التصحيح بشكل افتراضي، وتقديم تسع بقع مختلفة مع عدم وجود هوامش لمستوى أبي 14 أو في وقت لاحق.

استخدام فئة أبويدجيتبروفيدر
يجب أن تعلن تطبيق فئة أبويدجيتبروفيدر كمستقبل البث باستخدام عنصر <receiver> في أندريدمانيفيست (انظر إعلان القطعة التطبيقات في مانيفست أعلاه).
الطبقة AppWidgetProvider يمتد بروادكاستريسيفر كطبقة الراحة للتعامل مع البث التطبيقات القطعة. و أبويدجيتبروفيدر يتلقى فقط البث الحدث التي هي ذات الصلة إلى القطعة التطبيق، مثل عندما يتم تحديث التطبيق القطعة، حذف، تمكين، والمعوقين. عند حدوث أحداث البث هذه، يتلقى أبويدجيتبروفيدر المكالمات الأسلوب التالي:

onUpdate()
وهذا ما يسمى لتحديث التطبيق القطعة على فترات محددة بواسطة السمة updatePeriodMillis في أبويدجيتبروفيدرينفو (انظر إضافة أبويدجيتبروفيدرينفو البيانات الوصفية أعلاه). ويسمى هذا الأسلوب أيضا عندما يضيف المستخدم التطبيق القطعة، لذلك يجب أن تؤدي الإعداد الأساسي، مثل تحديد معالجات الحدث ل المشاهدات وبدء Service مؤقتة، إذا لزم الأمر. ومع ذلك، إذا قمت بإعلان نشاط تكوين لا يتم استدعاء هذا الأسلوب عندما يضيف المستخدم التطبيق القطعة ولكن يسمى التحديثات اللاحقة. ومن مسؤولية النشاط التكوين لإجراء التحديث الأول عند الانتهاء من التكوين. (راجع إنشاء نشاط تكوين أداة تطبيق التطبيقات أدناه.)
onAppWidgetOptionsChanged()
ويسمى هذا عندما يتم وضع القطعة لأول مرة وفي أي وقت يتم تغيير حجم القطعة. يمكنك استخدام هذا الرد لعرض المحتوى أو إخفائه استنادا إلى نطاقات حجم الأداة. يمكنك الحصول على نطاقات حجم عن طريق استدعاء getAppWidgetOptions() ، الذي يعود Bundle التي تشمل ما يلي: 

OPTION_APPWIDGET_MIN_WIDTH على الحد الأدنى على العرض الحالي، في وحدات دب، لمثيل أداة.
OPTION_APPWIDGET_MIN_HEIGHT على الحد الأدنى على الارتفاع الحالي، في وحدات دب، لمثيل أداة.
OPTION_APPWIDGET_MAX_WIDTH على الحد الأعلى على العرض الحالي، في وحدات دب، لمثيل أداة.
OPTION_APPWIDGET_MAX_HEIGHT على الحد الأعلى على العرض الحالي، في وحدات دب، لمثيل أداة.
تم تقديم هذا الرد في أبي ليفيل 16 (أندرويد 4.1). إذا نفذت هذا الرد، فتأكد من أن تطبيقك لا يعتمد عليه نظرا لأنه لن يتم استدعاؤه على الأجهزة القديمة.
onDeleted(Context, int[])
ويسمى هذا في كل مرة يتم حذف التطبيق القطعة من المضيف التطبيق القطعة.
onEnabled(Context)
ويسمى هذا عندما يتم إنشاء مثيل التطبيق القطعة لأول مرة. على سبيل المثال، إذا كان المستخدم يضيف مثيلين من التطبيق الخاص بك القطعة، وهذا يسمى فقط المرة الأولى. إذا كنت بحاجة إلى فتح قاعدة بيانات جديدة أو تنفيذ الإعداد الأخرى التي تحتاج فقط أن تحدث مرة واحدة لجميع مثيلات التطبيق القطعة، ثم وهذا هو مكان جيد للقيام بذلك.
onDisabled(Context)
ويسمى هذا عندما يتم حذف المثيل الأخير من التطبيق الخاص بك القطعة من المضيف التطبيق القطعة. هذا هو المكان الذي يجب عليك تنظيف أي عمل يتم في onEnabled(Context) ، مثل حذف قاعدة بيانات مؤقتة.
onReceive(Context, Intent)
وهذا مطلوب لكل بث وقبل كل من أساليب الاستدعاء المذكورة أعلاه. لا تحتاج عادة إلى تنفيذ هذه الطريقة لأن تطبيق أبويدجبتبروفيدر الافتراضي يقوم بتصفية كافة عمليات بث تطبيق القطعة ويدعو الطرق المذكورة أعلاه حسب الاقتضاء.
أهم استدعاء أبويدجيتبروفيدر هو onUpdate() لأنه يتم استدعاؤه عند إضافة كل أداة تطبيق إلى مضيف (ما لم تستخدم نشاط تكوين). إذا كان التطبيق الخاص بك القطعة تقبل أي أحداث التفاعل المستخدم، ثم تحتاج إلى تسجيل معالجات الحدث في هذا الاستدعاء. إذا كان التطبيق الخاص بك القطعة لا إنشاء ملفات أو قواعد بيانات مؤقتة، أو تنفيذ الأعمال الأخرى التي تتطلب تنظيف، ثم onUpdate() قد يكون أسلوب رد الاتصال الوحيد الذي تحتاج إلى تعريف. على سبيل المثال، إذا كنت تريد أداة تطبيق مع زر يقوم بإطلاق نشاط عند النقر عليه، يمكنك استخدام تنفيذ أبويدجيتبروفيدر التالي:


public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        final int N = appWidgetIds.length;

        // Perform this loop procedure for each App Widget that belongs to this provider
        for (int i=0; i<N; i++) {
            int appWidgetId = appWidgetIds[i];

            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0);

            // Get the layout for the App Widget and attach an on-click listener
            // to the button
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.appwidget_provider_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app widget
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

هذا أبويدجيتبروفيدر يحدد فقط طريقة onUpdate() لغرض تعريف PendingIntent التي تطلق Activity setOnClickPendingIntent(int, PendingIntent) إلى زر التطبيق القطعة مع setOnClickPendingIntent(int, PendingIntent) . لاحظ أنه يتضمن حلقة أن يتكرر من خلال كل إدخال في appWidgetIds ، وهو مجموعة من المعرفات التي تحدد كل التطبيقات القطعة التي تم إنشاؤها بواسطة هذا الموفر. وبهذه الطريقة، إذا كان المستخدم بإنشاء أكثر من مثيل واحد من التطبيق القطعة، ثم يتم تحديث كل ذلك في وقت واحد. ومع ذلك، سيتم إدارة جدول واحد updatePeriodMillis واحد فقط لجميع مثيلات التطبيق القطعة. على سبيل المثال، إذا تم تعريف جدول التحديث ليكون كل ساعتين، ويتم إضافة مثيل ثان من التطبيق القطعة بعد ساعة واحدة من أول واحد، ثم سيتم تحديث كلاهما على الفترة التي يحددها الأول والثاني التحديث (سيتم تحديثهما كل ساعتين وليس كل ساعة).

ملاحظة: لأن AppWidgetProvider هو امتداد ل BroadcastReceiver ، ليست مضمونة العملية الخاصة بك للحفاظ على تشغيل بعد عودة أساليب رد (انظر BroadcastReceiver للحصول على معلومات حول دورة حياة البث). إذا كانت عملية إعداد تطبيق ويدجيت قد تستغرق عدة ثوان (ربما أثناء تنفيذ طلبات الويب) وتطلب استمرار العملية، فكر في بدء تشغيل Service في طريقة onUpdate() . من داخل الخدمة، يمكنك إجراء التحديثات الخاصة بك إلى التطبيق القطعة دون الحاجة إلى القلق حول أبويدجبتبروفيدر إغلاق بسبب تطبيق عدم الاستجابة (أنر) خطأ. انظر أبكيدجيتبروفيدر عينة ويكاموس على سبيل المثال من التطبيق القطعة تشغيل Service .

راجع أيضا نموذج عينة ExampleAppWidgetProvider.java .

تلقي التطبيق القطعة بث النوايا
AppWidgetProvider هو مجرد فئة الراحة. إذا كنت ترغب في الحصول على التطبيق القطعة البث مباشرة، يمكنك تنفيذ BroadcastReceiver الخاص بك أو تجاوز onReceive(Context, Intent) رد الاتصال. النوايا تحتاج إلى الاهتمام هي كما يلي:

ACTION_APPWIDGET_UPDATE
ACTION_APPWIDGET_DELETED
ACTION_APPWIDGET_ENABLED
ACTION_APPWIDGET_DISABLED
ACTION_APPWIDGET_OPTIONS_CHANGED
تعلق التطبيقات الحاجيات
على الأجهزة التي تعمل بنظام التشغيل أندرويد 8.0 (مستوى أبي 26) وأعلى، وقاذفات التي تسمح لك لإنشاء اختصارات مثبتة أيضا تسمح لك دبوس الحاجيات التطبيق على قاذفة. وعلى غرار الاختصارات المثبتة، تتيح هذه الأدوات المصاحبة للمستخدمين إمكانية الدخول إلى مهام معينة في تطبيقك.

في التطبيق الخاص بك، يمكنك إنشاء طلب للنظام لتثبيت القطعة على قاذفة معتمدة من خلال استكمال التسلسل التالي من الخطوات:

أنشئ الأداة في ملف البيان الخاص بتطبيقك، كما هو موضح في المقتطف التالي:

<manifest>
...
  <application>
    ...
    <receiver android:name="MyAppWidgetProvider">
        <intent-filter>
            <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
        </intent-filter>
        <meta-data android:name="android.appwidget.provider"
                   android:resource="@xml/my_appwidget_info" />
    </receiver>
  </application>
</manifest>


استدعاء الأسلوب requestPinAddWidget() ، كما هو موضح في مقتطف الشفرة التالي:

AppWidgetManager mAppWidgetManager =

        context.getSystemService(AppWidgetManager.class);

ComponentName myProvider =

        new ComponentName(context, MyAppWidgetProvider.class);

if (mAppWidgetManager.isRequestPinAppWidgetSupported()) {

    // Create the PendingIntent object only if your app needs to be notified

    // that the user allowed the widget to be pinned. Note that, if the pinning

    // operation fails, your app isn't notified.

    Intent pinnedWidgetCallbackIntent = new Intent( ... );

    // Configure the intent so that your app's broadcast receiver gets

    // the callback successfully. This callback receives the ID of the

    // newly-pinned widget (EXTRA_APPWIDGET_ID).

    PendingIntent successCallback = PendingIntent.createBroadcast(context, 0,

            pinnedWidgetCallbackIntent);

    mAppWidgetManager.requestPinAppWidget(myProvider, null, successCallback);

}

ملاحظة: إذا لم يكن من الضروري إعلام تطبيقك بما إذا كان النظام مثبتا على أداة requestPinAddWidget() بنجاح، فيمكنك تمريره كطرف ثالث لطلب requestPinAddWidget() .

إنشاء نشاط تكوين أداة تطبيق
إذا كنت ترغب في أن يقوم المستخدم بتكوين الإعدادات عند إضافة أداة تطبيقات جديدة، فيمكنك إنشاء نشاط تكوين تطبيق القطعة. سيتم إطلاق هذا Activity تلقائيا من قبل مضيف التطبيق القطعة ويسمح للمستخدم لتكوين الإعدادات المتاحة للالقطعة التطبيق في خلق الوقت، مثل لون القطعة التطبيق، وحجم، فترة التحديث أو إعدادات وظائف أخرى.

يجب أن يتم الإعلان عن نشاط التكوين كنشاط عادي في ملف بيان أندرويد. ومع ذلك، سيتم إطلاقه من قبل مضيف التطبيق القطعة مع الإجراء ACTION_APPWIDGET_CONFIGURE ، وبالتالي فإن النشاط يحتاج إلى قبول هذه النية. فمثلا:

<activity android:name=".ExampleAppWidgetConfigure">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

أيضا، يجب أن يتم الإعلان عن النشاط في ملف شمل أبويدجيتبروفيدرينفو شمل، مع السمة android:configure (انظر إضافة أبويدجيتبروفيدرينفو البيانات الوصفية أعلاه). على سبيل المثال، يمكن الإعلان عن نشاط التكوين كما يلي:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigure"
    ... >
</appwidget-provider>


لاحظ أن يتم الإعلان عن النشاط مع مساحة اسم مؤهل بالكامل، لأنه سيتم الرجوع إليها من خارج نطاق الحزمة الخاصة بك.

هذا كل ما تحتاجه للبدء مع نشاط التكوين. الآن كل ما تحتاجه هو النشاط الفعلي. ومع ذلك، هناك أمران مهمان يجب تذكرهما عند تنفيذ النشاط:

يستدعي مضيف التطبيقات ويدجيت نشاط التكوين والتكوين يجب أن يرجع النشاط دائما نتيجة. يجب أن تتضمن النتيجة معرف أداة التطبيق الذي تم تمريره بواسطة النية التي أطلقت النشاط (حفظها في إضافات EXTRA_APPWIDGET_ID ك EXTRA_APPWIDGET_ID ).
لن يتم استدعاء الأسلوب onUpdate() عند إنشاء التطبيق القطعة (لن يقوم النظام بإرسال ACTION_APPWIDGET_UPDATE عند بدء تشغيل نشاط التكوين). ومن مسؤولية النشاط التكوين لطلب تحديث من أبويدجيتماناجر عند إنشاء التطبيق القطعة لأول مرة. ومع ذلك، سيتم استدعاء onUpdate() لإجراء تحديثات لاحقة - يتم تخطيها فقط في المرة الأولى.
راجع مقتطفات الشفرة في القسم التالي للحصول على مثال لكيفية إرجاع نتيجة من التهيئة وتحديث أداة التطبيق.

تحديث التطبيق القطعة من تكوين النشاط
عندما يستخدم التطبيق القطعة نشاط التكوين، فمن مسؤولية النشاط لتحديث التطبيق القطعة عند التكوين كاملة. يمكنك القيام بذلك عن طريق طلب تحديث مباشرة من AppWidgetManager .

وفيما يلي ملخص الإجراء لتحديث بشكل صحيح التطبيق القطعة وإغلاق التكوين النشاط:

أولا، الحصول على معرف التطبيق القطعة من النية التي أطلقت النشاط:

Intent intent = getIntent();
Bundle extras = intent.getExtras();
if (extras != null) {
    mAppWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_APPWIDGET_ID,
            AppWidgetManager.INVALID_APPWIDGET_ID);
}


جراء تكوين التطبيق القطعة الخاصة بك.
عند اكتمال التكوين، الحصول على مثيل أبويدجيتماناجر عن طريق استدعاء getInstance(Context) :
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

تحديث التطبيق القطعة مع تخطيط RemoteViews عن طريق استدعاء updateAppWidget(int, RemoteViews) :

RemoteViews views = new RemoteViews(context.getPackageName(),
R.layout.example_appwidget);
appWidgetManager.updateAppWidget(mAppWidgetId, views);

وأخيرا، إنشاء عزم العودة، تعيينه مع نتيجة النشاط، والانتهاء من النشاط:

Intent resultValue = new Intent();

resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId);

setResult(RESULT_OK, resultValue);

finish();

نصيحة: عند فتح نشاط التهيئة لأول مرة، عين نتيجة النشاط إلى RESULT_CANCELED، إلى جانب EXTRA_APPWIDGET_ID، كما هو موضح في الخطوة 5 أعلاه. وبهذه الطريقة، إذا كان المستخدم يدعم الخروج من النشاط قبل الوصول إلى النهاية، يتم إعلام المضيف التطبيق القطعة أن التكوين تم إلغاء ولن يتم إضافة التطبيق القطعة.

راجع فئة نموذج ExampleAppWidgetConfigure.java في أبيديموس للحصول على مثال.

تعيين صورة المعاينة
يقدم أندرويد 3.0 حقل previewImage ، الذي يحدد معاينة لما تبدو عليه أداة التطبيق. يتم عرض هذه المعاينة للمستخدم من منتقي القطعة. إذا لم يتم توفير هذا الحقل، يتم استخدام رمز القطعة التطبيق للمعاينة.

هذه هي الطريقة التي تحدد بها هذا الإعداد في شمل

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:previewImage="@drawable/preview">
</appwidget-provider>

للمساعدة في إنشاء صورة معاينة لعنصر تطبيقك (لتحديد في حقل previewImage )، يتضمن المحاكي أندرويد تطبيق يسمى "معاينة القطعة". لإنشاء صورة المعاينة، قم بتشغيل هذا التطبيق، حدد القطعة التطبيق للتطبيق الخاص بك وإعداده كيف كنت تريد أن تظهر صورة المعاينة الخاصة بك، ثم حفظه ووضعه في الموارد القابلة للتطبيق التطبيق الخاص بك.

باستخدام التطبيقات الحاجيات مع مجموعات
الروبوت 3.0 يقدم الحاجيات التطبيق مع المجموعات. تستخدم هذه الأنواع من تطبيقات الحاجيات RemoteViewsService لعرض المجموعات المدعومة ببيانات عن بعد، مثل من موفر المحتوى . يتم تقديم البيانات التي تقدمها RemoteViewsService في القطعة التطبيق باستخدام أحد أنواع العرض التالية، والتي RemoteViewsService إليها باسم "وجهات النظر جمع:"

ListView
طريقة عرض تعرض العناصر في قائمة تمرير رأسيا. للاطلاع على مثال، راجع أداة تطبيق غميل.
GridView
وجهة نظر تظهر العناصر في شبكة التمرير ثنائية الأبعاد. على سبيل المثال، راجع أداة تطبيق الإشارات المرجعية.
StackView
عرض بطاقة مكدسة (نوع من مثل رولوديكس)، حيث يمكن للمستخدم نفض الغبار على بطاقة الجبهة أعلى / أسفل لرؤية البطاقة السابقة / التالية، على التوالي. ومن الأمثلة على ذلك أدوات تطبيق يوتوب وكتب.
AdapterViewFlipper
ViewAnimator بسيط المدعومة ViewAnimator الذي ViewAnimator بين اثنين أو أكثر من وجهات النظر. يتم عرض طفل واحد فقط في كل مرة.
وكما ذكر أعلاه، فإن هذه المجموعة ترى مجموعات العرض المدعومة ببيانات عن بعد. وهذا يعني أنهم يستخدمون Adapter لربط واجهة مستخدمهم ببياناتهم. يقوم " Adapter بربط عناصر فردية من مجموعة من البيانات إلى كائنات View فردية. لأن هذه المجموعة وجهات النظر مدعومة من قبل محولات، يجب أن يتضمن إطار الروبوت بنية إضافية لدعم استخدامها في الحاجيات التطبيق. في سياق القطعة التطبيق، يتم استبدال Adapter بواسطة RemoteViewsFactory ، الذي هو ببساطة المجمع رقيقة حول واجهة Adapter . عند طلب عنصر معين في المجموعة، RemoteViewsFactory بإنشاء وإرجاع العنصر RemoteViews كائن RemoteViews . من أجل تضمين طريقة عرض مجموعة في عنصر واجهة التطبيق الخاص بك، يجب تنفيذ RemoteViewsService و RemoteViewsFactory .

RemoteViewsService هي خدمة تسمح لمحول بعيد طلب الكائنات RemoteViews . RemoteViewsFactory هو واجهة لمحول بين طريقة عرض مجموعة (مثل RemoteViewsFactory ، وهلم جرا) والبيانات الأساسية لهذا الرأي. من نموذج ستاكفيو ويدجيت ، هنا مثال على التعليمات البرمجية النمطية التي تستخدمها لتنفيذ هذه الخدمة والواجهة:

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {

//... include adapter-like methods here. See the StackView Widget sample.

}


تطبيق العينة
يتم استخراج مقتطفات رمز في هذا القسم من عينة ستاكفيو القطعة :

يتكون هذا النموذج من كومة من 10 وجهات النظر، والتي تعرض القيم "0!" من خلال "9!" التطبيق عينة التطبيق لديه هذه السلوكيات الأساسية:

يمكن للمستخدم قذف عموديا على أعلى عرض في القطعة التطبيق لعرض العرض التالي أو السابق. هذا هو المدمج في السلوك ستاكفيو.
دون أي تفاعل المستخدم، القطعة التطبيق تقدم تلقائيا من خلال وجهات نظرها في تسلسل، مثل عرض الشرائح. ويرجع ذلك إلى إعداد android:autoAdvanceViewId="@id/stack_view" في ملف res/xml/stackwidgetinfo.xml . ينطبق هذا الإعداد على معرف المشاهدة، والذي في هذه الحالة هو معرف طريقة العرض لعرض المكدس.
إذا كان المستخدم يمس وجهة نظر العلوي، يعرض التطبيق القطعة رسالة Toast "لمس عرض n ،" حيث ن هو مؤشر (موقف) من وجهة نظر لمسها. لمزيد من المناقشة حول كيفية تنفيذ ذلك، راجع إضافة سلوك إلى عناصر فردية .
تنفيذ الحاجيات التطبيق مع مجموعات
لتنفيذ أداة تطبيق مع مجموعات، اتبع الخطوات الأساسية نفسها التي ستستخدمها لتنفيذ أي أداة تطبيق. تصف الأقسام التالية الخطوات الإضافية التي تحتاج إلى تنفيذها لتنفيذ أداة تطبيق مع مجموعات.

بيان الحاجيات التطبيق مع مجموعات
بالإضافة إلى المتطلبات المذكورة في إعلان القطعة التطبيق في RemoteViewsService ، لجعل من الممكن الحاجيات التطبيق مع مجموعات لربط RemoteViewsService الخاص بك، يجب أن تعلن الخدمة في ملف البيان الخاص بك مع إذن BIND_REMOTEVIEWS . هذا يمنع التطبيقات الأخرى من الوصول بحرية البيانات القطعة التطبيق الخاص بك. على سبيل المثال، عند إنشاء أداة تطبيق تستخدم RemoteViewsService لملء طريقة عرض مجموعة، قد يبدو إدخال البيان كما يلي:


<service android:name="MyWidgetService"
...
android:permission="android.permission.BIND_REMOTEVIEWS" />

خط android:name="MyWidgetService" يشير إلى الفئة الفرعية الخاصة بك من RemoteViewsService .

تخطيط الحاجيات التطبيق مع مجموعات
والشرط الرئيسي لملف شمل تخطيط القطعة التطبيق الخاص بك هو أنه يشمل واحدة من وجهات النظر المجموعة: StackView ، StackView ، StackView ، أو AdapterViewFlipper . في ما يلي نموذج widget_layout.xml ويدجيت : _lout.xml لعينة ستاكفيو ويدجيت :

<?xml version="1.0" encoding="utf-8"?>

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <StackView xmlns:android="http://schemas.android.com/apk/res/android"
        android:id="@+id/stack_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:loopViews="true" />
    <TextView xmlns:android="http://schemas.android.com/apk/res/android"
        android:id="@+id/empty_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center"
        android:background="@drawable/widget_item_background"
        android:textColor="#ffffff"
        android:textStyle="bold"
        android:text="@string/empty_view_text"
        android:textSize="20sp" />
</FrameLayout>


لاحظ أن المشاهدات الفارغة يجب أن تكون أشقاء من طريقة عرض المجموعة التي يمثل فيها العرض الفارغ حالة فارغة.

بالإضافة إلى ملف التخطيط لعنصر تطبيقك بالكامل، يجب إنشاء ملف تخطيط آخر يحدد التنسيق لكل عنصر في المجموعة (على سبيل المثال، تخطيط لكل كتاب في مجموعة من الكتب). على سبيل المثال، نموذج ستاكفيو ويدجيت يحتوي فقط على ملف تخطيط واحد، widget_item.xml ، حيث أن كل العناصر تستخدم نفس التخطيط. ولكن نموذج ويثرليستويدجيت يحتوي على ملفين للتخطيط: dark_widget_item.xml و light_widget_item.xml .

أبويدجيتبروفيدر فئة الحاجيات التطبيق مع مجموعات
كما هو الحال مع القطعة التطبيق العادية، الجزء الأكبر من التعليمات البرمجية في الفئة الفرعية AppWidgetProvider الخاص بك يذهب عادة في onUpdate() . والفرق الرئيسي في التنفيذ الخاص بك ل onUpdate() عند إنشاء القطعة التطبيق مع المجموعات هو أنه يجب استدعاء setRemoteAdapter() . هذا يخبر طريقة عرض المجموعة حيث يمكن الحصول على بياناته. يمكن RemoteViewsService ثم إعادة تنفيذ الخاص بك من RemoteViewsFactory ، والقطعة يمكن أن يصل البيانات المناسبة. عند استدعاء هذا الأسلوب، يجب تمرير نية يشير إلى تنفيذ RemoteViewsService الخاص بك و RemoteViewsService التطبيق القطعة التي تحدد القطعة التطبيق لتحديث.

على سبيل المثال، وهنا كيف تقوم عينة ستاكفيو القطعة بتنفيذ أسلوب الاستدعاء onUpdate() تعيين RemoteViewsService بعيد لجمع التطبيق القطعة:

public void onUpdate(Context context, AppWidgetManager appWidgetManager,
int[] appWidgetIds) {
    // update each of the app widgets with the remote adapter
    for (int i = 0; i < appWidgetIds.length; ++i) {

        // Set up the intent that starts the StackViewService, which will
        // provide the views for this collection.
        Intent intent = new Intent(context, StackWidgetService.class);
        // Add the app widget ID to the intent extras.
        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
        intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
        // Instantiate the RemoteViews object for the app widget layout.
        RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
        // Set up the RemoteViews object to use a RemoteViews adapter.
        // This adapter connects
        // to a RemoteViewsService  through the specified intent.
        // This is how you populate the data.
        rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent);

        // The empty view is displayed when the collection has no items.
        // It should be in the same layout used to instantiate the RemoteViews
        // object above.
        rv.setEmptyView(R.id.stack_view, R.id.empty_view);

        //
        // Do additional processing specific to this app widget...
        //

        appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
    }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
}


الطبقة RemoteViewsService
البيانات استمرار
لا يمكنك الاعتماد على نسخة واحدة من الخدمة، أو أية بيانات التي يحتوي عليها، أن تستمر. بالتالي يتعين عليك عدم تخزين أي بيانات في حياتك RemoteViewsService(إلا إذا كان ثابت). إذا كنت تريد البيانات الخاصة بك التطبيق المصغر لتستمر، فإن أفضل نهج هو استخدام ContentProviderبياناتها استمرت إلى ما بعد دورة حياة العملية.
كما هو موضح أعلاه، الخاص بك RemoteViewsServiceيوفر فرعية لل RemoteViewsFactoryاستخدام لتعبئة الرأي جمع بعيد.

على وجه التحديد، تحتاج إلى تنفيذ الخطوات التالية:

فئة فرعية RemoteViewsService. RemoteViewsServiceهي خدمة التي من خلالها يمكن أن يطلبوا المحول البعيد RemoteViews.
في حياتك RemoteViewsServiceفرعية، تشمل فئة التي تطبق RemoteViewsFactoryالواجهة. RemoteViewsFactoryهي واجهة لمحول بين عرض المجموعة عن بعد (مثل ListView، GridView، وهلم جرا) والبيانات الأساسية عن هذا الرأي. التطبيق الخاص بك هو المسؤول عن جعل RemoteViewsالكائن لكل عنصر في مجموعة البيانات. هذه الواجهة هي إزار رقيق حول Adapter.
محتويات الرئيسية لل RemoteViewsServiceتنفيذ ولها RemoteViewsFactory، هو موضح أدناه.

واجهة RemoteViewsFactory
فئة مخصصة التي تطبق RemoteViewsFactoryالواجهة توفر القطعة التطبيق مع البيانات للعناصر الموجودة في مجموعتها. للقيام بذلك، فهو يجمع بين التطبيق البند القطعة ملف التخطيط XML الخاصة بك مع مصدر البيانات. هذا المصدر من مصادر البيانات يمكن أن يكون أي شيء من قاعدة بيانات لمجموعة بسيطة. في عينة StackView القطعة ، مصدر البيانات هو مجموعة من WidgetItems. و RemoteViewsFactoryوظائفها، ومحول لالغراء البيانات إلى عرض المجموعة عن بعد.

وهما أهم الطرق التي تحتاج إليها لتنفيذ الخاص بك RemoteViewsFactoryفرعية هي onCreate()و getViewAt().

ويدعو النظام onCreate()عند إنشاء المصنع الخاص بك لأول مرة. هذا هو المكان الذي قمت بإعداد أية اتصالات و / أو مؤشرات لمصدر البيانات. على سبيل المثال، عينة StackView القطعة تستخدم onCreate()لتهيئة مجموعة من WidgetItemالكائنات. عندما القطعة التطبيق نشطة، ونظام يصل إلى هذه الكائنات باستخدام موضع فهرس في مجموعة ويتم عرض النص التي تحتوي عليها.

هنا مقتطف من StackView القطعة العينة RemoteViewsFactoryالتنفيذ التي تظهر أجزاء من onCreate()طريقة:


class StackRemoteViewsFactory implements
RemoteViewsService.RemoteViewsFactory {
    private static final int mCount = 10;
    private List<WidgetItem> mWidgetItems = new ArrayList<WidgetItem>();
    private Context mContext;
    private int mAppWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        mContext = context;
        mAppWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    public void onCreate() {
        // In onCreate() you setup any connections / cursors to your data source. Heavy lifting,
        // for example downloading or creating content etc, should be deferred to onDataSetChanged()
        // or getViewAt(). Taking more than 20 seconds in this call will result in an ANR.
        for (int i = 0; i < mCount; i++) {
            mWidgetItems.add(new WidgetItem(i + "!"));
        }
        ...
    }
...

على RemoteViewsFactoryطريقة getViewAt()بإرجاع RemoteViewsكائن الموافق البيانات في المحدد positionفي مجموعة البيانات. هنا مقتطف من StackView القطعة العينة RemoteViewsFactoryالتنفيذ:


public RemoteViews getViewAt(int position) {

    // Construct a remote views item based on the app widget item XML file,
    // and set the text based on the position.
    RemoteViews rv = new RemoteViews(mContext.getPackageName(), R.layout.widget_item);
    rv.setTextViewText(R.id.widget_item, mWidgetItems.get(position).text);

    ...
    // Return the remote views object.
    return rv;
}

إضافة إلى السلوك الأصناف الفردية
تظهر لك المقاطع المذكورة أعلاه كيفية ربط البيانات إلى مجموعة تطبيقات عنصر واجهة المستخدم. ولكن ماذا إذا كنت ترغب في إضافة السلوك الديناميكي للعناصر فردية في عرض مجموعتك؟

كما هو موضح في طريق فئة AppWidgetProvider ، كنت تستخدم عادة setOnClickPendingIntent()لوضع الكائن فوق سلوك من هذا القبيل من شأنها أن تسبب زر لشن Activity. ولكن لا يسمح هذا النهج لوجهات نظر الطفل في عنصر جمع الفردية (لتوضيح، هل يمكن استخدام setOnClickPendingIntent()لإعداد زر العالمي في القطعة التطبيق Gmail والتي تطلق التطبيق، على سبيل المثال، ولكن ليس على عناصر القائمة الفردية). بدلا من ذلك، إضافة إلى سلوك النقر على العناصر الفردية في جمع واستخدام setOnClickFillInIntent(). وهذا يستتبع إنشاء قالب نية معلقة لعرض مجموعتك، ومن ثم وضع الحشو عازمة على كل عنصر في مجموعة عبر الخاص بك RemoteViewsFactory.

يستخدم هذا القسم عينة StackView القطعة لوصف كيفية إضافة السلوك إلى الأصناف الفردية. في عينة StackView القطعة ، إذا كان المستخدم يمس رأي كبار، تعرض القطعة التطبيق في Toastرسالة "لمست رأي ن "، حيث ن هو مؤشر (موقف) من وجهة نظر لمسها. هذه هي الطريقة التي يعمل بها:

و StackWidgetProvider(وهي AppWidgetProviderفئة فرعية) بإنشاء وجود نية في انتظار أن لديه عمل مخصص يسمى TOAST_ACTION.
عندما يلمس المستخدم وجهة نظر، وأطلق النية ويبث TOAST_ACTION.
يتم اعتراضها هذا البث من StackWidgetProviderالصورة onReceive()الأسلوب، والقطعة التطبيق يعرض Toastرسالة للرأي لمسها. يتم توفير بيانات للعناصر جمع من قبل RemoteViewsFactory، عبر RemoteViewsService.
ملاحظة: إن عينة StackView القطعة يستخدم البث، ولكن عادة ما القطعة التطبيق ببساطة إطلاق النشاط في سيناريو مثل هذا واحد.

إنشاء قالب نية انتظار
و StackWidgetProvider( AppWidgetProviderفرعية) يضع نية معلقة. الأفراد العناصر من مجموعة لا يمكن اقامة النوايا العالقة الخاصة بهم. بدلا من ذلك، جمع ككل يضع قالب نية المعلقة، وتعيين عناصر فردية تعبئة في نية لخلق سلوك فريدة من نوعها على أساس البند من بنود.

هذه الفئة أيضا يتلقى البث التي يتم إرسالها عندما يلمس المستخدم الرأي. يقوم بمعالجة هذا الحدث في تقريرها onReceive()الأسلوب. إذا عمل القصد هو TOAST_ACTION، تعرض القطعة التطبيق في Toastرسالة للرأي الحالي.

public class StackWidgetProvider extends AppWidgetProvider {
    public static final String TOAST_ACTION = "com.example.android.stackwidget.TOAST_ACTION";
    public static final String EXTRA_ITEM = "com.example.android.stackwidget.EXTRA_ITEM";

    ...

    // Called when the BroadcastReceiver receives an Intent broadcast.
    // Checks to see whether the intent's action is TOAST_ACTION. If it is, the app widget
    // displays a Toast message for the current item.
    @Override
    public void onReceive(Context context, Intent intent) {
        AppWidgetManager mgr = AppWidgetManager.getInstance(context);
        if (intent.getAction().equals(TOAST_ACTION)) {
            int appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
            int viewIndex = intent.getIntExtra(EXTRA_ITEM, 0);
            Toast.makeText(context, "Touched view " + viewIndex, Toast.LENGTH_SHORT).show();
        }
        super.onReceive(context, intent);
    }

    @Override
    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // update each of the app widgets with the remote adapter
        for (int i = 0; i < appWidgetIds.length; ++i) {

            // Sets up the intent that points to the StackViewService that will
            // provide the views for this collection.
            Intent intent = new Intent(context, StackWidgetService.class);
            intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            // When intents are compared, the extras are ignored, so we need to embed the extras
            // into the data so that the extras will not be ignored.
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            RemoteViews rv = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
            rv.setRemoteAdapter(appWidgetIds[i], R.id.stack_view, intent);

            // The empty view is displayed when the collection has no items. It should be a sibling
            // of the collection view.
            rv.setEmptyView(R.id.stack_view, R.id.empty_view);

            // This section makes it possible for items to have individualized behavior.
            // It does this by setting up a pending intent template. Individuals items of a collection
            // cannot set up their own pending intents. Instead, the collection as a whole sets
            // up a pending intent template, and the individual items set a fillInIntent
            // to create unique behavior on an item-by-item basis.
            Intent toastIntent = new Intent(context, StackWidgetProvider.class);
            // Set the action for the intent.
            // When the user touches a particular view, it will have the effect of
            // broadcasting TOAST_ACTION.
            toastIntent.setAction(StackWidgetProvider.TOAST_ACTION);
            toastIntent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetIds[i]);
            intent.setData(Uri.parse(intent.toUri(Intent.URI_INTENT_SCHEME)));
            PendingIntent toastPendingIntent = PendingIntent.getBroadcast(context, 0, toastIntent,
                PendingIntent.FLAG_UPDATE_CURRENT);
            rv.setPendingIntentTemplate(R.id.stack_view, toastPendingIntent);

            appWidgetManager.updateAppWidget(appWidgetIds[i], rv);
        }
    super.onUpdate(context, appWidgetManager, appWidgetIds);
    }
}

تحديد النوايا ملء في
الخاص بك RemoteViewsFactoryيجب تعيين تعبئة في عازمة على كل عنصر في المجموعة. هذا يجعل من الممكن للتمييز بين فرد على فوق العمل من بند معين. والقصد من ذلك ملء في وثم جنبا إلى جنب مع PendingIntentقالب من أجل تحديد القصد النهائي التي سيتم تنفيذها عند النقر فوق هذا البند.

public class StackWidgetService extends RemoteViewsService {
    @Override
    public RemoteViewsFactory onGetViewFactory(Intent intent) {
        return new StackRemoteViewsFactory(this.getApplicationContext(), intent);
    }
}

class StackRemoteViewsFactory implements RemoteViewsService.RemoteViewsFactory {
    private static final int mCount = 10;
    private List<WidgetItem> mWidgetItems = new ArrayList<WidgetItem>();
    private Context mContext;
    private int mAppWidgetId;

    public StackRemoteViewsFactory(Context context, Intent intent) {
        mContext = context;
        mAppWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,
                AppWidgetManager.INVALID_APPWIDGET_ID);
    }

    // Initialize the data set.
        public void onCreate() {
            // In onCreate() you set up any connections / cursors to your data source. Heavy lifting,
            // for example downloading or creating content etc, should be deferred to onDataSetChanged()
            // or getViewAt(). Taking more than 20 seconds in this call will result in an ANR.
            for (int i = 0; i < mCount; i++) {
                mWidgetItems.add(new WidgetItem(i + "!"));
            }
           ...
        }
        ...

        // Given the position (index) of a WidgetItem in the array, use the item's text value in
        // combination with the app widget item XML file to construct a RemoteViews object.
        public RemoteViews getViewAt(int position) {
            // position will always range from 0 to getCount() - 1.

            // Construct a RemoteViews item based on the app widget item XML file, and set the
            // text based on the position.
            RemoteViews rv = new RemoteViews(mContext.getPackageName(), R.layout.widget_item);
            rv.setTextViewText(R.id.widget_item, mWidgetItems.get(position).text);

            // Next, set a fill-intent, which will be used to fill in the pending intent template
            // that is set on the collection view in StackWidgetProvider.
            Bundle extras = new Bundle();
            extras.putInt(StackWidgetProvider.EXTRA_ITEM, position);
            Intent fillInIntent = new Intent();
            fillInIntent.putExtras(extras);
            // Make it possible to distinguish the individual on-click
            // action of a given item
            rv.setOnClickFillInIntent(R.id.widget_item, fillInIntent);

            ...

            // Return the RemoteViews object.
            return rv;
        }
    ...
    }

حفظ مجموعة جديدة البيانات
ويوضح الشكل التالي تدفق التي تحدث في القطعة التطبيق الذي يستخدم المجموعات عندما تحدث التحديثات. وتبين كيف يتفاعل رمز التطبيق القطعة مع RemoteViewsFactory، وكيف يمكن أن تؤدي التحديثات:

ميزة واحدة من الحاجيات التطبيق التي تستخدم مجموعات هي القدرة على تزويد المستخدمين مع المحتوى يصل إلى التاريخ. على سبيل المثال، والنظر في الروبوت 3.0 تطبيق Gmail القطعة، الذي يوفر للمستخدمين مع لقطة من علبة الوارد الخاصة بهم. لجعل هذا ممكنا، عليك أن تكون قادرا على تحريك الخاص بك RemoteViewsFactoryوعرض مجموعة لجلب وعرض البيانات الجديدة. يمكنك تحقيق ذلك مع AppWidgetManagerالدعوة notifyAppWidgetViewDataChanged(). هذه الدعوة النتائج في رد لديك RemoteViewsFactoryالصورة onDataSetChanged()طريقة، والتي تعطيك الفرصة لجلب أي بيانات جديدة. لاحظ أنه يمكنك تنفيذ عمليات مكثفة لتجهيز متزامن ضمن onDataSetChanged()الاستدعاء. ويضمن لك أن هذه الدعوة سيتم الانتهاء قبل صدور البيانات الفوقية أو الرأي المنال من RemoteViewsFactory. وبالإضافة إلى ذلك، يمكنك تنفيذ عمليات مكثفة لتجهيز داخلgetViewAt()طريقة. إذا تأخذ هذه الدعوة وقتا طويلا، وعرض تحميل (التي يحددها RemoteViewsFactoryالصورة getLoadingView()سيتم عرض طريقة) في الموقف المقابل ترى جمع حتى ترجع.



التطبيق القطعة المضيف


في هذه الوثيقة
تجليد التطبيقات الحاجيات
ربط الحاجيات التطبيق على الروبوت 4.0 وأقل
الحاجيات التطبيق ملزمة على الروبوت 4.1 وأعلى
مسؤوليات المضيف
أندرويد 3.0
أندرويد 3.1
أندرويد 4.0
أندرويد 4.1
الروبوت 4.2


تتيح شاشة أندرويد الرئيسية المتوفرة على معظم أجهزة أندرويد للمستخدم تضمين أدوات التطبيق للوصول السريع إلى المحتوى. إذا كنت بصدد إنشاء بديل للمنزل أو تطبيق مشابه، فيمكنك أيضا السماح للمستخدم بتضمين أدوات التطبيق من خلال تطبيق AppWidgetHost . هذا ليس شيئا أن معظم التطبيقات سوف تحتاج من أي وقت مضى للقيام به، ولكن إذا كنت تقوم بإنشاء المضيف الخاص بك، فمن المهم أن نفهم الالتزامات التعاقدية المضيف يوافق ضمنا.

وتركز هذه الوثيقة على المسؤوليات التي ينطوي عليها تنفيذ AppWidgetHost مخصص. للحصول على مثال حول كيفية تنفيذ AppWidgetHost ، راجع التعليمات البرمجية المصدر AppWidgetHost الشاشة الرئيسية الروبوت.

هنا لمحة عامة عن الفئات والمفاهيم الرئيسية المشاركة في تنفيذ AppWidgetHost مخصص:

التطبيق القطعة المضيف - و AppWidgetHost يوفر التفاعل مع خدمة أبويدجيت للتطبيقات، مثل الشاشة الرئيسية، التي تريد تضمين الحاجيات التطبيق في واجهة المستخدم الخاصة بهم. يجب أن يكون AppWidgetHost معرف فريد من نوعه داخل الحزمة الخاصة بالمضيف. يبقى هذا المعرف ثابتا في جميع استخدامات المضيف. معرف هو عادة قيمة الثابت ترميز التي قمت بتعيينها في التطبيق الخاص بك.
التطبيق القطعة إد - يتم تعيين كل مثيل القطعة التطبيق معرف فريد في وقت ملزمة (انظر bindAppWidgetIdIfAllowed() ، ونوقشت بمزيد من التفصيل في الحاجيات التطبيق ملزمة ). يتم الحصول على معرف فريد من قبل المضيف باستخدام allocateAppWidgetId() . هذا المعرف هو ثابت عبر عمر القطعة، وهذا هو، حتى يتم حذفها من المضيف. يجب أن تستمر أي حالة خاصة مضيف (مثل حجم وموقع القطعة) من قبل حزمة استضافة ويرتبط مع إد القطعة التطبيق.
التطبيق القطعة عرض المضيف - AppWidgetHostView يمكن أن يعتقد من الإطار الذي يتم ملفوفة القطعة في كلما يحتاج إلى أن يتم عرضها. يتم تعيين القطعة التطبيق إلى AppWidgetHostView كل مرة يتم تضخيم القطعة من قبل المضيف.
خيارات حزمة - يستخدم AppWidgetHost حزمة الخيارات لتوصيل المعلومات إلى AppWidgetProvider حول كيفية يتم عرض القطعة (على سبيل المثال، حجم النطاق، وعما إذا كان القطعة على شاشة لوكسكرين أو الشاشة الرئيسية). هذه المعلومات تسمح AppWidgetProvider لتخصيص محتويات القطعة والمظهر بناء على كيفية ومكان عرضه. يمكنك استخدام updateAppWidgetOptions() و updateAppWidgetSize() لتعديل حزمة عنصر واجهة مستخدم التطبيق. كل من هذه الأساليب تؤدي إلى إعادة الاتصال إلى AppWidgetProvider .
تجليد التطبيقات الحاجيات
عندما يضيف مستخدم أداة تطبيق إلى مضيف، تحدث عملية تسمى ملزمة . الربط يشير إلى ربط معرف معرف التطبيق معين إلى مضيف معين وإلى AppWidgetProvider محددة. هناك طرق مختلفة لتحقيق ذلك، اعتمادا على إصدار أندرويد الذي يعمل عليه التطبيق.

ربط الحاجيات التطبيق على الروبوت 4.0 وأقل
على الأجهزة التي تعمل بنظام التشغيل أندرويد الإصدار 4.0 والإصدارات الأحدث، يضيف المستخدمون أدوات التطبيق عبر نشاط النظام الذي يسمح للمستخدمين بتحديد أداة. وهذا يعني ضمنا التحقق من الإذن، وهذا هو، عن طريق إضافة القطعة التطبيق، المستخدم منح ضمنا إذن لتطبيقك لإضافة الحاجيات التطبيق إلى المضيف. هنا هو مثال يوضح هذا النهج، مأخوذة من قاذفة الأصلي. في هذا المقتطف، يستدعي معالج الأحداث startActivityForResult() برمز الطلب REQUEST_PICK_APPWIDGET استجابة لإجراء المستخدم:

private static final int REQUEST_CREATE_APPWIDGET = 5;
private static final int REQUEST_PICK_APPWIDGET = 9;
...
public void onClick(DialogInterface dialog, int which) {
    switch (which) {
    ...
        case AddAdapter.ITEM_APPWIDGET: {
            ...
            int appWidgetId =
                    Launcher.this.mAppWidgetHost.allocateAppWidgetId();
            Intent pickIntent =
                    new Intent(AppWidgetManager.ACTION_APPWIDGET_PICK);
            pickIntent.putExtra
                    (AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
            ...
            startActivityForResult(pickIntent, REQUEST_PICK_APPWIDGET);
            break;
    }
    ...
}

عندما ينتهي نشاط النظام، فإنه يعود نتيجة مع القطعة التطبيق المستخدم المختار إلى النشاط الخاص بك. في المثال التالي، يستجيب النشاط عن طريق استدعاء addAppWidget() لإضافة عنصر واجهة التطبيق:



public final class Launcher extends Activity
        implements View.OnClickListener, OnLongClickListener {
    ...
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        mWaitingForResult = false;

        if (resultCode == RESULT_OK && mAddItemCellInfo != null) {
            switch (requestCode) {
                ...
                case REQUEST_PICK_APPWIDGET:
                    addAppWidget(data);
                    break;
                case REQUEST_CREATE_APPWIDGET:
                    completeAddAppWidget(data, mAddItemCellInfo, !mDesktopLocked);
                    break;
                }
        }
        ...
    }
}

طريقة addAppWidget() يتحقق لمعرفة ما إذا كان يحتاج التطبيق القطعة ليتم تكوين قبل إضافته:


void addAppWidget(Intent data) {
    int appWidgetId = data.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, -1);

    String customWidget = data.getStringExtra(EXTRA_CUSTOM_WIDGET);
    AppWidgetProviderInfo appWidget =
            mAppWidgetManager.getAppWidgetInfo(appWidgetId);

    if (appWidget.configure != null) {
        // Launch over to configure widget, if needed.
        Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_CONFIGURE);
        intent.setComponent(appWidget.configure);
        intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
        startActivityForResult(intent, REQUEST_CREATE_APPWIDGET);
    } else {
        // Otherwise, finish adding the widget.
    }
}
لمزيد من المناقشة حول التهيئة، راجع إنشاء نشاط تكوين أداة تطبيق .

مرة واحدة القطعة التطبيق جاهز، فإن الخطوة التالية هي أن تفعل العمل الفعلي لإضافته إلى مساحة العمل. يستخدم قاذفة الأصلي طريقة تسمى completeAddAppWidget() للقيام بذلك.

الحاجيات التطبيق ملزمة على الروبوت 4.1 وأعلى
يضيف أندرويد 4.1 واجهات برمجة التطبيقات لعملية ربط أكثر سلاسة. كما تتيح واجهات برمجة التطبيقات هذه للمضيف توفير واجهة مستخدم مخصصة للربط. لاستخدام هذه العملية المحسنة، يجب أن يعلن تطبيقك عن إذن BIND_APPWIDGET في بيانه:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
ولكن هذه ليست سوى الخطوة الأولى. في وقت التشغيل يجب على المستخدم منح إذن صريح لتطبيقك للسماح له بإضافة أدوات التطبيق إلى المضيف. لاختبار ما إذا كان التطبيق لديه إذن لإضافة الأداة، يمكنك استخدام الأسلوب bindAppWidgetIdIfAllowed() . إذا bindAppWidgetIdIfAllowed() false ، يجب أن يعرض التطبيق مربع حوار bindAppWidgetIdIfAllowed() المستخدم بمنح الإذن ("السماح" أو "تسمح دائما" لتغطية جميع إضافات التطبيقات في المستقبل). يقدم هذا المقتطف مثالا على كيفية عرض مربع الحوار:

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 discussed above
intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options);
startActivityForResult(intent, REQUEST_BIND_APPWIDGET);


المضيف لديه أيضا للتحقق ما إذا كان المستخدم إضافة القطعة التطبيق الذي يحتاج التكوين. لمزيد من المناقشة حول هذا الموضوع، راجع إنشاء نشاط تكوين أداة تطبيق .

مسؤوليات المضيف
ما هي النسخة التي تستهدفها؟
يجب أن يعتمد النهج الذي تستخدمه في تنفيذ مضيفك على إصدار أندرويد الذي تستهدفه. تم عرض العديد من الميزات المذكورة في هذا القسم في 3.0 أو في وقت لاحق. فمثلا:

يقدم أندرويد 3.0 (أبي ليفيل 11) سلوك التقدم التلقائي للحاجيات.
الروبوت 3.1 (أبي مستوى 12) يدخل القدرة على تغيير حجم الحاجيات.
يقدم أندرويد 4.0 (أبي ليفيل 15) تغييرا في سياسة الحشو يضع المسؤولية على المضيف لإدارة الحشو.
يضيف أندرويد 4.1 (أبي ليفيل 16) واجهة برمجة التطبيقات التي تسمح لمزود الأداة للحصول على معلومات أكثر تفصيلا حول البيئة التي يتم فيها استضافة مثيلات الأداة.
يقدم أندرويد 4.2 (أبي ليفيل 17) حزمة الخيارات وطريقة bindAppWidgetIdIfAllowed() . كما يقدم الحاجيات قفل الشاشة.
إذا كنت تستهدف أجهزة سابقة، فارجع إلى المشغل الأصلي كمثال.
يمكن لمطوري البرامج تحديد عدد من إعدادات التكوين للحاجيات باستخدام البيانات الوصفية أبويدجيتبروفيدرينفو . يمكن استرجاع خيارات التكوين هذه، التي تمت مناقشتها بمزيد من التفصيل أدناه، بواسطة المضيف من الكائن AppWidgetProviderInfo المقترن بمزود الأداة.

بغض النظر عن إصدار أندرويد الذي تستهدفه، فإن جميع المضيفين يتحملون المسؤوليات التالية:

عند إضافة عنصر واجهة مستخدم، يجب تخصيص معرف الأداة كما هو موضح أعلاه. يجب أيضا التأكد من أنه عند إزالة أداة من المضيف، استدعاء deleteAppWidgetId() تحديد معرف الأداة.
عند إضافة عنصر واجهة مستخدم، تأكد من تشغيل نشاط التكوين الخاص به إذا كان موجودا، كما هو موضح في تحديث أداة التطبيق من نشاط التكوين . هذه خطوة ضرورية للعديد من الحاجيات التطبيق قبل أن يمكن عرضها بشكل صحيح.
كل القطعة التطبيق يحدد الحد الأدنى للعرض والارتفاع في دبس، كما هو محدد في البيانات الوصفية AppWidgetProviderInfo (باستخدام android:minWidth android:minHeight ). تأكد من أن القطعة وضعت بها على الأقل هذا العديد من دبس. على سبيل المثال، العديد من المضيفين محاذاة الرموز والحاجيات في شبكة. في هذا السيناريو، بشكل افتراضي المضيف يجب إضافة القطعة التطبيق باستخدام الحد الأدنى لعدد الخلايا التي تلبي minWidth و minHeight القيود.
بالإضافة إلى المتطلبات المذكورة أعلاه، إصدارات منصة محددة إدخال الميزات التي تضع مسؤوليات جديدة على المضيف. وهذا ما تم شرحه في الفقرات التالية.

أندرويد 3.0
الروبوت 3.0 (مستوى أبي 11) يقدم القدرة على القطعة لتحديد autoAdvanceViewId() . يجب أن يشير معرف المشاهدة هذا إلى مثيل ل Advanceable ، مثل StackView أو AdapterViewFlipper . هذا يشير إلى أن المضيف يجب استدعاء advance() على هذا الرأي في الفاصل الزمني الذي يعتبر مناسبا من قبل المضيف (مع الأخذ بعين الاعتبار ما إذا كان من المنطقي للمضي قدما القطعة - على سبيل المثال، المضيف ربما لا ترغب في دفع القطعة إذا كان على صفحة أخرى، أو إذا تم إيقاف تشغيل الشاشة).

أندرويد 3.1
الروبوت 3.1 (أبي مستوى 12) يدخل القدرة على تغيير حجم الحاجيات. يمكن android:resizeMode أن تحدد أنه يمكن تغيير android:resizeMode السمة android:resizeMode في البيانات الوصفية AppWidgetProviderInfo ، وبيان ما إذا كان يدعم تغيير الحجم الأفقي و / أو العمودي. قدم في الروبوت 4.0 (أبي مستوى 14)، القطعة يمكن أيضا تحديد android:minResizeWidth و / أو android:minResizeHeight .

ومن مسؤولية المضيف لجعل من الممكن القطعة لتغيير حجمها أفقيا و / أو عموديا، كما هو محدد من قبل القطعة. القطعة التي تحدد أنه يمكن تغيير حجمها يمكن تغيير حجمها بشكل تعسفي كبير، ولكن لا ينبغي تغيير حجمها أصغر من القيم المحددة من قبل android:minResizeWidth android:minResizeHeight . لتنفيذ نموذج، راجع AppWidgetResizeFrame في Launcher2 .

أندرويد 4.0
يقدم أندرويد 4.0 (أبي ليفيل 15) تغييرا في سياسة الحشو يضع المسؤولية على المضيف لإدارة الحشو. اعتبارا من 4.0، الحاجيات التطبيق لم تعد تشمل الحشو الخاصة بهم. بدلا من ذلك، يضيف النظام الحشو لكل القطعة، استنادا إلى خصائص الشاشة الحالية. وهذا يؤدي إلى عرض أكثر اتساقا، متسقة من الحاجيات في الشبكة. لمساعدة التطبيقات التي الحاجيات التطبيق المضيف، يوفر النظام الأساسي getDefaultPaddingForWidget() . يمكن للتطبيقات استدعاء هذه الطريقة للحصول على الحشو المعرفة من قبل النظام وحساب لذلك عند حساب عدد الخلايا لتخصيص القطعة.

أندرويد 4.1
يضيف أندرويد 4.1 (أبي ليفيل 16) واجهة برمجة التطبيقات التي تسمح لمزود الأداة للحصول على معلومات أكثر تفصيلا حول البيئة التي يتم فيها استضافة مثيلات الأداة. على وجه التحديد، يشير المضيف إلى موفر القطعة حول الحجم الذي يتم عرض القطعة. وتقع على عاتق المضيف مسؤولية توفير معلومات الحجم.

يوفر المضيف هذه المعلومات عبر updateAppWidgetSize() . يتم تحديد حجم كحد أدنى والحد الأقصى العرض / الارتفاع في دبس. السبب في تحديد نطاق (بدلا من حجم ثابت) لأن العرض والارتفاع من القطعة قد تتغير مع التوجه. لا تريد أن يقوم المضيف بتحديث جميع أدواته على التناوب، لأن ذلك قد يؤدي إلى تباطؤ خطير في النظام. يجب تحديث هذه القيم مرة واحدة على القطعة التي يتم وضعها، في أي وقت يتم تغيير حجم القطعة، وفي أي وقت قاذفة تضخيم القطعة لأول مرة في التمهيد معين (كما لا تستمر القيم عبر التمهيد).

الروبوت 4.2
الروبوت 4.2 (أبي مستوى 17) يضيف القدرة على حزمة الخيارات التي سيتم تحديدها في وقت الربط. هذه هي الطريقة المثلى لتحديد خيارات التطبيق القطعة، بما في ذلك حجم، لأنه يعطي الوصول الفوري AppWidgetProvider إلى بيانات الخيارات على التحديث الأول. يمكن تحقيق ذلك باستخدام طريقة bindAppWidgetIdIfAllowed() . لمزيد من المناقشة حول هذا الموضوع، راجع أدوات تطبيق الربط .

الروبوت 4.2 يقدم أيضا الحاجيات لوكسكرين. عند استضافة الحاجيات على لوكسكرين، يجب على المضيف تحديد هذه المعلومات داخل حزمة التطبيق خيارات حزمة (و AppWidgetProvider يمكن استخدام هذه المعلومات على غرار القطعة بشكل مناسب). لتعيين عنصر واجهة مستخدم باعتباره أداة لوكسكرين، استخدم updateAppWidgetOptions() OPTION_APPWIDGET_HOST_CATEGORY الحقل OPTION_APPWIDGET_HOST_CATEGORY بقيمة WIDGET_CATEGORY_KEYGUARD . هذا الخيار افتراضيا على WIDGET_CATEGORY_HOME_SCREEN ، لذلك ليس مطلوبا بشكل صريح لتعيين هذا المضيف المضيف للشاشة الرئيسية.

تأكد من أن المضيف يضيف فقط أدوات التطبيق المناسبة لتطبيقك - على سبيل المثال، إذا كان المضيف هو شاشة رئيسية، فتأكد من أن السمة android:widgetCategory في البيانات الوصفية AppWidgetProviderInfo تتضمن العلم WIDGET_CATEGORY_HOME_SCREEN . وبالمثل، بالنسبة لوكسكرين، تأكد من أن الحقل يتضمن العلم WIDGET_CATEGORY_KEYGUARD . لمزيد من المناقشة حول هذا الموضوع، راجع تمكين أدوات التطبيقات على شاشة لوكسكرين .