本頁面由 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

「字串資源」。(必填)應用程式的名稱。必須與套用至應用程式的 android:label 屬性 <activity> 或 <application> 資訊清單元素。只有在你設定後，使用者才會看見這個標籤 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

「關鍵字」。為輸入法提供其他選項。針對大多數搜尋，以預期的任意形式文字，則不需要這個屬性。預設輸入法編輯器為 actionSearch：提供「搜尋」而不要使用回車字元螢幕鍵盤。詳情請參閱 imeOptions ，取得適合這個屬性的值清單。

搜尋建議屬性

如要定義內容供應器來產生搜尋建議，請其他屬性來設定內容供應器的通訊。提供搜尋時您需要以下部分 <searchable> 屬性：

android:searchSuggestAuthority: 「字串」。(系統必須選取此欄位，才能提供搜尋建議)。這個值必須符合在 android:authorities 中提供的授權字串 Android 資訊清單 <provider> 元素的屬性。
android:searchSuggestPath: 「字串」。這個路徑會做為建議的一部分查詢 Uri，位於前置字串後方或是標準建議路徑的前方只有在具備單一內容供應器提供不同類型的建議，例如針對資料類型，並需要在收到這些資料時，明確指出在收到建議查詢時具體做法是指示 Kubernetes 建立並維護一或多個代表這些 Pod 的物件
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"`	使用語音搜尋按鈕，讓使用者直接存取內建語音錄音活動。這項活動提示使用者說話、轉錄語音，然後轉寄生成的內容查詢文字並嵌入可供搜尋的活動，就如同使用者在輸入查詢文字時並輕觸搜尋按鈕。

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>

搜尋設定

搜尋建議屬性

「快速搜尋框」屬性

語音搜尋屬性