검색 가능한 구성

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> manifest 요소의 android:label 속성에 적용된 이름과 같아야 합니다. 이 라벨은 개발자가 android:includeInGlobalSearch를 'true'로 설정하는 경우에만 사용자에게 표시됩니다. 'true'인 경우 이 라벨은 시스템의 검색 설정에서 애플리케이션을 검색 가능한 항목으로 식별하는 데 사용됩니다.

android:hint

문자열 리소스. (추천) 검색 텍스트 입력란에 텍스트가 입력되지 않은 경우 표시할 텍스트입니다. 사용자에게 검색 가능한 콘텐츠에 관한 힌트를 줍니다. 다른 Android 애플리케이션과 일관성을 위해 android:hint의 문자열을 'Search <content-or-product>' 형식으로 지정해야 합니다. 예를 들어 'Search songs and artists' 또는 'Search YouTube'입니다.

android:searchMode

키워드. 검색 표시를 제어하는 추가 모드를 설정합니다. 현재 사용 가능한 모드는 맞춤 제안이 포커스를 받을 때 쿼리 텍스트를 다시 쓰는 방법을 정의합니다. 허용되는 모드 값은 다음과 같습니다.

값	설명
`"queryRewriteFromText"`	`SUGGEST_COLUMN_TEXT_1` 열의 값을 사용하여 쿼리 텍스트를 다시 씁니다.
`"queryRewriteFromData"`	`SUGGEST_COLUMN_INTENT_DATA` 열의 값을 사용하여 쿼리 텍스트를 다시 씁니다. 이 값은 `SUGGEST_COLUMN_INTENT_DATA`의 값이 사용자 검사 및 수정에 적합한 경우에만(일반적으로 HTTP URI) 사용해야 합니다.

자세한 내용은 맞춤 제안 추가에서 쿼리 텍스트 다시 쓰기에 관한 설명을 참고하세요.

android:searchButtonText

문자열 리소스. 검색을 실행하는 버튼에 표시할 텍스트입니다. 기본적으로 이 버튼에는 국제화에 이상적인 검색 아이콘(돋보기)이 표시되므로 검색 이외의 다른 동작(예: 웹브라우저의 URL 요청)이 아닌 경우에는 이 속성을 사용하여 버튼을 변경하면 안 됩니다.

android:inputType

키워드. 사용할 입력 방법 유형(예: 소프트 키보드 유형)을 정의합니다. 자유 형식의 텍스트가 요구되는 대부분의 검색에는 이 속성이 필요하지 않습니다. 이 속성에 적합한 값 목록은 inputType을 참고하세요.

android:imeOptions

키워드. 입력 방법을 위한 추가 옵션을 제공합니다. 자유 형식의 텍스트가 요구되는 대부분의 검색에는 이 속성이 필요하지 않습니다. 기본 IME는 'actionSearch'입니다(소프트 키보드에서 캐리지 리턴 대신 '검색' 버튼 제공). 이 속성에 적합한 값 목록은 imeOptions를 참고하세요.

빠른 검색창 속성

빠른 검색창에서 사용할 수 있는 맞춤 추천 검색어를 만들려면 다음과 같은 <searchable> 속성이 필요합니다.

android:includeInGlobalSearch: 부울. (빠른 검색창에 추천 검색어를 제공하기 위해 필요) 전역적으로 액세스할 수 있는 빠른 검색창에 추천 검색어를 포함하려면 'true'로 설정합니다. 사용자가 시스템의 검색 설정에서 애플리케이션을 검색 가능 항목으로 사용 설정해야 추천 검색어가 빠른 검색창에 표시됩니다.
android:searchSettingsDescription: 문자열. 빠른 검색창에 제공하는 추천 검색어에 관한 간략한 설명을 제공하며, 이 설명은 애플리케이션 관련 검색 가능 항목에서 표시됩니다. 설명에서는 검색 가능한 콘텐츠를 간결하게 서술해야 합니다. 예를 들어 음악 애플리케이션의 경우 '아티스트, 앨범, 트랙'을, 메모장 애플리케이션의 경우 '저장된 메모'를 설명합니다.
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개 속성 중 하나 이상을 정의해야 합니다.

속성

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>

검색 가능한 구성

추천 검색어 속성

빠른 검색창 속성

음성 검색 속성