當你準備好要在應用程式中加入搜尋功能時,Android 可以協助你 導入使用者介面,並在頂端顯示搜尋對話方塊 或搜尋小工具,以便插入版面配置中。 搜尋對話方塊和小工具都能將使用者的搜尋查詢提供給 應用程式中的特定活動。如此一來,使用者就能透過任何 執行搜尋對話方塊或小工具且系統啟動的活動 符合執行搜尋並顯示結果的適當活動。
搜尋對話方塊和小工具還提供下列其他功能:
- 語音搜尋
- 根據近期查詢提供的搜尋建議
- 符合應用程式資料中實際結果的搜尋建議
本文件說明如何設定應用程式來提供搜尋介面 多個精確字詞和圖片 搜尋對話方塊或搜尋小工具
相關資源:
基本概念
在開始前,請先決定是否要實作搜尋介面 搜尋對話方塊或搜尋小工具他們提供相同的搜尋 但運作方式稍有不同:
- 搜尋對話方塊是由
Android 系統使用者啟用後,搜尋對話方塊會顯示在
活動的頂部。
Android 系統會控管搜尋對話方塊中的所有事件。當 使用者提交查詢後,系統便會將查詢傳送至 您所指定的處理搜尋對話方塊也提供搜尋功能 也能顯示系統建議
- 搜尋小工具是
您可以進行的
SearchView
放在版面配置中的任何位置根據預設,搜尋小工具的運作方式會與 標準EditText
也不會執行任何動作,但您可以加以設定 系統會處理所有輸入事件,並將查詢傳送至 ,並提供搜尋建議,就像搜尋項目一樣 對話方塊
當使用者透過搜尋對話方塊或搜尋小工具執行搜尋時,
系統會建立
「Intent
」和
會將使用者查詢儲存在資源中然後,系統會啟動您
宣告應處理搜尋 (「可搜尋活動」),
意圖。如要設定應用程式來使用這類輔助搜尋功能,您必須符合
包括:
- 搜尋設定
- 用於調整搜尋對話方塊或小工具設定的 XML 檔案。 其中包括語音搜尋、搜尋建議、 和搜尋框的提示文字。
- 可搜尋的活動
Activity
接收搜尋查詢、搜尋您的資料,以及顯示搜尋內容 結果。- 搜尋介面,由下列任一項目提供:
- 搜尋對話方塊
- 根據預設,系統會隱藏搜尋對話方塊。這會顯示在 通話時過濾螢幕
onSearchRequested()
使用者輕觸「搜尋」按鈕時觸發。SearchView
小工具- 有了搜尋小工具,您可以將搜尋框放在 並在應用程式列中記錄動作檢視畫面。
本文件的其餘部分將說明如何建立搜尋設定 「可供搜尋的活動」以及如何導入搜尋介面 搜尋對話方塊或搜尋小工具。
建立可供搜尋的設定
首先,您需要提供名為
搜尋設定。
可設定搜尋對話方塊或小工具的特定 UI 元素,並定義如何
功能,例如建議和語音搜尋功能。這是傳統上的檔案
名為 searchable.xml
,且必須儲存在 res/xml/
中
專案目錄
搜尋設定檔必須包含
<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" > </searchable>
android:label
是唯一的必要屬性。這項服務
指向字串資源,必須是應用程式名稱。這個標籤不屬於
您必須啟用「快速搜尋框」的搜尋建議,使用者才會看見。
標籤會顯示在系統的可搜尋項目清單中
可以管理叢集設定,像是節點
資源調度、安全性和其他預先設定項目
雖然並非必要,但建議您一律在
android:hint
屬性,可在搜尋中提供提示字串
方塊,讓系統在使用者輸入查詢前顯示相關廣告。提示很重要
讓使用者知道有哪些重要線索。
<searchable>
元素可接受多種其他屬性。
不過,您不一定要加入
搜尋建議和
語音搜尋。如要進一步瞭解
搜尋設定檔,請參閱
搜尋設定
參考文件
建立可供搜尋的活動
「可供搜尋的活動」是指應用程式中的 Activity
,且正在執行
根據查詢字串進行搜尋,並顯示搜尋結果。
使用者在搜尋對話方塊或小工具中執行搜尋時,系統
開始搜尋活動,並在
Intent
,其中包含
ACTION_SEARCH
動作。如此一來,您可以搜尋的活動會從意圖的
QUERY
然後搜尋您的資料並顯示結果。
因為您可以將搜尋對話方塊或小工具納入以下項目的任何其他活動中: 您的應用程式時,系統必須知道哪些活動屬於可供搜尋的活動, 以便正確提供搜尋查詢因此,首先要宣告您可以搜尋的 Android 資訊清單檔案中的活動。
宣告可搜尋的活動
如果您尚未建立可執行的 Activity
並顯示結果您不必實作搜尋
此時請先建立可在
資訊清單。資訊清單的
<activity>
敬上
元素時,請執行以下操作:
- 宣告活動,以接受以下應用程式中的
ACTION_SEARCH
意圖:<intent-filter>
元素。 - 指定要在
<meta-data>
元素。
例如:
<application ... > <activity android:name=".SearchableActivity" > <intent-filter> <action android:name="android.intent.action.SEARCH" /> </intent-filter> <meta-data android:name="android.app.searchable" android:resource="@xml/searchable"/> </activity> ... </application>
<meta-data>
元素必須包含
android:name
屬性,其值為
"android.app.searchable"
及android:resource
屬性以及可搜尋的設定檔參照。在
上述範例裡是指 res/xml/searchable.xml
檔案。
執行搜尋
在資訊清單中宣告可搜尋活動後,請按照下列步驟操作: 在可搜尋活動中執行搜尋的程序:
接收查詢
當使用者透過搜尋對話方塊或小工具執行搜尋時,系統
啟動可搜尋活動,並將ACTION_SEARCH
意圖。此意圖會將搜尋查詢儲存在 QUERY
字串中
外加。在活動開始時檢查是否有這個意圖,並擷取字串。
以下將舉例說明如何以搜尋方式顯示搜尋查詢
活動開始:
Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.search) // Verify the action and get the query. if (Intent.ACTION_SEARCH == intent.action) { intent.getStringExtra(SearchManager.QUERY)?.also { query -> doMySearch(query) } } }
Java
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.search); // Get the intent, verify the action, and get the query. Intent intent = getIntent(); if (Intent.ACTION_SEARCH.equals(intent.getAction())) { String query = intent.getStringExtra(SearchManager.QUERY); doMySearch(query); } }
QUERY
字串一律會包含在
ACTION_SEARCH
意圖。在上述範例中,查詢為
擷取並傳遞至本機 doMySearch()
方法,其中
實際搜尋作業完成時
搜尋資料
每個應用程式都有獨特的儲存和搜尋資料程序。你可以 以多種方式儲存及搜尋您的資料,但本文件並未說明相關做法。 考量您儲存及搜尋資料的方式,滿足您的需求和資料 格式。以下是您可以套用的訣竅:
- 如果資料儲存在裝置上的 SQLite 資料庫,請執行
全文搜尋:使用 FTS3 而非
LIKE
不僅能提供更強大的文字資料搜尋,還能 大幅加快產生結果的速度詳情請見 sqlite.org: 和 FTS3 和SQLiteDatabase
類別。 - 如果資料儲存在線上,則代表搜尋效能可能會
禁止使用者的數據連線。建議您在網站中顯示
直到搜尋傳回為止。詳情請見
android.net
取得網路 API 的參考資料ProgressBar
,以瞭解如何顯示進度指標。
呈現成果
無論資料存放在何處以及搜尋方式,我們都建議您
會將搜尋結果傳回可供搜尋活動,
Adapter
。這個
將所有搜尋結果顯示在
RecyclerView
。
如果資料來自 SQLite 資料庫查詢,您可以將結果套用至
RecyclerView
使用
CursorAdapter
。
如果資料採用不同的格式,您可以建立
BaseAdapter
。
Adapter
會將一組資料中的每個項目繫結至
View
物件。時間
Adapter
會套用至 RecyclerView
,每個部分
的資料會做為個別檢視畫面插入清單中。Adapter
是
只有介面,因此
CursorAdapter
:用於繫結來自
Cursor
—為
。如果現有的導入設定都不適合您的資料,您可以
自行在 BaseAdapter
中導入。
使用搜尋對話方塊
搜尋對話方塊的畫面頂端會顯示浮動式搜尋框 左側的應用程式圖示搜尋對話方塊可提供搜尋建議 做為使用者輸入內容當使用者執行搜尋時,系統會傳送搜尋 附加至執行搜尋的活動。
根據預設,系統會一律隱藏搜尋對話方塊,直到使用者啟用為止。
應用程式可透過以下方式啟動搜尋對話方塊:
onSearchRequested()
。然而,這個方法只有在您
啟用活動的搜尋對話方塊。
如要啟用搜尋對話方塊執行搜尋,請向系統指出
可供搜尋的活動必須從搜尋對話方塊中接收搜尋查詢。適用對象
例如前一節
建立可供搜尋的活動
已建立名為 SearchableActivity
的活動。如果希望
獨立的活動,例如名為 OtherActivity
的活動,以顯示
搜尋對話方塊並將搜尋傳送至 SearchableActivity
,宣告
SearchableActivity
是資訊清單中可供搜尋的活動
用於 OtherActivity
的搜尋對話方塊。
如要為活動的搜尋對話方塊宣告可供搜尋的活動,請新增
個別活動的 <meta-data>
元素
<activity>
元素。<meta-data>
元素必須包含指定android:value
可搜尋活動的類別名稱和 android:name
屬性
值為 "android.app.default_searchable"
。
舉例來說,以下是可供搜尋活動的宣告方式:
SearchableActivity
,以及另一項活動:
OtherActivity
,使用 SearchableActivity
透過搜尋對話方塊執行搜尋:
<application ... > <!-- This is the searchable activity; it performs searches. --> <activity android:name=".SearchableActivity" > <intent-filter> <action android:name="android.intent.action.SEARCH" /> </intent-filter> <meta-data android:name="android.app.searchable" android:resource="@xml/searchable"/> </activity> <!-- This activity enables the search dialog to initiate searches in the SearchableActivity. --> <activity android:name=".OtherActivity" ... > <!-- Enable the search dialog to send searches to SearchableActivity. --> <meta-data android:name="android.app.default_searchable" android:value=".SearchableActivity" /> </activity> ... </application>
因為 OtherActivity
現在包含
<meta-data>
元素,宣告可搜尋的活動
用於搜尋,活動會啟用搜尋對話方塊。雖然使用者
在這個活動中,onSearchRequested()
方法會啟動
搜尋對話方塊當使用者執行搜尋時,系統會啟動
SearchableActivity
,並傳送給ACTION_SEARCH
意圖。
如果您希望應用程式中的每個活動都能提供搜尋對話方塊,請插入
上述 <meta-data>
元素做為
<application>
元素,而非每個 <activity>
。如此一來
繼承值、提供搜尋對話方塊,並將搜尋項目傳送至
同一個可搜尋活動。如有多項可供搜尋的活動,您可以
將不同的
個別活動中的 <meta-data>
宣告。
現在啟用活動的搜尋對話方塊,您的應用程式已準備就緒 進行搜尋。
叫用搜尋對話方塊
雖然有些裝置提供專用的搜尋按鈕,但
按鈕可能會因裝置而異,而且許多裝置都沒有提供搜尋功能
按鈕。因此,使用搜尋對話方塊時,您必須提供搜尋按鈕
,藉由呼叫
onSearchRequested()
。
例如,在您的網站首頁加上搜尋按鈕
選項選單或 UI 版面配置
呼叫 onSearchRequested()
。
您也可以啟用「輸入搜尋」功能啟用這項功能後
搜尋對話方塊。按鍵動作
就會插入搜尋對話方塊你可以在活動中啟用文字搜尋功能
撥號
setDefaultKeyMode
,或
DEFAULT_KEYS_SEARCH_LOCAL
期間
你活動的
onCreate()
方法。
搜尋對話方塊對活動生命週期的影響
搜尋對話方塊為
浮動的 Dialog
位於畫面頂端。這不會導致活動堆疊產生任何變化
搜尋對話方塊出現時,不會顯示生命週期方法,例如
onPause()
—為
物件。您的活動失去輸入焦點,因為輸入焦點是由
搜尋對話方塊
如果您想在搜尋對話方塊啟用時收到通知,請覆寫
onSearchRequested()
方法。當系統呼叫此方法時
表示活動失去搜尋對話方塊的輸入焦點
也可以執行任何與活動相關的工作
例如暫停遊戲除非
你正在傳遞搜尋相關資訊
資料,如本文件其他章節所述,
方法,如下所示:
Kotlin
override fun onSearchRequested(): Boolean { pauseSomeStuff() return super.onSearchRequested() }
Java
@Override public boolean onSearchRequested() { pauseSomeStuff(); return super.onSearchRequested(); }
如果使用者輕觸「返回」按鈕取消搜尋,搜尋對話方塊
活動便會再次關閉輸入焦點。註冊即可收到通知
當搜尋對話方塊以
setOnDismissListener()
,
setOnCancelListener()
,
或兩者並行您只需要註冊
OnDismissListener
,
因為每次搜尋對話方塊關閉時都會呼叫此方法。
OnCancelListener
僅適用於使用者明確結束搜尋對話方塊的事件
而系統不會呼叫此方法。執行搜尋時,
搜尋對話方塊會自動消失。
如果該活動的目前活動不是可供搜尋的活動,
當使用者執行
搜尋:目前的活動會接收 onPause()
,如所述
系列
活動。不過,如果目前的活動是可供搜尋的活動
就會發生以下任一情況:
- 根據預設,可供搜尋的活動會接收
ACTION_SEARCH
意圖搭配onCreate()
呼叫 並將新的活動例項顯示在活動頂部 現在,您可以在 因此,輕觸「返回」按鈕,即可回到上一個 繼續搜尋活動的例項,而不要退出可搜尋活動 活動。 - 如果將
android:launchMode
設為"singleTop"
, 則可供搜尋的活動收到ACTION_SEARCH
意圖時 以及onNewIntent(Intent)
, 並傳遞新的ACTION_SEARCH
意圖。舉例說明 您可以處理這種狀況,此時可供搜尋活動的啟動模式 為"singleTop"
:Kotlin
override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.search) handleIntent(intent) } override fun onNewIntent(intent: Intent) { super.onNewIntent(intent) setIntent(intent) handleIntent(intent) } private fun handleIntent(intent: Intent) { if (Intent.ACTION_SEARCH == intent.action) { intent.getStringExtra(SearchManager.QUERY)?.also { query -> doMySearch(query) } } }
Java
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.search); handleIntent(getIntent()); } @Override protected void onNewIntent(Intent intent) { super.onNewIntent(intent); setIntent(intent); handleIntent(intent); } private void handleIntent(Intent intent) { if (Intent.ACTION_SEARCH.equals(intent.getAction())) { String query = intent.getStringExtra(SearchManager.QUERY); doMySearch(query); } }
與以下程式碼章節中的範例程式碼相比: 執行搜尋,就能處理所有處理 搜尋意圖現已支援
handleIntent()
方法,因此onCreate()
和onNewIntent()
可以執行這項工作。如果系統呼叫
onNewIntent(Intent)
時,活動就不會 因此getIntent()
方法會傳回與onCreate()
接收的相同意圖。 這就是為什麼您需要撥打setIntent(Intent)
在onNewIntent(Intent)
內:這樣一來,由 因此,如果您日後呼叫getIntent()
,系統會更新活動。
第二個情境 (使用 "singleTop"
啟動模式) 通常是
建議使用,因為使用者可能在搜尋完成後執行其他
您不希望應用程式建立多個
。建議您將可供搜尋的活動設為
應用程式資訊清單中的 "singleTop"
啟動模式,如
範例:
<activity android:name=".SearchableActivity" android:launchMode="singleTop" > <intent-filter> <action android:name="android.intent.action.SEARCH" /> </intent-filter> <meta-data android:name="android.app.searchable" android:resource="@xml/searchable"/> </activity>
傳遞搜尋情境資料
在某些情況下,您可以對裡面的搜尋查詢進行必要調整
每次搜尋都能搜尋到的活動記錄。不過,您想要修正
根據使用者正在執行的活動
搜尋,您可以在系統傳送給系統的意圖中提供額外資料
您的可搜尋活動。您可以將額外資料
APP_DATA
Bundle
,也就是
包含在 ACTION_SEARCH
意圖中
若要將這類資料傳送給可搜尋的活動,請覆寫
針對使用者可進行的活動使用 onSearchRequested()
方法
執行搜尋、建立包含其他資料的 Bundle
,並且
通話
startSearch()
啟用搜尋對話方塊例如:
Kotlin
override fun onSearchRequested(): Boolean { val appData = Bundle().apply { putBoolean(JARGON, true) } startSearch(null, false, appData, false) return true }
Java
@Override public boolean onSearchRequested() { Bundle appData = new Bundle(); appData.putBoolean(SearchableActivity.JARGON, true); startSearch(null, false, appData, false); return true; }
如果傳回 True,表示您已成功處理此回呼事件。
呼叫 startSearch()
以啟用搜尋對話方塊。使用者之後
提交查詢後,系統會將該查詢連同資料一併傳送至您可以搜尋的活動
或自行新增。您可以從 APP_DATA
中擷取額外的資料
使用 Bundle
可修正搜尋範圍,如以下範例所示:
Kotlin
val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false
Java
Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA); if (appData != null) { boolean jargon = appData.getBoolean(SearchableActivity.JARGON); }
使用搜尋小工具
![圖片:顯示在應用程式頂端列中的搜尋檢視畫面](https://developer.android.google.cn/static/images/ui/search-ui-topbar-33.png?authuser=9&hl=zh-tw)
圖 1. SearchView
小工具
動作檢視畫面。
搜尋小工具提供的功能與搜尋對話方塊相同,這項服務 當使用者執行搜尋時啟動適當的活動,且 提供搜尋建議和執行語音搜尋。如果行不通的 即可將搜尋小工具放在應用程式列中,也可以將搜尋 小工具就會在活動版面配置的某處顯示。
設定搜尋小工具
建立 Deployment 後
搜尋設定
可搜尋活動、啟用輔助搜尋
每個 SearchView
,方法是呼叫
setSearchableInfo()
然後傳送代表您的 SearchableInfo
物件
可供搜尋的設定。
如要取得 SearchableInfo
的參照,請呼叫
getSearchableInfo()
為
SearchManager
。
舉例來說,如果您使用 SearchView
做為
在應用程式列上啟用小工具,在
onCreateOptionsMenu()
回呼,如以下範例所示:
Kotlin
override fun onCreateOptionsMenu(menu: Menu): Boolean { // Inflate the options menu from XML. val inflater = menuInflater inflater.inflate(R.menu.options_menu, menu) // Get the SearchView and set the searchable configuration. val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager (menu.findItem(R.id.menu_search).actionView as SearchView).apply { // Assumes current activity is the searchable activity. setSearchableInfo(searchManager.getSearchableInfo(componentName)) setIconifiedByDefault(false) // Don't iconify the widget. Expand it by default. } return true }
Java
@Override public boolean onCreateOptionsMenu(Menu menu) { // Inflate the options menu from XML. MenuInflater inflater = getMenuInflater(); inflater.inflate(R.menu.options_menu, menu); // Get the SearchView and set the searchable configuration. SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE); SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView(); // Assumes current activity is the searchable activity. searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName())); searchView.setIconifiedByDefault(false); // Don't iconify the widget. Expand it by default. return true; }
搜尋小工具已設定完成,系統會提供搜尋查詢 以及可搜尋的活動您也可以啟用 搜尋建議。
如要進一步瞭解應用程式列中的動作檢視畫面,請參閱: 使用動作檢視畫面和動作 供應商。
其他搜尋小工具功能
SearchView
小工具提供幾項額外功能
可能想要:
- 提交按鈕
- 根據預設,系統並未提供可提交搜尋查詢的按鈕,因此使用者必須
按下鍵盤上的 Return 鍵來開始搜尋。個人中心
可以新增「提交」按鈕,透過
setSubmitButtonEnabled(true)
。 - 搜尋建議適用的查詢修正
- 啟用搜尋建議後,使用者通常會希望
但他們也可能會想修正建議的搜尋查詢。
您可以在每項插入建議建議旁邊新增按鈕
,即可在搜尋框中呼叫
setQueryRefinementEnabled(true)
。 - 可以切換搜尋框顯示設定的功能
- 搜尋小工具預設為「圖示化」,也就是
只顯示一個搜尋圖示 — 一個放大鏡。擴展至
會在使用者輕觸圖示時顯示搜尋框。如上
假設您預設顯示搜尋框
setIconifiedByDefault(false)
。 你也可以呼叫setIconified()
。
SearchView
類別中的其他 API 讓
自訂搜尋小工具即可但大部分的元件只有在
自行處理所有使用者輸入內容,而非使用 Android 系統
並顯示搜尋建議
同時使用小工具和對話方塊
如果您將搜尋小工具以
動作檢視,並啟用
例如,在有空間的情況下,應用程式列就會顯示該活動。
android:showAsAction="ifRoom"
),則搜尋小工具可能會
也不會顯示為動作檢視畫面相反地,選單項目可能會出現在溢位中
或前往 Google 試算表選單舉例來說,如果應用程式在較小的螢幕上執行,
應用程式列的空間不足以顯示搜尋小工具和其他動作
項目或導覽元素,因此選單項目會改為顯示在溢位中
或前往 Google 試算表選單放在溢位選單中時,項目的運作方式與一般選單類似
項目不會顯示動作檢視畫面,也就是搜尋小工具。
為了處理這種情況,您附加搜尋小工具的選單項目
當使用者從溢位選單中選取搜尋對話方塊時,必須啟用搜尋對話方塊。
要採用這個做法
onOptionsItemSelected()
處理「搜尋」選單項目,並呼叫
onSearchRequested()
。
進一步瞭解應用程式列中的項目運作方式和處理方式 請參閱 新增應用程式列。
新增語音搜尋
如要在搜尋對話方塊或小工具中新增語音搜尋功能,請按照下列步驟操作:
在可搜尋項目中加入 android:voiceSearchMode
屬性
此外還會從 0 自動調整資源配置
您完全不必調整資源調度設定系統會新增可啟動語音提示的語音搜尋按鈕。
使用者說完後,系統就會將轉錄好的搜尋查詢傳送至您的
。
例如:
<?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:voiceSearchMode="showVoiceSearchButton|launchRecognizer" > </searchable>
必須提供值 showVoiceSearchButton
才能啟用語音功能
搜尋。第二個值 launchRecognizer
會指定
語音搜尋按鈕必須啟動辨識器,
轉錄文字到可供搜尋的活動。
您可以提供其他屬性來指定語音搜尋行為 ,例如預期語言以及要傳回的結果數量上限。詳情請見 搜尋設定參考資料 可用屬性的詳細資訊
,瞭解如何調查及移除這項存取權。新增搜尋建議
搜尋對話方塊和搜尋小工具都能提供搜尋建議 並由 Android 系統協助處理。系統管理 建議清單,並在使用者選取 建議。
你可以提供兩種搜尋建議:
- 近期查詢搜尋建議
- 這些建議是使用者先前搜尋過的字詞 應用程式中的查詢內容請參閱新增 自訂搜尋建議。
- 自訂搜尋建議
- 這些搜尋建議是您對自家資料來源提供的搜尋建議 協助使用者立即選取正確的拼字或要搜尋的項目 。請參閱新增自訂搜尋 建議。