تنظیمات سریع کاشیهایی هستند که در پانل تنظیمات سریع نمایش داده میشوند و نشاندهنده اقداماتی هستند که کاربران میتوانند برای تکمیل سریع وظایف تکرار شونده روی آنها ضربه بزنند. برنامه شما می تواند یک کاشی سفارشی را از طریق کلاس 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
خود، روش های زیر را فراخوانی کنید:
پس از تنظیم فیلدهای شی 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 برنامه شما را فراخوانی می کند.
هنگامی که برنامه شما یک پاسخ به 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
را که به این روش ارسال می کنید، اجرا می کند.
از کاربر بخواهید کاشی شما را اضافه کند
برای افزودن دستی کاشی خود، کاربران باید چندین مرحله را دنبال کنند:
- برای باز کردن پانل تنظیمات سریع، انگشت خود را به پایین بکشید.
- روی دکمه ویرایش ضربه بزنید.
- در تمام کاشیهای دستگاه آنها پیمایش کنید تا زمانی که کاشی شما را پیدا کنند.
- کاشی خود را نگه دارید و آن را به لیست کاشی های فعال بکشید.
کاربر همچنین می تواند کاشی شما را در هر نقطه جابجا یا حذف کند.
با شروع اندروید 13، میتوانید از روش requestAddTileService()
استفاده کنید تا کاربران بتوانند کاشی خود را به دستگاه اضافه کنند. این روش از کاربران درخواست میکند که کاشی شما را مستقیماً به پانل تنظیمات سریع خود اضافه کنند. درخواست شامل نام برنامه، برچسب ارائه شده و نماد است.
public void requestAddTileService (
ComponentName tileServiceComponentName,
CharSequence tileLabel,
Icon icon,
Executor resultExecutor,
Consumer<Integer> resultCallback
)
پاسخ تماس حاوی اطلاعاتی در مورد اضافه شدن یا نبودن کاشی، اضافه نشدن، وجود آن یا وجود هرگونه خطایی است.
هنگام تصمیم گیری در مورد اینکه چه زمانی و چند وقت یکبار از کاربران درخواست کنید از صلاحدید خود استفاده کنید. توصیه میکنیم requestAddTileService()
فقط در زمینه فراخوانی کنید - مانند زمانی که کاربر برای اولین بار با ویژگیای که کاشی شما تسهیل میکند تعامل برقرار میکند.
اگر قبلاً بارها توسط کاربر رد شده باشد، سیستم میتواند پردازش درخواستها را برای یک ComponentName
معین متوقف کند. کاربر از روی Context
مورد استفاده برای بازیابی این سرویس تعیین می شود - باید با کاربر فعلی مطابقت داشته باشد.