搜尋設定

如要透過 Android 系統的輔助實作搜尋 (也就是為活動提供搜尋查詢及提供搜尋建議),應用程式必須以 XML 檔案格式提供搜尋設定。

此頁面說明瞭搜尋設定檔的語法和用法。如要進一步瞭解如何為應用程式實作搜尋功能,請參閱「建立搜尋介面」。

檔案位置:
res/xml/filename.xml
Android 會使用檔案名稱做為資源 ID。
語法:
<?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>
元素:
<searchable>
定義 Android 系統用於提供輔助搜尋功能的所有搜尋設定。

屬性:

android:label
「字串資源」。(必填)應用程式的名稱。必須與 <activity><application> 資訊清單元素中 android:label 屬性所套用的名稱相同。只有在您將 android:includeInGlobalSearch 設為 "true" 時,使用者才能看到這個標籤。在此情況下,這個標籤會用來在系統的搜尋設定中,將您的應用程式識別為可搜尋項目。
android:hint
「字串資源」。(建議選項)。未輸入任何文字時,搜尋文字欄位中顯示的文字。它可讓使用者提示搜尋哪些內容可以搜尋,為了與其他 Android 應用程式保持一致,請將 android:hint 的字串格式設為「搜尋 <content-or-product>」。例如「搜尋歌曲和藝人」或「搜尋 YouTube」。
android:searchMode
「關鍵字」。設定額外模式來控制搜尋呈現方式。可用的模式會定義當自訂建議收到焦點時,需要重新編寫查詢文字的方式。可接受以下模式值:
說明
"queryRewriteFromData" 使用 SUGGEST_COLUMN_INTENT_DATA 欄中的值來重新編寫 Bquery 文字。只有在 SUGGEST_COLUMN_INTENT_DATA 中的值適合用於使用者檢查和編輯時 (例如 HTTP URI),才能使用這個值。
"queryRewriteFromText" 使用 SUGGEST_COLUMN_TEXT_1 欄中的值來改寫查詢文字。

詳情請參閱「新增自訂搜尋建議」一文,瞭解如何重新撰寫查詢文字。

android:searchButtonText
「字串資源」。執行搜尋的按鈕中顯示的文字。根據預設,按鈕會顯示搜尋圖示 (放大鏡),非常適合國際化。因此,除非行為並非搜尋以外的行為 (例如網路瀏覽器中的網址要求),否則請勿使用這項屬性變更按鈕。
android:inputType
「關鍵字」。定義要使用的輸入法類型,例如螢幕鍵盤的類型。對於大多數的搜尋應該包含任意形式的文字,您不需要使用這項屬性。 如需此屬性的合適值清單,請參閱 inputType
android:imeOptions
「關鍵字」。提供輸入法的其他選項。對於大多數搜尋來說,預期的任意形式文字,則不需要這項屬性。預設的 IME 為 actionSearch,提供「搜尋」按鈕,而非螢幕鍵盤中的回車字元。如需這項屬性的適用值清單,請參閱 imeOptions

搜尋建議屬性

如果您定義內容供應器來產生搜尋建議,則需要定義其他屬性來設定與內容供應器之間的通訊。提供搜尋建議時,您需要下列部分 <searchable> 屬性:


android:searchSuggestAuthority
「字串」。(提供搜尋建議時必填)。這個值必須與 Android 資訊清單 <provider> 元素 android:authorities 屬性中提供的授權字串相符。
android:searchSuggestPath
「字串」。這個路徑會做為建議查詢 Uri 的一部分使用,放在前置字串與授權之後,以及標準建議路徑之前。只有在單一內容供應器發出不同類型的建議時 (例如適用於不同的資料類型),且需要在收到建議查詢時區分查詢查詢時,才需要使用這個選項。
android:searchSuggestSelection
「字串」。這個值會以 selection 參數的形式傳遞至查詢函式。一般而言,這是資料庫的 WHERE 子句,且必須包含單一問號做為使用者輸入的實際查詢字串的預留位置,例如 "query=?"。不過,您也可以使用 selectionArgs 參數,使用任何非空值來觸發查詢文字的傳送,然後忽略 selection 參數。
android:searchSuggestIntentAction
「字串」。使用者輕觸自訂搜尋建議 (例如 "android.intent.action.VIEW") 時,要使用的預設意圖動作。如果所選建議使用 SUGGEST_COLUMN_INTENT_ACTION 欄未覆寫這個值,則當使用者輕觸建議時,該值會顯示在 Intent 的動作欄位中。
android:searchSuggestIntentData
「字串」。使用者輕觸自訂搜尋建議時,要使用的預設意圖資料。如果未由所選建議覆寫 (透過 SUGGEST_COLUMN_INTENT_DATA 資料欄),在使用者輕觸建議時,這個值會置於 Intent 的資料欄位。
android:searchSuggestThreshold
「整數」。觸發建議查詢作業所需的字元數下限。這只能保證系統不會向內容供應器查詢低於門檻的結果。預設值為 0。

如要進一步瞭解上述搜尋建議屬性,請參閱新增自訂搜尋建議新增自訂建議的說明文件。

快速搜尋框屬性

如要讓快速搜尋框使用您的自訂搜尋建議,您必須具備以下部分 <searchable> 屬性:


android:includeInGlobalSearch
「布林值」。(如要在快速搜尋框中提供搜尋建議,此為必要條件)。如要將建議納入全球可存取的快速搜尋框,請設為 "true"。使用者必須先在系統搜尋設定中,啟用您的應用程式做為可搜尋項目,您的建議才會顯示在快速搜尋框中。
android:searchSettingsDescription
「字串資源」。簡述您提供給「快速搜尋框」的搜尋建議,該建議會顯示在應用程式的可搜尋項目中。您的說明必須簡述可供搜尋的內容。例如,音樂應用程式的「藝人、專輯和曲目」或記事本應用程式的「已儲存的記事」。
android:queryAfterZeroResults
「布林值」。如果希望針對先前未傳回任何結果的查詢超集叫用內容供應器,請設為 "true"。例如,如果內容供應器未傳回任何「bo」結果,則必須重新查詢「bob」。如果設為 "false",單一工作階段會忽略超集合,而「bob」並不會叫用重新查詢。只有在搜尋對話方塊的生命週期和活動期間,當您使用搜尋小工具時,系統都會保留該名稱。重新開啟搜尋對話方塊或活動時,「bo」會再次查詢您的內容供應器。預設值為否。

語音搜尋屬性

如要啟用語音搜尋功能,您必須具備下列部分 <searchable> 屬性:


android:voiceSearchMode
「關鍵字」。(提供語音搜尋功能為必填)。 啟用語音搜尋,以特定模式執行語音搜尋。裝置可能未提供語音搜尋,在這種情況下,標記不會產生作用。可接受以下模式值:
說明
"showVoiceSearchButton" 如果裝置支援語音搜尋功能,就會顯示語音搜尋按鈕。如有設定,則必須一併設定 "launchWebSearch""launchRecognizer",並以直立線 (|) 字元分隔。
"launchWebSearch" 語音搜尋按鈕會將使用者直接導向內建的語音搜尋活動。大多數應用程式都不使用這個標記,因為系統會讓使用者離開叫用搜尋的活動。
"launchRecognizer" 使用者按下語音搜尋按鈕後,畫面就會直接連往內建的語音錄音活動。這項活動會提示使用者說出語音、轉錄語音內容,並將產生的查詢文字轉送至可搜尋活動,就像使用者在搜尋 UI 中輸入字詞並輕觸搜尋按鈕一樣。
android:voiceLanguageModel
「關鍵字」。必須供語音辨識系統使用的語言模型。可接受的值如下:
說明
"free_form" 使用任意形式的語音辨識功能進行語音輸入。此版本主要針對英文最佳化。此為預設值。
"web_search" 使用網頁搜尋字詞辨識功能,建立類似搜尋的簡短詞組。這支援比 "free_form" 更多的語言。

詳情請參閱 EXTRA_LANGUAGE_MODEL

android:voicePromptText
「字串資源」。語音輸入對話方塊中顯示的其他訊息。
android:voiceLanguage
「字串」。預期的語言,以 Locale 中常數的字串值表示,例如 "de" 代表德文,"fr" 代表法文。只有在和 Locale.getDefault() 目前值不同時,才需要這麼做。
android:voiceMaxResults
「整數」。設定要傳回的結果數量上限 (包括「最佳」結果),一律提供為 ACTION_SEARCH 意圖的主要查詢。不得小於 1。使用 EXTRA_RESULTS 從意圖取得結果。如未提供,辨識器會選擇要傳回多少結果。
<actionkey>
定義搜尋動作的裝置金鑰和行為。搜尋動作會根據目前的查詢或聚焦的建議,在裝置輕觸按鈕時提供特殊行為。例如,當使用者輕觸「CALL」按鈕時,「聯絡人」應用程式會提供搜尋動作,讓撥號給目前聚焦的聯絡人建議。

並非所有動作金鑰都適用於所有裝置,且並非所有金鑰都以這種方式覆寫。例如,「主畫面」鍵無法覆寫,而且必須一律返回主畫面。此外,請勿為輸入搜尋查詢所需的按鍵定義動作鍵。這會將可用且合理的動作鍵限制在呼叫按鈕和選單按鈕上。

您必須定義 android:keycode 來定義索引鍵,以及至少另外三項屬性中的其中一項,才能定義搜尋動作。

屬性:

android:keycode
「字串」。(必填)KeyEvent 的按鍵程式碼,代表您要回應的動作鍵,例如 "KEYCODE_CALL"。這會新增至 ACTION_SEARCH 意圖,並傳遞至可搜尋的活動。如要檢查金鑰程式碼,請使用 getIntExtra(SearchManager.ACTION_KEY)。並非所有按鍵都支援搜尋動作,因為許多鍵都用於輸入、瀏覽或系統功能。
android:queryActionMsg
「字串」。當使用者輸入查詢文字時按下動作鍵時,系統會傳送的動作訊息。這會新增至系統傳送至可搜尋活動的 ACTION_SEARCH 意圖。如要檢查字串,請使用 getStringExtra(SearchManager.ACTION_MSG)
android:suggestActionMsg
「字串」。當焦點在建議時按下動作鍵時,系統會傳送的動作訊息。系統會使用您為建議定義的動作,將這項資訊新增至系統傳送至可搜尋活動的意圖中。如要檢查字串,請使用 getStringExtra(SearchManager.ACTION_MSG)。只有在所有建議都支援這個動作鍵時,才能使用這個動作鍵。如果並非所有建議都能處理同一個動作鍵,您就必須改用下列 android:suggestActionMsgColumn 屬性。
android:suggestActionMsgColumn
「字串」。內容供應器中的資料欄名稱,該欄會定義此動作鍵的動作訊息。當使用者在聚焦建議時按下動作鍵時,系統會傳送此資料欄。這項屬性可讓您按照建議 (而非使用 android:suggestActionMsg 屬性) 定義所有建議的動作訊息,因為內容供應器中的每個項目都會提供專屬的動作訊息。

首先,您必須為內容供應器中的每項建議定義一個資料欄,以便提供動作訊息,然後在這項屬性中提供該資料欄的名稱。系統會查看建議遊標,使用此處提供的字串選取動作訊息欄,然後從遊標選取動作訊息字串。該字串會加入系統傳遞給可搜尋活動的意圖,並使用您針對建議定義的動作。如要檢查字串,請使用 getStringExtra(SearchManager.ACTION_MSG)。如果所選建議的資料不存在,系統會忽略動作鍵。

例如:
儲存在 res/xml/searchable.xml 中的 XML 檔案:
<?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>