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

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

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

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

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

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

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

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

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

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

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

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

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

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

وستحتاج إلى إضافة رمز مخصّص يظهر على المربّع في لوحة "الإعدادات السريعة". (ستضيف هذا الرمز عند الإفصاح عن TileService، описанة في القسم التالي). يجب أن يكون الرمز أبيض خالصًا مع خلفية شفافة، وأن يكون أبعاده 24 x ‏24dp، وأن يكون على شكل 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". بعد ذلك، يستدعي النظام أسلوب callback 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 الذي تنقله إلى هذه الطريقة.

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

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

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

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

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

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

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

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

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