Google은 흑인 공동체를 위한 인종 간 평등을 진전시키기 위해 노력하고 있습니다. Google에서 어떤 노력을 하고 있는지 확인하세요.

검색 가능한 구성

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:searchSuggestAuthority
문자열. (추천 검색어를 제공하기 위해 필요) 이 값은 Android manifest <provider> 요소의 android:authorities 속성에 제공된 권한 문자열과 일치해야 합니다.
android:searchSuggestPath
문자열. 이 경로는 추천 검색어 쿼리 Uri의 일부로 사용되며 접두어 및 권한 다음, 표준 추천 검색어 경로 앞에 해당합니다. 다른 유형의 추천 검색어(예: 다른 데이터 유형)를 발행하는 단일 콘텐츠 제공자가 있고 맞춤 검색어 쿼리를 수신할 때 식별할 방법이 필요한 경우에만 이 값이 필요합니다.
android:searchSuggestSelection
문자열. 이 값은 쿼리 함수에 selection 매개변수로 전달됩니다. 일반적으로 데이터베이스의 WHERE 절이며 사용자가 입력한 실제 쿼리 문자열의 자리표시자인 단일 물음표를 포함해야 합니다(예: "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
부울. 콘텐츠 제공자에서 이전에 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>