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

إنشاء مربّعات مخصّصة للإعدادات السريعة لتطبيقك

"الإعدادات السريعة" هي مربّعات تظهر في لوحة الإعدادات السريعة، وتمثّل إجراءات يمكن للمستخدمين النقر عليها لإكمال المهام المتكرّرة بسرعة. يمكن لتطبيقك توفير مربّع مخصّص للمستخدمين من خلال الفئة TileService، واستخدام عنصر Tile لتتبُّع حالة المربّع. على سبيل المثال، يمكنك إنشاء مربّع يتيح للمستخدمين تفعيل شبكة VPN يوفّرها تطبيقك أو إيقافها.

لوحة "الإعدادات السريعة" مع تفعيل مربّع شبكة VPN
وإيقافه — **الشكل 1.** لوحة "الإعدادات السريعة" مع تفعيل مربّع شبكة VPN وإيقافه

تحديد وقت إنشاء مربّع

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

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

حالات استخدام مربّعات تطبيقات اللياقة البدنية — **الشكل 2.** أمثلة على المربّعات المقترَحة وغير المقترَحة لتطبيق لياقة بدنية

للمساعدة في تحسين قابلية اكتشاف المربّع وسهولة استخدامه، ننصحك بتجنُّب بعض الممارسات:

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

إنشاء مربّع

لإنشاء مربّع، عليك أولاً إنشاء رمز مربّع مناسب، ثم إنشاء TileService والإعلان عنه في ملف بيان تطبيقك.

يقدّم نموذج "الإعدادات السريعة" مثالاً على كيفية إنشاء مربّع وإدارته.

إنشاء رمز مخصّص

يجب تقديم رمز مخصّص يظهر على المربّع في لوحة "الإعدادات السريعة". (ستضيف هذا الرمز عند الإعلان عن TileService، كما هو موضّح في القسم التالي). يجب أن يكون الرمز باللون الأبيض الخالص مع خلفية شفافة، وأن يكون مقاسه 24 × 24 بكسل مستقل الكثافة، وأن يكون على شكل VectorDrawable.

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

إنشاء TileService والإعلان عنها

أنشئ خدمة لبطاقتك تمدّد فئة TileService.

class MyQSTileService : TileService() {

    // Called when the user adds your tile.
    override fun onTileAdded() {
        super.onTileAdded()
    }
    // Called when your app can update your tile.
    override fun onStartListening() {
        super.onStartListening()
    }

    // Called when your app can no longer update your tile.
    override fun onStopListening() {
        super.onStopListening()
    }

    // Called when the user taps on your tile in an active or inactive state.
    override fun onClick() {
        super.onClick()
    }
    // Called when the user removes your tile.
    override fun onTileRemoved() {
        super.onTileRemoved()
    }
}QuickSettingsTilesSnippets.kt

يُرجى تعريف TileService في ملف بيان تطبيقك. أضِف اسم TileService وتصنيفه (ما يصل إلى 18 حرفًا لـ android:label)، والرمز المخصّص الذي أنشأته في القسم السابق، والإذن المناسب.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

إدارة TileService

بعد إنشاء TileService والإعلان عنه في ملف بيان تطبيقك، عليك إدارة حالته.

‫TileService هي خدمة ربط. يتم ربط TileService عندما يطلب تطبيقك ذلك أو إذا كان النظام بحاجة إلى التواصل معه. تتضمّن مراحل النشاط لخدمة الربط العادية طرق رد الاتصال الأربع التالية: onCreate() وonBind() وonUnbind() وonDestroy(). يستدعي النظام هذه الطرق في كل مرة تدخل فيها الخدمة مرحلة جديدة من مراحل النشاط.

نظرة عامة على مراحل نشاط TileService

بالإضافة إلى عمليات الاستدعاء التي تتحكّم في مراحل نشاط خدمة الربط، عليك تنفيذ طرق أخرى خاصة بمراحل نشاط TileService. قد يتم استدعاء هذه الطرق خارج onCreate() وonDestroy() لأنّ طرق مراحل النشاط في Service وطرق مراحل النشاط في TileService يتم استدعاؤها في سلسلتَي عمليات منفصلتَين غير متزامنتَين.

تحتوي مراحل نشاط TileService على الطرق التالية التي يستدعيها النظام في كل مرة يدخل فيها TileService مرحلة جديدة من مراحل النشاط:

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

ملاحظة: لا يتم استدعاء onTileAdded() عند إنشاء المربّع. على سبيل المثال، لا يتم استدعاء onTileAdded() عند إعادة تشغيل الجهاز أو تشغيله إذا تمت إضافة المربّع ولم تتم إزالته قبل إيقاف تشغيل الجهاز.
‫onStartListening() وonStopListening(): يتم استدعاء هاتين الطريقتين كلما حدّث تطبيقك المربّع، ويتم استدعاؤهما بشكل متكرر. يظل TileService مرتبطًا بين onStartListening() وonStopListening()، ما يسمح لتطبيقك بتعديل المربّع وإرسال التحديثات.
onTileRemoved(): يتم استدعاء هذه الطريقة فقط إذا أزال المستخدم مربّعك.

اختيار وضع الاستماع

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

لا تفترض أنّ TileService سيعمل خارج نطاق الطريقتين onStartListening() وonStopListening().

وضع النشاط (يُنصح به)

استخدِم الوضع النشط لـ TileService يستمع إلى حالته ويراقبها في عمليته الخاصة. يتم ربط TileService في وضع النشاط بـ "onTileAdded()" و"onTileRemoved()" وأحداث النقر وعندما تطلب عملية التطبيق ذلك.

ننصحك باستخدام الوضع النشط إذا كان TileService يتلقّى إشعارًا عندما يجب تحديث حالة المربّع من خلال العملية الخاصة به. تحدّ المربّعات النشطة من الضغط على النظام لأنّه لا يلزم ربطها في كل مرة تظهر فيها لوحة "الإعدادات السريعة" للمستخدم.

يمكن استدعاء الطريقة الثابتة TileService.requestListeningState() لطلب بدء حالة الاستماع وتلقّي رد اتصال على onStartListening().

يمكنك الإعلان عن الوضع النشط من خلال إضافة META_DATA_ACTIVE_TILE إلى ملف بيان تطبيقك.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
       android:value="true" />
    ...
</service>

وضع عدم النشاط

الوضع غير النشط هو الوضع العادي. يكون TileService في الوضع غير النشط إذا كان مرتبطًا كلما كان المربّع مرئيًا للمستخدم. وهذا يعني أنّ TileService قد يتم إنشاؤه وربطه مرة أخرى في أوقات خارجة عن سيطرته. وقد يتم أيضًا إلغاء ربطها وإتلافها عندما لا يعرض المستخدم المربّع.

يتلقّى تطبيقك طلب معاودة الاتصال على onStartListening() بعد أن يفتح المستخدم لوحة "الإعدادات السريعة". يمكنك تعديل عنصر "Tile" عدة مرات حسب رغبتك بين ‎onStartListening() و‎onStopListening().

ليس عليك الإفصاح عن الوضع غير النشط: لا تُضِف META_DATA_ACTIVE_TILE إلى ملف بيان تطبيقك.

نظرة عامة على حالات المربّعات

بعد أن يضيف المستخدم مربّعك، يكون دائمًا في إحدى الحالات التالية.

‫STATE_ACTIVE: تشير إلى حالة التشغيل أو التفعيل. ويمكن للمستخدم التفاعل مع المربّع في هذه الحالة.

على سبيل المثال، بالنسبة إلى مربّع تطبيق اللياقة البدنية الذي يتيح للمستخدمين بدء جلسة تمرين محدّدة بوقت، فإنّ STATE_ACTIVE تعني أنّ المستخدم قد بدأ جلسة تمرين وأنّ الموقّت قيد التشغيل.
STATE_INACTIVE: يشير إلى حالة الإيقاف أو الإيقاف المؤقت. ويمكن للمستخدم التفاعل مع المربّع في هذه الحالة.

لنعد إلى مثال تطبيق اللياقة البدنية، فظهور مربّع في STATE_INACTIVE يعني أنّ المستخدم لم يبدأ جلسة تمرين، ولكن يمكنه فعل ذلك إذا أراد.
‫STATE_UNAVAILABLE: تشير إلى حالة عدم توفّر مؤقتة. لا يمكن للمستخدم التفاعل مع المربّع في هذه الحالة.

على سبيل المثال، يشير المربّع في STATE_UNAVAILABLE إلى أنّ المربّع غير متاح حاليًا للمستخدم لسبب ما.

تنبيه: استخدِم STATE_UNAVAILABLE للمربّعات غير المتاحة حاليًا ولكن يمكن إتاحتها لاحقًا. إذا كان المكوّن لن يتوفّر للمستخدم مرة أخرى، يمكنك تمرير COMPONENT_ENABLED_STATE_DISABLED إلى setComponentEnabledSetting().

يضبط النظام الحالة الأولية لكائن Tile فقط. يمكنك ضبط حالة الكائن Tile طوال الفترة المتبقية من مراحل نشاطه.

قد يغيّر النظام لون رمز المربّع وخلفيته ليعكس حالة عنصر Tile. تكون العناصر التي تم ضبطها على Tile على STATE_ACTIVE هي الأغمق، مع STATE_INACTIVE وSTATE_UNAVAILABLE أفتح بشكل متزايد. ويختلف تدرّج اللون الدقيق حسب الشركة المصنّعة والإصدار.

تم تلوين مربّع شبكة VPN ليعكس حالات العناصر — **الشكل 4.** أمثلة على مربّع ملوّن ليعكس حالة المربّع (الحالات النشطة وغير النشطة وغير المتاحة على التوالي)

تعديل المربّع

يمكنك تعديل المربّع بعد تلقّي مكالمة على الرقم ‎onStartListening(). استنادًا إلى وضع المربّع، يمكن تعديل المربّع مرة واحدة على الأقل حتى تلقّي معاودة الاتصال على onStopListening().

في وضع النشاط، يمكنك تعديل المربّع مرة واحدة بالضبط قبل تلقّي طلب معاودة الاتصال بـ onStopListening(). في الوضع غير النشط، يمكنك تعديل المربّع بقدر ما تريد بين onStartListening() وonStopListening().

يمكنك استرداد عنصر Tile من خلال طلب getQsTile(). لتعديل حقول معيّنة في عنصر Tile، يمكنك استدعاء الطرق التالية:

يجب استدعاء updateTile() لتعديل المربّع بعد الانتهاء من ضبط حقول عنصر Tile على القيم الصحيحة. سيؤدي ذلك إلى جعل النظام يحلّل بيانات المربّع المعدَّلة ويعدّل واجهة المستخدم.

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
    super.onStartListening()
    val state = getStateFromService()
    qsTile.label = state.label
    qsTile.contentDescription = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

التعامل مع النقرات

يمكن للمستخدمين النقر على المربّع لتنفيذ إجراء إذا كان المربّع في STATE_ACTIVE أو STATE_INACTIVE. بعد ذلك، يستدعي النظام دالة الاستدعاء onClick() في تطبيقك.

بعد أن يتلقّى تطبيقك طلب معاودة الاتصال من خلال onClick()، يمكنه تشغيل مربّع حوار أو نشاط أو بدء عمل في الخلفية أو تغيير حالة المربّع.

var counter = 0
override fun onClick() {
    super.onClick()
    counter++
    qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.label = "Clicked $counter times"
    qsTile.contentDescription = qsTile.label
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

فتح مربّع حوار

showDialog() يؤدي هذا الإجراء إلى تصغير لوحة "الإعدادات السريعة" وعرض مربّع حوار. استخدِم مربّع حوار لإضافة سياق إلى الإجراء إذا كان يتطلّب إدخالاً إضافيًا أو موافقة المستخدم.

بدء نشاط

startActivityAndCollapse() يبدأ نشاطًا أثناء تصغير اللوحة. تكون الأنشطة مفيدة إذا كانت هناك معلومات أكثر تفصيلاً لعرضها من داخل مربّع حوار، أو إذا كان الإجراء تفاعليًا للغاية.

إذا كان تطبيقك يتطلب تفاعلاً كبيرًا من المستخدم، يجب أن يشغّل التطبيق نشاطًا كملاذ أخير فقط. بدلاً من ذلك، ننصحك باستخدام مربّع حوار أو زر تبديل.

يؤدي النقر مع الاستمرار على مربّع إلى ظهور شاشة معلومات التطبيق للمستخدم. لتجاوز هذا السلوك وبدء نشاط لضبط الإعدادات المفضّلة بدلاً من ذلك، أضِف <intent-filter> إلى أحد أنشطتك باستخدام ACTION_QS_TILE_PREFERENCES.

بدءًا من الإصدار 28 من واجهة برمجة تطبيقات Android، يجب أن يتضمّن PendingIntent السمة Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}QuickSettingsTilesSnippets.kt

يمكنك بدلاً من ذلك إضافة العلامة في AndroidManifest.xml في قسم Activity المحدّد.

وضع علامة على المربّع تشير إلى أنّه قابل للتبديل

ننصحك بوضع علامة على المربّع كقابل للتبديل إذا كان يعمل بشكل أساسي كمفتاح تبديل بين حالتين (وهو السلوك الأكثر شيوعًا للمربّعات). يساعد ذلك في توفير معلومات حول سلوك المربّع لنظام التشغيل وتحسين إمكانية الوصول بشكل عام.

اضبط البيانات الوصفية TOGGLEABLE_TILE على true لوضع علامة على المربّع بأنّه قابل للتبديل.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

تنفيذ الإجراءات الآمنة فقط على الأجهزة المقفلة بأمان

قد يظهر المربّع أعلى شاشة القفل على الأجهزة المقفلة. إذا كان المربّع يحتوي على معلومات حساسة، تحقَّق من قيمة isSecure() لتحديد ما إذا كان الجهاز في حالة آمنة، ويجب أن يغيّر TileService سلوكه وفقًا لذلك.

إذا كان إجراء المربّع آمنًا أثناء قفل الشاشة، استخدِم startActivity() لبدء نشاط فوق شاشة القفل.

إذا كان الإجراء الذي يتم تنفيذه من خلال المربّع غير آمن، استخدِم unlockAndRun() لطلب فتح قفل الجهاز من المستخدم. في حال نجاح العملية، ينفّذ النظام عنصر Runnable الذي تم تمريره إلى هذه الطريقة.

تصنيف شاشة المعلومات

لتحسين تجربة المستخدم في "الإعدادات السريعة"، يمكنك تصنيف المربّع. ينظّم النظام المربّعات في فئات مثل "إمكانية الاتصال" و"الشاشة" و"الخصوصية". يستخدم النظام هذه الفئات لترتيب المربّعات وتجميعها في وضع تعديل "الإعدادات السريعة"، ما يسهّل على المستخدمين العثور عليها وإدارتها.

التنفيذ

لتحديد فئة لـ TileService، أضِف حقل بيانات وصفية إلى بيان الخدمة في ملف AndroidManifest.xml:

في AndroidManifest.xml، ضمن العنصر <service> لـ TileService، أضِف العنصر <meta-data>.
‫android:name: اضبط هذه القيمة على android.service.quicksettings.TILE_CATEGORY.
android:value: يمكنك تعيين أحد ثوابت الفئات المحدّدة مسبقًا، مثل android.service.quicksettings.CATEGORY_CONNECTIVITY أو android.service.quicksettings.CATEGORY_DISPLAY.

كما هو موضّح في المثال التالي:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

توفّر واجهة برمجة التطبيقات مجموعة من الفئات المحدّدة مسبقًا للاختيار من بينها. يتم تحديد هذه الفئات كسلاسل ثابتة ضمن فئة TileService.

إذا لم يتم تحديد فئة، يحدّد النظام تلقائيًا فئة تلقائية:

من تطبيقات النظام: للبطاقات التي تشكّل جزءًا من تطبيق نظام
من التطبيقات المثبَّتة: للمربّعات من التطبيقات التي ثبّتها المستخدم

على الرغم من أنّ أجهزة Google Pixel تستخدم الفئات في "الإعدادات السريعة"، يمكن للمصنّعين الأصليين للأجهزة استخدام معلومات الفئات هذه أو تجاهلها في واجهات مستخدم النظام الخاصة بهم.

طلب إضافة المربّع من المستخدم

لإضافة المربّع يدويًا، على المستخدمين اتّباع الخطوات التالية:

مرِّر سريعًا للأسفل لفتح لوحة "الإعدادات السريعة".
انقر على زر التعديل.
التمرير عبر جميع المربّعات على جهازه حتى يعثر على المربّع الخاص بك
اضغط مع الاستمرار على المربّع واسحبه إلى قائمة المربّعات النشطة.

ويمكن للمستخدم أيضًا نقل المربّع أو إزالته في أي وقت.

اعتبارًا من الإصدار 13 من نظام التشغيل Android، يمكنك استخدام طريقة requestAddTileService() لتسهيل إضافة المربّع إلى الجهاز على المستخدمين. تطلب هذه الطريقة من المستخدمين إضافة المربّع بسرعة إلى لوحة "الإعدادات السريعة" مباشرةً. يتضمّن الطلب اسم التطبيق والتصنيف المقدَّم والرمز.

**الشكل 5.** طلب Quick Settings Placement API

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

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

استخدِم تقديرك الخاص عند تحديد وقت طلب الإذن من المستخدمين وعدد مرات ذلك. ننصحك باستدعاء requestAddTileService() فقط في السياق، مثلاً عندما يتفاعل المستخدم لأول مرة مع ميزة يسهّلها المربّع.

يمكن للنظام اختيار إيقاف معالجة طلبات الحصول على ComponentName معيّن إذا رفضه المستخدم لعدد كافٍ من المرات من قبل. يتم تحديد المستخدم من خلال Context المستخدَم لاسترداد هذه الخدمة: يجب أن يتطابق مع المستخدم الحالي.