Uygulamanız için özel Hızlı Ayarlar blokları oluşturma

Hızlı Ayarlar, Hızlı Ayarlar panelinde kullanıcıların yinelenen görevleri hızlıca tamamlamak için dokunabileceği işlemler temsil eder. Uygulamanız, TileService sınıfı aracılığıyla kullanıcılara özel bir kart sağlayabilir ve kartın durumunu izlemek için bir Tile nesnesi kullanabilir. Örneğin, kullanıcıların uygulamanız tarafından sağlanan bir VPN'yi etkinleştirmesine veya devre dışı bırakmasına olanak tanıyan bir Kart oluşturabilirsiniz.

Kart oluşturmaya ne zaman karar vereceğinize karar verme

Kullanıcıların sıklıkla erişmesini beklediğiniz veya hızlı erişmesi gereken (veya her ikisinin de) belirli işlevler için kartlar oluşturmanızı öneririz. En etkili kartlar, sıklıkla gerçekleştirilen işlemlere hızlı erişim sağlayan ve bu iki özelliği de karşılayan kartlardır.

Örneğin, bir fitness uygulaması için kullanıcıların hızlıca antrenman oturumu başlatmasına olanak tanıyan bir Kart oluşturabilirsiniz. Ancak aynı uygulama için kullanıcıların tüm antrenman geçmişlerini inceleyebilecekleri bir Kart oluşturmanızı önermeyiz.

Kartınızın bulunabilirliğini ve kullanım kolaylığını artırmak için belirli uygulamalardan kaçınmanızı öneririz:

• Uygulama başlatmak için kutular kullanmaktan kaçının. Uygulama kısayolu veya standart bir kısayol kullanın başlatıcıyı deneyin.

• Tek seferlik kullanıcı işlemleri için kart kullanmaktan kaçının. Bir uygulama kısayolu veya bildirim gönderin.

• Çok fazla kart oluşturmaktan kaçının. Uygulama başına en fazla iki tane olmasını öneririz. Bir uygulama kısayolunu kullanın.

• Bilgi görüntüleyen ancak kullanıcılar için etkileşimli olmayan kartlar kullanmaktan kaçının. Bunun yerine bir bildirim veya widget kullanın.

Kartınızı oluşturma

Kart oluşturmak için önce uygun bir kart simgesi oluşturmanız, ardından uygulamanızın manifest dosyasında TileService'nizi oluşturup bildirmeniz gerekir.

Hızlı Ayarlar örneği, şuna bir örnek sunar: ve taşı yönetebilirsiniz.

Özel simgenizi oluşturun

Hızlı Ayarlar panelindeki kartta gösterilecek özel bir simge sağlamanız gerekir. (Bu simgeyi, sonraki bölümde açıklanan TileService öğesini tanımlarken eklersiniz.) Simgenin üzerinde düz beyaz renkte şeffaf arka plan, 24 x 24 dp ölçüm ve VectorDrawable.

Karonuzun amacına dair görsel ipuçları sağlayan bir simge oluşturun. Bu sayede kullanıcılar fayansınızın ihtiyaçlarına uygun olup olmadığını kolayca belirleyebilirsiniz. Örneğin, Arkadaş Bitkiler projenizde kullanıcıların başlatabilecekleri bir fitness uygulamasının karosuna ait kronometre simgesi bir plan hazırlamalısınız.

TileService'inizi oluşturma ve bildirme

Kartınız için TileService sınıfını genişleten bir hizmet oluşturun.

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();
  }
}

Uygulamanızın manifest dosyasında TileService beyan edin. Ad ve etiket ekleyin önceki bölümde oluşturduğunuz özel simge olan TileService ve uygun izne sahip olmalısınız.

 <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'inizi yönetme

Uygulama manifestinizde TileService oluşturup beyan ettikten sonra, ve durumu yönetmek zorunda kalacaksınız.

TileService bir bağlama hizmetidir. TileService cihazınız şu durumda bağlanır: uygulamanız tarafından istendiğinde veya sistemin uygulamayla iletişim kurması gerekiyorsa. Tipik bir bağlı hizmet yaşam döngüsü aşağıdaki dört geri çağırma yöntemini içerir: onCreate(), onBind(), onUnbind() ve onDestroy(). Bu yöntemler, hizmet yeni bir yaşam döngüsü aşamasına her girdiğinde sistem tarafından çağrılır.

TileService yaşam döngüsüne genel bakış

Bağlı hizmet yaşam döngüsünü kontrol eden geri çağırmalara ek olarak, TileService yaşam döngüsüne özgü diğer yöntemleri de uygulamanız gerekir. Service yaşam döngüsü yöntemleri ve TileService yaşam döngüsü yöntemleri iki ayrı ayarsız iş parçacığında çağrıldığı için bu yöntemler onCreate() ve onDestroy() dışında çağrılabilir.

TileService yaşam döngüsü, çağrılan şu yöntemleri içerir: TileService cihazınız yeni bir yaşam döngüsü aşamasına her geçtiğinde sistem tarafından otomatik olarak uygulanır:

• onTileAdded(): Bu yöntem yalnızca kullanıcı kullanıcının karonuzu kaldırıp tekrar eklemesi gerekir. Tek seferlik başlatma işlemi için en uygun zaman budur. Ancak bu, gerekli tüm ilklendirme işlemlerini gerçekleştirmeyebilir.

• onStartListening() ve onStopListening(): Bu yöntemler, uygulamanız kartvizitleri güncellediğinde çağrılır ve sık sık çağrılır. TileService, onStartListening() ile onStopListening() arasında bağlı kalır. Bu sayede uygulamanız kartta değişiklik yapabilir ve güncelleme yayınlayabilir.

• onTileRemoved(): Bu yöntem yalnızca kullanıcı tıklayın.

Dinleme modu seçin

TileService cihazınız etkin modda veya etkin olmayan modda dinler. Önerilerimiz: bunu uygulama manifest dosyasında belirtmeniz gerekir. Aksi halde TileService standart moddur ve bildirilmesi gerekmez.

TileService öğenizin onStartListening() dışında yayınlanacağını ve onStopListening() yöntem.

Etkin mod (önerilir)

Durumunu dinleyen ve izleyen bir TileService için etkin modu kullanın. sahip olmanız gerekir. Etkin moddaki TileService, onTileAdded() için bağlı. onTileRemoved(), dokunma etkinlikleri ve uygulama işlemi tarafından istendiğinde.

Kart durumunuz kendi işlemiyle güncellendiğinde TileService'ünüz bilgilendirilecekse etkin modu kullanmanızı öneririz. Etkin karolar, Hızlı Ayarlar paneline her defasında bağlı olmak zorunda olmadığından, sisteme kullanıcıya görünür hale gelir.

Dinleme durumunun başlatılmasını istemek ve onStartListening() için geri arama almak üzere statik TileService.requestListeningState() yöntemi çağrılabilir.

Dosyalarınıza META_DATA_ACTIVE_TILE ekleyerek etkin modu bildirebilirsiniz. uygulamanızın manifest dosyasına ait dosyayı indirin.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

Etkin olmayan mod

Etkin olmayan mod standart moddur. Aşağıdaki durumlarda TileService etkin olmayan moddadır: karonuz kullanıcıya görünür olduğunda bağlanır. Bu, TileService'ün kontrolü dışındaki zamanlarda oluşturulup yeniden bağlanabileceği anlamına gelir. Ayrıca, kullanıcı kartı görüntülemediğinde de bağlanma durumu kaldırılabilir ve kart yok edilebilir.

Kullanıcı Hızlı Ayarlar panelini açtıktan sonra uygulamanız onStartListening() için geri çağırma alır. Tile nesnenizi en fazla kez güncelleyebilirsiniz onStartListening() ile onStopListening() arasında.

Etkin olmayan modu bildirmeniz gerekmez. Yalnızca META_DATA_ACTIVE_TILE ekleyin.

Karo durumlarına genel bakış

Kullanıcılar kartınızı ekledikten sonra kartınız her zaman aşağıdaki durumlardan birinde bulunur.

• STATE_ACTIVE: Açık veya etkin durumunu belirtir. Kullanıcı bu durumda karonızla etkileşime girin.

  Örneğin, kullanıcıların zamanlı bir egzersiz oturumu başlatmasına olanak tanıyan bir fitness uygulaması kartında STATE_ACTIVE, kullanıcının bir egzersiz oturumu başlattığı ve zamanlayıcının çalıştığı anlamına gelir.

• STATE_INACTIVE: Kapalı veya duraklatılmış durumu gösterir. Kullanıcı bu durumdayken karonuzla etkileşim kurabilir.

  Fitness uygulaması kutusu örneğini tekrar kullanmak için STATE_INACTIVE bölgesindeki bir karo şunları yapar: kullanıcının antrenman oturumu başlatmamış, ancak bunu yapabileceği anlamına gelir. karar veriyor.

• STATE_UNAVAILABLE: Geçici olarak kullanılamayan durumu gösterir. İlgili içeriği oluşturmak için kullanılan kullanıcı bu durumdayken karonuzla etkileşimde bulunamaz.

  Örneğin, STATE_UNAVAILABLE durumundaki bir kart, kartın şu anda kullanıcı tarafından kullanılamadığını gösterir.

  yapabilirsiniz.

Sistem yalnızca Tile nesnenizin başlangıç durumunu ayarlar. Tile ayarını yaptınız yaşam döngüsünün geri kalanı boyunca nesnenin durumunu kontrol edebilirsiniz.

Sistem, Tile nesnenizin durumunu yansıtmak için karo simgesini ve arka planını renklendirebilir. Tile STATE_ACTIVE olarak ayarlanmış nesneler en koyu, STATE_INACTIVE ve STATE_UNAVAILABLE ise giderek daha açıktır. Tam renk üretici ve sürüme özgüdür.

Kartınızı güncelleme

onStartListening() numaralı telefondan geri arandıktan sonra kartınızı güncelleyebilirsiniz. Kartın moduna bağlı olarak, karonuz şu tarihe kadar en az bir kez güncellenebilir: onStopListening() aranıyor.

Etkin modda, yeni bir bildirim almadan önce karonuzu tam olarak bir kez güncelleyebilirsiniz. onStopListening() adlı kullanıcıya geri arama. Etkin olmayan modda, kartınızı onStartListening() ile onStopListening() arasında istediğiniz kadar güncelleyebilirsiniz.

getQsTile() çağrısı yaparak Tile nesnenizi alabilirsiniz. Güncellemek için Tile nesnenizin belirli alanlarına aşağıdaki yöntemleri çağırın:

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

Ayarı tamamladıktan sonra karonuzu güncellemek için updateTile() numaralı telefonu aramanız gerekir. Tile nesnesinin alanlarını doğru değerlere ayarlayın. Bu, sistemin güncellenen parça verilerini ayrıştırıp kullanıcı arayüzünü günceller.

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();
}

Dokunmaları işleme

Kutunuz açıksa kullanıcılar karonuza dokunarak işlem tetikleyebilir. STATE_ACTIVE veya STATE_INACTIVE. Ardından sistem, uygulamanızın onClick() geri çağırma işlevini çağırır.

Uygulamanız onClick() için geri çağırma aldıktan sonra bir iletişim kutusu veya etkinlik başlatabilir, arka planda çalışmayı tetikleyebilir ya da kartınızın durumunu değiştirebilir.

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();
}

İletişim başlatma

showDialog(), Hızlı Ayarlar panelini daraltır ve bir iletişim kutusu gösterir. Ek giriş gerektiriyorsa eyleminize bağlam eklemek için bir iletişim kutusu kullanın veya kullanıcı izni.

Etkinlik başlatma

startActivityAndCollapse(), paneli daraltırken bir etkinlik başlatır. Etkinlikler, görüntülenecek daha ayrıntılı bilgiler olduğunda yararlıdır daha çok iletişim kurabilirsiniz.

Uygulamanız önemli bir kullanıcı etkileşimi gerektiriyorsa, yalnızca son çare olarak kullanabilirsiniz. Bunun yerine bir iletişim kutusu veya açma/kapatma düğmesi kullanabilirsiniz.

Bir karoya uzun basıldığında kullanıcı için Uygulama Bilgileri ekranı gösterilir. Geçersiz kılmak için bunun yerine tercihleri ayarlamak için bir etkinlik başlatın, Etkinliklerinizden birine <intent-filter> ACTION_QS_TILE_PREFERENCES

Android API 28'den itibaren PendingIntent, Intent.FLAG_ACTIVITY_NEW_TASK'ye sahip olmalıdır:

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

Alternatif olarak, işareti AndroidManifest.xml öğesine ekleyebilirsiniz. Activity bölümü.

Karonuzu geçiş yapılabilir olarak işaretleyin

Kartınız temel olarak iki durumlu bir anahtar olarak çalışıyorsa (kartların en yaygın davranışı budur) kartı açma/kapatma olarak işaretlemenizi öneririz. Bu, kullanıcıların Kartın işletim sistemine davranışı hakkında bilgi verir ve ve genel erişilebilirliği artırmaktır.

Karonuzu geçiş yapılabilir olarak işaretlemek için TOGGLEABLE_TILE meta verilerini true olarak ayarlayın.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Yalnızca güvenli şekilde kilitlenmiş cihazlarda güvenli işlemler yapma

Kartınız, kilitli cihazlarda kilit ekranının üst kısmında gösterilebilir. Kart hassas bilgiler içeriyorsa cihazın güvenli durumda olup olmadığını belirlemek için isSecure() değerini kontrol edin. TileService, davranışını buna göre değiştirir.

Kart işleminin kilitliyken yapılması güvenliyse kilit ekranının üstünde bir etkinlik başlatmak için startActivity() simgesini kullanın.

Kutu işlemi güvenli değilse unlockAndRun() aracılığıyla kullanıcıdan şunları yapmasını isteyin cihazının kilidini açabilir. Başarılı olursa sistem Bu nesneye ilettiğiniz Runnable nesne yöntemidir.

Kullanıcıdan kartınızı eklemesini isteyin

Kartınızı manuel olarak eklemek için kullanıcıların birkaç adımı uygulaması gerekir:

1. Aşağı kaydırarak Hızlı Ayarlar panelini açın.
2. Düzenle düğmesine dokunun.
3. Kutunuzu bulana kadar cihazdaki tüm kutular arasında gezinin.
4. Karonuzu basılı tutun ve etkin karolar listesine sürükleyin.

Kullanıcı, istediğiniz zaman kartınızı taşıyabilir veya kaldırabilir.

Android 13'ten itibaren, kullanıcıların kartınızı cihaza eklemesini çok daha kolaylaştırmak için requestAddTileService() yöntemini kullanabilirsiniz. Bu yöntem Kullanıcılardan, karonuzu doğrudan Hızlı cihazlarına hızlı bir şekilde eklemelerini ister. Ayarlar paneli. İstem, uygulama adını, sağlanan etiketi ve simgeyi içerir.

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

Geri çağırma, kartın eklenip eklenmediği, eklenmediği takdirde zaten mevcut olup olmadığı veya herhangi bir hata olup olmadığı hakkında bilgi içerir.

Kullanıcılara ne zaman ve ne sıklıkta istem göndereceğinize karar verirken şahsi karar verme yetkinizi kullanın. Biz requestAddTileService() öğesini yalnızca bağlam içinde çağırmanızı öneririz; örneğin, Kullanıcı, karonuzun sağladığı bir özellikle ilk kez etkileşimde bulunduğunda.

Sistem, kullanıcı tarafından daha önce yeterince kez reddedilmişse belirli bir ComponentName için istekleri işlemeye son vermeyi seçebilir. Kullanıcı, bu hizmeti almak için kullanılan Context değerinden belirlenir. Bu değer, mevcut kullanıcıyla eşleşmelidir.