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
- 文字列リソース。クイック検索ボックスに提供する検索候補の簡単な説明を指定します。この説明は、アプリの検索対象エントリに表示されます。説明は、検索可能なコンテンツを簡潔に説明する必要があります。たとえば、音楽アプリの場合は「アーティスト、アルバム、トラック」、メモ帳アプリの場合は「保存したメモ」です。
android:queryAfterZeroResults
- ブール値。以前にゼロを返したクエリのスーパーセットに対してコンテンツ プロバイダを呼び出すには、
"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>