Arama yapılandırması

Compose yöntemini deneyin

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

Arama çubuğu →

Android sisteminin yardımıyla arama işlevini uygulamak (yani arama sorgularını bir etkinliğe iletmek ve arama önerileri sunmak) 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ğı. (Gerekli.) 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 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."true"

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 "<content-or-product> ara" 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ğer	Açı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, uluslararasılaştırma için ideal olan bir arama simgesi (büyüteç) gösterilir. 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 sayfasında 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

String. (Arama önerileri sağlamak için gereklidir.) Bu değer, Android manifest <provider> öğesinin android:authorities özelliğinde sağlanan yetkili dizesiyle eşleşmelidir.

android:searchSuggestPath

String. Bu yol, öneri sorgusunun bir bölümü olarak, önek ve yetkiden sonra, standart öneri 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

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

String. Kullanıcı özel bir arama önerisine (ör. "android.intent.action.VIEW") dokunduğunda kullanılacak varsayılan intent 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

String. Kullanıcı özel bir arama önerisine dokunduğunda kullanılacak varsayılan amaç verileri. Seçilen öneri tarafından geçersiz kılınmazsa (SUGGEST_COLUMN_INTENT_DATA sütunu aracılığıyla) bu değer, kullanıcı bir öneriye dokunduğunda Intent öğesinin 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 sunmak için gereklidir.) Önerilerinizin, herkesin erişebileceği Hızlı Arama Kutusu'na 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" veya 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 üst kümeler tek bir oturum için yoksayılır. "bob" yeniden sorgulama başlatmaz. 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. Varsayılan değer false'tur.

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ğer	Açı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. Kullanıcıyı aramanın başlatıldığı etkinlikten uzaklaştırdığı için çoğu uygulama 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ıdan konuşmasını ister, konuşulan metni yazıya döker ve sonuçtaki sorgu metnini, kullanıcı 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ğer	Açı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 bakın.

android:voicePromptText

Dize kaynağı. Ses girişi iletişim kutusunda gösterilecek ek mesaj.

android:voiceLanguage

String. 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 birincil sorgusu olarak sağlanır. ACTION_SEARCH 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>

Arama işlemi için cihaz anahtarını ve davranışını tanımlar. Arama işlemi, cihazdaki bir düğmeye dokunulduğunda mevcut 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

String. (Gerekli.) Yanıt vermek istediğiniz işlem tuşunu (ör. "KEYCODE_CALL") temsil eden KeyEvent tuş 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

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

String. Öneri odaklanmış durumdayken 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 intent'e eklenir. Dizeyi incelemek için getStringExtra(SearchManager.ACTION_MSG) kullanın. Bu yalnızca tüm önerileriniz bu eylem tuşunu destekliyorsa kullanılmalıdır. Tüm öneriler aynı eylem tuşunu işleyemiyorsa bunun yerine aşağıdaki android:suggestActionMsgColumn özelliğini kullanmanız gerekir.

android:suggestActionMsgColumn

String. 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 eylem tuşunu 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 ve bu sütunda bir işlem mesajı sağlamanız gerekir. 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 intent'e, ö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 eylem tuşu 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>