Arama arayüzü oluşturma

Yazma yöntemini deneyin

Jetpack Compose, Android için önerilen kullanıcı arayüzü araç setidir. Oluşturma'ya arama işlevselliği eklemeyi öğrenin.

Arama çubuğu →

Uygulamanıza arama işlevi eklemeye hazır olduğunuzda Android, kullanıcı arayüzünü uygulama penceresinin üst kısmında görünen bir arama iletişim kutusu veya düzeninize ekleyebileceğiniz bir arama widget'ı ile uygulamanıza yardımcı olur. Hem arama iletişim kutusu hem de widget, kullanıcının arama sorgusunu uygulamanızdaki belirli bir etkinliğe iletebilir. Bu sayede kullanıcı, arama iletişim kutusunun veya widget'ın kullanılabildiği herhangi bir etkinlikten arama başlatabilir ve sistem, aramayı gerçekleştirmek ve sonuçları sunmak için uygun etkinliği başlatır.

Arama iletişim kutusu ve widget'ında kullanılabilen diğer özellikler şunlardır:

• Sesli arama
• Son sorgulara dayalı arama önerileri
• Uygulama verilerinizdeki gerçek sonuçlarla eşleşen arama önerileri

Bu belgede, arama sorgularını iletmek için Android sistemi tarafından desteklenen bir arama arayüzü sağlamak üzere uygulamanızı nasıl ayarlayacağınız gösterilmektedir. Bu işlem için arama iletişim kutusu veya arama widget'ı kullanılabilir.

İlgili kaynaklar:

• Materyal Tasarım simgeleri

Temel bilgiler

Başlamadan önce arama arayüzünüzü arama iletişim kutusunu mu yoksa arama widget'ını mı kullanarak uygulamak istediğinize karar verin. Aynı arama özelliklerini biraz farklı şekillerde sunarlar:

• Arama iletişim kutusu, Android sistemi tarafından kontrol edilen bir kullanıcı arayüzü bileşenidir. Kullanıcı tarafından etkinleştirildiğinde arama iletişim kutusu etkinliğin en üstünde görünür.

  Arama iletişim kutusundaki tüm etkinlikler Android sistemi tarafından kontrol edilir. Kullanıcı bir sorgu gönderdiğinde sistem, sorguyu aramaları işlemek için belirttiğiniz etkinliğe iletir. Kullanıcı yazarken iletişim kutusunda arama önerileri de gösterilebilir.

• Arama widget'ı, düzeninizde herhangi bir yere yerleştirebileceğiniz bir SearchView örneğidir. Arama widget'ı varsayılan olarak standart bir EditText widget'ı gibi davranır ve herhangi bir işlem yapmaz. Ancak Android sisteminin tüm giriş etkinliklerini işlemesi, sorguları uygun etkinliğe iletmesi ve arama iletişim kutusunda olduğu gibi arama önerileri sunması için widget'ı yapılandırabilirsiniz.

Not: Bu belgede, arama widget'ının destekli arama uygulaması için sisteme nasıl entegre edileceği ele alınmaktadır. Ancak çeşitli geri çağırma yöntemleri ve dinleyiciler kullanarak arama widget'ına yapılan tüm kullanıcı girişlerini kendiniz de işleyebilirsiniz. Kullanıcı girişini kendiniz işlemek istiyorsanız SearchView ve iç içe yerleştirilmiş arayüzleriyle ilgili referans dokümanını okuyun.

Kullanıcı, arama iletişim kutusundan veya arama widget'ından arama yaptığında sistem bir Intent oluşturur ve kullanıcı sorgusunu bu öğede saklar. Sistem daha sonra aramaları işlemek için bildirdiğiniz etkinliği ("aranabilir etkinlik") başlatır ve intent'i bu etkinliğe iletir. Uygulamanızı bu tür bir destekli arama için ayarlamak üzere aşağıdakilere ihtiyacınız vardır:

Arama yapılandırması

Arama iletişim kutusu veya widget'ı için bazı ayarları yapılandıran bir XML dosyası. Sesli arama, arama önerisi ve arama kutusu için ipucu metni gibi özelliklerin ayarlarını içerir.

Aranabilir bir etkinlik

Arama sorgusunu alan, verilerinizde arama yapan ve arama sonuçlarını gösteren Activity.

Aşağıdakilerden biri tarafından sağlanan bir arama arayüzü:

Arama iletişim kutusu

Arama iletişim kutusu varsayılan olarak gizlidir. Kullanıcı Arama düğmenize dokunduğunda onSearchRequested() ekranın üst kısmında görünür.

SearchView widget'ı

Arama widget'ını kullanarak arama kutusunu, uygulama çubuğundaki işlem görünümü de dahil olmak üzere etkinliğinizin herhangi bir yerine yerleştirebilirsiniz.

Bu belgenin geri kalanında, arama yapılandırmasını ve aranabilir etkinliği nasıl oluşturacağınızın yanı sıra arama iletişim kutusu veya arama widget'ı ile arama arayüzünü nasıl uygulayacağınız gösterilmektedir.

Aranabilir yapılandırma oluşturma

İlk olarak arama yapılandırması adlı bir XML dosyasına ihtiyacınız vardır. Arama iletişim kutusunun veya widget'ının belirli kullanıcı arayüzü özelliklerini yapılandırır ve öneriler ile sesli arama gibi özelliklerin nasıl çalışacağını tanımlar. Bu dosya geleneksel olarak searchable.xml olarak adlandırılır ve res/xml/ proje dizinine kaydedilmesi gerekir.

Not: Sistem, bir SearchableInfo nesnesi oluşturmak için bu dosyayı kullanır. Bu nesneyi çalışma zamanında kendiniz oluşturamazsınız. Arama yapılandırmasını XML olarak bildirmeniz gerekir.

Arama yapılandırma dosyası, kök düğümü olarak <searchable> öğesini içermeli ve aşağıdaki örnekte gösterildiği gibi bir veya daha fazla özellik belirtmelidir:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/app_label"
    android:hint="@string/search_hint" >
</searchable>

Yalnızca android:label özelliği zorunludur. Bu, uygulama adı olması gereken bir dize kaynağına işaret eder. Bu etiket, Hızlı Arama Kutusu için arama önerilerini etkinleştirmediğiniz sürece kullanıcıya görünmez. Etkinleştirdiğinizde ise etiket, sistem ayarlarındaki Aranabilir öğeler listesinde görünür.

Gerekli olmasa da, kullanıcılar bir sorgu girmeden önce arama kutusunda ipucu dizesi sağlayan android:hint özelliğini her zaman eklemenizi öneririz. İpucu, kullanıcılara ne arayabilecekleri hakkında önemli ipuçları verdiği için önemlidir.

İpucu: Diğer Android uygulamalarıyla tutarlılık için android:hint dizesini "Search <content-or-product>" (Search <content-or-product>) olarak biçimlendirin. Örneğin, "Search songs and artists" (Şarkı ve sanatçı ara) veya "Search YouTube" (YouTube'da ara).

<searchable> öğesi başka özellikleri de kabul eder. Ancak arama önerileri ve sesli arama gibi özellikler ekleyene kadar çoğu özelliği kullanmanız gerekmez. Arama yapılandırma dosyası hakkında ayrıntılı bilgi için Arama yapılandırması referans belgesine bakın.

Aranabilir etkinlik oluşturma

Aranabilir etkinlik, uygulamanızda sorgu dizesine göre arama yapan ve arama sonuçlarını sunan Activity'dır.

Kullanıcı, arama iletişim kutusunda veya widget'ında arama yaptığında sistem, aranabilir etkinliğinizi başlatır ve arama sorgusunu Intent ile ACTION_SEARCH işlemiyle birlikte iletir. Aranabilir etkinliğiniz, sorguyu amacın QUERY extra'sından alır, ardından verilerinizde arama yapar ve sonuçları sunar.

Arama iletişim kutusunu veya widget'ını uygulamanızdaki diğer etkinliklere ekleyebildiğiniz için sistemin, arama sorgusunu düzgün şekilde iletebilmesi için hangi etkinliğin aranabilir etkinliğiniz olduğunu bilmesi gerekir. Bu nedenle, öncelikle aranabilir etkinliğinizi Android manifest dosyasında bildirin.

Aranabilir bir etkinlik bildirme

Henüz bir tane oluşturmadıysanız arama yapan ve sonuçları sunan bir Activity oluşturun. Arama işlevini henüz uygulamanız gerekmez. Yalnızca manifest dosyasında bildirebileceğiniz bir etkinlik oluşturmanız yeterlidir. Manifest dosyasının <activity> öğesinde aşağıdakileri yapın:

1. ACTION_SEARCH amacını bir <intent-filter> öğesinde kabul etmek için etkinliği bildirin.
2. Kullanılacak arama yapılandırmasını bir <meta-data> öğesinde belirtin.

Bu durum aşağıdaki örnekte gösterilmektedir:

<application ... >
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>
    ...
</application>

<meta-data> öğesi, "android.app.searchable" değerine sahip android:name özelliğini ve aranabilir yapılandırma dosyasına referans içeren android:resource özelliğini içermelidir. Önceki örnekte, res/xml/searchable.xml dosyası kastedilmektedir.

Not: Sistem, ACTION_SEARCH amacını bileşen adını kullanarak aranabilir etkinliğinize açıkça ilettiği için <intent-filter>, genellikle <activity> öğelerinde gördüğünüz DEFAULT değerine sahip bir <category> gerektirmez.

Arama gerçekleştirir

Arama yapılabilir etkinliğinizi manifestte bildirdikten sonra, arama yapılabilir etkinliğinizde arama yapmak için aşağıdaki prosedürü uygulayın:

1. Sorguyu alma
2. Verilerinizde arama yapın.
3. Sonuçları sunun.

Sorguyu alma

Bir kullanıcı arama iletişim kutusundan veya widget'ından arama yaptığında sistem, aranabilir etkinliğinizi başlatır ve bu etkinliğe ACTION_SEARCH intent'i gönderir. Bu amaç, arama sorgusunu QUERY dizesi ekstrasında taşır. Etkinlik başladığında bu amaca yönelik olup olmadığını kontrol edin ve dizeyi çıkarın. Örneğin, aranabilir etkinliğiniz başladığında arama sorgusunu nasıl alabileceğinizi aşağıda görebilirsiniz:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.search)

    // Verify the action and get the query.
    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doMySearch(query)
        }
    }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.search);

    // Get the intent, verify the action, and get the query.
    Intent intent = getIntent();
    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
      String query = intent.getStringExtra(SearchManager.QUERY);
      doMySearch(query);
    }
}

QUERY dizesi her zaman ACTION_SEARCH amacı ile birlikte gönderilir. Önceki örnekte, sorgu alınır ve gerçek arama işleminin yapıldığı yerel bir doMySearch() yöntemine iletilir.

Verilerinizi arama

Verilerinizi depolama ve arama süreci uygulamanıza özgüdür. Verilerinizi birçok şekilde depolayabilir ve arayabilirsiniz. Bu belgede nasıl yapacağınız gösterilmemektedir. Verilerinizi ihtiyaçlarınız ve veri biçiminiz açısından nasıl depoladığınızı ve aradığınızı göz önünde bulundurun. Uygulayabileceğiniz bazı ipuçlarını aşağıda bulabilirsiniz:

• Verileriniz cihazdaki bir SQLite veritabanında depolanıyorsa LIKE sorgusu yerine FTS3 kullanarak tam metin araması yapmak, metin verileri arasında daha kapsamlı bir arama sağlayabilir ve sonuçları önemli ölçüde daha hızlı üretebilir. FTS3 hakkında bilgi edinmek için sqlite.org, Android'de SQLite hakkında bilgi edinmek için SQLiteDatabase sınıfını inceleyin.
• Verileriniz internette depolanıyorsa algılanan arama performansı kullanıcının veri bağlantısından olumsuz etkilenebilir. Arama sonuçlarınız döndürülene kadar bir ilerleme göstergesi görüntülemek isteyebilirsiniz. Ağ API'leri referansı için android.net ilerleme durumu göstergesinin nasıl görüntüleneceği hakkında bilgi için ProgressBar başlıklı makaleye bakın.

Not: Yerel bir veritabanı kullanmayı planlıyorsanız Room kullanarak verileri yerel bir veritabanına kaydetme başlıklı makaleyi inceleyin.

Sonuçları sunma

Verilerinizin bulunduğu yer ve arama şekliniz ne olursa olsun, arama sonuçlarını Adapter ile aranabilir etkinliğinize döndürmenizi öneririz. Bu sayede, tüm arama sonuçlarını RecyclerView içinde sunabilirsiniz. Verileriniz bir SQLite veritabanı sorgusundan geliyorsa sonuçlarınızı RecyclerView kullanarak CursorAdapter'ye uygulayabilirsiniz. Verileriniz farklı bir biçimde geliyorsa BaseAdapter uzantısı oluşturabilirsiniz.

Bir Adapter, bir veri kümesindeki her öğeyi bir View nesnesine bağlar. Adapter, RecyclerView öğesine uygulandığında her bir veri parçası listeye ayrı bir görünüm olarak eklenir. Adapter yalnızca bir arayüzdür. Bu nedenle, CursorAdapter gibi uygulamalar (Cursor hesabındaki verileri bağlamak için) gereklidir. Mevcut uygulamalardan hiçbiri verileriniz için uygun değilse BaseAdapter adresinden kendi uygulamanızı oluşturabilirsiniz.

Arama iletişim kutusunu kullanma

Arama iletişim kutusu, ekranın üst kısmında kayan bir arama kutusu sağlar. Bu kutunun solunda uygulama simgesi bulunur. Arama iletişim kutusu, kullanıcı yazarken arama önerileri sunabilir. Kullanıcı bir arama yaptığında sistem, arama sorgusunu aramayı gerçekleştiren aranabilir bir etkinliğe gönderir.

Varsayılan olarak, arama iletişim kutusu kullanıcı etkinleştirene kadar her zaman gizlidir. Uygulamanız, onSearchRequested() çağrısı yaparak arama iletişim kutusunu etkinleştirebilir. Ancak bu yöntem, etkinlik için arama iletişim kutusunu etkinleştirene kadar çalışmaz.

Arama iletişim kutusunun arama yapabilmesi için sisteme, arama iletişim kutusundan hangi aranabilir etkinliğin arama sorgularını alması gerektiğini belirtin. Örneğin, aranabilir etkinlik oluşturma ile ilgili önceki bölümde SearchableActivity adlı aranabilir bir etkinlik oluşturulur. OtherActivity adlı bir etkinlik gibi ayrı bir etkinliğin arama iletişim kutusunu göstermesini ve aramaları SearchableActivity'ye iletmesini istiyorsanız manifestte OtherActivity'nın, OtherActivity'daki arama iletişim kutusu için kullanılacak aranabilir etkinlik olduğunu belirtin.SearchableActivity

Bir etkinliğin arama iletişim kutusunda aranabilir etkinliği bildirmek için ilgili etkinliğin <activity> öğesinin içine bir <meta-data> öğesi ekleyin. <meta-data> öğesi, aranabilir etkinliğin sınıf adını belirten android:value özelliğini ve "android.app.default_searchable" değerine sahip android:name özelliğini içermelidir.

Örneğin, hem aranabilir bir etkinlik (SearchableActivity) hem de arama iletişim kutusundan gerçekleştirilen aramaları yapmak için SearchableActivity kullanan başka bir etkinlik (OtherActivity) için bildirim aşağıda verilmiştir:

<application ... >
    <!-- This is the searchable activity; it performs searches. -->
    <activity android:name=".SearchableActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                   android:resource="@xml/searchable"/>
    </activity>

    <!-- This activity enables the search dialog to initiate searches
         in the SearchableActivity. -->
    <activity android:name=".OtherActivity" ... >
        <!-- Enable the search dialog to send searches to SearchableActivity. -->
        <meta-data android:name="android.app.default_searchable"
                   android:value=".SearchableActivity" />
    </activity>
    ...
</application>

OtherActivity artık aramalarda hangi aranabilir etkinliğin kullanılacağını bildiren bir <meta-data> öğesi içerdiğinden etkinlik, arama iletişim kutusunu etkinleştirir. Kullanıcı bu etkinlikte olmasına rağmen onSearchRequested() yöntemi arama iletişim kutusunu etkinleştirir. Kullanıcı aramayı yürüttüğünde sistem SearchableActivity başlatır ve ACTION_SEARCH amacını iletir.

Not: Arama yapılabilir etkinlik, arama iletişim kutusunu varsayılan olarak sağladığından bu bildirimi SearchableActivity'ye eklemeniz gerekmez. SearchableActivity.

Uygulamanızdaki her etkinliğin arama iletişim kutusunu sağlamasını istiyorsanız önceki <meta-data> öğesini her <activity> yerine <application> öğesinin alt öğesi olarak ekleyin. Bu şekilde, her etkinlik değeri devralır, arama iletişim kutusunu sağlar ve aramaları aynı aranabilir etkinliğe iletir. Birden fazla aranabilir etkinliğiniz varsa farklı bir <meta-data> bildirimi yerleştirerek varsayılan aranabilir etkinliği geçersiz kılabilirsiniz.

Etkinlikleriniz için arama iletişim kutusu etkinleştirildiğinden uygulamanız artık arama yapmaya hazırdır.

Arama iletişim kutusunu çağırma

Bazı cihazlarda özel bir arama düğmesi bulunsa da bu düğmenin davranışı cihazlar arasında farklılık gösterebilir ve birçok cihazda arama düğmesi bulunmaz. Bu nedenle, arama iletişim kutusunu kullanırken kullanıcı arayüzünüzde onSearchRequested() işlevini çağırarak arama iletişim kutusunu etkinleştiren bir arama düğmesi sağlamanız gerekir.

Örneğin, onSearchRequested() işlevini çağıran bir arama düğmesini seçenekler menünüze veya kullanıcı arayüzü düzeninize ekleyin.

Not: Uygulamanızda uygulama çubuğu kullanılıyorsa arama arayüzünüz için arama iletişim kutusunu kullanmayın. Bunun yerine, uygulama çubuğunda daraltılabilir görünüm olarak arama widget'ını kullanın.

Kullanıcı klavyede yazmaya başladığında arama iletişim kutusunu etkinleştiren "yazarak arama" işlevini de etkinleştirebilirsiniz. Tuş vuruşları arama iletişim kutusuna eklenir. Etkinliğinizde arama için yazma özelliğini etkinleştirmek istiyorsanız etkinliğinizin onCreate() yönteminde setDefaultKeyMode veya DEFAULT_KEYS_SEARCH_LOCAL yöntemini çağırın.

Arama iletişim kutusunun etkinlik yaşam döngünüz üzerindeki etkisi

Arama iletişim kutusu, ekranın üst kısmında yüzen bir Dialog şeklindedir. Etkinlik yığınında herhangi bir değişikliğe neden olmaz. Bu nedenle, arama iletişim kutusu göründüğünde onPause() gibi yaşam döngüsü yöntemleri çağrılmaz. Arama iletişim kutusuna giriş odağı verildiği için etkinliğiniz giriş odağını kaybeder.

Arama iletişim kutusu etkinleştirildiğinde bildirim almak istiyorsanız onSearchRequested() yöntemini geçersiz kılın. Sistem bu yöntemi çağırdığında etkinliğinizin arama iletişim kutusuna giriş odağını kaybettiği anlaşılır. Bu nedenle, etkinliğe uygun herhangi bir işlemi (ör. oyunu duraklatma) yapabilirsiniz. Bu belgenin başka bir bölümünde ele alınan arama bağlamı verilerini iletmiyorsanız üst sınıf uygulamasını çağırarak yöntemi sonlandırın:

Kotlin

override fun onSearchRequested(): Boolean {
    pauseSomeStuff()
    return super.onSearchRequested()
}

Java

@Override
public boolean onSearchRequested() {
    pauseSomeStuff();
    return super.onSearchRequested();
}

Kullanıcı, Geri düğmesine dokunarak aramayı iptal ederse arama iletişim kutusu kapanır ve etkinlik, giriş odağını yeniden kazanır. Arama iletişim kutusu setOnDismissListener(), setOnCancelListener() veya her ikisiyle de kapatıldığında bildirim almak için kaydolabilirsiniz. Arama iletişim kutusu her kapatıldığında çağrıldığı için yalnızca OnDismissListener öğesini kaydetmeniz gerekir. OnCancelListener yalnızca kullanıcının arama iletişim kutusundan açıkça çıktığı etkinliklerle ilgilidir. Bu nedenle, arama yürütüldüğünde çağrılmaz. Arama yürütüldüğünde arama iletişim kutusu otomatik olarak kaybolur.

Mevcut etkinlik, aranabilir etkinlik değilse kullanıcı arama yaptığında normal etkinlik yaşam döngüsü etkinlikleri tetiklenir. Mevcut etkinlik, Etkinliklere giriş bölümünde açıklandığı gibi onPause() alır. Ancak mevcut etkinlik aranabilir etkinlikse iki durumdan biri gerçekleşir:

• Varsayılan olarak, aranabilir etkinlik ACTION_SEARCH amaçlı onCreate() çağrısı alır ve etkinliğin yeni bir örneği etkinlik yığınının en üstüne getirilir. Etkinlik yığınında artık aranabilir etkinliğinizin iki örneği var. Bu nedenle, Geri düğmesine dokunduğunuzda aranabilir etkinlikten çıkmak yerine aranabilir etkinliğin önceki örneğine geri dönersiniz.
• android:launchMode değerini "singleTop" olarak ayarlarsanız, aranabilir etkinlik, yeni ACTION_SEARCH amacını ileterek onNewIntent(Intent) çağrısıyla birlikte ACTION_SEARCH amacını alır. Örneğin, aranabilir etkinliğin başlatma modunun "singleTop" olduğu bu durumu nasıl ele alabileceğinizi aşağıda görebilirsiniz:

  Kotlin

  override fun onCreate(savedInstanceState: Bundle?) {
      super.onCreate(savedInstanceState)
      setContentView(R.layout.search)
      handleIntent(intent)
  }
  
  override fun onNewIntent(intent: Intent) {
      super.onNewIntent(intent)
      setIntent(intent)
      handleIntent(intent)
  }
  
  private fun handleIntent(intent: Intent) {
      if (Intent.ACTION_SEARCH == intent.action) {
          intent.getStringExtra(SearchManager.QUERY)?.also { query ->
              doMySearch(query)
          }
      }
  }

  Java

  @Override
  public void onCreate(Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      setContentView(R.layout.search);
      handleIntent(getIntent());
  }
  
  @Override
  protected void onNewIntent(Intent intent) {
      super.onNewIntent(intent);
      setIntent(intent);
      handleIntent(intent);
  }
  
  private void handleIntent(Intent intent) {
      if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        doMySearch(query);
      }
  }

  Arama yapma bölümündeki örnek kodla karşılaştırıldığında, arama amacını işlemek için kullanılan tüm kodlar artık handleIntent() yönteminde yer alıyor. Böylece hem onCreate() hem de onNewIntent() bu kodu çalıştırabiliyor.

  Sistem onNewIntent(Intent) işlevini çağırdığında etkinlik yeniden başlatılmaz. Bu nedenle getIntent() yöntemi, onCreate() ile alınan aynı amaçla geri döner. Bu nedenle, gelecekte getIntent() işlevini çağırmanız durumunda etkinliğin kaydettiği amacın güncellenmesi için onNewIntent(Intent) içinde setIntent(Intent) işlevini çağırmanız gerekir.

"singleTop" başlatma modunun kullanıldığı ikinci senaryo genellikle tercih edilir. Çünkü bir arama yapıldıktan sonra kullanıcı ek aramalar yapabilir ve uygulamanızın aranabilir etkinliğin birden fazla örneğini oluşturmasını istemezsiniz. Aşağıdaki örnekte gösterildiği gibi, aranabilir etkinliğinizi uygulama manifestinde "singleTop" başlatma moduna ayarlamanızı öneririz:

<activity android:name=".SearchableActivity"
          android:launchMode="singleTop" >
    <intent-filter>
        <action android:name="android.intent.action.SEARCH" />
    </intent-filter>
    <meta-data
          android:name="android.app.searchable"
          android:resource="@xml/searchable"/>
  </activity>

Arama bağlamı verilerini iletme

Bazı durumlarda, yapılan her arama için aranabilir etkinlik içinde arama sorgusunda gerekli düzenlemeleri yapabilirsiniz. Ancak arama ölçütlerinizi kullanıcının arama yaptığı etkinliğe göre hassaslaştırmak istiyorsanız sistemin aranabilir etkinliğinize gönderdiği amaçta ek veriler sağlayabilirsiniz. Ek verileri, APP_DATA Bundle içinde iletebilirsiniz. Bu, ACTION_SEARCH amacına dahildir.

Bu tür verileri aranabilir etkinliğinize iletmek için kullanıcının arama yapabileceği etkinlik için onSearchRequested() yöntemini geçersiz kılın, ek verilerle bir Bundle oluşturun ve arama iletişim kutusunu etkinleştirmek için startSearch() yöntemini çağırın. Örneğin:

Kotlin

override fun onSearchRequested(): Boolean {
    val appData = Bundle().apply {
        putBoolean(JARGON, true)
    }
    startSearch(null, false, appData, false)
    return true
}

Java

@Override
public boolean onSearchRequested() {
     Bundle appData = new Bundle();
     appData.putBoolean(SearchableActivity.JARGON, true);
     startSearch(null, false, appData, false);
     return true;
 }

Doğru değerini döndürmek, bu geri çağırma etkinliğini başarıyla işlediğinizi ve arama iletişim kutusunu etkinleştirmek için startSearch() işlevini çağırdığınızı gösterir. Kullanıcı bir sorgu gönderdikten sonra, eklediğiniz verilerle birlikte aranabilir etkinliğinize iletilir. Aramayı hassaslaştırmak için APP_DATA Bundle simgesinden ek verileri ayıklayabilirsiniz. Aşağıdaki örnekte bu işlem gösterilmektedir:

Kotlin

val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false

Java

Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
if (appData != null) {
    boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
}

Dikkat: startSearch() yöntemini hiçbir zaman onSearchRequested() geri çağırma yönteminin dışından çağırmayın. Etkinliğinizde arama iletişim kutusunu etkinleştirmek için her zaman onSearchRequested() çağrısı yapın. Aksi takdirde, onSearchRequested() çağrılmaz ve önceki örnekte appData eklenmesi gibi özelleştirmeler atlanır.

Arama widget'ını kullanma

1.şekil SearchView widget'ı, uygulama çubuğunda işlem görünümü olarak.

Arama widget'ı, arama iletişim kutusuyla aynı işlevleri sağlar. Kullanıcı arama yaptığında uygun etkinliği başlatır, arama önerileri sunabilir ve sesli arama yapabilir. Arama widget'ını uygulama çubuğuna yerleştiremiyorsanız bunun yerine arama widget'ını etkinlik düzeninizde bir yere yerleştirebilirsiniz.

Not: Arama widget'ını işlem görünümü olarak kullandığınızda, arama widget'ının uygulama çubuğuna sığmadığı durumlarda arama iletişim kutusunun kullanılmasını desteklemeniz gerekebilir. Hem widget'ı hem de iletişim kutusunu kullanma bölümüne bakın.

Arama widget'ını yapılandırma

Arama yapılandırması ve aranabilir etkinlik oluşturduktan sonra, SearchView için yardımcı aramayı etkinleştirin. Bunu yapmak için setSearchableInfo() işlevini çağırın ve aranabilir yapılandırmanızı temsil eden SearchableInfo nesnesini iletin.

SearchableInfo öğesine referans almak için SearchManager üzerinde getSearchableInfo() işlevini çağırabilirsiniz.

Örneğin, uygulama çubuğunda işlem görünümü olarak SearchView kullanıyorsanız aşağıdaki örnekte gösterildiği gibi onCreateOptionsMenu() geri çağırması sırasında widget'ı etkinleştirin:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    // Inflate the options menu from XML.
    val inflater = menuInflater
    inflater.inflate(R.menu.options_menu, menu)

    // Get the SearchView and set the searchable configuration.
    val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
    (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
        // Assumes current activity is the searchable activity.
        setSearchableInfo(searchManager.getSearchableInfo(componentName))
        setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default.
    }

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the options menu from XML.
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.options_menu, menu);

    // Get the SearchView and set the searchable configuration.
    SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
    SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
    // Assumes current activity is the searchable activity.
    searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
    searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default.

    return true;
}

Arama widget'ı artık yapılandırıldı ve sistem, arama sorgularını aranabilir etkinliğinize iletiyor. Arama widget'ı için arama önerilerini de etkinleştirebilirsiniz.

Not: Tüm kullanıcı girişlerini kendiniz işlemek istiyorsanız bunu bazı geri çağırma yöntemleri ve etkinlik dinleyicileriyle yapabilirsiniz. Daha fazla bilgi için SearchView ve iç içe yerleştirilmiş arayüzleriyle ilgili referans belgelerine bakın.

Uygulama çubuğundaki işlem görünümleri hakkında daha fazla bilgi için İşlem görünümlerini ve işlem sağlayıcıları kullanma başlıklı makaleyi inceleyin.

Diğer arama widget'ı özellikleri

SearchView widget'ı, isteyebileceğiniz birkaç ek özellik sunar:

Gönder düğmesi

Varsayılan olarak arama sorgusu gönderme düğmesi yoktur. Bu nedenle, kullanıcının arama başlatmak için klavyedeki Return tuşuna basması gerekir. setSubmitButtonEnabled(true) işlevini çağırarak "gönder" düğmesi ekleyebilirsiniz.

Arama önerileri için sorgu hassaslaştırma

Arama önerilerini etkinleştirdiğinizde genellikle kullanıcıların bir öneriyi seçmesini beklersiniz ancak kullanıcılar önerilen arama sorgusunu da hassaslaştırmak isteyebilir. setQueryRefinementEnabled(true) işlevini çağırarak, her önerinin yanına, öneriyi arama kutusuna ekleyip kullanıcının aramayı daraltmasını sağlayan bir düğme ekleyebilirsiniz.

Arama kutusunun görünürlüğünü açıp kapatabilme

Arama widget'ı varsayılan olarak "küçültülmüş" durumdadır. Yani yalnızca bir arama simgesiyle (büyüteç) gösterilir. Kullanıcı simgeye dokunduğunda arama kutusunu göstermek için genişler. Önceki örnekte gösterildiği gibi, setIconifiedByDefault(false) işlevini çağırarak arama kutusunu varsayılan olarak gösterebilirsiniz. setIconified() işlevini çağırarak arama widget'ının görünümünü de değiştirebilirsiniz.

SearchView sınıfında, arama widget'ını özelleştirmenize olanak tanıyan başka API'ler de vardır. Ancak bunların çoğu, arama sorgularını iletmek ve arama önerilerini göstermek için Android sistemini kullanmak yerine tüm kullanıcı girişlerini kendiniz işlediğinizde kullanılır.

Hem widget'ı hem de iletişim kutusunu kullanma

Arama widget'ını uygulama çubuğuna işlem görünümü olarak eklerseniz ve android:showAsAction="ifRoom" ayarını yaparak yer varsa uygulama çubuğunda görünmesini sağlarsanız arama widget'ı işlem görünümü olarak görünmeyebilir. Bunun yerine, menü öğesi taşma menüsünde görünebilir. Örneğin, uygulamanız daha küçük bir ekranda çalışırken uygulama çubuğunda arama widget'ını diğer işlem öğeleri veya gezinme öğeleriyle birlikte görüntülemek için yeterli alan olmayabilir. Bu durumda menü öğesi, taşma menüsünde görünür. Taşma menüsüne yerleştirilen öğe, normal bir menü öğesi gibi çalışır ve işlem görünümünü (yani arama widget'ını) göstermez.

Bu durumu ele almak için, arama widget'ını eklediğiniz menü öğesi, kullanıcı taşma menüsünden bu öğeyi seçtiğinde arama iletişim kutusunu etkinleştirmelidir. Bunun için "Arama" menü öğesini işlemek ve onOptionsItemSelected() çağrısı yaparak arama iletişim kutusunu açmak için onSearchRequested() işlevini uygulayın.

Uygulama çubuğundaki öğelerin işleyiş şekli ve bu durumu ele alma hakkında daha fazla bilgi için Uygulama çubuğu ekleme başlıklı makaleyi inceleyin.

Sesli arama ekleme

Arama iletişim kutunuza veya widget'ınıza sesli arama işlevi eklemek için aranabilir yapılandırmanıza android:voiceSearchMode özelliğini ekleyin. Bu işlem, sesli istem başlatan bir sesli arama düğmesi ekler. Kullanıcı konuşmayı bitirdiğinde, transkripsiyonu yapılan arama sorgusu aranabilir etkinliğinize gönderilir.

Bu durum aşağıdaki örnekte gösterilmektedir:

<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="@string/search_label"
    android:hint="@string/search_hint"
    android:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
</searchable>

Sesli aramayı etkinleştirmek için showVoiceSearchButton değeri gereklidir. İkinci değer olan launchRecognizer, sesli arama düğmesinin, yazılı metni aranabilir etkinliğe döndüren bir tanıyıcı başlatması gerektiğini belirtir.

Beklenen dil ve döndürülecek maksimum sonuç sayısı gibi ek özellikler sağlayarak sesli arama davranışını belirtebilirsiniz. Kullanılabilir özellikler hakkında daha fazla bilgi için Arama yapılandırması referansına bakın.

Not: Sesli aramanın uygulamanız için uygun olup olmadığını dikkatlice değerlendirin. Sesli arama düğmesiyle yapılan aramalar, kullanıcının transkripsiyonu yapılan sorguyu incelemesine fırsat verilmeden anında aranabilir etkinliğinize gönderilir. Ses tanımayı test edin ve kullanıcının uygulamanızda gönderebileceği sorgu türlerini anladığından emin olun.

Arama önerileri ekleme

Hem arama iletişim kutusu hem de arama widget'ı, kullanıcı yazarken Android sisteminin yardımıyla arama önerileri sunabilir. Sistem, öneri listesini yönetir ve kullanıcı bir öneri seçtiğinde etkinliği işler.

İki tür arama önerisi sağlayabilirsiniz:

Son sorgu arama önerileri

Bu öneriler, kullanıcının daha önce uygulamanızda arama sorgusu olarak kullandığı kelimelerdir. Daha fazla bilgi için Özel arama önerileri ekleme başlıklı makaleyi inceleyin.

Özel arama önerileri

Bunlar, kullanıcıların aradıkları doğru yazımı veya öğeyi hemen seçmelerine yardımcı olmak için kendi veri kaynağınızdan sağladığınız arama önerileridir. Daha fazla bilgi için Özel arama önerileri ekleme başlıklı makaleyi inceleyin.