使用 Android 搜尋對話方塊或搜尋小工具時,您可以提供 根據應用程式中的資料建立的自訂搜尋建議。例如: 如果應用程式是字典,您可以從字典中建議 在使用者輸入完畢之前,在搜尋欄位中輸入的文字相符 他們的查詢。這些建議很實用,因為 讓使用者能夠立即存取所需資料圖 1 顯示範例 內含自訂建議的搜尋對話方塊
提供自訂建議後,也可以 系統通用的快速搜尋框,可讓您 應用程式。
新增自訂建議之前,請先實作 Android 搜尋對話方塊或 針對應用程式中的搜尋結果顯示搜尋小工具。請參閱建立 搜尋介面 內容 供應商。
基本概念
![](https://developer.android.com/static/images/search/search-suggest-custom.png?authuser=0000&hl=zh-tw)
圖 1. 搜尋對話方塊的螢幕截圖,其中包含 自訂搜尋建議。
當使用者選取自訂建議時,系統會傳送
訊息張貼時間:Intent
,分享對象:
。一般搜尋查詢會傳送
ACTION_SEARCH
動作,改為定義自訂建議
ACTION_VIEW
,或
任何其他意圖動作,並納入與目標對象相關的資料
已選取建議。在這個字典範例中,當使用者選取
建議的應用程式可立即開啟該字詞的定義
建議在字典中搜尋相符項目
如要提供自訂建議,請執行下列步驟:
- 實作基本的可搜尋活動,如下所述 建立搜尋介面。
- 根據內容相關資訊修改可供搜尋的設定 提供自訂建議的服務供應商
- 建立資料表,例如
SQLiteDatabase
, ,並以必要欄的格式設定表格格式。 - 建立內容 提供者,可存取建議表格並宣告 。
- 宣告當使用者選取
Intent
包括自訂動作和自訂資料
就像 Android 系統顯示搜尋對話方塊一樣,也會顯示 搜尋建議。您需要一個內容供應器,系統可 擷取建議。已讀 內容供應器 ,瞭解如何建立內容供應器
系統發現您的活動可供搜尋且提供 當使用者輸入搜尋建議時,系統會執行以下程序 查詢:
- 系統將接收搜尋查詢文字,也就是說,無論輸入什麼內容, 並向管理您 或取得寫作建議
- 內容供應者會傳回
Cursor
指向與搜尋查詢相關的所有建議 文字。 - 系統會顯示
Cursor
。
系統顯示自訂建議後,可能會發生下列情況:
- 如果使用者輸入其他字母或變更查詢, 相同的步驟,建議清單也會隨之更新。
- 如果使用者執行搜尋,系統會忽略建議,並且
則會透過
ACTION_SEARCH
意圖。 - 使用者選取建議後,系統就會將意圖傳送至您的可搜尋 包括自訂動作和自訂資料 建議的內容
修改可供搜尋的設定
如要新增自訂建議功能的支援功能,請將
將 android:searchSuggestAuthority
屬性設為
<searchable>
元素加入可供搜尋的設定檔,
如以下範例所示:
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider"> </searchable>
視意圖類型而定,您可能需要其他屬性 ,並思考你想如何為內容設定查詢格式 。其他選用屬性會在以下部分中討論 專區。
建立內容供應器
如要建立用於自訂建議的內容供應器,請先參閱
內容供應器
,瞭解如何建立內容供應器自訂的內容供應器
如同其他內容供應器但每個
則您需要在 Cursor
中的對應資料列
包含系統能夠理解且用來設定格式
或取得寫作建議
使用者在搜尋對話方塊或搜尋小工具中輸入文字時,系統
向內容供應器查詢
query()
。實作 query()
時,
內容供應器必須搜尋您的建議資料,
Cursor
:指向系統判定適當的資料列
或取得寫作建議
如要進一步瞭解如何為自訂建議建立內容供應器,請參閱 將深入探討
- 處理建議查詢
- 系統如何傳送要求給內容供應器以及處理方式 具體做法是指示 Kubernetes 建立並維護 一或多個代表這些 Pod 的物件
- 建立建議表格
- 如何定義系統預期出現在
每項查詢都會傳回
Cursor
。
處理建議查詢
當系統要求內容供應器提供建議時,系統會呼叫該內容
內容供應器的 query()
方法。導入這個方法
搜尋您的建議資料,並傳回Cursor
指向
您認為相關的建議
以下摘要說明系統傳遞至
query()
方法,依序列出:
uri
一律為內容
Uri
,格式為 如下:content://your.authority/optional.suggest.path/
SUGGEST_URI_PATH_QUERY
預設行為是讓系統傳遞這個 URI 並附加查詢 文字內容:
content://your.authority/optional.suggest.path/
SUGGEST_URI_PATH_QUERY
/puppies結尾的查詢文字是以 URI 編碼規則進行編碼,因此您或許可以採用 就必須先解碼才能搜尋
只有「
optional.suggest.path
」部分包含在 方法是在可搜尋的設定檔中用android:searchSuggestPath
屬性。只有在出現 使用相同的內容供應器執行多項可搜尋的活動。如果 請務必釐清建議查詢的來源。projection
- 一律為空值。
selection
android:searchSuggestSelection
中提供的值 屬性做為可搜尋設定檔的屬性;如果沒有,則傳回空值 宣告android:searchSuggestSelection
屬性。 下一節會進一步討論。selectionArgs
- 包含搜尋查詢為陣列的第一個和唯一的元素, 您必須在變數中宣告
android:searchSuggestSelection
屬性 您的搜尋設定如果您不宣告android:searchSuggestSelection
,則這個參數為空值。 下一節會進一步說明。sortOrder
- 一律為空值。
系統可透過以下兩種方式傳送搜尋查詢文字給您。預設方式為
,以便將查詢文字納入為傳入內容 URI 的最後一個路徑
uri
參數。不過,如果您在
可供搜尋設定的 android:searchSuggestSelection
屬性,則查詢文字會傳遞為
selectionArgs
字串陣列。以下說明這兩種選項
下一步。
在 URI 中取得查詢
預設會附加查詢做為 uri
的最後一個區段
參數:Uri
物件。如要擷取
大小寫,請使用
getLastPathSegment()
,
如以下範例所示:
Kotlin
val query: String = uri.lastPathSegment.toLowerCase()
Java
String query = uri.getLastPathSegment().toLowerCase();
這會傳回 Uri
的最後一個區段,也就是查詢
使用者輸入的文字
在選取引數中取得查詢
相較於 URI,
query()
方法,用於接收執行所需的一切
查詢,您可能會希望 selection
和
selectionArgs
參數來存放適當的值。在本
之後,請將 android:searchSuggestSelection
屬性新增至
使用 SQLite 搜尋設定。選取範圍
字串,加入問號 (?) 做為實際
搜尋查詢。系統會呼叫 query()
以及選取字串做為
selection
參數,並將搜尋查詢做為第一個元素
selectionArgs
陣列內第一個參數。
舉例來說,以下是在
android:searchSuggestSelection
屬性用於建立全文
搜尋聲明:
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" android:searchSuggestSelection="word MATCH ?"> </searchable>
完成這項設定後,query()
方法就會
selection
參數做為 "word MATCH ?"
,而
selectionArgs
參數做為搜尋查詢。只要將這些程式碼傳送至
一個 SQLite
query()
方法,做為各自的引數
換句話說,問號會替換成查詢文字。如果
以這種方式接收建議查詢,也需要在查詢中加入萬用字元
而是在 selectionArgs
參數後方加上或前置字元
這個值會以引號括住,並取代問號。
上述範例的另一項屬性是
android:searchSuggestIntentAction
,用於定義意圖動作
當使用者選取建議時,每個意圖都會傳送出去。無論是
您可以參閱宣告意圖
建議」一節。
建立建議表格
使用 Cursor
將建議傳回系統時,
系統應在每一列中輸入特定資料欄。無論店內
你在裝置的 SQLite 資料庫或網路上的資料庫
伺服器或裝置上其他格式時,請將建議格式顯示為列
,並用 Cursor
展示這些物件。
系統能辨識多個資料欄,但只需要輸入兩個資料欄:
_ID
- 每項建議的專屬整數列 ID。系統要求
會在
ListView
。 SUGGEST_COLUMN_TEXT_1
- 以建議形式顯示的字串。
以下各欄皆為選填。如要進一步瞭解 後續章節。
SUGGEST_COLUMN_TEXT_2
- 字串。如果您的
Cursor
包含這一欄,則 系統會以兩行格式提供建議。此欄中的字串是 顯示在主要建議下方第二行的小型文字 文字。可為空值或空白,表示沒有次要文字。 SUGGEST_COLUMN_ICON_1
- 可繪製資源、內容或檔案 URI 字串。如果您的
Cursor
包含這一欄,則系統會提供所有建議 圖示為加號-文字格式,左側為可繪項目圖示。這個 可以是空值或零,表示這個資料列中沒有圖示。 SUGGEST_COLUMN_ICON_2
- 可繪製資源、內容或檔案 URI 字串。如果您的
Cursor
包含這一欄,則系統會提供所有建議 。可用的值包括 空值或零表示這個資料列中沒有圖示。 SUGGEST_COLUMN_INTENT_ACTION
- 意圖動作字串。如果此欄存在,且包含
當資料列時,系統會使用此處定義的動作來產生建議的
意圖。如未提供元素,系統會從
可搜尋的「
android:searchSuggestIntentAction
」欄位 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定如果你對所有建議執行的動作都相同, 且能有效指定操作android:searchSuggestIntentAction
,然後省略這一欄。 SUGGEST_COLUMN_INTENT_DATA
- 資料 URI 字串。如果此欄存在,且包含
資料列,系統就會在建立建議的意圖時使用這個資料。如果元素
不需要提供資料,那麼資料取自
可搜尋的「
android:searchSuggestIntentData
」欄位 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定如果兩者皆未提供,則意圖的資料欄位為 空值。如果你提供的所有建議資料都相同,或是能說明 如果使用常數部分和特定 ID,指定常數時 使用android:searchSuggestIntentData
,並省略這項資訊 。 SUGGEST_COLUMN_INTENT_DATA_ID
- URI 路徑字串。如果此欄存在,且包含
,然後加上「/」這個值會附加在意圖中的資料欄位
只有在
可供搜尋的
android:searchSuggestIntentData
屬性 已設定適當的基本字串。 SUGGEST_COLUMN_INTENT_EXTRA_DATA
- 任意資料。如果這一欄存在且在指定資料列含有值,
這是構成建議意圖時使用的額外資料。
如未提供此屬性,則意圖的額外資料欄位為空值。這一欄可讓您
建議提供額外資料。這些資料將以額外的
意圖
EXTRA_DATA_KEY
鍵。 SUGGEST_COLUMN_QUERY
- 如果這一欄存在,且該元素存在於指定資料列中,那麼
構成建議查詢時使用的資料,包括
額外項目
QUERY
鍵。如果建議動作為ACTION_SEARCH
,此為必要參數。 但選用 SUGGEST_COLUMN_SHORTCUT_ID
- 僅在提供快速搜尋框建議時使用。這一欄
指出是否必須將搜尋建議儲存為捷徑,並
是否需要驗證快速鍵通常是在使用者
輕觸「快速搜尋框」中的建議。如果沒有,結果會以
且從未重新整理如果設為
SUGGEST_NEVER_MAKE_SHORTCUT
, 搜尋結果不會儲存為捷徑否則,快速鍵 ID 會用於 使用以下工具查看最新的建議SUGGEST_URI_PATH_SHORTCUT
。 SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
- 僅在提供快速搜尋框建議時使用。這一欄
會指定必須顯示輪轉選單,而非
SUGGEST_COLUMN_ICON_2
,這項建議的快速鍵為 重新整理快速搜尋框中。
我們會在下列章節中進一步討論大部分的資料欄。
宣告建議的意圖
當使用者從列於下方的清單中選取建議時,
搜尋對話方塊或小工具,系統會傳送自訂 Intent
至您的
。您必須為意圖定義動作和資料。
宣告意圖動作
自訂建議最常見的意圖動作為
ACTION_VIEW
,當你想要開啟檔案時,
例如字詞定義、使用者聯絡資訊或網頁
不過,意圖動作可以是任何其他動作,且每項動作也可能不同
建議。
視您是否要讓所有建議都使用相同的意圖動作而定, 您可以用兩種方式定義動作:
- 請使用
android:searchSuggestIntentAction
可供搜尋的設定檔,定義所有建議的動作,如 如以下範例所示:<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" > </searchable>
- 使用
SUGGEST_COLUMN_INTENT_ACTION
欄定義 以及個別建議的動作方法是將 建議表格加入SUGGEST_COLUMN_INTENT_ACTION
欄 每項建議都會納入相關操作"android.intent.action.VIEW"
。
你也可以結合這兩種技巧。舉例來說,您可以在名稱中加入
android:searchSuggestIntentAction
屬性,其中包含要執行的動作
與所有建議合併使用,然後針對部分建議覆寫這項動作
請在
SUGGEST_COLUMN_INTENT_ACTION
欄。排除值時
SUGGEST_COLUMN_INTENT_ACTION
欄中的意圖,那麼
「android:searchSuggestIntentAction
」屬性中提供的是
宣告意圖資料
使用者選取建議後,您的可供搜尋活動就會接收
您定義動作的意圖
但意圖也必須傳送活動資料,以供活動識別
並選出建議的回覆具體來說,資料不得重複
例如 SQLite 資料表中建議的資料列 ID。
收到意圖後,您可以使用
getData()
或
getDataString()
。
您可以使用下列兩種方式定義意圖包含的資料:
- 定義每項建議的資料
建議表格的
SUGGEST_COLUMN_INTENT_DATA
欄。在建議中為每個意圖提供所有必要資訊 表格,方法是加入
SUGGEST_COLUMN_INTENT_DATA
欄 然後在每一列中填入不重複的資料此欄中的資料 會跟您在此欄中定義的完全一樣附加至意圖。你可以 然後使用getData()
或getDataString()
。 - 將資料 URI 分為兩部分:所有建議通用的部分
以及每項建議特有的部分將這些部分放入
可供搜尋的
android:searchSuggestintentData
屬性 「設定」和「SUGGEST_COLUMN_INTENT_DATA_ID
」欄 和建議表格以下範例說明如何宣告 與所有建議的共通點 名為「
android:searchSuggestIntentData
」的可搜尋屬性 設定:<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" android:searchSuggestIntentData="content://com.example/datatable" > </searchable>
為每個建議加入最終路徑,也就是 建議項目的
SUGGEST_COLUMN_INTENT_DATA_ID
欄 表格。當使用者選取建議時,系統會從android:searchSuggestIntentData
,附加斜線 (/), 然後將從 使用SUGGEST_COLUMN_INTENT_DATA_ID
欄構成完整內容 URI。接著,您可以使用Uri
getData()
。
新增更多資料
如需透過意圖提供更多資訊,您可以新增其他意圖
例如 SUGGEST_COLUMN_INTENT_EXTRA_DATA
儲存建議的其他資訊。這一欄中儲存的資料
放在意圖額外軟體包的 EXTRA_DATA_KEY
中。
處理意圖
透過自訂意圖提供自訂搜尋建議後,您需要
您的可供搜尋活動,以便在使用者選取
建議。用來處理 ACTION_SEARCH
意圖,您的可搜尋活動已有這個意圖。以下範例將說明
您可以在活動期間處理意圖
onCreate()
回呼:
Kotlin
when(intent.action) { Intent.ACTION_SEARCH -> { // Handle the normal search query case. intent.getStringExtra(SearchManager.QUERY)?.also { query -> doSearch(query) } } Intent.ACTION_VIEW -> { // Handle a suggestions click, because the suggestions all use ACTION_VIEW. showResult(intent.data) } }
Java
Intent intent = getIntent(); if (Intent.ACTION_SEARCH.equals(intent.getAction())) { // Handle the normal search query case. String query = intent.getStringExtra(SearchManager.QUERY); doSearch(query); } else if (Intent.ACTION_VIEW.equals(intent.getAction())) { // Handle a suggestions click, because the suggestions all use ACTION_VIEW. Uri data = intent.getData(); showResult(data); }
在此範例中,意圖動作為 ACTION_VIEW
,且資料
包含指向建議項目的完整 URI,因為
「android:searchSuggestIntentData
」字串和
SUGGEST_COLUMN_INTENT_DATA_ID
欄。接著,URI 會傳遞
本機 showResult()
方法,會查詢內容供應器的內容供應器
透過 URI 指定的項目
重新撰寫查詢文字
根據預設,如果使用者使用 方向性控制項 (例如軌跡球或 D-Pad) 時,查詢文字並不會 更新。不過,您可以暫時重新撰寫畫面上顯示的使用者查詢文字 。這樣一來, 使用者會看到系統建議的查詢,然後選取搜尋框來編輯內容 再將其做為搜尋調派。
您可以透過下列方式重寫查詢文字:
- 將
android:searchMode
屬性加入可搜尋項目 產生"queryRewriteFromText"
值。在本 大小寫,則來自建議內容SUGGEST_COLUMN_TEXT_1
的內容 欄將用於重新撰寫查詢文字。 - 將
android:searchMode
屬性新增到可搜尋項目\ 產生"queryRewriteFromData"
值。在本 大小寫,則建議 Deployment 中的內容 「SUGGEST_COLUMN_INTENT_DATA
」欄用於重新編寫查詢 文字。請僅用於 URI 或其他有意使用的資料格式 例如 HTTP 網址請勿使用內部 URI 配置重新編寫 以此方式查詢。 - 請在
建議表格的
SUGGEST_COLUMN_QUERY
欄。如果這是 欄,且包含目前建議的值,則值為 以便改寫查詢文字並覆寫先前 。
在快速搜尋框中顯示搜尋建議
設定應用程式提供自訂搜尋建議後,
「快速搜尋框」 提供給全球所有的使用者使用,就像修改文字一樣簡單
您的搜尋設定
將 android:includeInGlobalSearch
設為值
"true"
。
只有在 2017 年 3 月 1 日
提供者要求讀取權限此時,您必須新增
<path-permission>
元素讓供應程式快速授予
可以讀取內容供應器的搜尋框讀取權限,如下所示
範例:
<provider android:name="MySuggestionProvider" android:authorities="com.example.MyCustomSuggestionProvider" android:readPermission="com.example.provider.READ_MY_DATA" android:writePermission="com.example.provider.WRITE_MY_DATA"> <path-permission android:pathPrefix="/search_suggest_query" android:readPermission="android.permission.GLOBAL_SEARCH" /> </provider>
在這個範例中,供應器會限制內容的讀取和寫入權限。
<path-permission>
元素會修改
授予 "/search_suggest_query"
中內容的讀取權限
"android.permission.GLOBAL_SEARCH"
權限時的路徑前置字串
存在。這會授予快速搜尋框的存取權,以便查詢你的內容
以獲得建議。
如果內容供應器不會強制執行讀取權限,則請使用「快速搜尋」 Box 預設會讀取這個程式碼。
在裝置上啟用建議功能
根據預設,應用程式並不會在「快速搜尋框」中提供建議, 就算是這樣設定使用者選擇是否要納入 在「快速搜尋框」中開啟應用程式的建議,方法是開啟可搜尋 items:位於 [設定] >Google 搜尋—並啟用 顯示為可供搜尋的項目
凡是支援「快速搜尋框」的應用程式,您都可以在
可搜尋項目設定頁面。項目包含應用程式名稱
以及簡短說明,讓使用者透過應用程式搜尋到的內容
,在快速搜尋框中顯示建議。如何定義說明文字
請將 android:searchSettingsDescription
屬性連結至可搜尋的設定,如下所示
範例:
<?xml version="1.0" encoding="utf-8"?> <searchable xmlns:android="http://schemas.android.com/apk/res/android" android:label="@string/app_label" android:hint="@string/search_hint" android:searchSuggestAuthority="com.example.MyCustomSuggestionProvider" android:searchSuggestIntentAction="android.intent.action.VIEW" android:includeInGlobalSearch="true" android:searchSettingsDescription="@string/search_description" > </searchable>
將 android:searchSettingsDescription
的字串調整為精簡
並註明可供搜尋的內容例如「藝人
專輯和曲目(音樂應用程式) 或「已儲存的記事」。
提供說明很重要,方便使用者瞭解
提示字元一律加入這個屬性
android:includeInGlobalSearch
為 true。
因為使用者必須前往設定選單才能啟用搜尋建議 如果搜尋是應用程式的重要面向,您可以考慮如何 也就是傳達給使用者的體驗舉例來說,您可以在首次提供 使用者啟動應用程式,說明如何啟用快速搜尋建議功能 搜尋框。
管理快速搜尋框建議捷徑
系統會自動在使用者從快速搜尋框選取建議 轉換為捷徑這些建議是從 內容供應器,可讓您快速存取建議,而無需手動 請重新查詢內容供應器
根據預設,「快速搜尋」擷取的所有建議都會啟用這項功能
方塊,不過如果建議資料會隨時間改變,你可以要求
即可重新整理快速鍵。舉例來說,如果建議內容是
資料,例如聯絡人的在家狀態,再要求系統根據
快速指令會在向使用者顯示時重新整理。方法是加入
建議表格中的SUGGEST_COLUMN_SHORTCUT_ID
。別擔心!您可以使用
這個資料欄可用於設定每項建議的快速鍵行為:
方法如下:
讓「快速搜尋框」重新查詢內容供應器,掌握最新資訊 快速連結。
在
SUGGEST_COLUMN_SHORTCUT_ID
欄中提供以下項目的值: 每次捷徑都會重新查詢新版本的建議 。快捷方式可快速顯示任何資料 直到重新整理查詢傳回為止 系統隨即會根據新的資訊重新整理建議。重新整理查詢是 透過SUGGEST_URI_PATH_SHORTCUT
:而非SUGGEST_URI_PATH_QUERY
。使用
Cursor
與原始建議相同的資料欄或空白,表示 捷徑已失效,在這種情況下,建議會消失 即可移除捷徑如果建議內容參照的資料需要較長的重新整理時間 (例如 網路重新整理也能新增 完成
SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING
欄的 值為 True 的建議表格,以顯示進度旋轉圖示 右手圖示,直到重新整理完成非 true 的任何值 不會顯示進度旋轉圖示完全不將建議內容複製到捷徑中。
在
SUGGEST_NEVER_MAKE_SHORTCUT
SUGGEST_COLUMN_SHORTCUT_ID
欄。在此情況下, 則一律不會複製到捷徑中只有在您使用了 您絕對不希望系統顯示先前複製的建議。如果發生以下情況: 請提供資料欄的正規值,然後是建議快速鍵 出現直到重新整理查詢傳回為止。套用預設捷徑行為。
將每個項目的
SUGGEST_COLUMN_SHORTCUT_ID
留空 不會變動的建議,而且可以儲存為 快速鍵。
如果沒有任何建議
SUGGEST_COLUMN_SHORTCUT_ID
欄。
關於快速搜尋框建議排名
將應用程式的搜尋建議套用到快速搜尋框後, 「快速搜尋框」排名會決定 Google 如何向搜尋使用者顯示建議 某個查詢帶出的結果這取決於其他應用程式有多少 以及使用者選取搜尋結果的頻率 其他應用程式的內容我們無法保證你的建議會如何 排名,還是針對特定查詢顯示您的應用程式建議。於 一般而言,提供品質結果可提升 會以顯眼的位置提供建議,如果應用程式為 品質偏低的建議通常排名較低或無法顯示。