Arama arayüzü oluşturma

Uygulamanıza arama işlevi eklemeye hazır olduğunuzda Android, etkinlik penceresinin üstünde görüntülenen bir arama iletişim kutusu veya düzeninize ekleyebileceğiniz bir arama widget'ı ile kullanıcı arayüzünü 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 şekilde, kullanıcı, arama iletişim kutusunun veya widget'ın bulunduğu 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 için kullanılabilen diğer özellikler şunlardır:

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

Bu dokümanda, uygulamanızı arama iletişim kutusunu veya arama widget'ını kullanarak arama sorguları sunmak için Android sistemi tarafından desteklenen bir arama arayüzü sağlayacak şekilde nasıl ayarlayacağınız gösterilmektedir.

İlgili kaynaklar:

Temel bilgiler

Başlamadan önce, arama iletişim kutusunu veya arama widget'ını kullanarak arama arayüzünüzü uygulamak isteyip istemediğinize karar verin. Bunlar, aynı arama özelliklerini sunar, ancak biraz farklı şekillerdedir:

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

    Android sistemi, arama iletişim kutusundaki tüm etkinlikleri kontrol eder. Kullanıcı bir sorgu gönderdiğinde, sistem bu sorguyu, aramaları işlemek için belirttiğiniz etkinliğe yayınlar. İletişim kutusu, kullanıcı yazarken arama önerileri de sağlayabilir.

  • Arama widget'ı, düzeninizde istediğiniz yere yerleştirebileceğiniz bir SearchView örneğidir. Varsayılan olarak, arama widget'ı standart bir EditText widget'ı gibi davranır ve hiçbir şey yapmaz. Ancak widget'ı, tıpkı arama iletişim kutusunda olduğu gibi Android sisteminin tüm giriş etkinliklerini işleyecek, sorguları uygun etkinliğe göndermesi ve arama önerileri sağlayacak şekilde yapılandırabilirsiniz.

Kullanıcı, arama iletişim kutusundan veya arama widget'ından arama gerçekleştirdiğinde, sistem bir Intent oluşturur ve kullanıcı sorgusunu bunun içinde depolar. Daha sonra sistem, aramaları ele alacağını belirttiğiniz etkinliği ("aranabilir etkinlik") başlatır ve bunu amacı iletir. Uygulamanızı bu tür bir destekli arama için ayarlamak üzere şunlara 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ıdır. Burada sesli arama, arama önerisi ve arama kutusu için ipucu metni gibi özelliklerle ilgili ayarlar bulunur.
  • Aranabilir bir etkinlik
    Arama sorgusunu alan Activity, verilerinizde arama yapar ve arama sonuçlarını görüntüler.
  • Aşağıdakilerden biri tarafından sağlanan bir arama arayüzü:
    • Arama iletişim kutusu
      Arama iletişim kutusu varsayılan olarak gizlidir. onSearchRequested() numaralı telefonu aradığınızda, kullanıcı Ara düğmenize dokunduğunda ekranın üst kısmında görünür.
    • Bir SearchView widget'ı
      Arama widget'ını kullanmak, arama kutusunu uygulama çubuğunda işlem görünümü de dahil olmak üzere etkinliğinizin herhangi bir yerine koymanıza olanak tanır.

Bu dokümanın geri kalanında, arama yapılandırmasının ve aranabilir etkinliğin nasıl oluşturulacağı ve arama iletişim kutusu veya arama widget'ıyla bir arama arayüzünün nasıl uygulanacağı gösterilmektedir.

Aranabilir bir yapılandırma oluşturma

İlk olarak, arama yapılandırması adı verilen bir XML dosyası gerekir. Arama iletişim kutusunun veya widget'ın belirli kullanıcı arayüzü özelliklerini yapılandırır, öneriler ve sesli arama gibi özelliklerin nasıl davranacağını tanımlar. Bu dosya geleneksel olarak searchable.xml şeklinde adlandırılır ve res/xml/ proje dizinine kaydedilmelidir.

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>

android:label özelliği, zorunlu olan tek özelliktir. Uygulama adı olması gereken bir dize kaynağını işaret eder. Siz Çabuk Arama Kutusu için arama önerilerini etkinleştirene kadar bu etiket kullanıcı tarafından görülmez. Bu noktada etiket, sistem ayarlarındaki Aranabilir öğeler listesinde görünür.

Zorunlu olmamakla birlikte, her zaman, kullanıcılar bir sorgu girmeden önce arama kutusuna bir ipucu dizesi sağlayan android:hint özelliğini eklemenizi öneririz. İpucu, kullanıcılara neleri arayabilecekleri hakkında önemli ipuçları sağladığı için önemlidir.

<searchable> öğesi diğer birkaç özelliği kabul eder. Ancak, arama önerileri ve sesli arama gibi özellikleri ekleyene kadar çoğu özelliğe ihtiyacınız olmaz. Arama yapılandırma dosyası hakkında ayrıntılı bilgi için Arama yapılandırması referans belgesine bakın.

Aranabilir bir etkinlik oluşturma

Aranabilir etkinlik, uygulamanızda bir sorgu dizesine göre arama yapan ve arama sonuçlarını sunan Activity öğesidir.

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

Arama iletişim kutusunu veya widget'ını uygulamanızdaki başka herhangi bir etkinliğe ekleyebileceğiniz için sistemin arama sorgusunu düzgün şekilde sunabilmesi için hangi etkinliğin aranabilir etkinliğiniz olduğunu bilmesi gerekir. Bu yüzden, önce Android manifest dosyasında aranabilir etkinliğinizi tanımlayın.

Aranabilir bir etkinlik bildirme

Henüz yoksa arama yapan ve sonuçları sunan bir Activity oluşturun. Arama işlevini henüz uygulamanız gerekmez. Manifest dosyasında tanımlayabileceğiniz bir etkinlik oluşturmanız yeterlidir. Manifest'in <activity> öğesinde aşağıdakileri yapın:

  1. Etkinliği bir <intent-filter> öğesinde ACTION_SEARCH amacını kabul edecek şekilde bildirin.
  2. <meta-data> öğesinde kullanılacak arama yapılandırmasını belirtin.

Bu, aşağıdaki örnekte gösterilmiştir:

<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 veren android:resource özelliğini içermelidir. Önceki örnekte, res/xml/searchable.xml dosyasına referans verilmiştir.

Arama gerçekleştirir

Manifest'te aranabilir etkinliğinizi bildirdikten sonra, aranabilir etkinliğinizde bir arama yapmak için şu prosedürü uygulayın:

  1. Sorguyu alın.
  2. Verilerinizi arayın.
  3. Sonuçları sunun.

Sorguyu alma

Bir kullanıcı, arama iletişim kutusundan veya widget'tan arama yaptığında, sistem aranabilir etkinliğinizi başlatır ve buna bir ACTION_SEARCH amacı gönderir. Bu amaç, arama sorgusunu QUERY dizesinde ekstra olarak taşır. Etkinlik başladığında bu amacı kontrol edin ve dizeyi ayıklayın. Örneğin, aranabilir etkinliğiniz başladığında arama sorgusunu nasıl alacağınız aşağıda açıklanmıştır:

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ına dahil edilir. Yukarıdaki örnekte sorgu alınır ve gerçek arama işleminin yapıldığı yerel bir doMySearch() yöntemine geçirilir.

Verilerinizde arama yapın

Verilerinizi depolama ve arama işlemi uygulamanıza özeldir. Verilerinizi depolamanın yanı sıra birçok farklı şekilde arama yapabilirsiniz ve bu belgede bunun nasıl yapıldığı gösterilmemektedir. İhtiyaçlarınıza ve veri biçiminize göre verilerinizi nasıl depoladığınızı ve aradığınızı düşünün. Aşağıda, uygulayabileceğiniz ipuçları verilmiştir:

  • Verileriniz cihazdaki bir SQLite veritabanında depolanıyorsa LIKE sorgusu yerine FTS3 kullanarak tam metin araması gerçekleştirmek, metin verilerinde daha güçlü bir arama sağlayabilir ve önemli ölçüde daha hızlı sonuç üretebilir. FTS3 hakkında bilgi için sqlite.org, Android'de SQLite hakkında bilgi için SQLiteDatabase sınıfını ziyaret edin.
  • Verileriniz çevrimiçi olarak depolanıyorsa kullanıcının veri bağlantısı, algılanan arama performansını engelleyebilir. Aramanız geri gelene kadar bir ilerleme göstergesi görüntülemek isteyebilirsiniz. Ağ API'lerine ilişkin referans için android.net ve ilerleme durumu göstergesinin nasıl gösterileceği hakkında bilgi için ProgressBar adresine göz atın.

Sonuçları sunma

Verilerinizin nerede bulunduğu ve nasıl arama yaptığınız fark etmeksizin, arama sonuçlarını Adapter ile aranabilir etkinliğinize döndürmenizi öneririz. Bu şekilde, tüm arama sonuçlarını RecyclerView içinde sunabilirsiniz. Verileriniz bir SQLite veritabanı sorgusundan geliyorsa sonuçlarınızı CursorAdapter kullanarak bir RecyclerView öğesine uygulayabilirsiniz. Verileriniz farklı bir biçimde geliyorsa BaseAdapter uzantısı oluşturabilirsiniz.

Adapter, bir veri kümesindeki her öğeyi bir View nesnesine bağlar. Adapter bir RecyclerView öğesine uygulandığında, her veri parçası listeye ayrı bir görünüm olarak eklenir. Adapter yalnızca bir arayüzdür. Bu nedenle, Cursor kaynağından veri bağlamak için CursorAdapter gibi uygulamaların kullanılması gerekir. Mevcut uygulamaların hiçbiri verileriniz için işe yaramazsa BaseAdapter adresinden kendi uygulamanızı uygulayabilirsiniz.

Arama iletişim kutusunu kullanma

Arama iletişim kutusunda, ekranın üst kısmında kayan bir arama kutusu, solda uygulama simgesi bulunur. Arama iletişim kutusu, kullanıcı yazarken arama önerileri sağlayabilir. Kullanıcı bir arama yaptığında, sistem arama sorgusunu aramayı yapan 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 kutusu etkinleştirilene kadar çalışmaz.

Arama iletişim kutusunu arama yapacak şekilde etkinleştirmek için, aranabilir etkinliğin hangi etkinliğin arama iletişim kutusundan arama sorgusu alması gerektiğini sisteme belirtin. Örneğin, önceki aranabilir etkinlik oluşturma bölümünde SearchableActivity adlı, aranabilir bir etkinlik oluşturulur. Arama iletişim kutusunu göstermek ve aramaları SearchableActivity adresine göndermek için OtherActivity adlı ayrı bir etkinlik istiyorsanız manifest'te, OtherActivity içindeki arama iletişim kutusu için kullanılacak aranabilir etkinlik SearchableActivity olduğunu belirtin.

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 etkinlik (SearchableActivity) hem de arama iletişim kutusundan yürütülen aramalar yapmak için SearchableActivity kullanan başka bir etkinlik (OtherActivity) ile ilgili bildirimi burada bulabilirsiniz:

<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 aramalar için hangi aranabilir etkinliğin kullanılacağını bildirmek üzere bir <meta-data> öğesi içerdiğinden, etkinlik arama iletişim kutusunu etkinleştirir. Kullanıcı bu etkinlikte olsa da onSearchRequested() yöntemi arama iletişim kutusunu etkinleştirir. Kullanıcı aramayı yaptığında sistem SearchableActivity başlatır ve ACTION_SEARCH niyetini sunar.

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

Arama iletişim kutusu etkinlikleriniz için artık etkin olan uygulamanız arama yapmaya hazırdır.

Arama iletişim kutusunu çağır

Bazı cihazlarda özel bir arama düğmesi sağlasa da düğmenin çalışma biçimi cihazlar arasında değişiklik gösterebilir ve birçok cihaz hiç arama düğmesi sağlamaz. Dolayısıyla, arama iletişim kutusunu kullanırken kullanıcı arayüzünüzde onSearchRequested() çağrısı yaparak arama iletişim kutusunu etkinleştiren bir arama düğmesi sağlamanız gerekir.

Örneğin, seçenekler menünüze veya kullanıcı arayüzü düzeninize onSearchRequested() çağrısı yapan bir arama düğmesi ekleyin.

Kullanıcı klavyede yazmaya başladığında arama iletişim kutusunu etkinleştiren "aramak için yaz" işlevini de etkinleştirebilirsiniz. Tuş vuruşları, arama iletişim kutusuna eklenir. Etkinliğinizin onCreate() yöntemi sırasında setDefaultKeyMode veya DEFAULT_KEYS_SEARCH_LOCAL yöntemini çağırarak etkinliğinizde tür arama özelliğini etkinleştirebilirsiniz.

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

Arama iletişim kutusu, ekranın üst kısmında kayan bir Dialog'dir. 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. Giriş odağı arama iletişim kutusuna 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. Sistemin bu yöntemi çağırması, etkinliğinizin arama iletişim kutusuna giriş odağını kaybettiğinin göstergesidir. Bu nedenle, bir oyunu duraklatmak gibi etkinlik için uygun olan tüm işlemleri yapabilirsiniz. Bu belgenin başka bir bölümünde açıklanan 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 elde eder. Arama iletişim kutusu setOnDismissListener() veya setOnCancelListener() ile kapatıldığında bildirim almak için kaydolabilirsiniz. Arama iletişim kutusu her kapatıldığında OnDismissListener çağrıldığından yalnızca kaydetmeniz gerekir. OnCancelListener yalnızca kullanıcının arama iletişim kutusundan açıkça çıktığı etkinliklerle ilgili olduğundan arama yapıldığında çağrılmaz. Arama yürütüldüğünde, arama iletişim kutusu otomatik olarak kaybolur.

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

  • Varsayılan olarak, aranabilir etkinlik ACTION_SEARCH amacını onCreate() çağrısıyla alır ve etkinliğin yeni bir örneği etkinlik yığınının en üstüne getirilir. Etkinlik yığınında aranabilir etkinliğinizin artık iki örneği olduğundan, Geri düğmesine dokunduğunuzda aranabilir etkinlikten çıkmak yerine, aranabilir etkinliğin bir önceki örneğine geri dönersiniz.
  • android:launchMode öğesini "singleTop" olarak ayarlarsanız aranabilir etkinlik, onNewIntent(Intent) çağrısıyla ACTION_SEARCH amacını alarak yeni ACTION_SEARCH niyetini iletir. Örneğin, aranabilir etkinliğin başlatma modunun "singleTop" olduğu bu durumu şöyle ele alabilirsiniz:

    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 gerçekleştirme ile ilgili bölümdeki örnek kodla karşılaştırıldığında, arama amacını işlemek için tüm kod artık handleIntent() yöntemindedir. Böylece hem onCreate() hem de onNewIntent() bunu yürütebilir.

    Sistem onNewIntent(Intent) yöntemini çağırdığında etkinlik yeniden başlatılmaz. Bu nedenle getIntent() yöntemi, onCreate() ile alınan amacı döndürür. Bu nedenle, onNewIntent(Intent) içinde setIntent(Intent) yöntemini çağırmanız gerekir. Böylece, ileride getIntent() çağrısı yapmanız durumunda etkinlik tarafından kaydedilen amacın güncellenmesini sağlayabilirsiniz.

"singleTop" başlatma modunun kullanıldığı ikinci senaryo genellikle tercih edilir, çünkü bir arama tamamlandıktan sonra kullanıcı ek aramalar yapabilir ve uygulamanızın aranabilir etkinliğin birden fazla örneğini oluşturmasını istemezsiniz. Aranabilir etkinliğinizi aşağıdaki örnekte gösterildiği gibi, uygulama manifest dosyasında "singleTop" başlatma modu olarak 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 etkinlikteki arama sorgusunda gerekli ayrıntılandırmaları yapabilirsiniz. Ancak, arama ölçütlerinizi kullanıcının arama yaparken gerçekleştiği etkinliğe göre hassaslaştırmak isterseniz sistemin aranabilir etkinliğinize gönderdiği amaca yönelik ek veriler sağlayabilirsiniz. Ek verileri, ACTION_SEARCH amacına dahil olan APP_DATA Bundle içinde aktarabilirsiniz.

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 döndürülmesi, bu geri çağırma etkinliğini başarıyla gerçekleştirdiğinizi ve arama iletişim kutusunu etkinleştirmek için startSearch() yöntemini çağırdığınızı belirtir. Kullanıcı bir sorgu gönderdikten sonra, bu sorgu, eklediğiniz verilerle birlikte aranabilir etkinliğinize gönderilir. Aşağıdaki örnekte gösterildiği gibi, aramayı hassaslaştırmak için APP_DATA Bundle aracından ekstra verileri çıkarabilirsiniz:

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

Arama widget'ını kullanma

Uygulamanın üst çubuğunda arama görünümünü gösteren resim

Şekil 1. Uygulama çubuğundaki bir işlem görünümü olarak SearchViewwidget.

Arama widget'ı, arama iletişim kutusuyla aynı işlevi sağlar. Kullanıcı bir arama yaptığında uygun etkinliği başlatır, arama önerileri sunabilir ve sesli arama gerçekleştirebilir. Arama widget'ını uygulama çubuğuna yerleştirme seçeneği yoksa bunun yerine arama widget'ını etkinlik düzeninizde herhangi bir yere yerleştirebilirsiniz.

Arama widget'ını yapılandırın

Bir arama yapılandırması ve bir aranabilir etkinlik oluşturduktan sonra, setSearchableInfo() çağırıp yapılandırmanızı temsil eden SearchableInfo nesnesini ileterek her SearchView için destekli aramayı etkinleştirin.

SearchManager numaralı telefondan getSearchableInfo() numaralı telefonu arayarak SearchableInfo için referans öğrenebilirsiniz.

Örneğin, uygulama çubuğunda işlem görünümü olarak bir SearchView kullanıyorsanız onCreateOptionsMenu() geri çağırma işlemi sırasında widget'ı aşağıdaki örnekte gösterildiği gibi 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'ı yapılandırılır ve sistem, arama sorgularını aranabilir etkinliğinize yayınlar. Arama widget'ı için arama önerilerini de etkinleştirebilirsiniz.

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ını kullanma bölümüne bakın.

Diğer arama widget'ı özellikleri

SearchView widget'ı isteyebileceğiniz birkaç ek özellik sağlar:

Gönder düğmesi
Varsayılan olarak, arama sorgusunu göndermek için herhangi bir düğme yoktur. Dolayısıyla kullanıcının, arama başlatmak için klavyedeki Return tuşuna basması gerekir. setSubmitButtonEnabled(true) yöntemini çağırarak "gönder" düğmesi ekleyebilirsiniz.
Arama önerileri için sorgu ayrıntılandırma
Arama önerilerini etkinleştirdiğinizde genellikle kullanıcıların bir öneriyi seçmelerini beklersiniz, ancak önerilen arama sorgusunu da hassaslaştırmak isteyebilirler. Her önerinin yanına, kullanıcı tarafından ayrıntılandırılmak üzere arama kutusuna eklenen bir düğme ekleyebilirsiniz. Bunun için setQueryRefinementEnabled(true) yöntemini çağırabilirsiniz.
Arama kutusu görünürlüğünü değiştirme olanağı
Varsayılan olarak arama widget'ı "simgeleştirilmiştir". Yani yalnızca arama simgesi, yani büyüteçle temsil edilir. Kullanıcı simgeye dokunduğunda arama kutusu görüntülenecek şekilde genişler. Önceki örnekte gösterildiği gibi, setIconifiedByDefault(false) yöntemini çağırarak arama kutusunu varsayılan olarak gösterebilirsiniz. Ayrıca setIconified() yöntemini çağırarak arama widget'ı görünümünü değiştirebilirsiniz.

SearchView sınıfında, arama widget'ını özelleştirmenize olanak tanıyan başka API'ler de vardır. Ancak çoğu arama sorgusu sunmak ve arama önerilerini görüntülemek için Android sistemini kullanmak yerine, yalnızca tüm kullanıcı girişlerini kendiniz yönettiğinizde kullanılır.

Hem widget'ı hem de iletişim kutusunu kullanma

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

Bu durumu düzeltmek için, kullanıcı taşma menüsünden seçtiğinde arama widget'ını eklediğiniz menü öğesinin, arama iletişim kutusunu etkinleştirmesi gerekir. Bunun için onOptionsItemSelected() işlemini, "Arama" menü öğesini işlemek üzere uygulayın ve onSearchRequested() yöntemini çağırarak arama iletişim kutusunu açın.

Uygulama çubuğundaki öğelerin nasıl çalıştığı ve bu durumun nasıl ele alınacağı hakkında daha fazla bilgi için Uygulama çubuğunu ekleme bölümüne bakın.

Sesli arama ekleyin

Aranabilir yapılandırmanıza android:voiceSearchMode özelliğini ekleyerek arama iletişim kutunuza veya widget'ınıza sesli arama işlevi ekleyebilirsiniz. Bu, sesli istemi başlatan bir sesli arama düğmesi ekler. Kullanıcı konuşmayı bitirdiğinde, metne dönüştürülen arama sorgusu, aranabilir etkinliğinize gönderilir.

Bu, aşağıdaki örnekte gösterilmiştir:

<?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 metne dönüştürülen metni aranabilir etkinliğe döndüren bir tanımlayıcı başlatması gerektiğini belirtir.

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

Arama önerileri ekle

Hem arama iletişim kutusu hem de arama widget'ı, Android sisteminin yardımıyla kullanıcı yazarken arama önerileri sağlayabilir. 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 sorguları olarak kullandığı kelimelerdir. Daha fazla bilgi için Özel arama önerileri ekleme konusuna bakın.
Özel arama önerileri
Bunlar, kullanıcıların aradıkları 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ı makaleye bakın.