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

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

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

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

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

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

• تجنَّب استخدام المربّعات لتشغيل تطبيق. بدلاً من ذلك، استخدِم اختصارًا للتطبيق أو مشغّلاً عاديًا.

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

• تجنَّب إنشاء الكثير من المربّعات. ننصحك باستخدام مربّعَين كحد أقصى لكل تطبيق. بدلاً من ذلك، استخدِم اختصارًا للتطبيق.

• تجنَّب استخدام المربّعات التي تعرض معلومات، ولكنها ليست تفاعلية للمستخدمين. بدلاً من ذلك، استخدِم إشعارًا أو أداة.

إنشاء المربّع

لإنشاء مربّع، عليك أولاً إنشاء رمز مربّع مناسب، ثم إنشاء 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()
  }
}

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

أعلن عن TileService في ملف بيان التطبيق. أضِف اسم TileService وتصنيفه والرمز المخصّص الذي أنشأته في القسم السابق والإذن المناسب.

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     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(): يتم استدعاء هذا الأسلوب فقط عندما يضيف المستخدم المربّع للمرة الأولى، وإذا أزاله المستخدم وأضافه مرة أخرى. هذا هو أفضل وقت لإجراء أي عملية تهيئة لمرة واحدة. ومع ذلك، قد لا يفي ذلك بجميع عمليات التهيئة المطلوبة.

• 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 أنّه غير متاح حاليًا للمستخدم لسبب ما.

لا يضبط النظام سوى الحالة الأولية لعنصر Tile. يمكنك ضبط حالة عنصر Tile خلال بقية دورة حياته.

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

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

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

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

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

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

عليك استدعاء 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 = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

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

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

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

var clicks = 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()
}

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

تشغيل مربّع حوار

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

تشغيل نشاط

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

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

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

بدءًا من Android API 28، يجب أن يحتوي PendingIntent على Intent.FLAG_ACTIVITY_NEW_TASK:

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

يمكنك بدلاً من ذلك إضافة العلامة في 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 تستخدم الفئات في "الإعدادات السريعة"، يمكن لمصنّعي المعدات الأصلية استخدام معلومات الفئة هذه أو تجاهلها في واجهات مستخدم النظام الخاصة بهم.

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

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

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

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

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

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

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

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

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