Özel arama önerileri ekleyin

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 →

Android arama iletişim kutusunu veya arama widget'ını kullanırken uygulamanızdaki verilerden oluşturulan özel arama önerileri sağlayabilirsiniz. Örneğin, uygulamanız bir sözlükse kullanıcı sorgusunu girmeyi tamamlamadan önce arama alanına girilen metinle eşleşen sözlükteki kelimeleri önerebilirsiniz. Bu öneriler, kullanıcının ne istediğini etkili bir şekilde tahmin edebildikleri ve buna anında erişim sağlayabildikleri için değerlidir. Şekil 1'de, özel öneriler içeren bir arama iletişim kutusu örneği gösterilmektedir.

Özel öneriler sağladıktan sonra bunları sistem genelindeki hızlı arama kutusunda da kullanılabilir hale getirebilirsiniz. Böylece, uygulamanızın dışından içeriğinize erişim sağlanır.

Özel öneriler eklemeden önce uygulamanızdaki aramalar için Android arama iletişim kutusunu veya bir arama widget'ı uygulayın. Arama arayüzü oluşturma ve İçerik sağlayıcılar başlıklı makalelere bakın.

Temel bilgiler

1.şekil Özel arama önerileri içeren bir arama iletişim kutusunun ekran görüntüsü.

Kullanıcı özel bir öneri seçtiğinde sistem, aranabilir etkinliğinize bir Intent gönderir. ACTION_SEARCH işlemiyle bir amaç gönderen normal bir arama sorgusunun aksine, özel önerilerinizi ACTION_VIEW veya başka bir amaç işlemi kullanacak şekilde tanımlayabilir ve seçilen öneriyle alakalı veriler de ekleyebilirsiniz. Sözlük örneğinde, kullanıcı bir öneri seçtiğinde uygulama, sözlükte eşleşme aramak yerine söz konusu kelimenin tanımını hemen açabilir.

Özel öneriler sunmak için aşağıdaki adımları uygulayın:

• Arama arayüzü oluşturma bölümünde açıklandığı gibi, temel bir aranabilir etkinlik uygulayın.
• Özel öneriler sunan içerik sağlayıcı hakkındaki bilgilerle aranabilir yapılandırmayı değiştirin.
• Önerileriniz için SQLiteDatabase gibi bir tablo oluşturun ve tabloyu gerekli sütunlarla biçimlendirin.
• Öneri tablonuza erişimi olan bir içerik sağlayıcı oluşturun ve sağlayıcıyı manifest dosyanızda bildirin.
• Kullanıcı bir öneri seçtiğinde gönderilecek Intent türünü (özel işlem ve özel veriler dahil) beyan edin.

Android sistemi, arama iletişim kutusunu gösterdiği gibi arama önerilerinizi de gösterir. Sistemin önerilerinizi alabileceği bir içerik sağlayıcıya ihtiyacınız vardır. İçerik sağlayıcı oluşturmayı öğrenmek için İçerik sağlayıcılar başlıklı makaleyi okuyun.

Sistem, etkinliğinizin aranabilir olduğunu belirleyip arama önerileri sunduğunda kullanıcı bir sorgu girdiğinde aşağıdaki prosedür uygulanır:

1. Sistem, arama sorgusu metnini (yani şu ana kadar girilenleri) alır ve önerilerinizi yöneten içerik sağlayıcınıza bir sorgu gönderir.
2. İçerik sağlayıcınız, arama sorgusu metniyle alakalı tüm önerilere işaret eden bir Cursor döndürür.
3. Sistem, Cursor tarafından sağlanan öneri listesini gösterir.

Özel öneriler gösterildikten sonra aşağıdakiler gerçekleşebilir:

• Kullanıcı başka bir harf girerse veya sorguyu herhangi bir şekilde değiştirirse önceki adımlar tekrarlanır ve öneri listesi buna göre güncellenir.
• Kullanıcı aramayı gerçekleştirirse öneriler yoksayılır ve arama, normal ACTION_SEARCH amaç kullanılarak aranabilir etkinliğinize iletilir.
• Kullanıcı bir öneri seçerse aranabilir etkinliğinize bir amaç gönderilir. Bu amaç, uygulamanızın önerilen içeriği açabilmesi için özel bir işlem ve özel veriler içerir.

Aranabilir yapılandırmayı değiştirme

Özel öneri desteği eklemek için aranabilir yapılandırma dosyanızdaki <searchable> öğesine aşağıdaki örnekte gösterildiği gibi android:searchSuggestAuthority özelliğini ekleyin:

<?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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider">
</searchable>

Her öneriye eklediğiniz amaç türüne ve içerik sağlayıcınıza yönelik sorguları nasıl biçimlendirmek istediğinize bağlı olarak ek özelliklere ihtiyacınız olabilir. Diğer isteğe bağlı özellikler aşağıdaki bölümlerde ele alınmaktadır.

İçerik sağlayıcı oluşturma

Özel öneriler için içerik sağlayıcı oluşturmak üzere öncelikle İçerik sağlayıcılar başlıklı makaleyi inceleyerek içerik sağlayıcı oluşturmayı öğrenin. Özel öneriler için içerik sağlayıcı, diğer içerik sağlayıcılara benzer. Ancak, sağladığınız her öneri için Cursor dosyasındaki ilgili satırda, sistemin anlayıp önerileri biçimlendirmek için kullandığı belirli sütunlar bulunmalıdır.

Kullanıcı arama iletişim kutusuna veya arama widget'ına metin girdiğinde sistem, her harf girildiğinde query() çağırarak içerik sağlayıcınızdan öneri ister. query() uygulamanızda, içerik sağlayıcınız öneri verilerinizde arama yapmalı ve iyi öneriler olduğuna karar verdiği satırları işaret eden bir Cursor döndürmelidir.

Özel öneriler için içerik sağlayıcı oluşturmayla ilgili ayrıntılar aşağıdaki iki bölümde ele alınmaktadır:

Öneri sorgusunu işleme

Sistemin, içerik sağlayıcınıza nasıl istek gönderdiği ve bu isteklerin nasıl işleneceği.

Öneri tablosu oluşturma

Sistemin her sorguyla birlikte döndürülmesini Cursor beklediği sütunları nasıl tanımlayacağınız.

Öneri sorgusunu işleme

Sistem, içerik sağlayıcınızdan öneri istediğinde içerik sağlayıcınızın query() yöntemini çağırır. Öneri verilerinizde arama yapmak ve alakalı olduğunu düşündüğünüz önerilere işaret eden bir Cursor döndürmek için bu yöntemi uygulayın.

Sistemin query() yönteminize ilettiği parametrelerin sırayla listelendiği özet aşağıda verilmiştir:

uri

Her zaman bir içerik Uri, aşağıdaki gibi biçimlendirilmelidir:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

Varsayılan davranış, sistemin bu URI'yi iletmesi ve sorgu metnini eklemesidir:

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

Sondaki sorgu metni, URI kodlama kuralları kullanılarak kodlanır. Bu nedenle, arama yapmadan önce metnin kodunu çözmeniz gerekebilir.

optional.suggest.path bölümü, yalnızca aranabilir yapılandırma dosyanızda android:searchSuggestPath özelliğiyle böyle bir yol ayarlarsanız URI'ye dahil edilir. Yalnızca birden fazla aranabilir etkinlik için aynı içerik sağlayıcıyı kullanıyorsanız gereklidir. Bu durumda, öneri sorgusunun kaynağını netleştirin.

Not: SUGGEST_URI_PATH_QUERY, URI'de sağlanan gerçek dize değildir; sabittir. Bu yola başvurmanız gerekirse kullanın.

projection

Her zaman null.

selection

Aranabilir yapılandırma dosyanızın android:searchSuggestSelection özelliğinde sağlanan değer veya android:searchSuggestSelection özelliğini bildirmezseniz null. Bu konu, aşağıdaki bölümde daha ayrıntılı olarak ele alınmıştır.

selectionArgs

Arama sorgusunu, aranabilir yapılandırmanızda android:searchSuggestSelection özelliğini bildirmeniz durumunda dizinin ilk ve tek öğesi olarak içerir. android:searchSuggestSelection değerini belirtmezseniz bu parametre null olur. Bu konu, sonraki bölümde daha ayrıntılı olarak ele alınmaktadır.

sortOrder

Her zaman null.

Sistem, arama sorgusu metnini size iki şekilde gönderebilir. Varsayılan yöntem, uri parametresinde iletilen içerik URI'sinin son yolu olarak sorgu metninin eklenmesidir. Ancak, aranabilir yapılandırmanızın android:searchSuggestSelection özelliğine bir seçim değeri eklerseniz sorgu metni bunun yerine selectionArgs dize dizisinin ilk öğesi olarak iletilir. Bu iki seçenek aşağıda açıklanmıştır.

Uri'deki sorguyu alma

Sorgu, varsayılan olarak uri parametresinin son segmenti olarak eklenir. Bu parametre, Uri nesnesidir. Bu durumda sorgu metnini almak için aşağıdaki örnekte gösterildiği gibi getLastPathSegment() kullanın:

Kotlin

val query: String = uri.lastPathSegment.toLowerCase()

Java

String query = uri.getLastPathSegment().toLowerCase();

Bu, kullanıcının girdiği sorgu metni olan Uri son segmentini döndürür.

Seçim bağımsız değişkenlerindeki sorguyu alma

URI'yi kullanmak yerine, query() yönteminizin aramayı gerçekleştirmek için ihtiyaç duyduğu her şeyi alması daha mantıklı olabilir ve selection ile selectionArgs parametrelerinin uygun değerleri taşımasını isteyebilirsiniz. Bu durumda, SQLite seçim dizenizle birlikte aranabilir yapılandırmanıza android:searchSuggestSelection özelliğini ekleyin. Seçim dizesine, gerçek arama sorgusu için yer tutucu olarak bir soru işareti (?) ekleyin. Sistem, query() işlevini, seçim dizesini selection parametresi olarak ve arama sorgusunu selectionArgs dizisindeki ilk öğe olarak çağırır.

Örneğin, tam metin arama ifadesi oluşturmak için android:searchSuggestSelection özelliğini şu şekilde oluşturabilirsiniz:

<?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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:searchSuggestSelection="word MATCH ?">
</searchable>

Bu yapılandırmayla query() yönteminiz, selection parametresini "word MATCH ?" olarak, selectionArgs parametresini ise arama sorgusu olarak sunar. Bunları, ilgili bağımsız değişkenleri olarak bir SQLite query() yöntemine ilettiğinizde birlikte sentezlenirler. Yani soru işareti, sorgu metniyle değiştirilir. Öneri sorgularını bu şekilde alıyorsanız ve sorgu metnine joker karakterler eklemeniz gerekiyorsa bu değer tırnak içine alınmış ve soru işareti yerine yerleştirilmiş olduğundan joker karakterleri selectionArgs parametresine ekleyin veya bu parametrenin önüne ekleyin.

Önceki örnekteki bir diğer özellik ise android:searchSuggestIntentAction. Bu özellik, kullanıcı bir öneri seçtiğinde her amaçla birlikte gönderilen amaç işlemini tanımlar. Bu konu, Öneriler için amaç beyan etme bölümünde daha ayrıntılı olarak ele alınmıştır.

İpucu: android:searchSuggestSelection özelliğinde bir seçim koşulu tanımlamak istemiyorsanız ancak sorgu metnini selectionArgs parametresinde almak istiyorsanız android:searchSuggestSelection özelliği için boş olmayan bir değer sağlayın. Bu işlem, sorgunun selectionArgs içinde iletilmesini tetikler ve selection parametresini yoksayabilirsiniz. Bu şekilde, gerçek seçim koşulunu daha düşük bir düzeyde tanımlayabilirsiniz. Böylece içerik sağlayıcınızın bu koşulla ilgilenmesi gerekmez.

Öneri tablosu oluşturma

Sisteme Cursor ile öneri döndürdüğünüzde sistem, her satırda belirli sütunlar olmasını bekler. Öneri verilerinizi cihazdaki bir SQLite veritabanında, bir web sunucusundaki veritabanında veya cihazda ya da web'de başka bir biçimde depolamanızdan bağımsız olarak, önerileri bir tablodaki satırlar şeklinde biçimlendirin ve Cursor ile birlikte sunun.

Not: Arama önerileriniz, sistemin gerektirdiği sütunlar kullanılarak tablo biçiminde (ör. SQLite tablosu) depolanmıyorsa öneri verilerinizde eşleşme arayabilir ve ardından her istekte bunları gerekli tabloya biçimlendirebilirsiniz. Bunu yapmak için gerekli sütun adlarını kullanarak bir MatrixCursor oluşturun ve ardından addRow(Object[]) kullanarak her öneri için bir satır ekleyin. İçerik sağlayıcınızın query() yönteminden nihai ürünü döndürün.

Sistem birkaç sütunu anlar ancak yalnızca ikisi gereklidir:

_ID

Her öneri için benzersiz bir tam sayı satır kimliği. Sistem, ListView içinde öneri sunmak için bu bilgiyi gerektirir.

SUGGEST_COLUMN_TEXT_1

Öneri olarak sunulan dize.

Aşağıdaki sütunların tümü isteğe bağlıdır. Çoğu aşağıdaki bölümlerde daha ayrıntılı olarak ele alınmıştır.

SUGGEST_COLUMN_TEXT_2

Bir dize. Cursor dosyanızda bu sütun varsa tüm öneriler iki satırlık biçimde sağlanır. Bu sütundaki dize, birincil öneri metninin altında ikinci ve daha küçük bir metin satırı olarak gösterilir. İkincil metin olmadığını belirtmek için boş olabilir.

SUGGEST_COLUMN_ICON_1

Çizilebilir kaynak, içerik veya dosya URI dizesi. Cursor bu sütunu içeriyorsa tüm öneriler, sol tarafta çizilebilir simgeyle birlikte simge ve metin biçiminde sağlanır. Bu, satırda simge olmadığını belirtmek için boş veya sıfır olabilir.

SUGGEST_COLUMN_ICON_2

Çizilebilir kaynak, içerik veya dosya URI dizesi. Cursor bu sütunu içeriyorsa tüm öneriler, sağ tarafta simge olacak şekilde simge ve metin biçiminde sağlanır. Bu, satırda simge olmadığını belirtmek için boş veya sıfır olabilir.

SUGGEST_COLUMN_INTENT_ACTION

Bir amaç işlemi dizesi. Bu sütun varsa ve belirli bir satırda değer içeriyorsa önerinin amacını oluştururken burada tanımlanan işlem kullanılır. Öğe sağlanmazsa işlem, aranabilir yapılandırmanızdaki android:searchSuggestIntentAction alanından alınır. Tüm öneriler için aynı işlemi yapıyorsanız işlemi android:searchSuggestIntentAction kullanarak belirtmeniz ve bu sütunu atlamanız daha verimli olur.

SUGGEST_COLUMN_INTENT_DATA

Veri URI'si dizesi. Bu sütun varsa ve belirtilen satırda bir değer içeriyorsa önerinin amacını oluştururken bu veriler kullanılır. Öğe sağlanmazsa veriler, aranabilir yapılandırmanızdaki android:searchSuggestIntentData alanından alınır. Kaynaklardan hiçbiri sağlanmazsa amaçın veri alanı null olur. Verileriniz tüm öneriler için aynıysa veya sabit bir bölüm ve belirli bir kimlik kullanılarak açıklanabiliyorsa android:searchSuggestIntentData ile belirtmek ve bu sütunu atlamak daha verimlidir.

SUGGEST_COLUMN_INTENT_DATA_ID

URI yolu dizesi. Bu sütun varsa ve belirtilen satırda bir değer içeriyorsa niyetin veri alanına "/" ve bu değer eklenir. Bu işlevi yalnızca aranabilir yapılandırmadaki android:searchSuggestIntentData özelliğiyle belirtilen veri alanı uygun bir temel dizeye ayarlanmışsa kullanın.

SUGGEST_COLUMN_INTENT_EXTRA_DATA

Rastgele veriler. Bu sütun varsa ve belirli bir satırda değer içeriyorsa bu, önerinin amacını oluştururken kullanılan ekstra veridir. Sağlanmazsa amaçla ilgili ek veri alanı boş olur. Bu sütun, önerilerin, niyetin EXTRA_DATA_KEY anahtarına ek olarak dahil edilen ek veriler sağlamasına olanak tanır.

SUGGEST_COLUMN_QUERY

Bu sütun varsa ve bu öğe belirtilen satırda bulunuyorsa bu, önerinin sorgusu oluşturulurken kullanılan veridir ve niyetin QUERY anahtarına ek olarak dahil edilir. Önerinin işlemi ACTION_SEARCH ise zorunlu, aksi takdirde isteğe bağlıdır.

SUGGEST_COLUMN_SHORTCUT_ID

Yalnızca Hızlı Arama Kutusu için öneriler sunarken kullanılır. Bu sütun, arama önerisinin kısayol olarak depolanıp depolanmayacağını ve doğrulanıp doğrulanmayacağını belirtir. Kısayollar genellikle kullanıcı Hızlı Arama Kutusundaki bir öneriye dokunduğunda oluşturulur. Eksikse sonuç, kısayol olarak saklanır ve hiçbir zaman yenilenmez. SUGGEST_NEVER_MAKE_SHORTCUT olarak ayarlanırsa sonuç kısayol olarak saklanmaz. Aksi takdirde, kısayol kimliği kullanılarak SUGGEST_URI_PATH_SHORTCUT ile güncel bir öneri aranır.

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

Yalnızca Hızlı Arama Kutusu için öneriler sunarken kullanılır. Bu sütun, bu önerinin kısayolu Hızlı Arama Kutusunda yenilenirken SUGGEST_COLUMN_ICON_2 simgesi yerine bir döndürücü gösterilmesi gerektiğini belirtir.

Bu sütunların çoğu, sonraki bölümlerde daha ayrıntılı olarak ele alınmaktadır.

Öneriler için amaç beyan etme

Kullanıcı, arama iletişim kutusunun veya widget'ının altında görünen listeden bir öneri seçtiğinde sistem, aranabilir etkinliğinize özel bir Intent gönderir. Amacın işlemini ve verilerini tanımlamanız gerekir.

Niyet işlemini bildirme

Özel öneriler için en yaygın amaç işlemi ACTION_VIEW'dır. Bu işlem, bir şeyi (ör. bir kelimenin tanımı, bir kişinin iletişim bilgileri veya bir web sayfası) açmak istediğinizde uygundur. Ancak amaç işlemi başka bir işlem olabilir ve her öneri için farklı olabilir.

Tüm önerilerin aynı amaç işlemini kullanmasını isteyip istemediğinize bağlı olarak işlemi iki şekilde tanımlayabilirsiniz:

• Aşağıdaki örnekte gösterildiği gibi, tüm öneriler için işlemi tanımlamak üzere aranabilir yapılandırma dosyanızın android:searchSuggestIntentAction özelliğini kullanın:

  <?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"
      android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
      android:searchSuggestIntentAction="android.intent.action.VIEW" >
  </searchable>

• Tek tek öneriler için işlemi tanımlamak üzere SUGGEST_COLUMN_INTENT_ACTION sütununu kullanın. Bunu yapmak için öneri tablonuza SUGGEST_COLUMN_INTENT_ACTION sütununu ekleyin ve her öneri için kullanılacak işlemi (ör. "android.intent.action.VIEW") bu sütuna yerleştirin.

Bu iki tekniği birlikte de kullanabilirsiniz. Örneğin, android:searchSuggestIntentAction özelliğini varsayılan olarak tüm önerilerle kullanılacak bir işlemle birlikte ekleyebilir, ardından SUGGEST_COLUMN_INTENT_ACTION sütununda farklı bir işlem belirterek bu işlemi bazı öneriler için geçersiz kılabilirsiniz. SUGGEST_COLUMN_INTENT_ACTION sütununa bir değer eklemezseniz android:searchSuggestIntentAction özelliğinde sağlanan amaç kullanılır.

Not: Aranabilir yapılandırmanıza android:searchSuggestIntentAction özelliğini eklemezseniz her öneri için SUGGEST_COLUMN_INTENT_ACTION sütununa bir değer eklemeniz gerekir. Aksi takdirde amaç başarısız olur.

Amaca yönelik verileri beyan etme

Kullanıcı bir öneri seçtiğinde, aranabilir etkinliğiniz önceki bölümde açıklandığı gibi tanımladığınız işlemle birlikte niyet alır. Ancak etkinliğinizin hangi önerinin seçildiğini belirleyebilmesi için niyetin veri de taşıması gerekir. Özellikle veriler, her öneri için benzersiz bir şey olmalıdır. Örneğin, SQLite tablonuzdaki önerinin satır kimliği gibi. Amaç alındığında, ekli verileri getData() veya getDataString() ile alabilirsiniz.

Amaca dahil edilen verileri iki şekilde tanımlayabilirsiniz:

• Öneri tablonuzun SUGGEST_COLUMN_INTENT_DATA sütununda her öneri için verileri tanımlayın.

  SUGGEST_COLUMN_INTENT_DATA sütununu ekleyip her satır için benzersiz verilerle doldurarak öneriler tablosundaki her amaç için gerekli tüm veri bilgilerini sağlayın. Bu sütundaki veriler, bu sütunda tanımladığınız şekilde tam olarak amaca eklenir. Daha sonra getData() veya getDataString() ile geri alabilirsiniz.

  İpucu: Tablonun satır kimliği her zaman benzersiz olduğundan, genellikle amaç verileri olarak kullanmak daha kolaydır. Bunu yapmanın en kolay yolu, SUGGEST_COLUMN_INTENT_DATA sütun adını satır kimliği sütunu için takma ad olarak kullanmaktır.
• Bir veri URI'sini iki parçaya ayırın: tüm önerilerde ortak olan kısım ve her öneriye özgü olan kısım. Bu parçaları, arama yapılabilir yapılandırmanın android:searchSuggestintentData özelliğine ve öneri tablonuzun SUGGEST_COLUMN_INTENT_DATA_ID sütununa yerleştirin.

  Aşağıdaki örnekte, aranabilir yapılandırmanızın android:searchSuggestIntentData özelliğindeki tüm öneriler için ortak olan URI parçasının nasıl bildirileceği gösterilmektedir:

    <?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"
        android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
        android:searchSuggestIntentAction="android.intent.action.VIEW"
        android:searchSuggestIntentData="content://com.example/datatable" >
    </searchable>
    

  Her önerinin son yolu (benzersiz kısım) öneriler tablonuzun SUGGEST_COLUMN_INTENT_DATA_ID sütununa ekleyin. Kullanıcı bir öneri seçtiğinde sistem, android:searchSuggestIntentData öğesinden dizeyi alır, eğik çizgi (/) ekler ve ardından SUGGEST_COLUMN_INTENT_DATA_ID sütunundaki ilgili değeri ekleyerek tam bir içerik URI'si oluşturur. Daha sonra Uri ile getData() kullanarak geri alabilirsiniz.

Daha fazla veri ekleme

Amacınızla ilgili daha fazla bilgi ifade etmeniz gerekiyorsa öneri hakkında ek bilgiler depolayabilecek SUGGEST_COLUMN_INTENT_EXTRA_DATA gibi başka bir tablo sütunu ekleyebilirsiniz. Bu sütuna kaydedilen veriler, amacın ek paketinin EXTRA_DATA_KEY bölümüne yerleştirilir.

Niyeti ele alma

Özel amaçlarla özel arama önerileri sağladıktan sonra, kullanıcının bir öneri seçtiğinde bu amaçları işlemek için aranabilir etkinliğinizin olması gerekir. Bu, aranabilir etkinliğinizin zaten yaptığı ACTION_SEARCH amacı ele almaya ek olarak yapılır. Etkinliğinizin onCreate() geri çağırma işlemi sırasında amaçları nasıl işleyebileceğinize dair bir örnek aşağıda verilmiştir:

Kotlin

when(intent.action) {
    Intent.ACTION_SEARCH -> {
        // Handle the normal search query case.
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            doSearch(query)
        }
    }
    Intent.ACTION_VIEW -> {
        // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
        showResult(intent.data)
    }
}

Java

Intent intent = getIntent();
if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
    // Handle the normal search query case.
    String query = intent.getStringExtra(SearchManager.QUERY);
    doSearch(query);
} else if (Intent.ACTION_VIEW.equals(intent.getAction())) {
    // Handle a suggestions click, because the suggestions all use ACTION_VIEW.
    Uri data = intent.getData();
    showResult(data);
}

Bu örnekte, amaç işlemi ACTION_VIEW ve veriler, android:searchSuggestIntentData dizesi ve SUGGEST_COLUMN_INTENT_DATA_ID sütunu tarafından sentezlenen, önerilen öğeyi işaret eden tam bir URI içeriyor. Ardından URI, içerik sağlayıcıya URI ile belirtilen öğe için sorgu gönderen yerel showResult() yöntemine iletilir.

Not: android:searchSuggestIntentAction özelliği veya SUGGEST_COLUMN_INTENT_ACTION sütunuyla tanımladığınız intent işlemi için Android manifest dosyanıza intent filtresi eklemeniz gerekmez. Sistem, önerinin amacını gerçekleştirmek için aranabilir etkinliğinizi ada göre açar. Bu nedenle, etkinliğin kabul edilen işlemi bildirmesi gerekmez.

Sorgu metnini yeniden yazma

Kullanıcı, öneri listesinde iz topu veya D-pad gibi yön kontrollerini kullanarak gezindiğinde sorgu metni varsayılan olarak güncellenmez. Ancak kullanıcının sorgu metnini, odaklanılan öneriyle eşleşen bir sorguyla metin kutusunda göründüğü şekilde geçici olarak yeniden yazabilirsiniz. Bu sayede kullanıcı, önerilen sorguyu görebilir, arama kutusunu seçebilir ve sorguyu arama olarak göndermeden önce düzenleyebilir.

Sorgu metnini aşağıdaki şekillerde yeniden yazabilirsiniz:

• android:searchMode özelliğini, "queryRewriteFromText" değeriyle birlikte aranabilir yapılandırmanıza ekleyin. Bu durumda, sorgu metnini yeniden yazmak için önerinin SUGGEST_COLUMN_TEXT_1 sütunundaki içerik kullanılır.
• android:searchMode özelliğini, aranabilir yapılandırmanıza "queryRewriteFromData" değeriyle birlikte ekleyin. Bu durumda, sorgu metnini yeniden yazmak için önerinin SUGGEST_COLUMN_INTENT_DATA sütunundaki içerik kullanılır. Bu işlevi yalnızca kullanıcı tarafından görülebilmesi amaçlanan URI'ler veya diğer veri biçimleriyle (ör. HTTP URL'leri) kullanın. Sorguyu bu şekilde yeniden yazmak için dahili URI şemalarını kullanmayın.
• Öneri tablonuzun SUGGEST_COLUMN_QUERY sütununda benzersiz bir sorgu metni dizesi sağlayın. Bu sütun mevcutsa ve geçerli öneri için bir değer içeriyorsa sorgu metnini yeniden yazmak ve önceki uygulamalardan birini geçersiz kılmak için kullanılır.

Arama önerilerini Hızlı Arama Kutusu'nda gösterme

Uygulamanızı özel arama önerileri sunacak şekilde yapılandırdıktan sonra, bu önerileri dünya genelinde erişilebilen Hızlı Arama Kutusu'nda kullanıma sunmak için aranabilir yapılandırmanızı android:includeInGlobalSearch değerini "true" içerecek şekilde değiştirmeniz yeterlidir.

Ek çalışma yapılması gereken tek senaryo, içerik sağlayıcınızın okuma izni istemesidir. Bu durumda, sağlayıcının içerik sağlayıcınıza Hızlı Arama Kutusu okuma erişimi vermesi için aşağıdaki örnekte gösterildiği gibi bir <path-permission> öğesi eklemeniz gerekir:

<provider android:name="MySuggestionProvider"
          android:authorities="com.example.MyCustomSuggestionProvider"
          android:readPermission="com.example.provider.READ_MY_DATA"
          android:writePermission="com.example.provider.WRITE_MY_DATA">
  <path-permission android:pathPrefix="/search_suggest_query"
                   android:readPermission="android.permission.GLOBAL_SEARCH" />
</provider>

Bu örnekte, sağlayıcı içeriğe okuma ve yazma erişimini kısıtlıyor. <path-permission> öğesi, "android.permission.GLOBAL_SEARCH" izni olduğunda "/search_suggest_query" yol önekindeki içeriğe okuma erişimi vererek kısıtlamayı değiştirir. Bu işlem, içerik sağlayıcınıza öneri sorgusu gönderebilmesi için Hızlı Arama Kutusu'na erişim izni verir.

İçerik sağlayıcınız okuma izinlerini zorunlu kılmıyorsa Hızlı Arama Kutusu bu izni varsayılan olarak okur.

Cihazda önerileri etkinleştirme

Uygulamalar, bu şekilde yapılandırılmış olsalar bile varsayılan olarak Hızlı Arama Kutusunda öneri sunmak üzere etkinleştirilmez. Kullanıcı, Ayarlar > Arama'da bulunan Aranabilir öğeler'i açıp uygulamanızı aranabilir öğe olarak etkinleştirerek uygulamanızdaki önerileri Hızlı Arama Kutusuna dahil edip etmeyeceğini seçer.

Hızlı Arama Kutusunda kullanılabilen her uygulamanın Aranabilir öğeler ayarları sayfasında bir girişi vardır. Girişte uygulamanın adı, uygulamada hangi içeriklerin aranabileceği ve Hızlı Arama Kutusunda öneri olarak sunulabileceği ile ilgili kısa bir açıklama yer alır. Aranabilir uygulamanızın açıklama metnini tanımlamak için aşağıdaki örnekte gösterildiği gibi aranabilir yapılandırmanıza android:searchSettingsDescription özelliğini ekleyin:

<?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"
    android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/search_description" >
</searchable>

android:searchSettingsDescription dizesini olabildiğince kısa tutun ve aranabilir içeriği belirtin. Örneğin, müzik uygulaması için "Sanatçılar, albümler ve parçalar" veya not defteri uygulaması için "Kayıtlı notlar". Kullanıcının ne tür öneriler sunulduğunu bilmesi için bu açıklamanın sağlanması önemlidir. android:includeInGlobalSearch doğru olduğunda bu özelliği her zaman ekleyin.

Kullanıcının, uygulamanızda arama önerilerini etkinleştirmek için ayarlar menüsünü ziyaret etmesi gerektiğinden, arama uygulamanızın önemli bir yönüyse bunu kullanıcılarınıza nasıl ileteceğinizi düşünün. Örneğin, bir kullanıcı uygulamayı ilk kez başlattığında Hızlı Arama Kutusu için arama önerilerinin nasıl etkinleştirileceğini açıklayan bir not gösterebilirsiniz.

Hızlı Arama Kutusu önerisi kısayollarını yönetme

Kullanıcının Hızlı Arama Kutusundan seçtiği öneriler otomatik olarak kısayola dönüştürülebilir. Bunlar, sistemin içerik sağlayıcınızdan kopyaladığı önerilerdir. Böylece sistem, içerik sağlayıcınıza yeniden sorgu göndermeden öneriye hızlıca erişebilir.

Bu özellik, varsayılan olarak Hızlı Arama Kutusu tarafından alınan tüm öneriler için etkindir. Ancak öneri verileriniz zaman içinde değişirse kısayolların yenilenmesini isteyebilirsiniz. Örneğin, önerileriniz bir kişinin müsaitlik durumu gibi dinamik verilerle ilgiliyse öneri kısayollarının kullanıcıya gösterilirken yenilenmesini isteyin. Bunu yapmak için öneri tablonuza SUGGEST_COLUMN_SHORTCUT_ID simgesini ekleyin. Bu sütunu kullanarak her önerinin kısayol davranışını aşağıdaki yöntemlerden biriyle yapılandırabilirsiniz:

• Hızlı Arama Kutusu'nun, öneri kısayolunun yeni bir sürümü için içerik sağlayıcınıza yeniden sorgu göndermesini sağlayın.

  Kısayol her görüntülendiğinde önerinin yeni bir sürüm için yeniden sorgulanması amacıyla SUGGEST_COLUMN_SHORTCUT_ID sütununa bir değer girin. Yenileme sorgusu döndürülene kadar kısayol, en son kullanılabilir verilerle hızlıca görüntülenir. Bu noktada, öneri yeni bilgilerle yenilenir. Yenileme sorgusu, SUGGEST_URI_PATH_QUERY yerine SUGGEST_URI_PATH_SHORTCUT URI yoluyla içerik sağlayıcınıza gönderilir.

  Döndürdüğünüz Cursor, orijinal öneriyle aynı sütunları kullanan bir öneri içermeli veya kısayolun artık geçerli olmadığını belirten boş bir yanıt olmalıdır. Bu durumda, öneri kaybolur ve kısayol kaldırılır.

  Bir öneri, ağ tabanlı yenileme gibi yenilenmesi daha uzun sürebilecek verilerle ilgiliyse yenileme tamamlanana kadar sağdaki simge için ilerleme çarkı göstermek üzere SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING sütununu öneri tablonuza "true" değeriyle de ekleyebilirsiniz. Doğru değeri dışındaki tüm değerler ilerleme çarkını göstermez.

• Önerinin kısayola kopyalanmasını tamamen engelleme

  SUGGEST_COLUMN_SHORTCUT_ID sütununda SUGGEST_NEVER_MAKE_SHORTCUT değerini sağlayın. Bu durumda, öneri hiçbir zaman kısayola kopyalanmaz. Bu işlem yalnızca daha önce kopyalanan önerinin kesinlikle görünmesini istemiyorsanız gereklidir. Sütun için normal bir değer sağlarsanız öneri kısayolu yalnızca yenileme sorgusu döndürülene kadar görünür.

• Varsayılan kısayol davranışının uygulanmasına izin verin.

  Değişmeyen ve kısayol olarak kaydedilebilen her öneri için SUGGEST_COLUMN_SHORTCUT_ID boş bırakın.

Önerileriniz hiç değişmiyorsa SUGGEST_COLUMN_SHORTCUT_ID sütununa ihtiyacınız yoktur.

Not: Hızlı Arama Kutusu, bu değerleri uygulamanızdan gelen güçlü bir istek olarak değerlendirerek bir öneri için kısayol oluşturup oluşturmayacağına nihai olarak karar verir. Öneri kısayollarınız için istediğiniz davranışın yerine getirileceği garanti edilmez.

Hızlı Arama Kutusu öneri sıralaması hakkında

Uygulamanızın arama önerilerini Hızlı Arama Kutusu'nda kullanılabilir hale getirdiğinizde, Hızlı Arama Kutusu sıralaması, önerilerin belirli bir sorgu için kullanıcıya nasıl gösterileceğini belirler. Bu durum, söz konusu sorgu için kaç uygulamanın sonuç gösterdiğine ve kullanıcının sonuçlarınızı diğer uygulamaların sonuçlarına kıyasla ne sıklıkta seçtiğine bağlı olabilir. Önerilerinizin nasıl sıralandığı veya uygulamanızın önerilerinin belirli bir sorgu için gösterilip gösterilmediği konusunda garanti verilmez. Genel olarak, kaliteli sonuçlar sunmak uygulamanızın önerilerinin belirgin bir konumda gösterilme olasılığını artırır. Düşük kaliteli öneriler sunan uygulamaların ise daha düşük sıralanma veya hiç gösterilmeme olasılığı daha yüksektir.