Arama yapılandırması

Android sisteminin yardımıyla arama özelliğini uygulamak (yani bir etkinliğe arama sorguları göndermek ve arama önerileri sağlamak) için uygulamanızın XML dosyası biçiminde bir arama yapılandırması sağlaması gerekir.

Bu sayfada, arama yapılandırma dosyası söz dizimi ve kullanım açısından açıklanmaktadır. Uygulamanız için arama özelliklerini nasıl uygulayacağınız hakkında daha fazla bilgi edinmek için Arama arayüzü oluşturma bölümüne bakın.

dosya konumu:
res/xml/filename.xml
Android, kaynak kimliği olarak dosya adını 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 sisteminin yardımlı arama sağlamak için kullandığı tüm arama yapılandırmalarını tanımlar.

Özellikler:

android:label
Dize kaynağı. (Zorunludur.) 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 öğesini "true" olarak ayarladığınızda kullanıcı tarafından görülebilir. Bu durumda, uygulamanızı sistemin arama ayarlarında aranabilir öğe olarak tanımlamak için bu etiket kullanılır.
android:hint
Dize kaynağı. (Önerilir.) Metin girilmediğinde arama metni alanında görüntülenecek metin. Kullanıcıya hangi içeriklerin aranabileceği 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 sunusunu kontrol eden ek modlar ayarlar. Kullanılabilir modlar, özel bir öneriye odaklanıldığı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 (HTTP URI'leri gibi) 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 yazmayla ilgili dokümanlara bakın.

android:searchButtonText
Dize kaynağı. Aramayı yürüten düğmede görüntülenecek metin. Bu düğmede uluslararasılaştırma için ideal olan arama simgesi (büyüteç) varsayılan olarak gösterilir. Bu nedenle, web tarayıcısındaki URL isteği gibi arama dışında bir davranış olmadığı sürece düğmeyi değiştirmek için bu özelliği kullanmayın.
android:inputType
Anahtar kelime. Kullanılacak giriş yönteminin türünü (ör. klavyenin türü) tanımlar. Serbest biçimli metin olması beklenen çoğu arama için bu özelliğe ihtiyacınız yoktur. Bu özelliğe uygun değerlerin listesi için inputType adresini ziyaret edin.
android:imeOptions
Anahtar kelime. Giriş yöntemi için ek seçenekler sağlar. Serbest biçimli metinlerin beklendiği çoğu arama için bu özelliğe ihtiyacınız yoktur. Varsayılan IME actionSearch, yazılım klavyesinde satır başı yerine "arama" düğmesi sağlar. Bu özelliğe uygun değerlerin listesi için imeOptions adresine bakın.

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> özelliklerinden bazılarına ihtiyacınız vardır:


android:searchSuggestAuthority
Dize. (Arama önerileri sağlayabilmek için gereklidir.) Bu değer, Android manifest <provider> öğesinin android:authorities özelliğinde sağlanan yetki dizesiyle eşleşmelidir.
android:searchSuggestPath
Dize. Bu yol, Uri öneri sorgusunun bir bölümü olarak, ön ek ve yetkiden sonra ve standart öneriler yolundan önce kullanılır. Bu, yalnızca farklı veri türleri için farklı türde öneriler (örneğin, farklı veri türleri için) veren tek bir içerik sağlayıcınız varsa ve öneri sorgularını aldığınızda bunları netleştirmek için bir yönteme ihtiyacınız varsa gereklidir.
android:searchSuggestSelection
Dize. Bu değer, sorgu işlevinize selection parametresi olarak aktarılır. Genellikle bu, 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=?"). Bununla birlikte, selectionArgs parametresini kullanarak sorgu metninin yayınlanmasını tetiklemek için null olmayan herhangi bir değer kullanabilir ve ardından selection parametresini yoksayabilirsiniz.
android:searchSuggestIntentAction
Dize. Kullanıcı, "android.intent.action.VIEW" gibi özel bir arama önerisine dokunduğunda kullanılacak varsayılan intent işlemi. Bu değer, seçilen öneri tarafından SUGGEST_COLUMN_INTENT_ACTION sütunu kullanılarak 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 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ı tetiklemek için gereken minimum karakter sayısı. Bu yalnızca sistemin, içerik sağlayıcınızı eşikten daha düşük bir değer için sorgulamamasını garanti eder. Varsayılan değer 0'dır.

Arama önerileriyle ilgili yukarıdaki özellikler hakkında daha fazla bilgi için özel arama önerileri ekleme ve özel öneriler ekleme dokümanlarına bakın.

Çabuk Arama Kutusu özellikleri

Özel arama önerilerinizin Hızlı Arama Kutusu'nda kullanılabilmesi için aşağıdaki <searchable> özelliklerinden bazılarına ihtiyacınız vardır:


android:includeInGlobalSearch
Boole. (Hızlı Arama Kutusu'nda arama önerileri sağlamak için gereklidir.) Önerilerinizin tüm dünyada erişilebilen Hızlı Arama Kutusu'na dahil edilmesini istiyorsanız "true" olarak ayarlayın. Önerilerinizin Hızlı Arama Kutusu'nda görünmesi için kullanıcının yine de uygulamanızı sistem arama ayarlarında aranabilir öğe olarak etkinleştirmesi gerekir.
android:searchSettingsDescription
Dize kaynağı. Hızlı Arama Kutusu'na sağladığınız arama önerilerinin kısa bir açıklamasını sağlar ve uygulamanızın aranabilir öğeler girişinde görüntülenir. Açıklamanız, aranabilir içeriği kısa ve öz bir şekilde açıklamalıdır. Örneğin, bir müzik uygulaması için "Sanatçılar, albümler ve parçalar", not defteri uygulaması için "Kayıtlı notlar".
android:queryAfterZeroResults
Boole. İçerik sağlayıcınızın, daha önce sıfır sonuç döndürmeyen sorguların üst kümeleri için ç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ürse "bob" için tekrar sorgulanması gerekir. "false" olarak ayarlanırsa üst kümeler tek bir oturum için yoksayılır. "Ali", yeniden sorgu çağırmaz. Bu durum, yalnızca arama iletişim kutusunun veya arama widget'ının kullanıldığı etkinliğin ömrü boyunca geçerlidir. Arama iletişim kutusu veya etkinlik yeniden açıldığında "bo", içerik sağlayıcınızı tekrar sorgular. False varsayılan değerdir.

Sesli arama özellikleri

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


android:voiceSearchMode
Anahtar kelime. (Sesli arama özelliklerini sağlamak için gereklidir.) Belirli bir sesli arama moduyla sesli aramayı etkinleştirir. Cihaz, sesli arama özelliğini sağlamayabilir. Bu durumda, bu işaretlerin herhangi bir etkisi olmaz. Aşağıdaki mod değerleri kabul edilir:
DeğerAçıklama
"showVoiceSearchButton" Cihazda sesli arama kullanılabiliyorsa bir sesli arama düğmesi görüntüleyin. Ayarlanırsa dikey çizgi (|) karakteriyle ayrılmış "launchWebSearch" veya "launchRecognizer" de ayarlanmalıdır.
"launchWebSearch" Sesli arama düğmesi, kullanıcıyı doğrudan yerleşik sesli web araması etkinliğine yönlendirir. Çoğu uygulama, kullanıcıyı aramanın başlatıldığı etkinlikten uzaklaştırdığı için 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, söylenen metni metne dönüştürür ve sonuçta ortaya çıkan sorgu metnini, kullanıcının arama kullanıcı arayüzüne girip arama düğmesine dokunduğu 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 öncelikle İngilizce için optimize edilmiştir. Bu varsayılan seçenektir.
"web_search" Aramaya benzeyen daha kısa ifadeler için web araması terimi tanımayı kullanın. Bu özellik, "free_form" dilinden daha fazla dilde kullanılabilir.

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

android:voicePromptText
Dize kaynağı. Ses girişi iletişim kutusunda gösterilecek ek bir mesaj.
android:voiceLanguage
Dize. Locale dilindeki bir sabit değerin dize değeri olarak ifade edilen beklenen konuşma dili. Örneğin, Almanca için "de" veya Fransızca için "fr". Bu, yalnızca mevcut Locale.getDefault() değerinden farklıysa gereklidir.
android:voiceMaxResults
Tamsayı. Her zaman ACTION_SEARCH amacının birincil sorgusu olarak sağlanan "en iyi" sonuç dahil olmak üzere döndürülecek maksimum sonuç sayısını belirler. 1 veya daha büyük olmalıdır. Amaçtan sonuçları almak için EXTRA_RESULTS kullanın. Değer sağlanmazsa tanıyıcı kaç sonuç döndürüleceğini seçer.
<actionkey>
Arama işlemi için cihaz tuşunu ve çalışma biçimini tanımlar. Bir arama işlemi, cihazdaki bir düğmeye dokunduğunuzda geçerli sorguya veya odaklanılan öneriye göre özel bir davranış sağlar. Örneğin, Kişiler uygulaması, ARA düğmesine dokunulduğunda, o sırada odaklanılmış kişi önerisine bir telefon araması başlatmak için bir arama işlemi sağlar.

Tüm işlem anahtarları her cihazda kullanılamaz ve tüm anahtarlar 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 tuşa yönelik bir işlem tuşu tanımlamadığınızdan emin olun. Bu, arama düğmesi ve menü düğmesi için kullanılabilir ve makul işlem tuşlarını sınırlandırır.

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

Özellikler:

android:keycode
Dize. (Zorunludur.) Yanıtlamak istediğiniz işlem anahtarını temsil eden KeyEvent anahtar kodu (örneğin, "KEYCODE_CALL"). Bu veri, aranabilir etkinliğinize aktarılan ACTION_SEARCH amacına eklenir. Anahtar kodunu incelemek için getIntExtra(SearchManager.ACTION_KEY) kullanın. Çoğu tuş yazma, gezinme veya sistem işlevleri için kullanıldığından tüm tuşlar desteklenmez.
android:queryActionMsg
Dize. Kullanıcı sorgu metnini girerken işlem tuşuna basılırsa gönderilecek bir işlem mesajı. Bu veri, sistemin aranabilir etkinliğinize gönderdiği ACTION_SEARCH amacına 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 bir işlem mesajı. Bu değer, sistemin öneri için tanımladığınız işlem kullanılarak aranabilir etkinliğinize gönderdiği amaca eklenir. Dizeyi incelemek için getStringExtra(SearchManager.ACTION_MSG) işlevini 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 aşağıdaki android:suggestActionMsgColumn özelliğini kullanmanız gerekir.
android:suggestActionMsgColumn
Dize. İçerik sağlayıcınızda bu işlem tuşu için işlem mesajını tanımlayan ve öneri odaklanıldığında kullanıcı işlem tuşuna bastığında gönderilecek olan sütunun adı. Bu özellik, işlem anahtarını öneri bazında kontrol etmenizi sağlar. Bunun nedeni, tüm öneriler için işlem mesajını tanımlamak üzere android:suggestActionMsg özelliğini kullanmak yerine içerik sağlayıcınızdaki her girişin kendi işlem mesajını sağlamasıdır.

Öncelikle, içerik sağlayıcınızda her öneri için bir işlem mesajı sağlamak üzere bir sütun tanımlamanız ve ardından bu özellikte ilgili sütunun adını girmeniz gerekir. Sistem, burada sağlanan dizeyi kullanarak işlem mesajı sütununuzu seçmek için öneri imlecinizi inceler ve ardından imleçten işlem mesajı dizesini seçer. Bu dize, öneriler için tanımladığınız işlem kullanılarak sistemin aranabilir etkinliğinize gönderdiği amaca 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>