Setelan Cepat adalah kartu yang ditampilkan di panel Setelan Cepat,
mewakili tindakan, yang dapat diketuk pengguna untuk menyelesaikan tugas berulang dengan cepat.
Aplikasi Anda dapat menyediakan kartu kustom kepada pengguna melalui TileService
class, dan gunakan objek Tile
untuk melacak status kartu. Misalnya,
Anda dapat membuat kartu yang memungkinkan pengguna mengaktifkan VPN yang disediakan oleh aplikasi Anda atau
nonaktif.
![Panel Setelan Cepat dengan kartu VPN diaktifkan
aktif dan nonaktif](https://android-dot-devsite-v2-prod.appspot.com/static/develop/ui/views/images/quick-settings-vpn-on-off.png?hl=id)
Menentukan kapan harus membuat kartu
Sebaiknya buat kartu untuk fungsi tertentu yang Anda harapkan dari pengguna untuk sering mengakses atau memerlukan akses cepat ke (atau keduanya). Yang paling efektif Kartu adalah kartu yang sesuai dengan kedua kualitas ini, sehingga memberikan akses cepat ke tindakan yang sering dilakukan.
Misalnya, Anda dapat membuat kartu untuk aplikasi kebugaran yang memungkinkan pengguna memulai sesi latihan dengan cepat. Namun, sebaiknya jangan membuat kartu untuk aplikasi yang sama yang akan memungkinkan pengguna meninjau seluruh riwayat olahraga mereka.
![Kasus penggunaan kartu aplikasi kebugaran](https://android-dot-devsite-v2-prod.appspot.com/static/develop/ui/views/images/use-cases-fitness-tiles.png?hl=id)
Untuk membantu meningkatkan visibilitas dan kemudahan penggunaan kartu Anda, sebaiknya menghindari praktik-praktik tertentu:
Hindari menggunakan kartu untuk meluncurkan aplikasi. Gunakan pintasan aplikasi atau pintasan standar peluncur.
Hindari penggunaan kartu untuk tindakan pengguna satu kali. Gunakan pintasan aplikasi atau notifikasi.
Hindari membuat terlalu banyak kartu. Sebaiknya gunakan maksimum dua format per aplikasi. Gunakan pintasan aplikasi.
Hindari penggunaan ubin yang menampilkan informasi, tetapi tidak interaktif untuk pengguna. Gunakan notifikasi atau widget sebagai gantinya.
Membuat kartu
Untuk membuat kartu, Anda harus terlebih dahulu membuat ikon kartu yang sesuai, lalu
membuat dan mendeklarasikan TileService
dalam file manifes aplikasi.
Contoh Setelan Cepat memberikan contoh cara membuat dan mengelola kartu.
Buat ikon khusus Anda
Anda harus menyediakan ikon khusus, yang akan ditampilkan pada kartu di
Panel setelan. (Anda akan menambahkan ikon ini saat mendeklarasikan TileService
,
yang akan dijelaskan di bagian berikutnya.) Ikon harus berwarna putih solid dengan
latar belakang transparan, berukuran 24 x 24dp, dan dalam bentuk
VectorDrawable
![Contoh vektor drawable](https://android-dot-devsite-v2-prod.appspot.com/static/develop/ui/views/images/vector-drawable.png?hl=id)
Buat ikon yang secara visual mengisyaratkan tujuan kartu Anda. Hal ini membantu pengguna agar dapat dengan mudah mengidentifikasi apakah ubin Anda sesuai dengan kebutuhan mereka. Misalnya, Anda dapat membuat ikon stopwatch untuk kartu aplikasi kebugaran yang memungkinkan pengguna memulai sesi latihan fisik.
Membuat dan mendeklarasikan TileService Anda
Buat layanan untuk kartu Anda yang memperluas class TileService
.
Kotlin
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() } }
Java
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(); } }
Deklarasikan TileService
di file manifes aplikasi Anda. Tambahkan nama dan label
TileService
, ikon khusus yang Anda buat di bagian sebelumnya,
dan izin akses yang tepat.
<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>
Mengelola TileService Anda
Setelah membuat dan mendeklarasikan TileService
di manifes aplikasi, Anda
harus mengelola statusnya.
TileService
adalah layanan terikat. TileService
Anda terikat saat
diminta oleh aplikasi atau jika sistem perlu berkomunikasi dengannya. Karakteristik
Siklus proses layanan terikat berisi empat metode callback berikut:
onCreate()
, onBind()
, onUnbind()
, dan
onDestroy()
. Metode ini dipanggil oleh sistem setiap kali
layanan memasuki fase
siklus proses yang baru.
Ringkasan siklus proses TileService
Selain callback yang mengontrol siklus proses layanan terikat, Anda harus
mengimplementasikan metode lain khusus untuk siklus proses TileService
. Metode ini
dapat dipanggil di luar onCreate()
dan onDestroy()
karena Service
metode siklus proses dan metode siklus proses TileService
dipanggil dalam dua
dan thread asinkron yang terpisah.
Siklus proses TileService
berisi metode berikut, yang dipanggil
oleh sistem setiap kali TileService
memasuki fase siklus proses baru:
onTileAdded()
: Metode ini hanya dipanggil jika pengguna menambahkan untuk pertama kalinya, dan jika pengguna menghapus dan menambahkan kartu Anda lagi. Ini adalah waktu terbaik untuk melakukan inisialisasi satu kali. Namun, hal ini mungkin tidak memenuhi semua inisialisasi yang diperlukan.onStartListening()
danonStopListening()
: Metode ini dipanggil setiap kali aplikasi memperbarui kartu, dan sering dipanggil. TujuanTileService
tetap terikat antaraonStartListening()
danonStopListening()
, yang memungkinkan aplikasi Anda mengubah kartu dan mengirim update.onTileRemoved()
: Metode ini hanya dipanggil jika pengguna menghapus kartu.
Memilih mode mendengarkan
TileService
Anda mendengarkan dalam mode aktif atau mode nonaktif. Saran dari kami
menggunakan mode aktif, yang perlu Anda deklarasikan dalam manifes aplikasi. Jika tidak,
TileService
adalah mode standar dan tidak perlu dideklarasikan.
Jangan berasumsi TileService
akan aktif di luar onStartListening()
dan
Pasangan metode onStopListening()
.
Mode aktif (direkomendasikan)
Gunakan mode aktif untuk TileService
yang memproses dan memantau statusnya di
proses itu sendiri. TileService
dalam mode aktif terikat untuk onTileAdded()
,
onTileRemoved()
, peristiwa ketuk, dan jika diminta oleh proses aplikasi.
Kami merekomendasikan mode aktif jika TileService
diberi tahu saat kartu Anda berstatus
harus diperbarui oleh prosesnya sendiri. Ubin aktif membatasi keregangan pada
sistem karena tidak harus terikat setiap kali panel Setelan Cepat
terlihat oleh pengguna.
Metode TileService.requestListeningState()
statis dapat dipanggil ke
meminta dimulainya status pemrosesan dan menerima callback untuk
onStartListening()
.
Anda dapat mendeklarasikan mode aktif dengan menambahkan META_DATA_ACTIVE_TILE
ke elemen
file manifes aplikasi Anda.
<service ...>
<meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
android:value="true" />
...
</service>
Mode nonaktif
Mode nonaktif adalah mode standar. TileService
berada dalam mode nonaktif jika
itu akan terikat setiap kali kartu Anda dapat dilihat oleh pengguna. Ini berarti bahwa
TileService
dapat dibuat dan diikat lagi pada saat di luar kendali. Ini
juga dapat dilepas dan dihancurkan saat pengguna tidak melihat kartu.
Aplikasi Anda menerima callback ke onStartListening()
setelah pengguna membuka
Panel Setelan Cepat. Anda dapat memperbarui objek Tile
sebanyak yang Anda
yang diinginkan antara onStartListening()
dan onStopListening()
.
Anda tidak perlu mendeklarasikan mode non-aktif—cukup jangan tambahkan
META_DATA_ACTIVE_TILE
ke file manifes aplikasi Anda.
Ringkasan status kartu
Setelah pengguna menambahkannya, kartu Anda akan selalu ada dalam salah satu status berikut.
STATE_ACTIVE
: Menunjukkan status aktif atau diaktifkan. Pengguna dapat berinteraksi dengan kartu Anda saat dalam status ini.Misalnya, untuk kartu aplikasi kebugaran yang memungkinkan pengguna memulai olahraga terjadwal sesi,
STATE_ACTIVE
berarti pengguna telah memulai olahraga sesi dan timer sedang berjalan.STATE_INACTIVE
: Menunjukkan status nonaktif atau dijeda. Pengguna dapat berinteraksi dengan kartu Anda saat dalam status ini.Untuk menggunakan contoh kartu aplikasi kebugaran lagi, kartu di
STATE_INACTIVE
akan berarti bahwa pengguna belum memulai sesi latihan fisik, tetapi dapat melakukannya jika mereka ingin mewujudkannya.STATE_UNAVAILABLE
: Menunjukkan status tidak tersedia untuk sementara. Tujuan pengguna tidak dapat berinteraksi dengan kartu Anda saat dalam status ini.Misalnya, kartu di
STATE_UNAVAILABLE
berarti kartu tersebut tidak saat ini tersedia untuk pengguna karena suatu alasan.
Sistem hanya menetapkan status awal objek Tile
Anda. Anda menetapkan Tile
status objek di sepanjang sisa siklus prosesnya.
Sistem dapat memberikan warna pada ikon kotak dan latar belakang untuk mencerminkan status
Objek Tile
. Objek Tile
yang disetel ke STATE_ACTIVE
adalah yang paling gelap, dengan
STATE_INACTIVE
dan STATE_UNAVAILABLE
semakin ringan. Rona yang tepat
spesifik untuk produsen
dan versinya.
![Kartu VPN diberi warna untuk mencerminkan status objek](https://android-dot-devsite-v2-prod.appspot.com/static/develop/ui/views/images/state-hues.png?hl=id)
Memperbarui kartu Anda
Anda dapat memperbarui kartu setelah menerima callback ke onStartListening()
.
Tergantung pada mode kartu, kotak Anda bisa diperbarui setidaknya sekali sampai
menerima callback ke onStopListening()
.
Dalam mode aktif, Anda bisa memperbarui kotak tepat satu kali sebelum menerima
callback ke onStopListening()
. Dalam mode nonaktif, Anda dapat memperbarui kartu sebagai
sesering yang Anda inginkan antara onStartListening()
dan onStopListening()
.
Anda dapat mengambil objek Tile
dengan memanggil getQsTile()
. Untuk memperbarui
kolom tertentu dari objek Tile
Anda, panggil metode berikut:
Anda harus memanggil updateTile()
untuk memperbarui kartu setelah selesai menyetel
kolom objek Tile
ke nilai yang benar. Hal ini akan membuat sistem
mengurai data kartu yang diupdate dan mengupdate UI.
Kotlin
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() }
Java
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(); }
Menangani ketukan
Pengguna dapat mengetuk kartu untuk memicu tindakan jika kartu Anda berada
STATE_ACTIVE
atau STATE_INACTIVE
. Sistem kemudian memanggil metode
Callback onClick()
.
Setelah menerima callback ke onClick()
, aplikasi Anda dapat meluncurkan dialog atau
aktivitas, memicu pekerjaan latar belakang, atau mengubah status kartu.
Kotlin
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() }
Java
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(); }
Meluncurkan dialog
showDialog()
menciutkan panel Setelan Cepat dan menampilkan dialog.
Gunakan dialog untuk menambahkan konteks ke tindakan jika memerlukan input tambahan
atau persetujuan pengguna.
Meluncurkan aktivitas
startActivityAndCollapse()
memulai aktivitas saat menciutkan
. Aktivitas akan berguna jika ada informasi yang lebih detail untuk ditampilkan
daripada dalam dialog, atau jika tindakan Anda sangat interaktif.
Jika aplikasi Anda memerlukan interaksi pengguna yang signifikan, aplikasi harus meluncurkan aktivitas data hanya sebagai opsi terakhir. Sebagai gantinya, pertimbangkan untuk menggunakan dialog atau tombol.
Dengan mengetuk lama kartu, pengguna akan melihat layar Info Aplikasi. Untuk mengganti
perilaku ini dan sebagai gantinya meluncurkan aktivitas untuk menyetel preferensi, tambahkan
<intent-filter>
ke salah satu aktivitas Anda dengan
ACTION_QS_TILE_PREFERENCES
.
Mulai Android API 28, PendingIntent
harus
memiliki Intent.FLAG_ACTIVITY_NEW_TASK
:
if (Build.VERSION.SDK_INT >= 28) {
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}
Atau, Anda dapat menambahkan flag di AndroidManifest.xml
dalam metode
Activity
.
Menandai kartu Anda sebagai dapat dialihkan
Sebaiknya tandai kartu Anda sebagai dapat diganti-ganti jika fungsinya terutama sebagai tombol dua status (yang merupakan perilaku kartu yang paling umum). Hal ini membantu memberikan informasi tentang perilaku kartu ke sistem operasi dan meningkatkan aksesibilitas secara keseluruhan.
Setel metadata TOGGLEABLE_TILE
ke true
untuk menandai kartu Anda sebagai dapat diganti-ganti.
<service ...>
<meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
android:value="true" />
</service>
Hanya lakukan tindakan aman pada perangkat yang terkunci dengan aman
Kartu Anda mungkin ditampilkan di atas layar kunci pada perangkat yang terkunci. Jika ubin
berisi informasi sensitif, periksa nilai isSecure()
untuk
tentukan apakah perangkat dalam status aman, dan TileService
Anda harus
mengubah perilakunya secara tepat.
Jika tindakan kartu aman dilakukan saat terkunci, gunakan startActivity()
untuk meluncurkan aktivitas di atas layar kunci.
Jika tindakan kartu tidak aman, gunakan unlockAndRun()
untuk meminta pengguna
membuka kunci perangkatnya. Jika berhasil, sistem akan menjalankan
Objek Runnable
yang Anda teruskan ke objek ini
.
Meminta pengguna untuk menambahkan kartu
Untuk menambahkan kartu secara manual, pengguna harus mengikuti beberapa langkah:
- Geser ke bawah untuk membuka panel Setelan Cepat.
- Ketuk tombol edit.
- Men-scroll semua kartu di perangkat mereka sampai mereka menemukan kartu Anda.
- Tahan kotak Anda, dan seret ke daftar kotak yang aktif.
Pengguna juga dapat memindahkan atau menghapus kartu kapan saja.
Mulai Android 13, Anda dapat menggunakan metode requestAddTileService()
untuk memudahkan pengguna menambahkan kartu Anda ke perangkat. Metode ini
meminta pengguna untuk menambahkan kartu Anda dengan cepat langsung ke aplikasi Quick
Panel setelan. Perintahnya mencakup nama aplikasi, label yang diberikan,
dan ikon.
![Perintah Quick Settings Placement API](https://android-dot-devsite-v2-prod.appspot.com/static/develop/ui/views/images/placement-api-user-prompt.png?hl=id)
public void requestAddTileService (
ComponentName tileServiceComponentName,
CharSequence tileLabel,
Icon icon,
Executor resultExecutor,
Consumer<Integer> resultCallback
)
Callback berisi informasi tentang apakah kartu telah ditambahkan atau tidak, bukan ditambahkan, apakah sudah ada, atau jika terjadi {i>error<i}.
Gunakan pertimbangan Anda saat menentukan waktu dan frekuensi untuk meminta izin kepada pengguna. Rab
sebaiknya panggil requestAddTileService()
hanya dalam konteks, seperti
saat pengguna pertama kali berinteraksi dengan fitur yang difasilitasi kartu Anda.
Sistem dapat memilih untuk berhenti memproses permintaan untuk
ComponentName
jika telah ditolak oleh pengguna cukup kali sebelumnya. Tujuan
ditentukan dari Context
yang digunakan untuk mengambil
layanan—harus cocok dengan pengguna saat ini.