搜尋設定

為了在 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>