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 aracılığıyla kullanıcılara özel Kartlar sunabilir ve karonun durumunu izlemek için bir Tile nesnesi kullanın. Örneğin, kullanıcıların uygulamanız tarafından sağlanan bir VPN'yi açmasına veya kapalı.

Ne zaman kart oluşturacağınıza karar verme

Kullanıcıların beklediği belirli işlevler için kutular oluşturmanızı öneririz. ya da her ikisine birden hızlı erişilmesi gerekir. En etkili bu niteliklerin her ikisiyle de eşleşenlerdir ve öğelere hızlı bir şekilde yapılan işlemlerdir.

Örneğin, bir fitness uygulaması için, kullanıcıların hızlıca bir antrenman oturumu başlatabilirsiniz. Ancak karo oluşturmanızı önermeyiz geçmişin tamamını görüntülemesini sağlayacak bir uygulama için ayrı bir uygulama kampanyası yürütüyoruz.

Karonuzun bulunabilirliğini ve kullanım kolaylığını artırmak için şunları yapmanızı öneririz: belirli uygulamalardan kaçının:

• 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 kutular kullanmaktan kaçının. Bir uygulama kısayolu veya bildirim gönderin.

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

• Bilgi içeren ancak aşağıdakiler için etkileşimli olmayan kutular kullanmaktan kaçının yardımcı olur. Bunun yerine bir bildirim veya widget kullanın.

Karonuzu oluşturun

Kart oluşturmak için önce uygun bir karo simgesi oluşturmanız, ardından uygulamanızın manifest dosyasında TileService oluşturun ve beyan edin.

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

Özel simgenizi oluşturun

Hızlı açılan menüdeki karoda görüntülenecek özel bir simge sağlamanız gerekir. Ayarlar paneli. (TileService ifadesini tanımlarken bu simgeyi ekleyeceksiniz. açıklığa kavuşturulmuştur.) 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

Karonuz 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 bağlı bir hizmettir. TileService cihazınız şu durumda bağlanır: uygulamanız tarafından istendiğinde veya sistemin uygulamayla iletişim kurması gerekiyorsa. Normal bound-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 geçer.

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 özel diğer yöntemleri uygulayın. Bu yöntemler onCreate() ve onDestroy() dışında çağrılabilir çünkü Service yaşam döngüsü yöntemleri ve TileService yaşam döngüsü yöntemleri ayrı eşzamansız iş parçacıkları.

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, olduğundan emin olun.

• onStartListening() ve onStopListening(): Bu yöntemler şunlardır: çağrılır. İlgili içeriği oluşturmak için kullanılan TileService, onStartListening() ile arasında bağlı kalmaya devam ediyor onStopListening(), uygulamanızın kartı değiştirmesine ve güncellemeler aktarmasına olanak tanıyor.

• 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 TileService tarafından bildirilirse etkin modu kullanmanızı öneririz. kendi süreciyle güncellenmesi gerekir. 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.

Statik TileService.requestListeningState() yöntemi, dinleme durumunun başlamasını isteyebilir ve onStartListening().

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, sizin açınızdan TileService, kontrolü dışındaki zamanlarda oluşturulabilir ve tekrar bağlanabilir. Google kullanıcı karoyu görüntülemediğinde de bağlantısı kaldırılabilir ve kaldırılabilir.

KullanıcıonStartListening() Hızlı Ayarlar paneli. 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ış

Bir kullanıcı tarafından eklendikten sonra karo her zaman aşağıdaki durumlardan birinde olur.

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

  Örneğin, kullanıcıların süreli antrenman başlatmasına olanak tanıyan bir fitness uygulaması kutusu için oturum, STATE_ACTIVE kullanıcının bir antrenman başlattığı anlamına gelir ve zamanlayıcı çalışıyor.

• STATE_INACTIVE: Kapalı veya duraklatılmış durumu gösterir. Kullanıcı bu durumda karonızla etkileşime girin.

  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 verdiler.

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

  Örneğin, STATE_UNAVAILABLE içindeki bir karo, karonun kullanılabilir hale getirebilirsiniz.

  adlı müşteriye geçiş yapabilirsiniz.

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

Sistem, arka plan renginizi renklendirmek için karo simgesini ve arka planı Tile nesne algılandı. STATE_ACTIVE değerine ayarlanan Tile nesne en koyu ve STATE_INACTIVE ve STATE_UNAVAILABLE giderek daha hafif. Tam renk üreticiye ve sürüme özgüdür.

Karonuzu güncelleme

onStartListening() sizi geri aradıktan sonra karonuzu 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() numaralı telefona geri arama. Etkin olmayan modda, karonuzu şu şekilde güncelleyebilirsiniz: onStartListening() ile onStopListening() arasında istediğiniz kadar tekrarlayabilirsiniz.

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

Ekrana dokunma

Kutunuz açıksa kullanıcılar karonuza dokunarak işlem tetikleyebilir. STATE_ACTIVE veya STATE_INACTIVE. Ardından sistem, onClick() geri arama.

Uygulamanız onClick() çağrısı aldığında bir iletişim kutusu başlatabilir veya etkinliği tetikleyebilir, arka plan çalışmasını tetikleyebilir veya karonuzun durumunu değiştirebilirsiniz.

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 kutusu başlat

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(), etiketi daraltırken bir etkinlik başlatır kontrol edebilirsiniz. Etkinlikler, görüntülenecek daha ayrıntılı bilgiler olduğunda kullanışlı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üğmesini kullanabilirsiniz.

Bir karta uzun dokunduğunuzda, kullanıcı ile ilgili Uygulama Bilgileri ekranı görüntülenir. Geçersiz kılmak için bunun yerine tercihleri ayarlamak için bir etkinlik başlatın, <intent-filter> etkinliğinden birine ACTION_QS_TILE_PREFERENCES

Android API 28'den itibaren PendingIntent, Intent.FLAG_ACTIVITY_NEW_TASK:

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 açıp kapatılabilir olarak işaretleyin

Temel olarak iki durumlu anahtar (karoların en yaygın davranışıdır). 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 bir şekilde kilitlenen cihazlarda güvenli işlemler gerçekleştirme

Kartınız, kilitli cihazlarda kilit ekranının üzerinde gösterilebilir. Kart hassas bilgiler içeriyorsa isSecure() değerini kontrol ederek cihazınızın güvenli durumda olup olmadığını belirlemeli ve TileService cihazınızın ve davranışlarını uygun şekilde değiştirir.

Kutu işlemi, kilitli durumdayken güvenli bir şekilde gerçekleştirilebiliyorsa startActivity() özelliğini kullanın. tuşuna basarak kilit ekranının üzerinde bir etkinlik başlatabilirsiniz.

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 karonuzu eklemesini isteyin

Kullanıcıların, karonuzu manuel olarak eklemek için birkaç adımı uygulaması gerekir:

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

Kullanıcı, karonuzu istediği zaman taşıyabilir veya kaldırabilir.

Android 13'ten itibaren requestAddTileService() yöntemini kullanabilirsiniz kullanıma sunduk. Bu yöntem Kullanıcılardan, karonuzu doğrudan Hızlı cihazlarına hızlı bir şekilde eklemelerini ister. Ayarlar paneli. İstemde uygulama adı, sağlanan etiket, ve simge.

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

Geri çağırma, karonun eklenip eklenmemesiyle ilgili bilgileri içerir eklenmiş olabilir.

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, verilen bir istek için istekleri işlemeyi ComponentName (Kullanıcı tarafından daha önce yeterince reddedildiyse). İlgili içeriği oluşturmak için kullanılan kullanıcı, bunu almak için kullanılan Context cihazından belirlenir hizmet (mevcut kullanıcıyla eşleşmelidir).