검색 구성

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의 문자열 형식을 'Search <content-or-product>'로 지정합니다. 예를 들어 'SearchSong and artists' 또는 'Search 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 절이며 사용자가 입력한 실제 쿼리 문자열의 자리표시자로 단일 물음표를 포함해야 합니다(예: "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를 정의하여 키를 정의하고 다른 세 개 속성 중 하나 이상을 정의하여 검색 작업을 정의해야 합니다.

속성:

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>