Arama yapılandırması

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 sisteminin yardımıyla arama uygulamak (yani arama sorgularını bir etkinliğe iletmek ve arama önerileri sağlamak) için uygulamanız XML dosyası biçiminde bir arama yapılandırması sağlamalıdır.

Bu sayfada, arama yapılandırma dosyası söz dizimi ve kullanımı açısından açıklanmaktadır. Uygulamanızda arama özelliklerini uygulama hakkında daha fazla bilgi için Arama arayüzü oluşturma başlıklı makaleyi inceleyin.

Dosya konumu:
res/xml/filename.xml
Android, dosya adını kaynak kimliği olarak kullanır.
söz dizimi:
<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>
öğeler:
<searchable>
Android sistemi tarafından destekli arama sağlamak için kullanılan tüm arama yapılandırmalarını tanımlar.

Özellikler:

android:label
Dize kaynağı. (Zorunlu.) Uygulamanızın adı. <activity> veya <application> manifest öğenizin android:label özelliğine uygulanan adla aynı olmalıdır. Bu etiket, yalnızca android:includeInGlobalSearch değerini "true" olarak ayarladığınızda kullanıcı tarafından görülebilir. Bu durumda, uygulamanızı sistemin arama ayarlarında aranabilir bir öğe olarak tanımlamak için bu etiket kullanılır.
android:hint
Dize kaynağı. (Önerilir.) Metin girilmediğinde arama metni alanında gösterilecek metin. Kullanıcıya hangi içeriğin aranabilir olduğu hakkında ipucu verir. Diğer Android uygulamalarıyla tutarlılık sağlamak için android:hint dizesini "Search <content-or-product>" olarak biçimlendirin. Örneğin, "Şarkı ve sanatçı ara" veya "YouTube'da ara".
android:searchMode
Anahtar kelime. Arama sunumunu kontrol eden ek modları ayarlar. Kullanılabilir modlar, özel bir öneri odaklandığında sorgu metninin nasıl yeniden yazılması gerektiğini tanımlar. Aşağıdaki mod değerleri kabul edilir:
DeğerAçıklama
"queryRewriteFromData" Sorgu metnini yeniden yazmak için SUGGEST_COLUMN_INTENT_DATA sütunundaki değeri kullanın. Bu yalnızca SUGGEST_COLUMN_INTENT_DATA içindeki değerler kullanıcı incelemesi ve düzenlemesi için uygun olduğunda (ör. HTTP URI'leri) kullanılmalıdır.
"queryRewriteFromText" Sorgu metnini yeniden yazmak için SUGGEST_COLUMN_TEXT_1 sütunundaki değeri kullanın.

Daha fazla bilgi için Özel arama önerileri ekleme başlıklı makalede sorgu metnini yeniden yazma ile ilgili dokümanı inceleyin.

android:searchButtonText
Dize kaynağı. Aramayı yürüten düğmede gösterilecek metin. Düğmede varsayılan olarak arama simgesi (büyüteç) gösterilir. Bu, uluslararasılaştırma için idealdir. Bu nedenle, davranış bir arama dışında bir şey (ör. web tarayıcısında URL isteği) olmadığı sürece bu özelliği düğmeyi değiştirmek için kullanmayın.
android:inputType
Anahtar kelime. Kullanılacak giriş yöntemi türünü (ör. sanal klavye türü) tanımlar. Serbest biçimli metnin beklendiği çoğu arama için bu özellik gerekli değildir. Bu özellik için uygun değerlerin listesini inputType bölümünde bulabilirsiniz.
android:imeOptions
Anahtar kelime. Giriş yöntemi için ek seçenekler sunar. Serbest biçimli metnin beklendiği çoğu arama için bu özellik gerekli değildir. Varsayılan IME, actionSearch'dır. Bu IME, sanal klavyede satır başı yerine "arama" düğmesini sağlar. Bu özellik için uygun değerlerin listesini imeOptions bölümünde bulabilirsiniz.

Arama önerisi özellikleri

Arama önerileri oluşturmak için bir içerik sağlayıcı tanımlarsanız içerik sağlayıcıyla iletişimi yapılandıran ek özellikler tanımlamanız gerekir. Arama önerileri sağlarken aşağıdaki <searchable> özelliklerden bazılarını kullanmanız gerekir:


android:searchSuggestAuthority
Dize. (Arama önerileri sağlamak için gereklidir.) Bu değer, Android manifest <provider> öğesinin android:authorities özelliğinde sağlanan yetkili dizeyle eşleşmelidir.
android:searchSuggestPath
Dize. Bu yol, öneriler sorgusunun bir bölümü olarak, önek ve yetkiden sonra, standart öneriler yolundan önce kullanılır.Uri Bu yalnızca, farklı veri türleri gibi farklı öneri türleri sunan tek bir içerik sağlayıcınız varsa ve öneri sorgularını aldığınızda netleştirmenin bir yolunu arıyorsanız gereklidir.
android:searchSuggestSelection
Dize. Bu değer, sorgu işlevinize selection parametresi olarak iletilir. Bu genellikle veritabanınız için bir WHERE ifadesidir ve kullanıcı tarafından girilen gerçek sorgu dizesi için yer tutucu olarak tek bir soru işareti içermelidir (örneğin, "query=?"). Ancak, selectionArgs parametresini kullanarak sorgu metninin yayınlanmasını tetiklemek için boş olmayan herhangi bir değeri kullanabilir ve ardından selection parametresini yok sayabilirsiniz.
android:searchSuggestIntentAction
Dize. Kullanıcı özel bir arama önerisine (ör. "android.intent.action.VIEW") dokunduğunda kullanılacak varsayılan amaç işlemi. Bu değer, SUGGEST_COLUMN_INTENT_ACTION sütunu kullanılarak seçilen öneriyle geçersiz kılınmazsa kullanıcı bir öneriye dokunduğunda değer, Intent öğesinin işlem alanına yerleştirilir.
android:searchSuggestIntentData
Dize. Kullanıcı özel bir arama önerisine dokunduğunda kullanılacak varsayılan amaç verileri. Seçilen öneri tarafından SUGGEST_COLUMN_INTENT_DATA sütunu aracılığıyla geçersiz kılınmazsa bu değer, kullanıcı bir öneriye dokunduğunda Intent veri alanına yerleştirilir.
android:searchSuggestThreshold
Tamsayı. Öneri aramasının tetiklenmesi için gereken minimum karakter sayısı. Bu yalnızca sistemin, eşikten daha kısa olan hiçbir şey için içerik sağlayıcınıza sorgu göndermeyeceğini garanti eder. Varsayılan değer 0'dır.

Arama önerileri için yukarıdaki özellikler hakkında daha fazla bilgi edinmek üzere özel arama önerileri ekleme ve özel öneriler ekleme ile ilgili dokümanları inceleyin.

Hızlı Arama Kutusu özellikleri

Özel arama önerilerinizi Hızlı Arama Kutusu'nda kullanılabilir hale getirmek için aşağıdaki <searchable> özelliklerden bazılarına ihtiyacınız vardır:


android:includeInGlobalSearch
Boole. (Hızlı arama kutusunda arama önerileri sağlamak için gereklidir.) Önerilerinizin, herkesin erişebileceği Hızlı Arama Kutusuna dahil edilmesini istiyorsanız "true" olarak ayarlayın. Önerilerinizin Hızlı Arama Kutusunda görünmesi için kullanıcının sistem arama ayarlarında uygulamanızı aranabilir bir öğe olarak etkinleştirmesi gerekir.
android:searchSettingsDescription
Dize kaynağı. Uygulamanızın aranabilir öğeler girişinde gösterilen Hızlı Arama Kutusu'na sağladığınız arama önerilerinin kısa bir açıklamasını sunar. Açıklamanız, aranabilir içeriği kısa ve öz bir şekilde açıklamalıdır. Örneğin, müzik uygulaması için "Sanatçılar, albümler ve parçalar", not defteri uygulaması için "Kayıtlı notlar".
android:queryAfterZeroResults
Boole. Daha önce sıfır sonuç döndüren sorguların üst kümeleri için içerik sağlayıcınızın çağrılmasını istiyorsanız "true" olarak ayarlayın. Örneğin, içerik sağlayıcınız "bo" için sıfır sonuç döndürüyorsa "bob" için yeniden sorgulanması gerekir. "false" olarak ayarlanırsa tek bir oturum için üst kümeler yoksayılır. Örneğin, "bob" yeniden sorgulama işlemini tetiklemez. Bu yalnızca arama iletişim kutusu veya arama widget'ı kullanılırken etkinliğin süresi boyunca geçerlidir. Arama iletişim kutusu veya etkinliği yeniden açıldığında "bo" içerik sağlayıcınıza tekrar sorgu gönderir. False varsayılan değerdir.

Sesli arama özellikleri

Sesli aramayı etkinleştirmek için aşağıdaki <searchable> özelliklerden bazılarına ihtiyacınız vardır:


android:voiceSearchMode
Anahtar kelime. (Sesli arama özelliklerinin sağlanması için gereklidir.) Sesli arama özelliğini etkinleştirir. Sesli arama için özel bir mod vardır. Sesli arama cihaz tarafından sağlanmıyor olabilir. Bu durumda bu işaretlerin etkisi olmaz. Aşağıdaki mod değerleri kabul edilir:
DeğerAçıklama
"showVoiceSearchButton" Cihazda sesli arama özelliği varsa sesli arama düğmesini gösterin. Ayarlanırsa "launchWebSearch" veya "launchRecognizer" da ayarlanmalı ve dikey çizgi (|) karakteriyle ayrılmalıdır.
"launchWebSearch" Sesli arama düğmesi, kullanıcıyı doğrudan yerleşik bir sesli web arama etkinliğine yönlendirir. Çoğu uygulama, kullanıcının aramanın başlatıldığı etkinlikten uzaklaşmasına neden olduğundan bu işareti kullanmaz.
"launchRecognizer" Sesli arama düğmesi, kullanıcıyı doğrudan yerleşik bir ses kaydı etkinliğine yönlendirir. Bu etkinlik, kullanıcının konuşmasını ister, konuşulan metni yazıya döker ve sonuçtaki sorgu metnini, kullanıcının arama kullanıcı arayüzüne yazıp arama düğmesine dokunmuş gibi aranabilir etkinliğe yönlendirir.
android:voiceLanguageModel
Anahtar kelime. Ses tanıma sistemi tarafından kullanılması gereken dil modeli. Aşağıdaki değerler kabul edilir:
DeğerAçıklama
"free_form" Sorguları dikte etmek için serbest biçimli konuşma tanıma özelliğini kullanın. Bu özellik öncelikli olarak İngilizce için optimize edilmiştir. Bu, varsayılan seçenektir.
"web_search" Daha kısa, arama benzeri ifadeler için web arama terimi tanımayı kullanın. Bu özellik, "free_form"'dan daha fazla dilde kullanılabilir.

Daha fazla bilgi için EXTRA_LANGUAGE_MODEL sayfasına göz atın.

android:voicePromptText
Dize kaynağı. Ses girişi iletişim kutusunda gösterilecek ek mesaj.
android:voiceLanguage
Dize. Beklenen konuşma dili, Locale içindeki bir sabitin dize değeri olarak ifade edilir. Örneğin, Almanca için "de" veya Fransızca için "fr". Bu yalnızca Locale.getDefault() öğesinin mevcut değerinden farklıysa gereklidir.
android:voiceMaxResults
Tamsayı. "En iyi" sonuç da dahil olmak üzere döndürülecek maksimum sonuç sayısını ayarlar. Bu sonuç her zaman amacın ACTION_SEARCH birincil sorgusu olarak sağlanır. 1 veya daha fazla olmalıdır. Amacın sonuçlarını almak için EXTRA_RESULTS kullanın. Sağlanmazsa tanıyıcı, kaç sonuç döndürüleceğini seçer.
<actionkey>
Bir arama işlemi için cihaz anahtarını ve davranışını tanımlar. Arama işlemi, cihazdaki bir düğmeye dokunulduğunda geçerli sorguya veya odaklanılan öneriye göre özel bir davranış sağlar. Örneğin, Kişiler uygulaması, ARA düğmesine dokunulduğunda şu anda odaklanılan kişi önerisine telefon araması başlatmak için bir arama işlemi sağlar.

Tüm işlem tuşları her cihazda kullanılamaz ve tüm tuşlar bu şekilde geçersiz kılınamaz. Örneğin, "Ana Sayfa" tuşu geçersiz kılınamaz ve her zaman ana ekrana dönmelidir. Ayrıca, arama sorgusu yazmak için gereken bir tuş için işlem tuşu tanımlamadığınızdan emin olun. Bu, kullanılabilir ve makul işlem tuşlarını arama düğmesi ve menü düğmesiyle sınırlar.

Anahtarı tanımlamak için android:keycode, arama işlemini tanımlamak için ise diğer üç özellikten en az birini tanımlamanız gerekir.

Özellikler:

android:keycode
Dize. (Zorunlu.) Yanıt vermek istediğiniz işlem tuşunu (ör. "KEYCODE_CALL") temsil eden KeyEvent anahtar kodu. Bu, aranabilir etkinliğinize iletilen ACTION_SEARCH amacına eklenir. Anahtar kodunu incelemek için getIntExtra(SearchManager.ACTION_KEY) komutunu kullanın. Birçok tuş yazma, gezinme veya sistem işlevleri için kullanıldığından arama işlemi için tüm tuşlar desteklenmez.
android:queryActionMsg
Dize. Kullanıcı sorgu metni girerken işlem tuşuna basılırsa gönderilecek işlem mesajı. Bu, sistemin aranabilir etkinliğinize ilettiği ACTION_SEARCH amacıyla birlikte eklenir. Dizeyi incelemek için getStringExtra(SearchManager.ACTION_MSG) kullanın.
android:suggestActionMsg
Dize. Bir öneri odaktayken işlem tuşuna basılırsa gönderilecek işlem mesajı. Bu, sistemin, öneri için tanımladığınız işlemi kullanarak aranabilir etkinliğinize ilettiği amaca eklenir. Dizeyi incelemek için getStringExtra(SearchManager.ACTION_MSG) kullanın. Bu yalnızca tüm önerileriniz bu işlem anahtarını destekliyorsa kullanılmalıdır. Tüm öneriler aynı işlem anahtarını işleyemiyorsa bunun yerine aşağıdaki android:suggestActionMsgColumn özelliğini kullanmanız gerekir.
android:suggestActionMsgColumn
Dize. Kullanıcı bir öneri odaklanmış durumdayken işlem tuşuna bastığında gönderilecek olan bu işlem tuşu için işlem mesajını tanımlayan içerik sağlayıcınızdaki sütunun adı. Bu özellik, öneri bazında işlem anahtarını kontrol etmenize olanak tanır. Çünkü tüm öneriler için işlem mesajını tanımlamak üzere android:suggestActionMsg özelliği kullanılmak yerine, içerik sağlayıcınızdaki her giriş kendi işlem mesajını sağlar.

Öncelikle, her öneri için içerik sağlayıcınızda bir sütun tanımlamanız gerekir. Bu sütun, işlem mesajı sağlamak için kullanılır. Ardından, bu sütunun adını bu özellikte belirtin. Sistem, işlem mesajı sütununuzu seçmek için burada sağlanan dizeyi kullanarak öneri imlecinize bakar ve ardından imleçten işlem mesajı dizesini seçer. Bu dize, sistemin aranabilir etkinliğinize ilettiği amaca, öneriler için tanımladığınız işlem kullanılarak eklenir. Dizeyi incelemek için getStringExtra(SearchManager.ACTION_MSG) kullanın. Seçilen öneri için veri yoksa işlem anahtarı yoksayılır.

örnek:
XML dosyası res/xml/searchable.xml konumuna kaydedildi: 
<?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:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>