検索可能構成
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
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- キーワード。検索の固定表示を制御する追加のモードを設定します。現在使用可能なモードで、カスタム候補がフォーカスを受け取ったときにクエリテキストを書き換える方法を定義します。指定できるモードの値は次のとおりです。
詳しくは、カスタム候補の追加でクエリテキストの書き換えについての説明をご覧ください。
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=?"）。ただし、null 以外の任意の値を使用し、selectionArgs パラメータを介してクエリテキストの提供をトリガーすることもできます（これにより、selection パラメータは無視されます）。
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 属性を使用してすべての候補のアクション メッセージを定義するのではなく、コンテンツ プロバイダの各エントリが独自のアクション メッセージを提供するためです。まず、アクション メッセージを提供する各候補のコンテンツ プロバイダで列を定義し、その列の名前をこの属性で指定する必要があります。システムが候補のカーソルを確認し、ここで提供される文字列を使用してアクション メッセージの列を選択します。さらに、Cursor からアクション メッセージの文字列を選択します。この文字列は、システムが検索可能なアクティビティに渡すインテントに追加されます（候補に対して定義したアクションを使用）。この文字列を調べるには、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>
このページのコンテンツやコードサンプルは、コンテンツ ライセンスに記載のライセンスに従います。Java および OpenJDK は Oracle および関連会社の商標または登録商標です。
最終更新日 2019-12-27 UTC。
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"必要な情報がない"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"複雑すぎる / 手順が多すぎる"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"最新ではない"
},{
"type": "thumb-down",
"id": "translationIssue",
"label":"翻訳に関する問題"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"サンプル / コードに問題がある"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"その他"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"わかりやすい"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"問題の解決に役立った"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"その他"
}]
