Searchable Configuration
譯者署名：呆呆大蝦
譯者鏈接：
版本：Android 4.0 r1
參閱
爲了能在Android系統的輔助下（發送搜索請求到activity並提供搜索建議項）實現搜索功能，應用程序必須提供一個XML格式的搜索配置文件。
本文描述了搜索配置文件的語法和使用方式。關於應用程序如何實現搜索特性的詳細信息，在開發者指南的 創建搜索界面 中進行描述。
文件位置：
res/xml/filename.xml
Android用文件名作爲資源ID。
語法：
<?xml version="1.0" encoding="utf-8"?>
<searchablexmlns: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"
>
android:keycode="KEYCODE"
android:queryActionMsg="string"
android:suggestActionMsg="string"
android:suggestActionMsgColumn="string">
</searchable>
元素：
<searchable>
定義了Android系統爲了支持搜索所需的全部搜索配置信息。
屬性：
android:label
字符串資源。（必填項。）應用程序的名稱。應該是與<activity> 或manifest中<application>元素的android:label屬性相一致。僅當android:includeInGlobalSearch設爲“true”時，用戶才能看見本文本標籤。這時標籤用於標識本應用程序，並作爲可搜索項顯示在系統的搜索設置菜單中。
android:hint
字符串資源。（建議項。）在沒有錄入文字時，顯示在搜索文本框中的文本。它向用戶提示了可搜索的內容。爲了與其它Android 應用保持一致，應該把android:hint定義的文本寫成“搜索<內容-或-產品>”的格式。例如，“搜索歌曲和藝術家”或“搜索YouTube”。
android:searchMode
關鍵字。設置控制搜索顯示的其它模式。目前可用的模式定義了自定義建議項獲得焦點時搜索文本的改寫方式。以下列出了可用的模式：
|
值 |
描述 |
|
"queryRewriteFromText" |
用SUGGEST_COLUMN_TEXT_1列中的值改寫查詢請求文本。 |
|
"queryRewriteFromData" |
用SUGGEST_COLUMN_INTENT_DATA列中的值改寫查詢請求文本。僅當SUGGEST_COLUMN_INTENT_DATA中的值符合用戶的要求並開始編輯時纔會用到，典型的場合是HTTP URI 。 |
詳情請參閱添加自定義建議項中關於改寫請求文本的部分。
android:searchButtonText
字符串資源。顯示在執行搜索按鈕上的文本。默認情況下，按鈕上會顯示一個搜索圖標（放大鏡），這是理想的國際化方案。除非某些時候不是要執行搜索操作（比如Web瀏覽器中的URL請求），否則不應該使用本屬性來改變按鈕的顯示。
android:inputType
關鍵字。定義了要使用的錄入方式（比如軟鍵盤）。大多數搜索都需要能錄入任意字符，也就不必用到本屬性。本屬性可用值的清單請參閱inputType。
android:imeOptions
關鍵字。提供錄入方式的其它選項。大多數搜索都需要能錄入任意字符，也就不必用到本屬性。缺省的IME 是“actionSearch”（在軟鍵盤上提供“搜索”按鈕並取代回車）。本屬性可用值的清單請參閱imeOptions。
搜索建議項的屬性
如果定義了content provider來提供搜索建議項，則需要定義更多的屬性來對content provider的交互進行配置。當提供自定義建議項時，需要以下<searchable>屬性：
android:searchSuggestAuthority
字符串。（提供搜索建議項時需要。）本屬性值必須符合Android manifest文件中<provider>元素的android:authorities屬性所提供的權限。
android:searchSuggestPath
字符串。該路徑用作建議項請求Uri的組成部分，位於前綴和權限之後，但在標準建議項路徑之前。僅當只有一個content provider來提供多種建議項時（比如不同數據類型），才需要用到該屬性，並且需要採取必要措施來消除建議項請求的歧義（區分出不同的建議項請求）。
android:searchSuggestSelection
字符串。該值將作爲selection參數傳給查詢函數。典型的情況是一個數據庫WHERE語句，並應包含一個問號作爲用戶錄入的實際查詢字符的佔位符（比如"query=?"）。當然也可以通過在selectionArgs參數中指定任何非空值來觸發查詢文本的傳遞（這樣就會忽略selection參數）。
android:searchSuggestIntentAction
字符串。用戶點擊自定義搜索建議項時（比如"android.intent.action.VIEW"）默認使用的intent action。如果未被選中建議項覆蓋（通過SUGGEST_COLUMN_INTENT_ACTION列），則用戶點擊建議項時本屬性值將被放入Intent的action部分。
android:searchSuggestIntentData
字符串。用戶點擊自定義搜索建議項時默認使用的intent data。如果未被選中建議項覆蓋（通過SUGGEST_COLUMN_INTENT_DATA列），則用戶點擊建議項時本屬性值將被放入Intent的data部分。
android:searchSuggestThreshold
整數。請求文本的字符數量至少要大於該數值纔會觸發建議項的查詢。系統只保證不會向content provider 提交任何短於該閾值的查詢請求。默認值是0。
關於以上搜索建議項屬性的詳情，請參閱開發者指南的添加最近請求建議項和添加自定義建議項部分。
“快速搜索框”的屬性
爲了讓自定義建議項能被用於“快速搜索框”，需要以下<searchable>屬性：
android:includeInGlobalSearch
布爾值。（在“快速搜索框”中提供搜索建議項時需要。）如果建議項需被用於全局訪問的“快速搜索框”，則設爲“true”。用戶還是必須先在系統的搜索配置菜單中啓用應用程序對應的可搜索項，然後建議項才能出現在“快速搜索框”中。
android:searchSettingsDescription
字符串。爲提交給“快速搜索框”的搜索建議項提供簡要描述信息，這些信息將顯示在應用程序對應的可搜索項條目中（搜索配置菜單內）。描述信息應該簡要描述可搜索的內容。比如：音樂程序可以是“藝術家、專輯名和音軌”，記事本程序則可以是“已保存的記錄”。
android:queryAfterZeroResults
布爾值。如果需要讓content provider能夠接受搜索請求的超集，則設置爲“true”，這些請求在以前搜索時返回結果爲零。比如，如果content provider對“bo”返回0個結果，則應該要搜索“bob”。如果設爲“false”，同一個session中將忽略超集（“bob”將不會再次發起請求）。不過這隻會維持至搜索對話框生命週期結束，如果使用搜索widget則是到activity生命週期結束（當搜索對話框或activity重新被打開時，“bo”會再次向content provider提交請求）。默認值是false。
語音搜索的屬性
爲了啓用語音搜索功能，需要以下<searchable>屬性中的一些：
android:voiceSearchMode
關鍵字。（提供語音搜索功能時需要。）啓用語音搜索功能，並同時指定搜索模式。（某些設備可能不支持語音搜索，那這些標記就無效。）可以接受以下模式值：
|
值 |
描述 |
|
"showVoiceSearchButton" |
如果設備支持語音搜索，則顯示一個語音搜索按鈕。如果設置此值，則必須同時設置"launchWebSearch"或"launchRecognizer"（用管道符“|”分隔）。 |
|
"launchWebSearch" |
語音搜索按鈕讓用戶直接使用內置的語音web搜索activity。絕大部分應用程序不需要用到本標記，因爲它會使得用戶離開提交搜索的當前activity。 |
|
"launchRecognizer" |
語音搜索按鈕讓用戶直接使用內置的錄音activity。該activity將會引導用戶說話，把語音轉譯爲文本，並把結果作爲請求文本提交給搜索activity，就如同用戶在搜索界面錄入並點擊搜索按鈕一樣。 |
android:voiceLanguageModel
關鍵字。語音識別系統使用的語言模式。可接受以下值：
|
值 |
描述 |
|
"free_form" |
語音識別使用自由模式（free-form）。這種模式主要是爲英語優化的。這是缺省值。 |
|
"web_search" |
語音識別使用web檢索詞（web-search-term）模式，用於簡短的、類似檢索關鍵詞的短語。該模式可用的語言比上述自由模式“free_form”多一些。 |
詳情請參閱EXTRA_LANGUAGE_MODEL。
android:voicePromptText
字符串。顯示在語音輸入對話框中的其它信息。
android:voiceLanguage
字符串。期望的語言，用Locale中的字符串常量表示（比如“de”表示德語，“”表示法語）。僅當所用語言與Locale.getDefault()獲得的當前值不同時，才需要用到本值。
android:voiceMaxResults
整數。指定最多返回幾個結果，其中的“最佳”結果將用於ACTION_SEARCH intent的主要請求文本。本值必須大於等於1。用EXTRA_RESULTS可以從intent獲取這些結果。如果未提供本值，則語音識別程序將會確定返回結果的數量。
<actionkey>
爲搜索action指定一個設備上的按鍵及動作。在觸摸屏幕按鈕時，根據當前搜索請求或當前獲得焦點的建議項，搜索action將能執行設定的操作。比如，聯繫人應用程序在按下通話按鈕時能夠執行啓動電話的搜索action，與當前獲得焦點的聯繫人建議項進行通話。
並不是每臺設備都支持全部的action鍵，也不是所有鍵都允許用這種方式覆蓋。比如，“Home”鍵就不行，它必須保證能返回初始屏幕。還必須確保不要指定爲錄入搜索請求時可能會用到的鍵。本屬性基本上僅限於指定爲通話按鈕和菜單按鈕。請記住action鍵通常不是很顯眼，因此不應該把它作爲核心功能來提供給用戶。
必須定義android:keycode來指定鍵，並至少要同時指定另外三個屬性中的一個，才能完成搜索action的定義。
屬性：
android:keycode
字符串。（必填項）KeyEvent中定義的鍵值，代表所響應的action鍵（比如“KEYCODE_CALL”）。本值將附在ACTION_SEARCH intent中傳遞給搜索activity。用getIntExtra(SearchManager.ACTION_KEY)可以獲取本值。並非所有鍵都可用於搜索action，多數鍵是用於錄入鍵盤或者系統功能鍵的。
android:queryActionMsg
字符串。在用戶錄入搜索請求文本時，按下action鍵所附帶的action信息。本值將附在ACTION_SEARCH intent中傳遞給搜索activity。用getStringExtra(SearchManager.ACTION_MSG)可以獲取本值。
android:suggestActionMsg
字符串。在建議項獲得焦點時，按下action鍵所附帶的action信息。本值將附在系統傳遞給搜索activity 的intent中（使用預先定義的建議項對應的action）。用getStringExtra(SearchManager.ACTION_MSG)可以獲取本值。僅當所有建議項都支持本action 鍵時才能使用本屬性。如果不是所有建議項都能處理同一個action鍵，必須換用下面的android:suggestActionMsgColumn屬性。
android:suggestActionMsgColumn
字符串。content provider中的數據列名，用於提供本action鍵對應的action信息，在建議項獲得焦點時，按下action鍵將發送該action信息。本屬性可以控制每個建議項各自的action鍵，content provider中的每一條數據都有自己的action 信息。本屬性可以取代android:suggestActionMsg屬性，因爲它爲所有建議項指定相同的action信息。
首先，必須在content provider中爲每個建議項定義數據列，用於提供action信息，然後在本屬性中給出列名。系統會用本屬性給出的字符串在建議項cursor中查找，選中action信息列，並讀取Cursor 中的action信息。本值將附在系統傳遞給搜索activity 的intent中（使用預先定義的建議項對應的action）。用getStringExtra(SearchManager.ACTION_MSG)可以獲取本值。如果選定建議項對應的數據不存在，action鍵將被忽略。
示例：
保存於res/xml/searchable.xml的XML文件：
<?xml version="1.0" encoding="utf-8"?>
<searchablexmlns: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>