為了在 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- 「關鍵字」。設定其他模式，用於控制搜尋呈現方式。可用
模式可定義當自訂建議收到時，查詢文字應如何重寫
重點。系統接受下列模式值：
詳情請參閱相關說明文件
新增自訂搜尋建議。
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>
