이제 두 번째 Android 11 개발자 프리뷰를 사용할 수 있습니다. 테스트해 보고 의견을 공유하세요.

검색 인터페이스 만들기

애플리케이션에 검색 기능을 추가할 준비가 되면 Android는 활동 창 상단에 표시되는 검색 대화상자 또는 레이아웃에 삽입할 수 있는 검색 위젯이 포함된 사용자 인터페이스를 구현하도록 지원합니다. 검색 대화상자와 위젯은 모두 사용자의 검색어를 애플리케이션의 특정 활동에 전달할 수 있습니다. 이렇게 하면 사용자는 검색 대화상자 또는 위젯을 사용할 수 있는 활동에서 검색을 시작할 수 있으며 시스템은 적합한 활동을 시작하여 검색하고 결과를 표시합니다.

검색 대화상자 및 위젯에 사용할 수 있는 다른 기능은 다음과 같습니다.

  • 음성 검색
  • 최근 검색어 기반의 추천 검색어
  • 애플리케이션 데이터의 실제 결과와 일치하는 추천 검색어

이 가이드에서는 Android 시스템에서 지원되며 검색 대화상자나 검색 위젯을 사용하는 검색 인터페이스를 통해 검색어를 전달하도록 애플리케이션을 설정하는 방법을 설명합니다.

관련 리소스

기본 사항

그림 1. 애플리케이션의 검색 대화상자 스크린샷

시작하기 전에, 검색 인터페이스를 구현하기 위해 검색 대화상자를 사용할지 검색 위젯을 사용할지 결정해야 합니다. 검색 대화상자와 검색 위젯은 동일한 검색 기능을 제공하지만 그 방식이 약간 다릅니다.

  • 검색 대화상자는 Android 시스템에서 제어하는 UI 구성요소입니다. 사용자가 활성화하면 검색 대화상자가 활동의 상단에 표시됩니다(그림 1 참조).

    Android 시스템은 검색 대화상자의 모든 이벤트를 제어합니다. 사용자가 쿼리를 제출하면 검색을 처리하도록 개발자가 지정한 활동에 이 쿼리가 전달됩니다. 대화상자에서는 사용자가 입력하는 동안 추천 검색어가 제공될 수도 있습니다.

  • 검색 위젯은 레이아웃의 임의의 위치에 배치할 수 있는 SearchView 인스턴스입니다. 기본적으로 검색 위젯은 표준 EditText 위젯처럼 동작하며 아무것도 하지 않습니다. 하지만 Android 시스템이 모든 입력 이벤트를 처리하고, 적합한 활동에 쿼리를 전달하고, 추천 검색어를 제공(검색 대화상자처럼)하도록 위젯을 구성할 수 있습니다.

    참고: 원하는 경우 개발자는 다양한 콜백 메서드와 리스너를 사용하여 검색 위젯의 모든 사용자 입력을 직접 처리할 수 있습니다. 하지만 이 문서에서는 지원 검색 구현을 위해 시스템과 검색 위젯을 통합하는 방법을 주로 다룹니다. 모든 사용자 입력을 직접 처리하려면 SearchView 및 중첩된 인터페이스에 관한 참조 문서를 확인하세요.

사용자가 검색 대화상자나 검색 위젯에서 검색을 실행하면 시스템은 Intent를 생성하고 여기에 사용자 쿼리를 저장합니다. 그런 다음 시스템은 개발자가 검색을 처리하도록 선언한 활동('검색 가능 활동')을 시작하고 이 활동에 인텐트를 전달합니다. 이러한 종류의 지원 검색이 가능하도록 애플리케이션을 설정하려면 다음이 필요합니다.

  • 검색 가능한 구성

    검색 대화상자 또는 위젯의 일부 설정을 구성하는 XML 파일입니다. 여기에는 음성 검색, 추천 검색어, 검색창 힌트 텍스트와 같은 기능의 설정이 포함됩니다.

  • 검색 가능 활동

    검색어를 수신하고, 개발자의 데이터를 검색하고, 검색결과를 표시하는 Activity입니다.

  • 검색 인터페이스로서 다음 중 하나에서 제공됩니다.
    • 검색 대화상자

      기본적으로 검색 대화상자는 숨겨지지만 onSearchRequested()를 호출하면(사용자가 검색 버튼을 누름) 화면 상단에 표시됩니다.

    • 또는 SearchView 위젯

      검색 위젯을 사용하면 활동의 임의의 위치에 검색창을 배치할 수 있습니다. 활동 레이아웃에 배치하는 대신 일반적으로 SearchView를 앱 바의 작업 뷰로 사용해야 합니다.

이 문서의 나머지 부분에서는 검색 가능한 구성 및 검색 가능 활동을 만들고 검색 대화상자나 검색 위젯이 포함된 검색 인터페이스를 구현하는 방법을 설명합니다.

검색 가능한 구성 만들기

가장 먼저 필요한 것은 검색 가능한 구성이라는 XML 파일입니다. 이 파일은 검색 대화상자 또는 위젯의 특정 UI 요소를 구성하고 추천 검색어 및 음성 검색과 같은 기능의 작동 방식을 정의합니다. 이 파일은 일반적으로 이름이 searchable.xml이며 res/xml/ 프로젝트 디렉터리에 저장해야 합니다.

참고: 시스템에서는 이 파일을 사용하여 SearchableInfo 객체를 인스턴스화하지만 개발자는 런타임에 직접 이 객체를 만들 수 없습니다. 검색 가능한 구성을 XML로 선언해야 합니다.

검색 가능한 구성 파일은 <searchable> 요소를 루트 노드로 포함하고 속성을 하나 이상 지정해야 합니다. 예를 들어 다음과 같습니다.

    <?xml version="1.0" encoding="utf-8"?>
    <searchable xmlns:android="http://schemas.android.com/apk/res/android"
        android:label="@string/app_label"
        android:hint="@string/search_hint" >
    </searchable>
    

android:label 속성은 유일한 필수 속성으로서 문자열 리소스(애플리케이션 이름이어야 함)를 가리킵니다. 이 라벨은 개발자가 빠른 검색창용 추천 검색어를 사용 설정하기 전까지는 사용자에게 실제로 표시되지 않습니다. 사용 설정하면 이 라벨은 시스템 설정에서 검색 가능 항목 목록에 표시됩니다.

필수 사항은 아니지만, 사용자가 쿼리를 입력하기 전에 검색창에 힌트 문자열을 제공하는 android:hint 속성을 항상 포함하는 것이 좋습니다. 힌트는 검색할 수 있는 정보에 관해 사용자에게 중요한 단서를 제공하기 때문에 중요합니다.

도움말: 다른 Android 애플리케이션 간의 일관성을 위해 android:hint의 문자열을 'Search <content-or-product>' 형식으로 지정해야 합니다. 예를 들어 'Search songs and artists' 또는 'Search YouTube'입니다.

<searchable> 요소는 다른 속성도 허용합니다. 그러나 대부분의 속성은 추천 검색어음성 검색과 같은 기능을 추가한 후에만 필요합니다. 검색 가능한 구성 파일에 관한 자세한 내용은 검색 가능한 구성 참조 문서를 확인하세요.

검색 가능 활동 만들기

검색 가능 활동은 애플리케이션에서 쿼리 문자열을 기반으로 검색하고 검색결과를 표시하는 Activity입니다.

사용자가 검색 대화상자 또는 위젯에서 검색을 실행하면 시스템에서 검색 가능 활동을 시작하고 ACTION_SEARCH 작업을 통해 Intent에 포함하여 검색어를 전달합니다. 검색 가능 활동은 인텐트의 QUERY extra에서 쿼리를 검색한 후 데이터를 검색하고 결과를 표시합니다.

개발자가 검색 대화상자 또는 위젯을 애플리케이션의 다른 활동에 포함할 수도 있으므로 시스템은 어느 활동이 검색 가능 활동인지 알아야 검색어를 제대로 전달할 수 있습니다. 따라서 먼저 Android manifest 파일에서 검색 가능 활동을 선언해야 합니다.

검색 가능 활동 선언하기

검색하고 결과를 표시할 Activity가 아직 없다면 만드세요. 검색 기능은 아직 구현하지 않아도 됩니다. manifest에서 선언할 수 있는 활동을 만들면 됩니다. manifest의 <activity> 요소 내부에서 다음과 같이 하세요.

  1. ACTION_SEARCH 인텐트를 허용하는 활동을 <intent-filter> 요소에서 선언합니다.
  2. 사용할 검색 가능한 구성을 <meta-data> 요소에서 지정합니다.

예를 들어 다음과 같습니다.

    <application ... >
        <activity android:name=".SearchableActivity" >
            <intent-filter>
                <action android:name="android.intent.action.SEARCH" />
            </intent-filter>
            <meta-data android:name="android.app.searchable"
                       android:resource="@xml/searchable"/>
        </activity>
        ...
    </application>
    

<meta-data> 요소는 android:name 속성(값 "android.app.searchable" 사용)을 포함하고 검색 가능한 구성 파일(이 예에서는 res/xml/searchable.xml 파일을 나타냄)의 참조와 함께 android:resource 속성을 포함해야 합니다.

참고: <intent-filter>에는 DEFAULT 값을 가진 <category>가 필요 없습니다(일반적으로 <activity> 요소에는 존재함). 왜냐하면 시스템에서 구성요소 이름을 사용해 명시적으로 ACTION_SEARCH 인텐트를 검색 가능 활동에 전달하기 때문입니다.

검색하기

manifest에서 검색 가능 활동을 선언하고 나면 다음 3개 단계를 통해 검색 가능 활동에서 검색이 이루어집니다.

  1. 쿼리 수신하기
  2. 데이터 검색하기
  3. 결과 표시하기

일반적으로 검색결과는 ListView에 표시되므로 검색 가능 활동이 ListActivity를 확장해야 할 수도 있습니다. 이 활동은 단일 ListView와 함께 기본 레이아웃을 포함하며 ListView 작업을 위한 다수의 편의 메서드를 제공합니다.

쿼리 수신하기

사용자가 검색 대화상자 또는 위젯에서 검색을 실행하면 검색 가능 활동이 시작되고 이 활동에 ACTION_SEARCH 인텐트가 전송됩니다. 이 인텐트는 QUERY 문자열 extra에 검색어를 포함하고 있습니다. 활동이 시작될 때 이 인텐트를 확인하고 문자열을 추출해야 합니다. 예를 들어 검색 가능 활동이 시작될 때 검색어를 가져올 수 있는 방법은 다음과 같습니다.

Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.search)

        // Verify the action and get the query
        if (Intent.ACTION_SEARCH == intent.action) {
            intent.getStringExtra(SearchManager.QUERY)?.also { query ->
                doMySearch(query)
            }
        }
    }
    

자바

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.search);

        // Get the intent, verify the action and get the query
        Intent intent = getIntent();
        if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
          String query = intent.getStringExtra(SearchManager.QUERY);
          doMySearch(query);
        }
    }
    

QUERY 문자열은 항상 ACTION_SEARCH 인텐트와 함께 포함됩니다. 이 예에서는 쿼리가 검색되어 실제 검색 작업이 완료되는 로컬 doMySearch() 메서드에 전달됩니다.

데이터 검색하기

데이터를 저장하고 검색하는 프로세스는 애플리케이션에 따라 다릅니다. 다양한 방법으로 데이터를 저장하고 검색할 수 있지만, 이 가이드에서는 데이터를 저장하고 검색하는 방법을 설명하지는 않습니다. 데이터 저장 및 검색은 요구사항과 데이터 형식의 측면에서 신중하게 고려해야 합니다. 다음은 적용할 수 있는 도움말입니다.

  • 데이터가 기기의 SQLite 데이터베이스에 저장되는 경우 전체 텍스트를 검색하면(LIKE 쿼리 대신 FTS3 사용) 텍스트 데이터를 더욱 안정적으로 찾을 수 있으며 훨씬 더 빠르게 결과를 생성할 수 있습니다. Android의 SQLite에 관해 자세히 알아보려면 sqlite.org에서 FTS3 및 SQLiteDatabase 클래스 관련 내용을 확인하세요.
  • 데이터가 온라인으로 저장되는 경우 인식되는 검색 성능은 사용자의 데이터 연결에 의해 저하될 수 있습니다. 검색에서 결과가 반환될 때까지 회전하는 진행률 동그라미를 표시해야 할 수 있습니다. 네트워크 API 참조는 android.net을 확인하고, 진행률 동그라미를 표시하는 방법에 관한 자세한 내용은 진행률 대화상자 만들기를 참고하세요.

결과 표시하기

데이터의 위치 및 데이터를 검색하는 방법과 관계없이 검색결과는 Adapter를 통해 검색 가능 활동에 반환하는 것이 좋습니다. 이렇게 하면 모든 검색결과를 ListView에 쉽게 표시할 수 있습니다. 데이터가 SQLite 데이터베이스 쿼리에서 제공되는 경우 CursorAdapter를 사용하여 결과를 ListView에 적용할 수 있습니다. 데이터가 다른 유형의 형식으로 제공되는 경우 BaseAdapter의 확장자를 만들 수 있습니다.

Adapter는 데이터 세트의 각 항목을 View 객체에 바인딩합니다. AdapterListView에 적용되면 각 데이터는 개별 뷰로 목록에 삽입됩니다. Adapter는 인터페이스일 뿐이므로, CursorAdapter(Cursor의 데이터를 바인딩하는 용도)와 같은 구현이 필요합니다. 기존 구현이 데이터에 적합하지 않은 경우 BaseAdapter에서 고유하게 구현할 수 있습니다.

검색 가능 활동이 ListActivity를 확장해야 할 수도 있습니다. 이런 경우에는 setListAdapter()를 호출하고 데이터에 바인딩된 Adapter를 전달하면 됩니다. 그러면 모든 검색결과가 ListView 활동에 삽입됩니다.

결과를 목록으로 표시하는 방법에 관해 추가 도움말을 보려면 ListActivity 문서를 참고하세요.

검색 대화상자 사용하기

검색 대화상자는 왼쪽에 애플리케이션 아이콘이 표시된 플로팅 검색창을 화면 상단에 제공합니다. 검색 대화상자는 사용자가 입력할 때 추천 검색어를 제공할 수 있으며, 사용자가 검색을 실행하면 시스템에서는 검색을 실행하는 검색 가능 활동에 검색어를 전송합니다. Android 3.0을 실행하는 기기용 애플리케이션을 개발하는 경우에는 검색 대화상자 대신 검색 위젯을 고려하세요(검색 위젯 사용하기 섹션 참고).

검색 대화상자는 사용자가 활성화할 때까지 기본적으로 항상 숨겨집니다. 애플리케이션은 onSearchRequested()를 호출하여 검색 대화상자를 활성화할 수 있습니다. 하지만 이 방법은 활동에 검색 대화상자를 사용 설정한 후에만 작동합니다.

검색 대화상자를 사용 설정하려면 검색이 이루어지기 위해서는 어느 검색 가능 활동이 검색 대화상자의 검색어를 수신해야 하는지를 시스템에 알려야 합니다. 예를 들어 이전 섹션인 검색 가능 활동 만들기에서 SearchableActivity라는 검색 가능 활동을 만들었습니다. 검색 대화상자를 표시하고 검색어를 SearchableActivity에 전달하는 OtherActivity라는 별도의 활동을 만들려면 SearchableActivityOtherActivity의 검색 대화상자에 사용할 검색 가능 활동이라는 것을 manifest에서 선언해야 합니다.

활동의 검색 대화상자를 위한 검색 가능 활동을 선언하려면 개별 활동의 <activity> 요소 내부에 <meta-data> 요소를 추가합니다. <meta-data> 요소에는 검색 가능 활동의 클래스 이름을 지정하는 android:value 속성과 android:name 속성(값 "android.app.default_searchable" 사용)을 포함해야 합니다.

예를 들어 다음은 검색 가능 활동 SearchableActivity 및 다른 활동 OtherActivity(검색 대화상자에서 실행된 검색을 를 사용해 수행함)를 모두 선언합니다.

    <application ... >
        <!-- this is the searchable activity; it performs searches -->
        <activity android:name=".SearchableActivity" >
            <intent-filter>
                <action android:name="android.intent.action.SEARCH" />
            </intent-filter>
            <meta-data android:name="android.app.searchable"
                       android:resource="@xml/searchable"/>
        </activity>

        <!-- this activity enables the search dialog to initiate searches
             in the SearchableActivity -->
        <activity android:name=".OtherActivity" ... >
            <!-- enable the search dialog to send searches to SearchableActivity -->
            <meta-data android:name="android.app.default_searchable"
                       android:value=".SearchableActivity" />
        </activity>
        ...
    </application>
    

현재 OtherActivity에는 검색에 사용할 검색 가능 활동을 선언하는 <meta-data> 요소가 포함되어 있으므로, 활동은 검색 대화상자를 사용 설정한 상태입니다. 사용자가 이 활동에 있는 동안 onSearchRequested() 메서드는 검색 대화상자를 활성화합니다. 사용자가 검색을 실행하면 시스템에서 SearchableActivity가 시작되고 ACTION_SEARCH 인텐트가 이 활동에 전달됩니다.

참고: 검색 가능 활동 자체가 기본적으로 검색 대화상자를 제공하므로 개발자는 이 선언을 SearchableActivity에 추가할 필요가 없습니다.

애플리케이션의 모든 활동에서 검색 대화상자를 제공하려면 각 <activity> 대신 위의 <meta-data> 요소를 <application> 요소의 하위 요소로 삽입하세요. 이렇게 하면 모든 활동이 값을 상속하고, 검색 대화상자를 제공하며, 동일한 검색 가능 활동에 검색어를 전달합니다. 검색 가능 활동이 여러 개인 경우 개별 활동 내부에 다른 <meta-data> 선언을 배치하여 기본 검색 가능 활동을 재정의할 수 있습니다.

이제 활동에 관해 검색 대화상자를 사용 설정했으므로 애플리케이션에서 검색할 준비가 되었습니다.

검색 대화상자 호출하기

일부 기기에서 전용 검색 버튼을 제공하지만 버튼의 동작은 기기마다 다를 수 있으며, 대부분의 기기는 검색 버튼을 제공하지 않습니다. 따라서 검색 대화상자를 사용할 때는 onSearchRequested() 호출을 통해 검색 대화상자를 활성화하는 검색 버튼을 UI에 제공해야 합니다.

예를 들어 옵션 메뉴 또는 onSearchRequested()를 호출하는 UI 레이아웃에 검색 버튼을 추가합니다. Android 시스템 및 다른 앱과의 일관성을 위해 Android 검색 아이콘을 사용해 버튼에 라벨을 지정해야 합니다. 이 아이콘은 작업 모음 아이콘 팩에서 구할 수 있습니다.

참고: 앱에 앱 바가 사용되는 경우 검색 인터페이스로 검색 대화상자를 사용해서는 안 됩니다. 대신 검색 위젯을 앱 바에서 축소할 수 있는 뷰로 사용하세요.

'입력하여 검색' 기능을 사용 설정할 수도 있으며, 이 경우 사용자가 키보드에서 입력하기 시작하면 검색 대화상자가 활성화되어 키 입력이 검색 대화상자에 삽입됩니다. 활동의 onCreate() 메서드 중에 setDefaultKeyMode(DEFAULT_KEYS_SEARCH_LOCAL)를 호출하면 활동에 관해 '입력하여 검색' 기능을 사용 설정할 수 있습니다.

검색 대화상자가 활동 수명 주기에 미치는 영향

검색 대화상자는 화면 상단에 표시되는 플로팅 Dialog입니다. 이 대화상자로 인해 활동 스택이 변경되지는 않으므로, 검색 대화상자가 표시되어도 onPause()와 같은 수명 주기 메서드가 호출되지 않습니다. 입력 포커스는 검색 대화상자에 표시되므로, 활동에 위치한 입력 포커스가 사라질 뿐입니다.

검색 대화상자가 활성화되었을 때 알림을 받으려면 onSearchRequested() 메서드를 재정의합니다. 시스템에서 이 메서드를 호출하면 이는 입력 포커스가 활동에서 검색 대화상자로 옮겨졌으며 이벤트에 적합한 모든 작업(예: 게임 일시중지)을 할 수 있다는 것을 나타냅니다. 검색 문맥 데이터를 전달(아래에서 설명)하지 않는 경우 슈퍼클래스 구현을 호출하여 메서드를 종료해야 합니다. 예를 들어 다음과 같습니다.

Kotlin

    override fun onSearchRequested(): Boolean {
        pauseSomeStuff()
        return super.onSearchRequested()
    }
    

자바

    @Override
    public boolean onSearchRequested() {
        pauseSomeStuff();
        return super.onSearchRequested();
    }
    

사용자가 뒤로 버튼을 눌러 검색을 취소하면 검색 대화상자가 닫히고 활동에 입력 포커스가 다시 표시됩니다. setOnDismissListener() 및/또는 setOnCancelListener()를 사용하면 검색 대화상자가 닫힐 때 알림을 받도록 등록할 수 있습니다. 검색 대화상자가 닫힐 때마다 호출되는 OnDismissListener만 등록하면 됩니다. OnCancelListener는 사용자가 명시적으로 검색 대화상자를 종료한 경우에만 적용되며 검색이 실행된 경우에는 호출되지 않습니다(검색 대화상자가 저절로 사라짐).

현재 활동이 검색 가능 활동이 아닌 경우에는 사용자가 검색을 실행하면 일반 활동 수명 주기 이벤트가 트리거됩니다(현재 활동은 활동 문서의 설명대로 onPause() 등을 수신함). 이와 달리, 현재 활동이 검색 가능 활동인 경우에는 다음 둘 중 하나가 발생합니다.

  1. 기본적으로 검색 가능 활동은 onCreate() 호출이 있는 ACTION_SEARCH 인텐트를 수신하며 활동의 새 인스턴스가 활동 스택의 맨 위에 표시됩니다. 이제 활동 스택에 검색 가능 활동의 인스턴스 2개가 있으므로 뒤로 버튼을 누르면 기존 검색 가능 활동이 종료되는 것이 아니라 이전 검색 가능 활동 인스턴스로 돌아갑니다.
  2. android:launchMode"singleTop"으로 설정하는 경우 검색 가능 활동은 onNewIntent(Intent) 호출이 있는 ACTION_SEARCH 인텐트를 수신하고 여기에 새 ACTION_SEARCH 인텐트를 전달합니다. 예를 들어, 검색 가능 활동의 실행 모드가 "singleTop"일 때 이런 경우를 처리하는 방법은 다음과 같습니다.

    Kotlin

        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            setContentView(R.layout.search)
            handleIntent(intent)
        }
    
        override fun onNewIntent(intent: Intent) {
            setIntent(intent)
            handleIntent(intent)
        }
    
        private fun handleIntent(intent: Intent) {
            if (Intent.ACTION_SEARCH == intent.action) {
                intent.getStringExtra(SearchManager.QUERY)?.also { query ->
                    doMySearch(query)
                }
            }
        }
        

    자바

        @Override
        public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.search);
            handleIntent(getIntent());
        }
    
        @Override
        protected void onNewIntent(Intent intent) {
            setIntent(intent);
            handleIntent(intent);
        }
    
        private void handleIntent(Intent intent) {
            if (Intent.ACTION_SEARCH.equals(intent.getAction())) {
              String query = intent.getStringExtra(SearchManager.QUERY);
              doMySearch(query);
            }
        }
        

    검색 수행하기 섹션의 예제 코드와 비교할 때, 검색 인텐트를 처리하는 모든 코드가 이제 onCreate()onNewIntent() 모두에서 실행될 수 있도록 handleIntent() 메서드에 배치되었습니다.

    시스템에서 onNewIntent(Intent)를 호출하는 시점에 활동이 아직 다시 시작되지 않았으므로 getIntent() 메서드는 onCreate()에서 수신된 것과 동일한 인텐트를 반환합니다. 이러한 이유로 onNewIntent(Intent) 내부에서 setIntent(Intent)를 호출해야 합니다(활동이 저장한 인텐트가 이후 getIntent()를 호출하는 경우 업데이트됨).

"singleTop" 실행 모드를 사용하는 두 번째 시나리오는 대체로 이상적입니다. 검색이 완료된 후에 사용자가 추가 검색을 수행할 가능성이 높기 때문입니다. 이때 애플리케이션에서 검색 가능 활동 인스턴스를 여러 개 만드는 경우에는 검색 환경이 저하될 수 있습니다. 그러므로 애플리케이션 manifest에서 검색 가능 활동을 "singleTop" 실행 모드로 설정하는 것이 좋습니다. 예를 들어 다음과 같습니다.

    <activity android:name=".SearchableActivity"
              android:launchMode="singleTop" >
        <intent-filter>
            <action android:name="android.intent.action.SEARCH" />
        </intent-filter>
        <meta-data android:name="android.app.searchable"
                          android:resource="@xml/searchable"/>
      </activity>
    

검색 문맥 데이터 전달하기

경우에 따라서는 검색할 때마다 검색 가능 활동 내에서 검색어를 필요한 대로 수정할 수 있습니다. 그러나 사용자가 검색을 수행하는 활동을 기반으로 검색 기준을 조정하려면 시스템이 검색 가능 활동에 전송하는 인텐트에 추가 데이터를 제공하면 됩니다. ACTION_SEARCH 인텐트에 포함되는 APP_DATA Bundle로 추가 데이터를 전달할 수 있습니다.

이런 종류의 데이터를 검색 가능 활동에 전달하려면 사용자가 검색을 수행할 수 있는 활동에 관한 onSearchRequested() 메서드를 재정의하고, 추가 데이터가 있는 Bundle을 만들고, startSearch()를 호출해 검색 대화상자를 활성화합니다. 예를 들어 다음과 같습니다.

Kotlin

    override fun onSearchRequested(): Boolean {
        val appData = Bundle().apply {
            putBoolean(JARGON, true)
        }
        startSearch(null, false, appData, false)
        return true
    }
    

자바

    @Override
    public boolean onSearchRequested() {
         Bundle appData = new Bundle();
         appData.putBoolean(SearchableActivity.JARGON, true);
         startSearch(null, false, appData, false);
         return true;
     }
    

'true'가 반환되면 이 콜백 이벤트를 성공적으로 처리했으며 startSearch()를 호출해 검색 대화상자를 활성화했다는 의미입니다. 사용자가 쿼리를 제출하면 이 쿼리는 개발자가 추가한 데이터와 함께 검색 가능 활동에 전달됩니다. APP_DATA Bundle에서 추가 데이터를 추출하여 검색 범위를 더 좁힐 수 있습니다. 예를 들어 다음과 같습니다.

Kotlin

    val jargon: Boolean = intent.getBundleExtra(SearchManager.APP_DATA)?.getBoolean(JARGON) ?: false
    

자바

    Bundle appData = getIntent().getBundleExtra(SearchManager.APP_DATA);
    if (appData != null) {
        boolean jargon = appData.getBoolean(SearchableActivity.JARGON);
    }
    

주의: onSearchRequested() 콜백 메서드 외부에서 startSearch() 메서드를 호출하지 마세요. 활동에서 검색 대화상자를 활성화하려면 항상 onSearchRequested()를 호출하세요. 그러지 않으면 onSearchRequested()가 호출되지 않으며 맞춤설정(예: 위 예에서 appData 추가)이 누락됩니다.

검색 위젯 사용하기

그림 2. 작업 모음의 '작업 뷰'인 SearchView 위젯

SearchView 위젯은 Android 3.0 이상에서 사용할 수 있습니다. 검색 위젯을 사용하기로 하고 Android 3.0용 애플리케이션을 개발하는 중이면 검색 대화상자를 사용하지 말고, 검색 위젯을 활동 레이아웃에 배치하는 대신 앱 바에 작업 뷰로 삽입하는 것이 좋습니다. 예를 들어 그림 2는 앱 바의 검색 위젯을 보여줍니다.

검색 위젯은 검색 대화상자와 동일한 기능을 제공합니다. 사용자가 검색을 실행하면 적합한 활동을 시작하며 추천 검색어를 제공하고 음성 검색을 실행할 수 있습니다. 작업 모음에 검색 위젯을 배치하지 않는 경우 활동 레이아웃의 어딘가에 검색 위젯을 배치할 수 있습니다.

참고: 검색 위젯을 작업 뷰로 사용할 때에도 검색 위젯이 작업 모음에 맞지 않는 경우를 위해 검색 대화상자 사용을 지원해야 할 수 있습니다. 아래의 위젯과 대화상자 모두 사용하기 섹션을 참고하세요.

검색 위젯 구성하기

검색 가능한 구성검색 가능 활동을 만든 후에는 위의 설명대로 각 SearchView의 지원 검색을 사용 설정해야 합니다. setSearchableInfo()를 호출하여 검색 가능한 구성을 나타내는 SearchableInfo 객체에 전달하면 됩니다.

SearchManager에 관해 getSearchableInfo()를 호출하여 SearchableInfo 참조를 가져올 수 있습니다.

예를 들어 SearchView앱 바의 작업 뷰로 사용 중인 경우 onCreateOptionsMenu() 콜백 도중에 위젯을 사용 설정해야 합니다.

Kotlin

    override fun onCreateOptionsMenu(menu: Menu): Boolean {
        // Inflate the options menu from XML
        val inflater = menuInflater
        inflater.inflate(R.menu.options_menu, menu)

        // Get the SearchView and set the searchable configuration
        val searchManager = getSystemService(Context.SEARCH_SERVICE) as SearchManager
        (menu.findItem(R.id.menu_search).actionView as SearchView).apply {
            // Assumes current activity is the searchable activity
            setSearchableInfo(searchManager.getSearchableInfo(componentName))
            setIconifiedByDefault(false) // Do not iconify the widget; expand it by default
        }

        return true
    }
    

자바

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        // Inflate the options menu from XML
        MenuInflater inflater = getMenuInflater();
        inflater.inflate(R.menu.options_menu, menu);

        // Get the SearchView and set the searchable configuration
        SearchManager searchManager = (SearchManager) getSystemService(Context.SEARCH_SERVICE);
        SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
        // Assumes current activity is the searchable activity
        searchView.setSearchableInfo(searchManager.getSearchableInfo(getComponentName()));
        searchView.setIconifiedByDefault(false); // Do not iconify the widget; expand it by default

        return true;
    }
    

완료되었습니다. 이제 검색 위젯이 구성되었고 시스템은 검색 가능 활동에 검색어를 전달하게 됩니다. 검색 위젯에 추천 검색어를 사용하도록 설정할 수도 있습니다.

참고: 모든 사용자 입력을 직접 처리하려면 일부 콜백 메서드와 이벤트 리스너를 사용하면 됩니다. 자세한 내용은 SearchView 및 중첩된 인터페이스에 관한 참조 문서에서 적절한 이벤트 리스너를 확인하세요.

작업 모음의 작업 뷰에 관한 자세한 내용은 작업 뷰 및 작업 제공자를 참고하세요.

기타 검색 위젯 기능

SearchView 위젯은 개발자에게 필요할 수도 있는 다음과 같은 추가 기능을 제공합니다.

제출 버튼
기본적으로 검색어를 제출하는 버튼이 없으며 사용자가 키보드의 'Return' 키를 눌러야 검색이 시작됩니다. setSubmitButtonEnabled(true)를 호출하여 '제출' 버튼을 추가할 수 있습니다.
추천 검색어의 쿼리 조정
추천 검색어를 사용 설정했다면 일반적으로 사용자가 단순히 추천 검색어를 선택하기를 기대합니다. 하지만 사용자는 추천된 검색어를 조정할 수도 있습니다. setQueryRefinementEnabled(true)를 호출하면 사용자가 조정할 수 있게 추천 검색어를 검색창에 삽입하는 버튼을 추가하여 각 추천 검색어와 함께 표시할 수 있습니다.
검색창 표시 여부를 전환하는 기능
기본적으로 검색 위젯은 '아이콘화'되어 검색 아이콘(돋보기)으로만 표시되며 사용자가 터치하면 위젯이 확장되어 검색창이 표시됩니다. 위에 예처럼 setIconifiedByDefault(false)를 호출하면 기본적으로 검색 창을 표시할 수 있습니다. setIconified()를 호출하여 검색 위젯 디자인을 전환할 수도 있습니다.

SearchView 클래스에는 검색 위젯을 맞춤설정할 수 있는 다른 API가 몇 가지 있습니다. 하지만 그중 대부분은 Android 시스템을 사용하여 검색어를 전달하고 추천 검색어를 표시하는 대신 모든 사용자 입력을 직접 처리할 때만 사용됩니다.

위젯과 대화상자 모두 사용하기

검색 위젯을 작업 모음에 작업 뷰로 삽입하고 '공간이 있을 때' 작업 모음에 표시되도록 설정하는(android:showAsAction="ifRoom" 설정) 경우 검색 위젯이 작업 뷰로 표시되지 않고 메뉴 항목이 더보기 메뉴에 표시될 수 있습니다. 예를 들어 작은 화면에서 애플리케이션을 실행할 때는 작업 모음에 공간이 부족하여 다른 작업 항목 또는 탐색 요소와 함께 검색 위젯이 표시되지 않을 수 있으며 이 경우 대신 더보기 메뉴에 메뉴 항목이 표시됩니다. 더보기 메뉴에 배치된 항목은 일반적인 메뉴 항목처럼 작동하며 작업 뷰(검색 위젯)를 표시하지 않습니다.

이러한 상황을 처리하기 위해서는 검색 위젯에 연결한 메뉴 항목을 사용자가 더보기 메뉴에서 선택하면 검색 대화상자가 활성화되어야 합니다. 그러려면 '검색' 메뉴 항목을 처리하도록 onOptionsItemSelected()를 구현하고 onSearchRequested()를 호출하여 검색 대화상자를 열어야 합니다.

작업 모음의 항목이 작동하는 방식 및 이 상황을 처리하는 방법을 자세히 알아보려면 작업 모음 개발자 가이드를 참고하세요.

음성 검색 추가하기

검색 가능한 구성에 android:voiceSearchMode 속성을 추가하여 검색 대화상자 또는 위젯에 음성 검색 기능을 추가할 수 있습니다. 그러면 음성 안내를 시작하는 음성 검색 버튼이 추가됩니다. 사용자가 말하기를 마치면 텍스트로 변환된 검색어가 검색 가능 활동에 전달됩니다.

예를 들어 다음과 같습니다.

    <?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:voiceSearchMode="showVoiceSearchButton|launchRecognizer" >
    </searchable>
    

showVoiceSearchButton은 음성 검색을 사용 설정하는 데 필요하고, 두 번째 값 launchRecognizer는 음성 검색 버튼이 변환된 텍스트를 검색 가능 활동에 반환하는 인식기를 실행해야 한다는 것을 지정합니다.

예상되는 언어 및 반환할 최대 검색결과 수와 같이 음성 검색 동작을 지정하는 추가 속성을 제공할 수 있습니다. 사용할 수 있는 속성에 관한 자세한 내용은 검색 가능한 구성 참조를 확인하세요.

참고: 음성 검색이 애플리케이션에 적합한지 여부를 신중하게 고려하세요. 음성 검색 버튼을 사용한 모든 검색은 사용자가 텍스트 변환된 쿼리를 검토할 기회 없이 즉시 검색 가능 활동에 전송됩니다. 음성 인식을 충분히 테스트하여 사용자가 애플리케이션 내에서 제출할 수 있는 유형의 쿼리를 음성 인식에서 이해하는지 확인하세요.

추천 검색어 추가하기

그림 3. 검색 대화상자의 맞춤 추천 검색어 스크린샷

검색 대화상자와 검색 위젯은 모두 사용자가 입력할 때 Android 시스템의 지원을 통해 추천 검색어를 제공할 수 있습니다. 시스템에서는 추천 검색어 목록을 관리하고 사용자가 추천 검색어를 선택하면 이벤트를 처리합니다.

두 가지 추천 검색어를 제공할 수 있습니다.

최근 검색어 추천
이 추천어는 사용자가 이전에 애플리케이션에서 검색어로 사용한 단어입니다.

최근 쿼리 제안 추가를 참고하세요.

맞춤 추천 검색어
개발자가 고유의 데이터 소스에서 제공하는 추천 검색어이며 사용자가 찾고 있는 올바른 맞춤법 또는 항목을 즉시 선택하도록 도와줍니다. 그림 3은 사전 애플리케이션용 맞춤 추천 검색어의 예를 보여줍니다. 추천 검색어를 선택하여 즉시 정의로 이동할 수 있습니다.

맞춤 제안 추가를 참고하세요.