カスタムの検索候補を追加する

Android の検索ダイアログまたは検索ウィジェットを使用する場合、アプリ内のデータから作成されたカスタム検索候補を提供できます。たとえば、アプリが辞書の場合は、ユーザーがクエリの入力を完了する前に、検索フィールドに入力したテキストと一致する単語を辞書から候補として提示できます。これらの候補は、ユーザーが求めているものを効果的に予測し、すぐにアクセスできるようにできるため価値があります。図 1 は、カスタム候補が表示された検索ダイアログの例を示しています。

提示したカスタム候補をシステム全体のクイック検索ボックスでも使用できるようにして、アプリ外からコンテンツにアクセスできるようにします。

カスタム候補を追加する前に、アプリ内で検索を行うための Android 検索ダイアログまたは検索ウィジェットを実装します。検索インターフェースを作成するコンテンツ プロバイダをご覧ください。

基本情報

図 1. カスタム検索候補が表示された検索ダイアログのスクリーンショット。

ユーザーがカスタム候補を選択すると、検索可能なアクティビティに Intent が送信されます。ACTION_SEARCH アクションでインテントを送信する通常の検索クエリとは異なり、ACTION_VIEW またはその他のインテント アクションを使用し、選択した候補に関連するデータを含めるようにカスタム候補を定義できます。辞書の例では、ユーザーが候補を選択すると、アプリは辞書で一致を検索する代わりに、その単語の定義をすぐに開くことができます。

カスタム候補を表示する手順は次のとおりです。

  • 検索インターフェースを作成するの説明に従って、検索可能な基本的なアクティビティを実装します。
  • カスタム候補を提供するコンテンツ プロバイダに関する情報を使用して、検索可能な構成を変更します。
  • 提案用にテーブル(SQLiteDatabase 内など)を作成し、必要な列でテーブルをフォーマットします。
  • 候補テーブルにアクセスできるコンテンツ プロバイダを作成し、マニフェストでプロバイダを宣言します。
  • ユーザーが候補(カスタム アクションやカスタムデータなど)を選択したときに送信される Intent のタイプを宣言します。

Android システムが検索ダイアログを表示するのと同様に、検索候補も表示します。システムが候補を取得できるコンテンツ プロバイダが必要です。コンテンツ プロバイダの作成方法については、コンテンツ プロバイダをご覧ください。

アクティビティが検索可能であるとシステムが判断し、検索候補を提示すると、ユーザーがクエリを入力すると、以下の処理が行われます。

  1. システムは検索語句テキスト(これまでに入力された内容)を受け取り、候補を管理するコンテンツ プロバイダにクエリを実行します。
  2. コンテンツ プロバイダが、検索クエリテキストに関連するすべての候補を指す Cursor を返します。
  3. Cursor により提供される候補のリストが表示されます。

カスタム候補が表示された後、以下の処理が行われることがあります。

  • ユーザーが別の文字を入力するか、なんらかの方法でクエリを変更すると、上記の手順が繰り返され、それに応じて候補リストが更新されます。
  • ユーザーが検索を実行すると、候補は無視され、通常の ACTION_SEARCH インテントを使用して、検索可能なアクティビティに検索が配信されます。
  • ユーザーが候補を選択すると、インテントが検索可能なアクティビティに送信され、カスタム アクションとカスタムデータが渡され、アプリが候補コンテンツを開くことができます。

検索可能な構成を変更する

カスタム候補のサポートを追加するには、次の例に示すように、検索可能な構成ファイルの <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>

各候補に添付するインテントのタイプや、コンテンツ プロバイダに対するクエリのフォーマット方法によっては、追加の属性が必要になることがあります。その他の省略可能な属性については、次のセクションで説明します。

コンテンツ プロバイダを作成する

カスタム候補用のコンテンツ プロバイダを作成するには、まずコンテンツ プロバイダでコンテンツ プロバイダの作成方法をご確認ください。カスタム候補のコンテンツ プロバイダは、他のコンテンツ プロバイダと同様です。ただし、提示する提案ごとに、Cursor の各行に、システムが認識し、提案のフォーマットに使用する特定の列を含める必要があります。

ユーザーが検索ダイアログまたは検索ウィジェットでテキストを入力すると、文字が入力されるたびに query() を呼び出して、コンテンツ プロバイダに候補を照会します。query() の実装では、コンテンツ プロバイダは候補データを検索し、適切な候補であると判断する行を指す Cursor を返す必要があります。

カスタム候補用のコンテンツ プロバイダの作成の詳細については、次の 2 つのセクションで説明します。

候補のクエリを処理する
システムがコンテンツ プロバイダにリクエストを送信する方法と、その処理方法。
候補テーブルを作成する
各クエリで返される Cursor にシステムが想定する列を定義する方法。

候補のクエリを処理する

システムは、コンテンツ プロバイダに提案をリクエストすると、コンテンツ プロバイダの query() メソッドを呼び出します。このメソッドを実装して候補データを検索し、関連する候補を参照する Cursor を返します。

以下では、システムが query() メソッドに渡すパラメータの概要を以下の順序で示します。

  1. 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 の部分が URI に含まれるのは、検索可能な構成ファイルで android:searchSuggestPath 属性を使用してこのようなパスを設定した場合のみです。この属性が必要になるのは、複数の検索可能なアクティビティに対して同じコンテンツ プロバイダを使用する場合のみです。この場合は、提案クエリのソースを明確化します。

  2. projection
    常に null です。
  3. selection
    検索可能な構成ファイルの android:searchSuggestSelection 属性で指定された値。android:searchSuggestSelection 属性を宣言していない場合は null。次のセクションで、詳しく説明します。
  4. selectionArgs
    検索可能な構成で android:searchSuggestSelection 属性を宣言している場合、検索クエリが配列の最初の唯一の要素として格納されます。android:searchSuggestSelection を宣言しない場合、このパラメータは null になります。次のセクションで、詳しく説明します。
  5. sortOrder
    常に null です。

システムは検索クエリのテキストを 2 つの方法で送信できます。デフォルトでは、uri パラメータで渡されるコンテンツ URI の最後のパスとしてクエリテキストが含まれます。ただし、検索可能構成の android:searchSuggestSelection 属性に選択値を含めると、クエリテキストが selectionArgs 文字列配列の最初の要素として渡されます。次に、この 2 つのオプションについて説明します。

URI でクエリを取得する

デフォルトでは、クエリは uri パラメータの最後のセグメント(Uri オブジェクト)として追加されます。この場合にクエリテキストを取得するには、次の例のように getLastPathSegment() を使用します。

Kotlin

val query: String = uri.lastPathSegment.toLowerCase()

Java

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

これは、Uri の最後のセグメント(ユーザーが入力したクエリテキスト)を返します。

選択引数でクエリを取得する

URI を使用するよりも、query() メソッドでルックアップの実行に必要なものをすべて受け取る方が理にかなっています。また、selection パラメータと selectionArgs パラメータで適切な値を指定することも可能です。この場合は、SQLite 選択文字列を使用して、検索可能な構成に android:searchSuggestSelection 属性を追加します。選択文字列には、実際の検索クエリのプレースホルダとして疑問符(?)を含めます。システムは、選択文字列を selection パラメータとして、検索クエリを selectionArgs 配列の最初の要素として、query() を呼び出します。

たとえば、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 パラメータに追加するか、接頭辞に追加します。この値は引用符で囲まれ、疑問符の代わりに挿入されるためです。

上記の例のもう 1 つの属性は android:searchSuggestIntentAction です。これは、ユーザーが候補を選択したときに各インテントで送信されるインテント アクションを定義します。詳細については、候補のインテントを宣言するのセクションをご覧ください。

候補テーブルを作成する

Cursor を使用してシステムに提案を返す場合、システムは各行に特定の列があると想定します。候補のデータをデバイスの SQLite データベース、ウェブサーバーのデータベース、デバイスまたはウェブ上の別の形式のいずれに保存するかにかかわらず、候補をテーブル内に行としてフォーマットし、Cursor で表示します。

システムでは複数の列が認識されますが、必要な列はそのうちの 2 つだけです。

_ID
各候補の一意の行 ID(整数)。システムが ListView で候補を提示するには、この必要があります。
SUGGEST_COLUMN_TEXT_1
候補として表示される文字列。

以下の列はすべて省略可能です。これらについては、以降のセクションで詳しく説明します。

SUGGEST_COLUMN_TEXT_2
文字列。Cursor にこの列が含まれている場合、すべての候補が 2 行形式で表示されます。この列の文字列は、メインの候補テキストの下に 2 番目の小さい行として表示されます。第二のテキストを表示しない場合は、null を指定するか、空にします。
SUGGEST_COLUMN_ICON_1
ドローアブル リソース、コンテンツ、またはファイル URI の文字列。Cursor にこの列が含まれている場合、すべての候補がアイコンとテキストの形式で表示され、ドローアブル アイコンが左側に表示されます。この行にアイコンがない場合、null またはゼロになります。
SUGGEST_COLUMN_ICON_2
ドローアブル リソース、コンテンツ、またはファイル URI の文字列。Cursor にこの列が含まれている場合、すべての候補がアイコンとテキストの形式で、右側にアイコン付きで表示されます。この行にアイコンがない場合、null またはゼロになります。
SUGGEST_COLUMN_INTENT_ACTION
インテント アクションの文字列。この列が存在し、所定の行に値が含まれている場合、ここで定義されたアクションが候補のインテントの形成時に使用されます。この要素が指定されていない場合、アクションは検索可能な構成の android:searchSuggestIntentAction フィールドから取得されます。アクションがすべての提案で同じ場合は、android:searchSuggestIntentAction を使用してアクションを指定し、この列を省略したほうが効率的です。
SUGGEST_COLUMN_INTENT_DATA
データ URI の文字列。この列が存在し、所定の行に値が含まれている場合、このデータは候補のインテントの形成時に使用されます。この要素が指定されていない場合、データは検索可能な構成の android:searchSuggestIntentData フィールドから取得されます。どちらのソースも指定されていない場合、インテントのデータ フィールドは null になります。すべての候補でデータが同一の場合、または定数部分と特定の ID を使用して記述できる場合は、android:searchSuggestIntentData を使用してデータを指定し、この列を省略するほうが効率的です。
SUGGEST_COLUMN_INTENT_DATA_ID
URI パスの文字列。この列が存在し、指定された行に値が含まれている場合、「/」とこの値がインテントのデータ フィールドに追加されます。これは、検索可能構成の android:searchSuggestIntentData 属性で指定されたデータ フィールドがすでに適切なベース文字列に設定されている場合にのみ使用します。
SUGGEST_COLUMN_INTENT_EXTRA_DATA
任意のデータ。この列が存在し、特定の行に値が含まれている場合、これは候補のインテントの形成時に使用されるエクストラ データです。指定されていない場合、インテントの追加データ フィールドは null になります。この列を使用すると、インテントの 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 です。これは、単語の定義、個人の連絡先情報、ウェブページなど、何かを開く場合に適しています。ただし、インテントのアクションは他の任意のアクションにすることができ、また候補ごとに異なるアクションにすることもできます。

すべての候補で同じインテントのアクションを使用するかどうかに応じて、次の 2 つの方法でアクションを定義できます。

  • 次の例に示すように、検索可能な構成ファイルの 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" など)をその列に配置します。

この 2 つの方法を組み合わせることも可能です。たとえば、android:searchSuggestIntentAction 属性に、すべての提案でデフォルトで使用するアクションを組み込み、SUGGEST_COLUMN_INTENT_ACTION 列で別のアクションを宣言して、このアクションを一部の提案でオーバーライドできます。SUGGEST_COLUMN_INTENT_ACTION 列に値を含めない場合、android:searchSuggestIntentAction 属性で指定されたインテントが使用されます。

インテント データを宣言する

ユーザーが候補を選択すると(前のセクションで説明したように)、検索可能なアクティビティは定義されたアクションを含むインテントを受け取りますが、インテントには、選択された候補を識別するためのアクティビティのデータも渡す必要があります。具体的には、データは候補ごとに一意のもの(SQLite テーブル内の候補の行 ID など)である必要があります。インテントを受信したら、getData() または getDataString() を使用して添付データを取得できます。

インテントに含めるデータは、次の 2 つの方法で定義できます。

  • 候補テーブルの SUGGEST_COLUMN_INTENT_DATA 列内で、各候補のデータを定義します。

    SUGGEST_COLUMN_INTENT_DATA 列を追加してから行ごとに一意のデータを入力し、候補テーブルの各インテントに必要なすべてのデータ情報を提供します。この列のデータは、この列で定義したとおりにインテントに関連付けられます。その後、getData() または getDataString() で取得できます。

  • データ URI を 2 つに分割します。すべての提案に共通する部分と、各提案に固有の部分です。これらの部分をそれぞれ検索可能構成の android:searchSuggestintentData 属性と候補テーブルの SUGGEST_COLUMN_INTENT_DATA_ID 列に配置します。

    次の例は、検索可能な構成の android:searchSuggestIntentData 属性内のすべての候補に共通する 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>
      

    各候補の最終パス(一意の部分)を候補テーブルの SUGGEST_COLUMN_INTENT_DATA_ID 列に含めます。ユーザーが候補を選択すると、システムは android:searchSuggestIntentData から文字列を取得し、スラッシュ(/)を加え、SUGGEST_COLUMN_INTENT_DATA_ID 列からそれぞれの値を追加して、完全なコンテンツ URI を作成します。その後、getData()Uri を取得できます。

データの追加

インテントを使用してより多くの情報を表現する必要がある場合は、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 であり、データには、android:searchSuggestIntentData 文字列と SUGGEST_COLUMN_INTENT_DATA_ID 列で合成された候補アイテムを指す完全な URI が含まれています。この URI はローカルの showResult() メソッドに渡されます。このメソッドは URI で指定されたアイテムをコンテンツ プロバイダに問い合わせます。

質問文を書き換える

デフォルトでは、ユーザーがトラックボールや D-pad などの方向コントロールを使用して候補リスト内を移動しても、クエリテキストは更新されません。ただし、テキスト ボックスに表示されているユーザーのクエリテキストを、フォーカスされている候補に一致するクエリで一時的に書き換えることができます。これにより、ユーザーは提案されているクエリを確認し、検索ボックスを選択してクエリを編集してから、検索として送信することができます。

クエリテキストは以下の方法で書き換えることができます。

  • "queryRewriteFromText" 値を使用して、android:searchMode 属性を検索可能な構成に追加します。この場合、候補の SUGGEST_COLUMN_TEXT_1 列の内容がクエリテキストの書き換えに使用されます。
  • "queryRewriteFromData" 値を使用して、android:searchMode 属性を検索可能構成に追加します。この場合、候補の SUGGEST_COLUMN_INTENT_DATA 列の内容がクエリテキストの書き換えに使用されます。これは、HTTP URL など、ユーザーに表示されることを意図した URI やその他のデータ形式でのみ使用してください。内部 URI スキームを使用してクエリを書き換えないでください。
  • 候補テーブルの SUGGEST_COLUMN_QUERY 列に一意のクエリ文字列を指定します。この列が存在し、現在の候補の値が含まれている場合、この列はクエリテキストを書き換えて、以前の実装のいずれかをオーバーライドするために使用されます。

クイック検索ボックスに検索候補を表示する

カスタム検索候補を表示するようにアプリを設定すると、検索可能な構成を変更して値 "true" を指定して、簡単にグローバルにアクセス可能なクイック検索ボックスから候補を表示できるようになります。android:includeInGlobalSearch

追加の作業が必要なシナリオは、コンテンツ プロバイダが読み取り権限を要求する場合のみです。その場合、次の例のように、プロバイダの <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> 要素は、"android.permission.GLOBAL_SEARCH" 権限が存在する場合に、"/search_suggest_query" パス プレフィックス内のコンテンツへの読み取りアクセス権を付与することで、制限を修正します。クイック検索ボックスへのアクセスが許可され、コンテンツ プロバイダに対して候補を照会できるようになります。

コンテンツ プロバイダが読み取り権限を適用していない場合、クイック検索ボックスはデフォルトで読み取ります。

デバイスで候補リストの表示を有効にする

デフォルトでは、アプリは、設定されていてもクイック検索ボックスに候補を表示できません。ユーザーは、アプリから候補をクイック検索ボックスに含めるかどうかを選択するには、[設定] > [検索] にある [検索可能な項目] を開き、アプリを検索可能なアイテムとして有効にします。

クイック検索ボックスから使用できる各アプリの [検索対象] 設定ページにエントリがあります。このエントリには、アプリの名前と、アプリから検索でき、クイック検索ボックスで候補に提示するコンテンツの簡単な説明が含まれます。検索可能なアプリの説明テキストを定義するには、次の例に示すように、検索可能な設定に 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_QUERY ではなく SUGGEST_URI_PATH_SHORTCUT の URI パスを使用してコンテンツ プロバイダに送信されます。

    返す Cursor に、元の提案と同じ列を使用した 1 つの提案を含めるか、ショートカットが無効であることを示す空にします。その場合、提案が消えて、ショートカットが削除されます。

    ネットワーク ベースの更新など、更新に時間がかかるデータを候補が参照する場合は、値を true に設定して SUGGEST_COLUMN_SPINNER_WHILE_REFRESHING 列を候補テーブルに追加して、更新が完了するまで右側のアイコンに進行状況スピナーを表示することもできます。true 以外の値の場合、進行状況スピナーは表示されません。

  • 候補がショートカットにコピーされないようにします。

    SUGGEST_COLUMN_SHORTCUT_ID 列に SUGGEST_NEVER_MAKE_SHORTCUT の値を指定します。この場合、候補はショートカットにコピーされません。これは、以前にコピーした候補を絶対に表示しない場合にのみ必要です。列に通常の値を指定した場合、更新クエリが返されるまでは、候補のショートカットが表示されます。

  • デフォルトのショートカットの動作を適用します。

    変更されず、ショートカットとして保存できる候補については、SUGGEST_COLUMN_SHORTCUT_ID を空のままにします。

提案がまったく変化しない場合は、SUGGEST_COLUMN_SHORTCUT_ID 列は必要ありません。

クイック検索ボックスの候補のランキングについて

アプリの検索候補をクイック検索ボックスで利用できるようにすると、クイック検索ボックスのランキングによって、特定のクエリに対する候補がユーザーに表示される方法が決まります。これは、そのクエリに対する結果を持つ他のアプリの数や、他のアプリから結果を選択する場合と比較した、ユーザーが結果を選択する頻度によって異なる場合があります。候補がランク付けされる仕組みや、特定のクエリに対してアプリの候補がまったく表示されるかどうかは保証されません。一般的に、質の高い結果を提供すると、アプリの候補が目立つ位置に表示される可能性が高くなります。また、品質の低い候補を提供するアプリは、順位が下がったり、表示されない可能性が高くなります。