新增自訂搜尋建議

您可以在 Android 搜尋對話方塊中根據最近的搜尋查詢提供搜尋建議，或是 搜尋小工具。例如，如果使用者查詢「小狗」系統會顯示建議項目 再次輸入相同的查詢圖 1 顯示含有最近查詢的搜尋對話方塊範例 或取得寫作建議

開始之前，請先實作搜尋對話方塊或基本搜尋的搜尋小工具 應用程式。若要瞭解操作方式，請參閱 建立搜尋介面。

基本概念

圖 1. 顯示最近查詢的搜尋對話方塊螢幕截圖 或取得寫作建議

近期查詢建議是儲存的搜尋項目。使用者選取建議後，您就能搜尋 活動收到 ACTION_SEARCH意圖 做為可供搜尋活動使用的搜尋查詢。

如要提供近期查詢建議，您必須：

  • 實作可供搜尋的活動。
  • 建立 SearchRecentSuggestionsProvider 並在應用程式資訊清單中進行宣告
  • 根據提供的內容供應器相關資訊修改可供搜尋的設定 搜尋建議。
  • 每次執行搜尋時，將查詢儲存至內容供應器。

如同 Android 系統顯示搜尋對話方塊，也會在下方顯示搜尋建議 對話方塊或搜尋小工具。請提供系統擷取建議的來源。

如果系統發現您的活動可供搜尋，並提供搜尋建議， 當使用者輸入查詢時會發生下列情況：

  1. 系統會接收搜尋查詢文字 (不論使用者開始輸入什麼內容)， 對包含您建議的內容供應器執行查詢。
  2. 內容供應者會傳回 Cursor，指向所有顧客 符合搜尋查詢文字的建議
  3. 系統會顯示 Cursor 提供的建議清單。

系統顯示近期查詢建議後，可能會發生下列情況：

  • 當使用者輸入其他鍵或以任何方式變更查詢時，上述步驟 系統就會更新建議清單
  • 如果使用者執行搜尋，系統會忽略建議並將搜尋傳送至 使用一般 ACTION_SEARCH 意圖的搜尋活動。
  • 如果使用者選取建議，系統會將 ACTION_SEARCH 意圖傳送至您的 使用建議文字做為查詢內容，即可搜尋活動。

您為內容供應器擴充的 SearchRecentSuggestionsProvider 類別 自動執行上述步驟，因此您不必編寫程式碼。

建立內容供應器

需要的內容供應器就是 SearchRecentSuggestionsProvider。這個課程會為您完成所有工作。您只需要 編寫可執行一行程式碼的類別建構函式。

舉例來說，以下是近期查詢內容供應器的完整實作方式 建議：

Kotlin

class MySuggestionProvider : SearchRecentSuggestionsProvider() {
    init {
        setupSuggestions(AUTHORITY, MODE)
    }

    companion object {
        const val AUTHORITY = "com.example.MySuggestionProvider"
        const val MODE: Int = SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES
    }
}

Java

public class MySuggestionProvider extends SearchRecentSuggestionsProvider {
    public final static String AUTHORITY = "com.example.MySuggestionProvider";
    public final static int MODE = DATABASE_MODE_QUERIES;

    public MySuggestionProvider() {
        setupSuggestions(AUTHORITY, MODE);
    }
}

呼叫 setupSuggestions() 會傳送搜尋授權的名稱和資料庫模式。搜尋引擎可以是任何獨一無二的 但最佳做法是為內容供應器使用完整的名稱，例如 套件名稱後面加上供應器的類別名稱。例如 "com.example.MySuggestionProvider"。

資料庫模式必須包含 DATABASE_MODE_QUERIES 並視需要納入 DATABASE_MODE_2LINES, 在建議表格中加入一欄，方便您提供第二行文字 建議。如要為每個建議內容提供兩行內容，請參閱以下範例：

Kotlin

const val MODE: Int = DATABASE_MODE_QUERIES or DATABASE_MODE_2LINES

Java

public final static int MODE = DATABASE_MODE_QUERIES | DATABASE_MODE_2LINES;

使用應用程式資訊清單中的主機名稱字串，宣告應用程式資訊清單中的內容供應器 SearchRecentSuggestionsProvider 類別以及可供搜尋的設定。例如：

<application>
    <provider android:name=".MySuggestionProvider"
              android:authorities="com.example.MySuggestionProvider" />
    ...
</application>

修改可供搜尋的設定

如要設定系統使用建議供應程式，請將 「android:searchSuggestAuthority」和「android:searchSuggestSelection」 屬性新增至可搜尋設定檔中的 <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.MySuggestionProvider"
    android:searchSuggestSelection=" ?" >
</searchable>

android:searchSuggestAuthority 的值必須是您 與內容供應器所用授權完全相符的內容供應器，例如 "com.example.MySuggestionProvider"。

android:searchSuggestSelection 的值必須在前面加上一個問號 分組依據：" ?"。這是 SQLite 選取引數的預留位置， 自動替換為使用者輸入的查詢文字。

儲存查詢

如要在近期收集的所有查詢中填入資料，請新增可搜尋的每個查詢 「SearchRecentSuggestionsProvider」的活動。方法是建立 SearchRecentSuggestions 並撥號 saveRecentQuery() 每次可供搜尋的活動收到查詢時。以下舉例說明如何儲存查詢 期間 onCreate() 方法：

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.main)

    if (Intent.ACTION_SEARCH == intent.action) {
        intent.getStringExtra(SearchManager.QUERY)?.also { query ->
            SearchRecentSuggestions(this, MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE)
                    .saveRecentQuery(query, null)
        }
    }
}

Java

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);

    Intent intent  = getIntent();

    if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
        String query = intent.getStringExtra(SearchManager.QUERY);
        SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
                MySuggestionProvider.AUTHORITY, MySuggestionProvider.MODE);
        suggestions.saveRecentQuery(query, null);
    }
}

SearchRecentSuggestionsProvider 建構函式需要 內容供應器所宣告的相同授權和資料庫模式。

saveRecentQuery() 方法會將搜尋查詢字串做為第一個參數 並視需要加入第二個字串，做為建議的第二行或空值。第二個 參數只有在您使用含有 DATABASE_MODE_2LINES。如果啟用兩行模式，系統就會將查詢文字與 系統尋找相符的建議時，第二行。

清除建議資料

為了保護使用者隱私，請一律提供使用者清除近期查詢內容的方法 或取得寫作建議如要清除查詢記錄，請呼叫 clearHistory()。 例如：

Kotlin

SearchRecentSuggestions(this, HelloSuggestionsProvider.AUTHORITY, HelloSuggestionsProvider.MODE)
        .clearHistory()

Java

SearchRecentSuggestions suggestions = new SearchRecentSuggestions(this,
        HelloSuggestionProvider.AUTHORITY, HelloSuggestionProvider.MODE);
suggestions.clearHistory();

透過 [清除搜尋記錄] 選項執行此作業選單項目、偏好設定項目或按鈕 顯示確認對話方塊，確認使用者要刪除自己的搜尋記錄。