搜尋設定

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