前言

　　本章內(nèi)容為 Android開發(fā)者指南的 Framework Topics/Search/Adding Custom Suggestions章節(jié)，譯為"添加自定義建議項(xiàng)"，版本為Android 4.0 r1，翻譯來自："呆呆大蝦"，歡迎訪問他的微博："http://weibo.com/popapa"，再次感謝"呆呆大蝦" ！期待你一起參與翻譯Android的相關(guān)資料，聯(lián)系我over140@gmail.com。

?

聲明

　　歡迎轉(zhuǎn)載，但請保留文章原始出處:)?

　　　　博客園：http://www.cnblogs.com/

Android中文翻譯組：http://androidbox.sinaapp.com/

?

?

添加自定義建議項(xiàng)

譯者署名：?呆呆大蝦

譯者微博：?http://weibo.com/popapa

版本：Android 4.0 r1

原文

?????????http://developer.android.com/guide/topics/search/adding-custom-suggestions.html??

?

在本文中

簡介

修改搜索配置文件

創(chuàng)建Content Provider

處理建議項(xiàng)請求

建立建議項(xiàng)數(shù)據(jù)表

聲明建議項(xiàng)所需的Intent

聲明intent的action

聲明intent的data

處理Intent

改寫查詢請求文本

向快速搜索框提供搜索建議項(xiàng)

關(guān)鍵類

SearchManager

SearchRecentSuggestionsProvider

ContentProvider

相關(guān)示例

支持檢索的字典

參閱

搜索配置文件

Content Providers

?

利用Android的搜索對話框或搜索widget，可以提供自定義搜索建議項(xiàng)，它的數(shù)據(jù)來源于應(yīng)用程序自身。比如，假設(shè)應(yīng)用程序是一個字典應(yīng)用，可以把字典中最匹配已錄入文本的單詞作為建議項(xiàng)。由于能有效預(yù)測用戶所查文本并能讓用戶直接獲得字典中的釋義，這種建議項(xiàng)是最有價值的。圖1展示了使用自定義建議項(xiàng)的搜索對話框示例：

圖1.?使用自定義對話框的搜索對話框截屏

一旦提供了自定義建議項(xiàng)，就可以同時讓它應(yīng)用于系統(tǒng)級的“快速搜索框”，從應(yīng)用程序之外訪問搜索內(nèi)容。

在添加自定義建議項(xiàng)之前，需要先在應(yīng)用程序中實(shí)現(xiàn)一個Android搜索對話框或搜索widget。如果還沒有的話，請參閱創(chuàng)建搜索界面。

?

簡介

如果用戶選中了某個自定義建議項(xiàng)，Android系統(tǒng)將向搜索activity發(fā)送一個Intent。標(biāo)準(zhǔn)的搜索請求將會發(fā)送一個附帶ACTION_SEARCH?action的intent，不過仍可讓自定義建議項(xiàng)使用ACTION_VIEW（或者任何其它action），并放入相應(yīng)的選中建議項(xiàng)數(shù)據(jù)。接著上面的字典應(yīng)用示例，用戶選中一個建議項(xiàng)時，應(yīng)用程序可以立即顯示單詞的釋義，而不是去字典檢索匹配項(xiàng)。

為了提供自定義建議項(xiàng)功能，請按以下步驟操作：

·???????實(shí)現(xiàn)一個基本的搜索activity，如創(chuàng)建搜索界面所述。

·???????修改搜索配置文件中有關(guān)content provider的信息，用于提供自定義建議項(xiàng)的數(shù)據(jù)。

·???????建立存放建議項(xiàng)的數(shù)據(jù)表（比如在SQLiteDatabase庫中），根據(jù)所需數(shù)據(jù)列定義表結(jié)構(gòu)。

·???????創(chuàng)建訪問建議項(xiàng)數(shù)據(jù)表的Content Provider，并在manifest文件中聲明provider。

·???????聲明Intent的類型，用戶選中某個建議項(xiàng)時可用于發(fā)送數(shù)據(jù)（包括自定義action和自定義數(shù)據(jù)）。

當(dāng)搜索對話框顯示出來時，Android系統(tǒng)同時也會顯示搜索建議項(xiàng)。需要提供的只是系統(tǒng)能從中讀取建議項(xiàng)的content provider。如果對創(chuàng)建content provider還不很熟悉，請先閱讀Content Providers開發(fā)者指南再往下繼續(xù)吧。

一旦系統(tǒng)識別出activity支持搜索功能且已提供搜索建議項(xiàng)，用戶鍵入搜索請求時會執(zhí)行以下步驟：

1.?????系統(tǒng)讀取搜索請求文本（錄入了多少就讀取多少），并在存放建議項(xiàng)的content provider中進(jìn)行檢索。

2.?????content provider返回一個Cursor，它指向匹配搜索文本的全部建議項(xiàng)。

3.?????系統(tǒng)顯示該Cursor提供的建議項(xiàng)列表。

顯示完畢，將發(fā)生以下事情：

·???????如果用戶鍵入其它字符，或者以其它任何方式修改了請求文本，則上述步驟會重復(fù)執(zhí)行，建議項(xiàng)列表將同步更新。

·???????如果用戶執(zhí)行了搜索，建議項(xiàng)將被忽略，搜索文本將用正常的ACTION_SEARCH?intent發(fā)送給搜索activity。

·???????如果用戶選中了某個建議項(xiàng)，帶有自定義action和自定義數(shù)據(jù)的intent將會發(fā)送給搜索activity，應(yīng)用程序可以打開建議項(xiàng)內(nèi)容。

?

修改搜索配置文件

要加入對自定義建議項(xiàng)的支持，請?jiān)谒阉髋渲梦募?/span><searchable>元素中添加android:searchSuggestAuthority屬性。例如：

<?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>

根據(jù)建議項(xiàng)相關(guān)的intent類型，以及如何組織提交給content provider的請求文本，可能還需要用到其它一些屬性。其它可選的屬性將在后續(xù)章節(jié)中討論。

?

創(chuàng)建Content Provider

?????????要為自定義建議項(xiàng)創(chuàng)建content provider，需要具備content provider的相關(guān)知識，這在Content Provider開發(fā)者指南中描述。自定義建議項(xiàng)所需的content provider絕大部分都與其它content provider相同。不過，Cursor中對應(yīng)每個建議項(xiàng)的數(shù)據(jù)行都必須包含系統(tǒng)可解析的數(shù)據(jù)列，用于組織建議項(xiàng)數(shù)據(jù)。

用戶開始在搜索對話框或搜索widget里輸入文本時，每鍵入一個字符，系統(tǒng)都將調(diào)用一次query()，并在content provider中檢索建議項(xiàng)。在query()中，必須實(shí)現(xiàn)對content provider建議項(xiàng)數(shù)據(jù)的檢索，并返回一個指向最佳建議項(xiàng)數(shù)據(jù)行的Cursor。

關(guān)于為自定義建議項(xiàng)創(chuàng)建content provider的詳情，將在以下章節(jié)討論：

處理建議項(xiàng)請求

系統(tǒng)如何向content provider發(fā)送請求及如何處理。

建立建議項(xiàng)數(shù)據(jù)表??

如何定義數(shù)據(jù)列，系統(tǒng)用于在每次搜索時返回Cursor?。

?

處理建議項(xiàng)請求

當(dāng)系統(tǒng)向content provider發(fā)送建議項(xiàng)檢索請求時，將會調(diào)用content provider的query()方法。必須在該方法中實(shí)現(xiàn)搜索建議項(xiàng)數(shù)據(jù)并返回指向最匹配建議項(xiàng)的Cursor。

以下是系統(tǒng)傳給query()方法的所有參數(shù)（按照調(diào)用順序排列）：

uri

通常是content?Uri，格式如下：

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY

系統(tǒng)的默認(rèn)行為是傳遞URI并后跟搜索請求文本。例如：

content://your.authority/optional.suggest.path/SUGGEST_URI_PATH_QUERY/puppies

末尾的請求文本是用URI?編碼規(guī)則編碼過的，因此可能要在執(zhí)行搜索前進(jìn)行解碼。

僅當(dāng)搜索配置文件中用android:searchSuggestPath屬性設(shè)置了路徑時，URI中才要包含optional.suggest.path部分。只有多個搜索activity需共用同一個content provider時，才需要用到該配置。在這種情況下，需要解析建議項(xiàng)請求的來源。

注意：SUGGEST_URI_PATH_QUERY?并不屬于URI的一部分，而應(yīng)是用于指向此路徑的常量。

projection

總為null

selection

該值由搜索配置文件中的android:searchSuggestSelection屬性提供，如果未聲明android:searchSuggestSelection屬性則為null。更多使用信息請參見下文讀取請求?。

selectionArgs

如果已在搜索配置文件中聲明了android:searchSuggestSelection屬性，那么數(shù)組的第一個（也只有一個）元素包含了搜索請求。如果未聲明android:searchSuggestSelection，則本參數(shù)將為null。更多使用信息請參見下文讀取請求?。

sortOrder

總為null。

系統(tǒng)可以用兩種方式發(fā)送搜索請求文本。默認(rèn)的方式是作為content URI路徑的末尾部分（last segment）在uri參數(shù)中傳遞。不過，假如在搜索配置文件的android:searchSuggestSelection屬性中包含了選項(xiàng)值，那么請求文本將作為字符串?dāng)?shù)組selectionArgs的第一個元素傳遞。這兩種方式將在下文中一起討論。

?

讀取Uri中的搜索請求

默認(rèn)情況下，請求文本是附加在uri參數(shù)（Uri對象）的末尾的。這時只要簡單地用getLastPathSegment()即可讀取請求文本了。例如：

String?query?=?uri.getLastPathSegment().toLowerCase();

這將返回Uri的末尾部分（last segment），也就是用戶錄入的請求文本。

?

讀取selection參數(shù)中的搜索請求

與URI不同，還可以采用更智能的方式，query()方法能夠接收執(zhí)行搜索所需的任何信息，selection和selectionArgs屬性也能夠傳遞合適的值。這種情況下，只要把SQLite查詢語句作為android:searchSuggestSelection屬性加入到搜索配置文件中去即可。在查詢語句中，問號用作占位符，代表實(shí)際的查詢請求。系統(tǒng)將用該查詢語句作為selection參數(shù)，搜索請求作為selectionArgs數(shù)組的第一個元素，對query()進(jìn)行調(diào)用。

以下是如何定義android:searchSuggestSelection屬性來創(chuàng)建全文搜索語句的示例：

<?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參數(shù)賦為"word MATCH ?"?，selectionArgs參數(shù)賦為搜索請求。當(dāng)這些信息作為參數(shù)傳給SQLite?query()?方法時，會被組合在一起（問號由搜索請求文本代替）。如果選擇以這種方式接收建議項(xiàng)請求并需要在請求文本中加入通配符，可以在selectionArgs參數(shù)的后面（或前面）加入即可，因?yàn)樵撝祵⒂靡柊⒄w插入到問號所在位置。

以上例子中新出現(xiàn)的屬性是android:searchSuggestIntentAction，用于定義用戶每次選中建議項(xiàng)時所發(fā)送intent的action。這將在后續(xù)章節(jié)為建議項(xiàng)聲明Intent討論。

提示：如果不需要在android:searchSuggestSelection屬性中定義查詢語句，但還要在selectionArgs參數(shù)中接收請求文本，則只要簡單地把android:searchSuggestSelection屬性賦成非空值即可。這將導(dǎo)致請求文本傳遞給selectionArgs，并且selection參數(shù)可被忽略。這樣就可以不用定義實(shí)際的底層查詢語句，content provider也不必再對其進(jìn)行處理。

?

?

建立建議項(xiàng)數(shù)據(jù)表

創(chuàng)建脫離數(shù)據(jù)庫表的Cursor

如果搜索建議項(xiàng)不是按照系統(tǒng)要求的數(shù)據(jù)列存儲在數(shù)據(jù)庫表中的（比如SQLite表），那可以在每次發(fā)起請求時檢索匹配的建議項(xiàng)數(shù)據(jù)并把它們格式化后保存到必要的表中。要實(shí)現(xiàn)這一目標(biāo)，用系統(tǒng)要求的列名創(chuàng)建一個MatrixCursor，并用addRow(Object[])為每個建議項(xiàng)創(chuàng)建一行數(shù)據(jù)。Content Provider的query()方法將返回最終結(jié)果。

用Cursor向系統(tǒng)返回建議項(xiàng)時，每一行數(shù)據(jù)的列格式都是系統(tǒng)規(guī)定的。因此，無論是要把建議項(xiàng)數(shù)據(jù)存儲在本地或Web服務(wù)器的SQLite數(shù)據(jù)庫中，還是要以本地或web的其它格式存儲，都必須把建議項(xiàng)格式化為表的一行數(shù)據(jù)，并用Cursor來表示。系統(tǒng)可以識別多個列，但有兩列是必需的：

ID

整數(shù)類型的行ID，唯一標(biāo)識建議項(xiàng)。在ListView中顯示建議項(xiàng)時，系統(tǒng)會用到該值。

SUGGEST_COLUMN_TEXT_1

代表建議項(xiàng)的字符串。

以下各列是可選的（大部分都會在后續(xù)章節(jié)中討論）：

SUGGEST_COLUMN_TEXT_2

字符串。如果Cursor包含該列，那么所有的建議項(xiàng)都提供兩行模式。本列中的字符串將會顯示為第二行，它的字體較小并顯示主建議項(xiàng)文本的下方。也可以為null或空串，表示沒有第二行文本。

SUGGEST_COLUMN_ICON_1

drawable資源、content或文件URI串。如果Cursor包含該列，那么所有建議項(xiàng)都提供圖標(biāo)加文字模式，圖標(biāo)居左顯示。該項(xiàng)可以為null或0，表示本行沒有圖標(biāo)。

SUGGEST_COLUMN_ICON_2

drawable資源、content或文件URI串。如果Cursor包含該列，那么所有建議項(xiàng)都提供圖標(biāo)加文本模式，圖標(biāo)居右顯示。該項(xiàng)可以為null或0，表示本行沒有圖標(biāo)。

SUGGEST_COLUMN_INTENT_ACTION

intent action字符串。如果給定行中存在本列并且有值，那么此處定義的action將用于格式化建議項(xiàng)的intent。如果未提供本值，則會采用搜索配置文件中的android:searchSuggestIntentAction部分。如果所有建議項(xiàng)的action都是相同的，則更有效的方式是用android:searchSuggestIntentAction?指定action并省略本列。

SUGGEST_COLUMN_INTENT_DATA

數(shù)據(jù)URI字符串。如果給定行中存在本列并且有值，那么此值在格式化建議項(xiàng)時將作為intent的data部分來使用。如果未提供本值，則會采用搜索配置文件中的android:searchSuggestIntentData部分。如果前面兩處都未提供值，則intent的data部分將為null。如果所有建議項(xiàng)的數(shù)據(jù)都是相同的，或者能用固定部分+ID來描述的，那么更有效的的方式是用android:searchSuggestIntentData指定，并省略本列。

SUGGEST_COLUMN_INTENT_DATA_ID

URI路徑字符串。如果給定行中存在本列并且有值，那么“/”加上本值將會添加到intent的data之后。僅當(dāng)搜索配置文件中的android:searchSuggestIntentData屬性已經(jīng)設(shè)置了適當(dāng)?shù)幕A(chǔ)數(shù)據(jù)字符串時，本項(xiàng)才會用到。

SUGGEST_COLUMN_INTENT_EXTRA_DATA

任何數(shù)據(jù)。如果給定行中存在本列并且有值，則表示格式化建議項(xiàng)intent時需要用到的extra?data。如果未提供本值，則intent的extra data部分為null。本列允許建議項(xiàng)附帶額外的數(shù)據(jù)，包含于intent的EXTRA_DATA_KEY鍵內(nèi)。

SUGGEST_COLUMN_QUERY

如果給定行中存在本列并且有值，則為格式化建議項(xiàng)請求時需要用到的數(shù)據(jù)，包含于intent的QUERY鍵內(nèi)。當(dāng)建議項(xiàng)的action是ACTION_SEARCH時需要用到本值，否則則是可選列。

SUGGEST_COLUMN_SHORTCUT_ID

僅當(dāng)向“快速搜索框”提供建議項(xiàng)時才會用到。本列標(biāo)明了搜索建議項(xiàng)是否要存儲為快捷方式，以及是否需要驗(yàn)證有效性。快捷方式一般是在用戶從“快速搜索框”中點(diǎn)擊建議項(xiàng)時生成。如果本ID缺失的話，結(jié)果將會存儲為快捷方式且不再會更新。如果設(shè)置為SUGGEST_NEVER_MAKE_SHORTCUT，結(jié)果將不會存儲為快捷方式。否則，快捷方式的ID將用于檢查并更新建議項(xiàng)，這時還會用到SUGGEST_URI_PATH_SHORTCUT.。

SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING

僅用于向“快速搜索框”提供建議項(xiàng)。本列指明當(dāng)“快速搜索框”內(nèi)建議項(xiàng)的快捷方式更新后，是否用進(jìn)度滾輪（spinner）替代SUGGEST_COLUMN_ICON_2所設(shè)的圖標(biāo)。

以上各列中的一部分將會在后續(xù)章節(jié)中繼續(xù)討論。

?

聲明建議項(xiàng)所需的Intent

當(dāng)用戶在搜索對話框或widget下方的列表內(nèi)選中某個建議項(xiàng)時，系統(tǒng)會向搜索activity發(fā)送一個自定義的Intent。intent必須定義好action和data部分。

?

聲明intent的action

自定義建議項(xiàng)最常用的intent action是ACTION_VIEW，適用于要啟動某些應(yīng)用的場合，類似單詞的釋義、聯(lián)系人信息、網(wǎng)頁等。當(dāng)然，intent action也可以是其它任何action，甚至每個建議項(xiàng)的action都可以不同。

根據(jù)全部建議項(xiàng)是否共用同一種intent action，可以用以下兩種方式來定義action：

a.?????利用搜索配置文件的android:searchSuggestIntentAction?屬性來定義所有建議項(xiàng)的action。

例如：

<?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>

b.?????利用SUGGEST_COLUMN_INTENT_ACTION?列來定義單個建議項(xiàng)的action。

在建議項(xiàng)表中添加SUGGEST_COLUMN_INTENT_ACTION?列，并把每個建議項(xiàng)所用到的action放入其中（類似"android.Intent.action.VIEW"）。

也可以混合使用以上兩種方式。比如，可以包含android:searchSuggestIntentAction屬性，為所有建議項(xiàng)提供默認(rèn)action。然后在某些建議項(xiàng)的SUGGEST_COLUMN_INTENT_ACTION列中聲明另一個action，以覆蓋默認(rèn)action。如果SUGGEST_COLUMN_INTENT_ACTION列中未包含值，將會采用android:searchSuggestIntentAction屬性提供的intent。

注意：如果搜索配置文件中未包含android:searchSuggestIntentAction屬性，則必須為每個建議項(xiàng)的SUGGEST_COLUMN_INTENT_ACTION列指定值，否則，intent將會啟動失敗。

?

聲明intent的data

當(dāng)用戶選中一個建議項(xiàng)時，搜索activity將會接收到附帶指定action（如上節(jié)所述）的intent，但該intent還必須同時攜帶data才行，這樣搜索activity才能識別出選中的建議項(xiàng)。有一點(diǎn)尤為重要，data應(yīng)該是能唯一標(biāo)識每個建議項(xiàng)的信息，比如SQLite表中的行ID。在收到intent時，可以利用getData()或getDataString().來讀取附帶的data。

可以用以下兩種方式來定義intent中的data：

a.?????在建議項(xiàng)表的SUGGEST_COLUMN_INTENT_DATA列中為每個建議項(xiàng)都定義一個data。

在建議項(xiàng)表中包含SUGGEST_COLUMN_INTENT_DATA列，以便為每個intent?都提供必要的data信息，然后把每行的唯一信息填入。該列中的值將會原封不動地附加到intent中。可以利用getData()或getDataString()來讀取它們。

提示：?通常表的行ID最容易被用作Intent data，因?yàn)樗偸俏ㄒ坏摹Ｗ詈啽愕姆绞骄褪怯?/span>SUGGEST_COLUMN_INTENT_DATA列名作為行ID的別名。具體示例請參閱支持檢索的字典例程，其中SQLiteQueryBuilder創(chuàng)建了一個列名和別名的映射關(guān)系。

b.?????把data URI分解為兩部分：所有建議項(xiàng)公共的部分和每個建議項(xiàng)唯一的部分。把這兩部分分別放入搜索配置文件的android:searchSuggestintentData屬性和建議項(xiàng)表的SUGGEST_COLUMN_INTENT_DATA_ID?列中。

在搜索配置文件的android:searchSuggestIntentData屬性中聲明全部建議項(xiàng)公共的URI部分。例如：

<?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>

然后在建議項(xiàng)表中的SUGGEST_COLUMN_INTENT_DATA_ID列中放入每個建議項(xiàng)的final path（唯一部分）。用戶選中建議項(xiàng)后，系統(tǒng)會把android:searchSuggestIntentData中指定的字符串加上斜杠?("/")，再加入各自SUGGEST_COLUMN_INTENT_DATA_ID列中的值，組成一個完整的content URI。然后就可以用getData()讀取Uri?了。

?

附加更多的數(shù)據(jù)

如果需要在intent中表示更多信息，可以添加另一列SUGGEST_COLUMN_INTENT_EXTRA_DATA來存放與建議項(xiàng)相關(guān)的附加數(shù)據(jù)。在此列中存放的數(shù)據(jù)將被置于intent附帶Bundle的EXTRA_DATA_KEY?部分中。

?

處理Intent

現(xiàn)在已經(jīng)能利用自定義intent提供自定義的搜索建議項(xiàng)，用戶選中某建議項(xiàng)時，需要用搜索activity來處理這些intent。在這之前，搜索activity已經(jīng)對ACTION_SEARCH?intent進(jìn)行了處理。下面是如何在activity的onCreate()回調(diào)方法中處理intent的示例：

Intent?intent?=?getIntent();?

if?(Intent.ACTION_SEARCH.equals(intent.getAction()))?{?

? ??//?處理正常的搜索請求

? ??String?query?=?intent.getStringExtra(SearchManager.QUERY);?

? ? doSearch(query);?

}?else?if?(Intent.ACTION_VIEW.equals(intent.getAction()))?{?

? ??//?處理對建議項(xiàng)的點(diǎn)擊操作（因?yàn)榻ㄗh項(xiàng)都是使用ACTION_VIEW的）

? ??Uri?data?=?intent.getData();?

? ? showResult(data);?

}

在上例中，intent action是ACTION_VIEW，并且通過組合android:searchSuggestIntentData字符串和SUGGEST_COLUMN_INTENT_DATA_ID列，數(shù)據(jù)已包含了指向建議項(xiàng)的完整URI。該URI傳給本地的showResult()方法，對URI指定的建議項(xiàng)在content provider中執(zhí)行查詢。

注意：在Android manifest文件中，不需要對android:searchSuggestIntentAction屬性或SUGGEST_COLUMN_INTENT_ACTION列設(shè)定的intent action添加intent?過濾器。系統(tǒng)將根據(jù)名稱啟動搜索activity并傳遞建議項(xiàng)的intent，因此activity不需要對可接受的action進(jìn)行聲明。

?

改寫搜索請求文本

如果用戶使用方向控制設(shè)備（比如軌跡球或d-pad）來瀏覽建議項(xiàng)列表，則默認(rèn)情況下搜索請求文本不會被更新。不過可以暫時用當(dāng)前焦點(diǎn)所在的建議項(xiàng)來改寫用戶請求文本，讓它顯示在搜索文本框中。這樣就能讓用戶看到建議的請求文本（假如合適的話）并能在發(fā)送請求之前選中搜索框來編輯請求文本。

可以通過以下方式來改寫搜索請求文本：

a.?????在搜索配置文件中添加android:searchMode?屬性，并賦值為"queryRewriteFromText"?。這種情況下，建議項(xiàng)表的SUGGEST_COLUMN_TEXT_1列中的內(nèi)容將會用于改寫請求文本。

b.?????在搜索配置文件中添加android:searchMode?屬性，并賦值為"queryRewriteFromData"?。這種情況下，建議項(xiàng)表的SUGGEST_COLUMN_INTENT_DATA列中的內(nèi)容將會用于改寫請求文本。這只適用于用戶需要能看見URI或其它格式數(shù)據(jù)的場合，比如HTTP URL。內(nèi)部的URI格式不應(yīng)該使用這種方式來改寫請求文本。

c.?????在建議項(xiàng)表的SUGGEST_COLUMN_QUERY列內(nèi)提供唯一的請求文本串。如果當(dāng)前建議項(xiàng)的該列存在并且包含值，將被用于改寫請求文本（并且覆蓋上面的兩種方式）。

?

向“快速搜索框”提供搜索建議項(xiàng)

一旦把應(yīng)用程序配置成提供自定義搜索建議項(xiàng)的話，讓它適用于全局訪問的“快速搜索框”是很容易的，只要修改一下搜索配置文件，讓其包含值為"true"的android:includeInGlobalSearch屬性即可。

唯一要進(jìn)行額外工作的情況，就是需要向content provider請求讀權(quán)限的時候。這種情況下，需要添加<path-permission>元素，賦予“快速搜索框”對content provider的讀權(quán)限。例如：

<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>

在上例中，provider先規(guī)定了對content的讀和寫權(quán)限。<path-permission>元素修改了這個規(guī)定，當(dāng)存在"android.permission.GLOBAL_SEARCH"權(quán)限時，允許對路徑前綴為"/search_suggest_query"的內(nèi)容進(jìn)行讀取訪問。這樣就對“快速搜索框”賦予向content provider查詢建議項(xiàng)的權(quán)限。

如果content provider未明確指定讀權(quán)限，默認(rèn)情況下“快速搜索框”是可以讀取其中內(nèi)容的。

?

啟用設(shè)備上的建議項(xiàng)

即使已經(jīng)把應(yīng)用程序配置為向“快速搜索框”提供建議項(xiàng)，缺省情況下也不會真正生效。是否要在“快速搜索框”中包含應(yīng)用程序所提供的建議項(xiàng)，是需要由用戶選擇的。為了啟用應(yīng)用程序提供的搜索建議項(xiàng)，必須打開“可搜索的項(xiàng)”（在“搜索”的“搜索設(shè)置”菜單中）并指定應(yīng)用程序?yàn)榭伤阉黜?xiàng)。

每個可用于“快速搜索框”的應(yīng)用程序都會在“可搜索的項(xiàng)”設(shè)置頁面中有一個條目。條目中包含了應(yīng)用程序名稱和簡要描述信息，這些信息描述了應(yīng)用程序能夠搜索并提交給“快速搜索框”作為建議項(xiàng)的內(nèi)容。通過在搜索配置文件中添加android:searchSettingsDescription屬性，可以定義可搜索應(yīng)用程序的這些描述文字信息。例如：

<?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的值應(yīng)該盡可能地簡明扼要，能表明可搜索的內(nèi)容即可。比如：音樂程序可以用“藝術(shù)家、專輯和音軌”，記事本程序則可用“已保存的記錄”。提供這些描述信息是非常重要的，這樣用戶就知道有哪些建議項(xiàng)可用。當(dāng)android:includeInGlobalSearch的值為“true”時，應(yīng)該確保能包含該屬性。

請記住，用戶必須訪問設(shè)置菜單并為應(yīng)用程序啟用搜索建議項(xiàng)，然后搜索建議項(xiàng)才能出現(xiàn)在“快速搜索框中”。因此，假如搜索是應(yīng)用程序的重要特性之一，則可能需要考慮通過某種方式提醒用戶進(jìn)行設(shè)置——可以在第一次啟動應(yīng)用程序時提醒一下，告訴用戶如何啟用“快速搜索框”中的搜索建議項(xiàng)。

?

管理“快速搜索框”建議項(xiàng)的快捷方式

用戶在“快速搜索框”選中的建議項(xiàng)可以自動變?yōu)榭旖莘绞健＿@些快捷方式是系統(tǒng)從content provider中復(fù)制過來的建議項(xiàng)，這樣就能快速訪問建議項(xiàng)，而不必再次查詢content provider。

默認(rèn)情況下，“快速搜索框”所讀取的全部建議項(xiàng)都能啟用快捷方式。如果建議項(xiàng)數(shù)據(jù)經(jīng)過一段時間后發(fā)生了變化，可以發(fā)起刷新快捷方式的請求。舉例來說，如果建議項(xiàng)指向動態(tài)數(shù)據(jù)，比如聯(lián)系人的在線狀態(tài)，那就應(yīng)該在顯示給用戶的時候刷新建議項(xiàng)的快捷方式。只要在建議項(xiàng)表中包含SUGGEST_COLUMN_SHORTCUT_ID列即可實(shí)現(xiàn)這一目標(biāo)。利用該列可以把每個建議項(xiàng)的快捷方式配置為以下動作：

a.?????讓“快速搜索框”重新查詢content provider?，以獲取建議項(xiàng)快捷方式的最新版本。
在SUGGEST_COLUMN_SHORTCUT_ID列中指定一個值，每次顯示快捷方式時都會去查詢建議項(xiàng)的最新版本。刷新請求返回后，快捷方式將會與最新數(shù)據(jù)一起顯示出來，這時建議項(xiàng)已經(jīng)用最新信息刷新。刷新請求利用SUGGEST_URI_PATH_SHORTCUT的URI路徑發(fā)送至content provider，（而不是SUGGEST_URI_PATH_QUERY）。
返回的Cursor應(yīng)該包含數(shù)據(jù)列與原來相同的一條建議項(xiàng)，或者為空——表示快捷方式不可用了（這時，建議項(xiàng)將會消失，快捷方式也會被刪除）。
如果建議項(xiàng)指向數(shù)據(jù)的刷新可能需要耗費(fèi)很長時間，比如基于網(wǎng)絡(luò)的的刷新，則可以在建議項(xiàng)表中添加SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING列并賦值為“true”，這樣刷新時就會顯示為進(jìn)度滾輪圖標(biāo)。除“true”以外的任何值都不會顯示進(jìn)度滾輪。

b.?????完全阻止把建議項(xiàng)復(fù)制為快捷方式。
把SUGGEST_COLUMN_SHORTCUT_ID列賦值為SUGGEST_NEVER_MAKE_SHORTCUT。這時，建議項(xiàng)就不會復(fù)制為快捷方式了。僅當(dāng)確實(shí)不想讓以前復(fù)制過的建議項(xiàng)顯示出來，才會這么做。（如果在該列中提供正常的值并重新調(diào)用的話，建議項(xiàng)快捷方式將在刷新請求返回后才顯示出來。）

c.?????使用默認(rèn)的快捷方式動作。

建議項(xiàng)不會變化且可以保存為快捷方式，則保持SUGGEST_COLUMN_SHORTCUT_ID列為空即可。

如果建議項(xiàng)全都不會發(fā)生變化，那就根本不需要SUGGEST_COLUMN_SHORTCUT_ID列。

注意：上述值只是被視作應(yīng)用程序的需求而已，“快速搜索框”有權(quán)最終確定是否建立建議項(xiàng)的快捷方式，它并不保證指定的建議項(xiàng)快捷方式動作一定會實(shí)現(xiàn)。

?

關(guān)于“快速搜索框”建議項(xiàng)的級別

一旦應(yīng)用程序的搜索建議項(xiàng)能夠用于“快速搜索框”，則“快速搜索框”將會對其評級，并確定如何根據(jù)請求把建議項(xiàng)展現(xiàn)給用戶。這可能會依賴于有多少其它應(yīng)用程序也對該請求返回了結(jié)果，也可能會根據(jù)用戶選中哪個應(yīng)用程序來返回結(jié)果的頻度。建議項(xiàng)的評級并沒有固定的規(guī)則，對于給定的搜索請求是否顯示應(yīng)用程序的建議項(xiàng)也是不能保證的。可以大致這么認(rèn)為，高質(zhì)量的結(jié)果會增加建議項(xiàng)顯示在顯著位置的可能性，而低質(zhì)的建議項(xiàng)則更可能會獲得較低的級別或者干脆就不會顯示。

關(guān)于自定義搜索建議項(xiàng)的完整范例，請參閱支持檢索的字典例程。

轉(zhuǎn)載：http://www.cnblogs.com/over140/archive/2012/01/06/2314114.html

總結(jié)

以上是生活随笔為你收集整理的Android开发指南(42) —— Adding Custom Suggestions的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。