搜尋設定
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
如要透過 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
的字串格式設為「搜尋 <content-or-product>」。例如「搜尋歌曲和藝人」或「搜尋 YouTube」。
android:searchMode
- 「關鍵字」。設定額外模式來控制搜尋呈現方式。可用的模式會定義當自訂建議收到焦點時,需要重新編寫查詢文字的方式。可接受以下模式值:
詳情請參閱「新增自訂搜尋建議」一文,瞭解如何重新撰寫查詢文字。
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>
- 定義搜尋動作的裝置金鑰和行為。搜尋動作會根據目前的查詢或聚焦的建議,在裝置輕觸按鈕時提供特殊行為。例如,當使用者輕觸「CALL」按鈕時,「聯絡人」應用程式會提供搜尋動作,讓撥號給目前聚焦的聯絡人建議。
並非所有動作金鑰都適用於所有裝置,且並非所有金鑰都以這種方式覆寫。例如,「主畫面」鍵無法覆寫,而且必須一律返回主畫面。此外,請勿為輸入搜尋查詢所需的按鍵定義動作鍵。這會將可用且合理的動作鍵限制在呼叫按鈕和選單按鈕上。
您必須定義 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)
。如果所選建議的資料不存在,系統會忽略動作鍵。
- 例如:
- 儲存在
res/xml/searchable.xml
中的 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>
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間:2024-02-22 (世界標準時間)。
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"缺少我需要的資訊"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"過於複雜/步驟過多"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"過時"
},{
"type": "thumb-down",
"id": "translationIssue",
"label":"翻譯問題"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"示例/程式碼問題"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"其他"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"容易理解"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"確實解決了我的問題"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"其他"
}]