کاشی‌های تنظیمات سریع سفارشی را برای برنامه خود ایجاد کنید

تنظیمات سریع کاشی‌هایی هستند که در پانل تنظیمات سریع نمایش داده می‌شوند و نشان‌دهنده اقداماتی هستند که کاربران می‌توانند برای تکمیل سریع وظایف تکرار شونده روی آنها ضربه بزنند. برنامه شما می تواند یک کاشی سفارشی را از طریق کلاس TileService در اختیار کاربران قرار دهد و از یک شی Tile برای ردیابی وضعیت کاشی استفاده کند. به عنوان مثال، می توانید کاشی ایجاد کنید که به کاربران امکان می دهد VPN ارائه شده توسط برنامه شما را روشن یا خاموش کنند.

تصمیم بگیرید که چه زمانی یک کاشی ایجاد کنید

توصیه می‌کنیم کاشی‌هایی را برای قابلیت‌های خاصی ایجاد کنید که انتظار دارید کاربران اغلب به آن‌ها دسترسی داشته باشند یا نیاز به دسترسی سریع به آن‌ها (یا هر دو) داشته باشند. مؤثرترین کاشی‌ها آنهایی هستند که با هر دوی این ویژگی‌ها مطابقت داشته باشند و دسترسی سریع به کارهایی که اغلب انجام می‌شوند را فراهم می‌کنند.

به عنوان مثال، می توانید یک کاشی برای یک برنامه تناسب اندام ایجاد کنید که به کاربران اجازه می دهد تا به سرعت یک جلسه تمرین را شروع کنند. با این حال، ما ایجاد کاشی برای همان برنامه را توصیه نمی کنیم که به کاربران اجازه دهد کل تاریخچه تمرین خود را مرور کنند.

برای کمک به بهبود قابلیت کشف و سهولت استفاده از کاشی خود، توصیه می کنیم از برخی اقدامات اجتناب کنید:

• از استفاده از کاشی ها برای راه اندازی برنامه خودداری کنید. به جای آن از یک میانبر برنامه یا یک راه‌انداز استاندارد استفاده کنید.

• از استفاده از کاشی‌ها برای اقدامات یک‌باره کاربر خودداری کنید. به جای آن از میانبر برنامه یا اعلان استفاده کنید.

• از ایجاد کاشی های زیاد خودداری کنید. ما حداکثر دو در هر برنامه را توصیه می کنیم. به جای آن از میانبر برنامه استفاده کنید.

• از استفاده از کاشی هایی که اطلاعات را نمایش می دهند، اما برای کاربران تعاملی نیستند، خودداری کنید. به جای آن از اعلان یا ویجت استفاده کنید.

کاشی خود را ایجاد کنید

برای ایجاد یک کاشی، ابتدا باید یک نماد کاشی مناسب ایجاد کنید، سپس 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()

پس از تنظیم فیلدهای شی Tile روی مقادیر صحیح، باید updateTile() فراخوانی کنید تا کاشی خود را به روز کنید. این باعث می شود که سیستم داده های کاشی به روز شده را تجزیه کند و رابط کاربری را به روز کند.

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 داشته باشد.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. کاشی خود را نگه دارید و آن را به لیست کاشی های فعال بکشید.

کاربر همچنین می تواند کاشی شما را در هر نقطه جابجا یا حذف کند.

با شروع اندروید 13، می‌توانید از روش requestAddTileService() استفاده کنید تا کاربران بتوانند کاشی خود را به دستگاه اضافه کنند. این روش از کاربران درخواست می‌کند که کاشی شما را مستقیماً به پانل تنظیمات سریع خود اضافه کنند. درخواست شامل نام برنامه، برچسب ارائه شده و نماد است.

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

پاسخ تماس حاوی اطلاعاتی در مورد اضافه شدن یا نبودن کاشی، اضافه نشدن، وجود آن یا وجود هرگونه خطایی است.

هنگام تصمیم گیری در مورد اینکه چه زمانی و چند وقت یکبار از کاربران درخواست کنید از صلاحدید خود استفاده کنید. توصیه می‌کنیم requestAddTileService() را فقط در زمینه فراخوانی کنید - مانند زمانی که کاربر برای اولین بار با ویژگی‌ای که کاشی شما تسهیل می‌کند تعامل برقرار می‌کند.

اگر قبلاً بارها توسط کاربر رد شده باشد، سیستم می‌تواند پردازش درخواست‌ها را برای یک ComponentName معین متوقف کند. کاربر از Context مورد استفاده برای بازیابی این سرویس تعیین می شود - باید با کاربر فعلی مطابقت داشته باشد.