検索構成

Compose をお試しください
Jetpack Compose は、Android で推奨される UI ツールキットです。Compose で検索機能を追加する方法について説明します。
検索バー →

Android システムがサポートする検索を実装するためには（検索クエリをアクティビティに渡したり、検索候補を表示したりするためには）、アプリで XML ファイルの形式で検索構成を指定する必要があります。

このページでは、検索構成ファイルの構文と使用法について説明します。アプリに検索機能を実装する方法について詳しくは、検索インターフェースを作成するをご覧ください。

ファイルの場所:
res/xml/filename.xml
Android ではリソース ID としてファイル名を使用します。
構文:
<?xml version="1.0" encoding="utf-8"?>
<searchable xmlns:android="http://schemas.android.com/apk/res/android"
    android:label="string resource"
    android:hint="string resource"
    android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"]
    android:searchButtonText="string resource"
    android:inputType="inputType"
    android:imeOptions="imeOptions"
    android:searchSuggestAuthority="string"
    android:searchSuggestPath="string"
    android:searchSuggestSelection="string"
    android:searchSuggestIntentAction="string"
    android:searchSuggestIntentData="string"
    android:searchSuggestThreshold="int"
    android:includeInGlobalSearch=["true" | "false"]
    android:searchSettingsDescription="string resource"
    android:queryAfterZeroResults=["true" | "false"]
    android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"]
    android:voiceLanguageModel=["free-form" | "web_search"]
    android:voicePromptText="string resource"
    android:voiceLanguage="string"
    android:voiceMaxResults="int"
    >
    <actionkey
        android:keycode="KEYCODE"
        android:queryActionMsg="string"
        android:suggestActionMsg="string"
        android:suggestActionMsgColumn="string" />
</searchable>
要素:
<searchable>
Android システムがサポートする検索を提供するために使用する検索構成をすべて定義します。

属性:

android:label
文字列リソース。（必須）。アプリの名前。この名前は、<activity> または <application> マニフェスト要素の android:label 属性に適用される名前と同じにする必要があります。このラベルは、android:includeInGlobalSearch を "true" に設定した場合にのみユーザーに表示されます。その場合、システムの検索設定でこのラベルを使用して、アプリを検索対象として指定できます。
android:hint
文字列リソース。（推奨）。テキストが入力されていない場合に検索テキスト フィールドに表示するテキスト。検索可能なコンテンツについてのヒントをユーザーに提供します。他の Android アプリとの整合性を保つために、android:hint の文字列は「<content-or-product> を検索」の形式にする必要があります（例: 「曲とアーティストを検索」、「YouTube を検索」）。
android:searchMode
キーワード。検索の固定表示を制御する追加のモードを設定します。使用可能なモードで、カスタム候補がフォーカスを受け取ったときにクエリテキストを書き換える方法を定義します。指定できるモードの値は次のとおりです。
値説明
"queryRewriteFromData" SUGGEST_COLUMN_INTENT_DATA 列の値を使用してクエリテキストを書き換えます。これは、SUGGEST_COLUMN_INTENT_DATA の値がユーザーによる検査や編集に適している場合（HTTP URI など）にのみ使用します。
"queryRewriteFromText" SUGGEST_COLUMN_TEXT_1 列の値を使用してクエリテキストを書き換えます。

詳しくは、カスタム検索候補を追加するでクエリテキストの書き換えについての説明をご覧ください。

android:searchButtonText
文字列リソース。検索の実行ボタンに表示するテキスト。デフォルトでは、このボタンを押すと、多言語対応に最適な検索アイコン（虫メガネ）が表示されます。そのため、動作が検索以外のもの（ウェブブラウザでの URL リクエストなど）でない限り、この属性を使用してボタンを変更しないでください。
android:inputType
キーワード。使用する入力方法のタイプ（ソフト キーボードのタイプなど）を定義します。ほとんどの検索では自由形式のテキストが要求されるため、この属性は必要ありません。この属性に適した値の一覧については、inputType をご覧ください。
android:imeOptions
キーワード。入力方法の追加オプションを指定します。ほとんどの検索では自由形式のテキストが要求されるため、この属性は必要ありません。デフォルトの IME は actionSearch で、ソフト キーボードで、改行の代わりに「検索」ボタンが表示されます。この属性に適した値の一覧については、imeOptions をご覧ください。

検索候補の属性

検索候補を生成するようにコンテンツ プロバイダを定義した場合、コンテンツ プロバイダとの通信を構成する追加の属性を定義する必要があります。検索候補を表示する場合、以下の <searchable> 属性の一部が必要になります。


android:searchSuggestAuthority
文字列。（検索候補を表示する場合は必須）。この値は、Android マニフェストの <provider> 要素の android:authorities 属性で指定されている権限文字列と一致する必要があります。
android:searchSuggestPath
文字列。このパスは候補のクエリ Uri の一部として、プレフィックスと権限の後、かつ標準の候補パスの前で使用されます。この属性が必要なのは、単一のコンテンツ プロバイダでさまざまな種類の候補（さまざまなデータタイプが存在する場合など）を発行し、候補のクエリを受け取ったときにその曖昧さを解消する方法が必要な場合だけです。
android:searchSuggestSelection
文字列。この値は selection パラメータとしてクエリ関数に渡されます。通常、これはデータベースの WHERE 句であり、ユーザーが入力した実際のクエリ文字列のプレースホルダとして 1 つの疑問符（"query=?" など）を含んでいる必要があります。ただし、selectionArgs パラメータを使用してクエリテキストの配信をトリガーし、selection パラメータを無視するために、null 以外の値を使用することもできます。
android:searchSuggestIntentAction
文字列。ユーザーがカスタム検索候補をタップしたときに使用されるデフォルトのインテント アクション（"android.intent.action.VIEW" など）。SUGGEST_COLUMN_INTENT_ACTION 列を使用して選択された候補によってこの値がオーバーライドされない場合、ユーザーが候補をタップしたときにこの値が Intent のアクション フィールドに入力されます。
android:searchSuggestIntentData
文字列。ユーザーがカスタム検索候補をタップしたときに使用されるデフォルトのインテント データ。（SUGGEST_COLUMN_INTENT_DATA 列で）選択された候補によってオーバーライドされない場合、ユーザーが候補をタップしたときにこの値が Intent のデータ フィールドに入力されます。
android:searchSuggestThreshold
整数。候補の検索をトリガーするために必要な最小文字数。システムがコンテンツ プロバイダに対して、このしきい値より短い文字列を照会しないことだけが保証されます。デフォルト値は 0 です。

検索候補の上記の属性について詳しくは、カスタム検索候補の追加とカスタム候補の追加に関するドキュメントをご覧ください。

クイック検索ボックスの属性

カスタム検索候補をクイック検索ボックスで使用できるようにするには、以下の <searchable> 属性の一部が必要になります。


android:includeInGlobalSearch
ブール値。（クイック検索ボックスに検索候補を表示する場合は必須）。グローバルにアクセス可能なクイック検索ボックスに候補を表示する場合は "true" に設定します。ただし、候補がクイック検索ボックスに表示される前に、ユーザーがシステムの検索設定でアプリを検索対象として有効にする必要があります。
android:searchSettingsDescription
文字列リソース。クイック検索ボックスに表示する検索候補の簡単な説明を指定します。この説明がアプリの検索対象のエントリに表示されます。説明は、検索可能なコンテンツについて簡潔に記述する必要があります。たとえば、音楽アプリの場合は「アーティスト、アルバム、トラック」、NotePad アプリの場合は「保存したメモ」といった具合です。
android:queryAfterZeroResults
ブール値。以前に 0 件の結果を返したことがあるクエリのスーパーセットに対してコンテンツ プロバイダを呼び出す場合は "true" に設定します。たとえば、コンテンツ プロバイダが「bo」に対して 0 件の結果を返した場合、「bob」を再クエリする必要があります。"false" に設定すると、単一のセッションではスーパーセットが無視されます（「bob」の再クエリは行われません）。この動作は、検索ウィジェットの使用時に検索ダイアログが表示されている間、またはアクティビティが実行されている間だけ継続されます。検索ダイアログまたはアクティビティが再表示されると、「bo」のクエリがコンテンツ プロバイダに対して再び行われます。デフォルト値は false です。

音声検索の属性

音声検索を有効にするには、以下の <searchable> 属性の一部が必要になります。


android:voiceSearchMode
キーワード。（音声検索機能を提供する場合は必須）。音声検索の特定のモードで音声検索を有効にしますデバイスが音声検索機能を提供していないこともあり、その場合はこれらのフラグを設定しても効果がありません。指定できるモードの値は次のとおりです。
値説明
"showVoiceSearchButton" デバイスで音声検索を使用できる場合に音声検索ボタンを表示します。設定する場合、"launchWebSearch" または "launchRecognizer" も設定する必要があります（パイプ文字（|）で区切ります）。
"launchWebSearch" 音声検索ボタンをクリックすると、組み込みのウェブ音声検索アクティビティに直接移動します。ただし、検索が呼び出されたアクティビティから離れてしまうため、ほとんどのアプリではこのフラグは使用されません。
"launchRecognizer" 音声検索ボタンをクリックすると、組み込みの録音アクティビティに直接移動します。このアクティビティは、ユーザーに話すよう促し、ユーザーが話した内容を文字に起こして、ユーザーが検索 UI に入力して検索ボタンをタップした場合と同じように、生成されたクエリテキストを検索可能なアクティビティに転送します。
android:voiceLanguageModel
キーワード。音声認識システムで使用する必要がある言語モデル。指定できる値は次のとおりです。
値説明
"free_form" 自由形式の音声認識を使用してクエリを音声入力します。この値は主に英語向けに最適化されています。これがデフォルトです。
"web_search" 検索に似た短いフレーズの場合にウェブ検索キーワード認識を使用します。この値は "free_form" より多くの言語で使用できます。

詳しくは、EXTRA_LANGUAGE_MODEL をご覧ください。

android:voicePromptText
文字列リソース。音声入力ダイアログに表示する追加メッセージ。
android:voiceLanguage
文字列。求められる音声の言語。定数の文字列値として Locale で表されます（ドイツ語の場合は "de"、フランス語の場合は "fr" など）。Locale.getDefault() の現在の値と異なる場合にのみ指定する必要があります。
android:voiceMaxResults
整数。返す結果の最大数（ACTION_SEARCH インテントの主クエリとして常に提供される「最適な」結果を含む）を設定します。1 以上を指定する必要があります。インテントから結果を取得するには、EXTRA_RESULTS を使用します。指定されていない場合、返す結果の数を認識ツールが選択します。
<actionkey>
検索アクションのデバイスキーと動作を定義します。検索アクションは、デバイスのボタンがタップされたときに、現在のクエリまたはフォーカスされている候補に基づいて特別な動作を提供します。たとえば連絡先アプリは、通話ボタンがタップされたときに現在フォーカスされている連絡先候補への通話を開始するための検索アクションを提供します。

すべてのアクションキーをすべてのデバイスで使用できるわけではありません。また、すべてのキーをこの方法でオーバーライドできるわけでもありません。たとえば、「ホーム」キーはオーバーライドできず、常にホーム画面に戻る必要があります。また、検索クエリの入力に必要なキーに対するアクションキーは定義しないでください。こうすることで、通話ボタンとメニューボタンで使用できる妥当なアクションキーが制限されます。

検索アクションを定義するためには、android:keycode を定義し、キーと、他の 3 つの属性のうち少なくとも 1 つを定義する必要があります。

属性:

android:keycode
文字列。（必須）。応答するアクションキーを表す KeyEvent のキーコード（例: "KEYCODE_CALL"）。これは、検索可能なアクティビティに渡される ACTION_SEARCH インテントに追加されます。このキーコードを調べるには、getIntExtra(SearchManager.ACTION_KEY) を使用します。すべてのキーが検索アクション用にサポートされているわけではありませんが、その多くが入力、ナビゲーション、システム機能で使用されています。
android:queryActionMsg
文字列。ユーザーがクエリテキストを入力している間にアクションキーが押された場合に送信されるアクション メッセージ。これは、システムが検索可能なアクティビティに渡す ACTION_SEARCH インテントに追加されます。この文字列を調べるには、getStringExtra(SearchManager.ACTION_MSG) を使用します。
android:suggestActionMsg
文字列。候補がフォーカスされている間にアクションキーが押された場合に送信されるアクション メッセージ。これは、システムが検索可能なアクティビティに渡すインテントに追加されます（候補に対して定義したアクションを使用）。この文字列を調べるには、getStringExtra(SearchManager.ACTION_MSG) を使用します。この属性は、すべての候補がこのアクションキーをサポートしている場合にのみ使用してください。すべての候補が同じアクションキーを処理できるわけではない場合は、代わりに次の android:suggestActionMsgColumn 属性を使用する必要があります。
android:suggestActionMsgColumn
文字列。このアクションキーのアクション メッセージを定義する、コンテンツ プロバイダ内の列の名前。候補がフォーカスされている間にユーザーがアクションキーを押すと、このメッセージが送信されます。この属性を使用すると、候補ごとにアクションキーを管理できます。これは、android:suggestActionMsg 属性を使用してすべての候補のアクション メッセージを定義するのではなく、コンテンツ プロバイダの各エントリが独自のアクション メッセージを提供するためです。

まず、アクション メッセージを提供する各候補のコンテンツ プロバイダで列を定義し、その列の名前をこの属性で指定する必要があります。システムが候補のカーソルを確認し、ここで提供される文字列を使用してアクション メッセージの列を選択します。さらに、カーソルからアクション メッセージの文字列を選択します。この文字列は、システムが検索可能なアクティビティに渡すインテントに追加されます（候補に対して定義したアクションを使用）。この文字列を調べるには、getStringExtra(SearchManager.ACTION_MSG) を使用します。選択した候補のデータが存在しない場合、アクションキーは無視されます。

例:
res/xml/searchable.xml に保存された XML ファイル: 
<?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:searchSuggestAuthority="dictionary"
    android:searchSuggestIntentAction="android.intent.action.VIEW"
    android:includeInGlobalSearch="true"
    android:searchSettingsDescription="@string/settings_description" >
</searchable>