本頁面由 Cloud Translation API 翻譯而成。

搜尋設定

如要實作 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 的字串格式設為「搜尋<內容或產品>」，例如「搜尋歌曲和藝人」或「搜尋 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>

定義搜尋動作的裝置鍵和行為。根據目前的查詢或焦點建議，搜尋動作會在輕觸裝置上的按鈕時提供特殊行為。舉例來說，當使用者輕觸「通話」按鈕時，「聯絡人」應用程式會提供搜尋動作，以便撥打電話給目前焦點聯絡人建議。

並非所有裝置都提供所有動作鍵，且並非所有按鍵都能以這種方式覆寫。舉例來說，「首頁」鍵無法覆寫，且一律會返回主畫面。此外，請勿為輸入搜尋查詢所需的按鍵定義動作鍵。這會將可用的合理動作鍵限制為通話按鈕和選單按鈕。

您必須定義 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)。如果所選建議沒有資料，系統會忽略動作鍵。

例如：

XML 檔案儲存在 res/xml/searchable.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>

搜尋設定 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

搜尋建議屬性

快速搜尋框屬性

語音搜尋屬性

搜尋設定