검색 인터페이스 만들기

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

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

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

이 문서에서는 Android 시스템에서 지원하는 검색 인터페이스를 통해 검색 대화상자나 검색 위젯을 사용하여 검색어를 전달하도록 앱을 설정하는 방법을 보여줍니다.

관련 리소스:

기본사항

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

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

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

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

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

  • 검색 구성
    검색 대화상자 또는 위젯의 일부 설정을 구성하는 XML 파일입니다. 여기에는 음성 검색, 추천 검색어, 검색창 힌트 텍스트와 같은 기능의 설정이 포함됩니다.
  • 검색 가능 활동
    검색어를 수신하고, 데이터를 검색하고, 검색결과를 표시하는 Activity입니다.
  • 검색 인터페이스로서 다음 중 하나로 제공됩니다.
    • 검색 대화상자
      기본적으로 검색 대화상자는 숨겨져 있습니다. 사용자가 검색 버튼을 탭하면 onSearchRequested()를 호출하면 화면 상단에 표시됩니다.
    • SearchView 위젯
      검색 위젯을 사용하면 앱 바의 작업 뷰 등으로 활동의 어느 위치에나 검색창을 배치할 수 있습니다.

이 문서의 나머지 부분에서는 검색 구성 및 검색 가능 활동을 만드는 방법과 검색 대화상자 또는 검색 위젯으로 검색 인터페이스를 구현하는 방법을 보여줍니다.

검색 가능한 구성 만들기

가장 먼저 필요한 것은 검색 구성이라는 XML 파일입니다. 검색 대화상자나 위젯의 특정 UI 측면을 구성하고 추천 검색어 및 음성 검색과 같은 기능의 작동 방식을 정의합니다. 이 파일은 일반적으로 searchable.xml로 이름이 지정되며 res/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 속성을 항상 포함하는 것이 좋습니다. 힌트는 사용자가 무엇을 검색할 수 있는지에 관한 중요한 단서를 제공하기 때문에 중요합니다.

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

검색 가능 활동 만들기

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

사용자가 검색 대화상자나 위젯에서 검색을 실행하면 시스템에서 검색 가능 활동을 시작하고 ACTION_SEARCH 작업과 함께 Intent의 검색어를 전달합니다. 검색 가능 활동은 인텐트의 QUERY 추가 항목에서 쿼리를 가져온 후 데이터를 검색하여 결과를 표시합니다.

검색 대화상자나 위젯을 앱의 다른 활동에 포함할 수 있으므로 시스템은 검색어를 제대로 전달할 수 있도록 어떤 활동이 검색 가능 활동인지 알아야 합니다. 따라서 먼저 Android 매니페스트 파일에서 검색 가능한 활동을 선언합니다.

검색 가능 활동 선언

아직 없으면 검색을 실행하고 결과를 표시하는 Activity를 만듭니다. 아직 검색 기능을 구현할 필요는 없습니다. 매니페스트에서 선언할 수 있는 활동을 만들기만 하면 됩니다. 매니페스트의 <activity> 요소 내에서 다음을 실행합니다.

  1. <intent-filter> 요소에서 ACTION_SEARCH 인텐트를 허용하는 활동을 선언합니다.
  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.app.searchable"android:name 속성 및 검색 가능한 구성 파일의 참조와 함께 android:resource 속성을 포함해야 합니다. 앞의 예에서는 res/xml/searchable.xml 파일을 참조합니다.

검색 수행

매니페스트에서 검색 가능 활동을 선언한 후 다음 절차에 따라 검색 가능 활동에서 검색을 실행합니다.

  1. 쿼리를 수신합니다.
  2. 데이터를 검색합니다.
  3. 결과를 제시합니다.

쿼리 수신

사용자가 검색 대화상자나 위젯에서 검색을 실행하면 시스템은 검색 가능 활동을 시작하고 이에 ACTION_SEARCH 인텐트를 전송합니다. 이 인텐트는 QUERY 문자열 추가 항목에 검색어를 전달합니다. 활동이 시작될 때 이 인텐트를 확인하고 문자열을 추출합니다. 예를 들어 검색 가능한 활동이 시작될 때 검색어를 가져오는 방법은 다음과 같습니다.

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)
        }
    }
}

Java

@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에 관한 자세한 내용은 FTS3 및 SQLiteDatabase 클래스에 관한 sqlite.org를 참고하세요.
  • 데이터가 온라인에 저장된 경우 사용자의 데이터 연결로 인해 검색 성능이 저하될 수 있습니다. 검색이 반환될 때까지 진행률 표시기를 표시하는 것이 좋습니다. 네트워크 API 참조는 android.net를 참고하고 진행률 표시기를 표시하는 방법에 관한 자세한 내용은 ProgressBar를 참고하세요.

결과 발표

데이터의 위치 및 검색 방법에 관계없이 Adapter를 사용하여 검색 결과를 검색 활동에 반환하는 것이 좋습니다. 이렇게 하면 모든 검색 결과를 RecyclerView에 표시할 수 있습니다. 데이터의 출처가 SQLite 데이터베이스 쿼리인 경우 CursorAdapter를 사용하여 결과를 RecyclerView에 적용할 수 있습니다. 데이터의 형식이 다른 경우 BaseAdapter의 확장 프로그램을 만들 수 있습니다.

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

검색 대화상자 사용

검색 대화상자는 화면 상단에 플로팅 검색창을 제공하며, 왼쪽에 앱 아이콘이 있습니다. 사용자가 입력할 때 검색 대화상자에서 추천 검색어가 제공될 수 있습니다. 사용자가 검색을 실행하면 시스템은 검색을 실행하는 검색 가능한 활동에 검색어를 전송합니다.

기본적으로 검색 대화상자는 사용자가 활성화할 때까지 항상 숨겨져 있습니다. 앱은 onSearchRequested()를 호출하여 검색 대화상자를 활성화할 수 있습니다. 그러나 이 방법은 활동에 검색 대화상자를 사용 설정할 때까지 작동하지 않습니다.

검색 대화상자에서 검색을 실행할 수 있도록 하려면 검색 대화상자에서 검색어를 수신할 검색 가능한 활동이 무엇인지 시스템에 알립니다. 예를 들어 검색 가능 활동 만들기에 관한 이전 섹션에서는 SearchableActivity라는 검색 가능한 활동이 생성됩니다. OtherActivity라는 별도의 활동(예: 검색 대화상자를 표시하고 검색 결과를 SearchableActivity)에 전달하려면 SearchableActivityOtherActivity의 검색 대화상자에 사용할 검색 가능 활동임을 매니페스트에서 선언합니다.

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

예를 들어 다음은 검색 가능 활동 SearchableActivitySearchableActivity를 사용하여 검색 대화상자에서 실행된 검색을 실행하는 또 다른 활동 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 인텐트를 전달합니다.

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

이제 활동에 검색 대화상자가 사용 설정되었으므로 앱에서 검색을 실행할 준비가 된 것입니다.

검색 대화상자 호출

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

예를 들어 옵션 메뉴 또는 onSearchRequested()를 호출하는 UI 레이아웃에 검색 버튼을 추가합니다.

'입력하여 검색' 기능을 사용 설정할 수도 있습니다. 이 기능은 사용자가 키보드에서 입력을 시작할 때 검색 대화상자를 활성화합니다. 키 입력이 검색 대화상자에 삽입됩니다. 활동의 onCreate() 메서드 중에 setDefaultKeyMode 또는 DEFAULT_KEYS_SEARCH_LOCAL를 호출하여 활동에서 '입력하여 검색' 기능을 사용 설정할 수 있습니다.

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

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

검색 대화상자가 활성화되었을 때 알림을 받으려면 onSearchRequested() 메서드를 재정의합니다. 시스템에서 이 메서드를 호출하면 활동이 검색 대화상자에서 입력 포커스를 받지 못하므로 게임 일시중지와 같이 이벤트에 적합한 모든 작업을 실행할 수 있다는 의미입니다. 이 문서의 다른 섹션에서 설명하는 검색 컨텍스트 데이터를 전달하지 않는 이상 슈퍼클래스 구현을 호출하여 메서드를 종료합니다.

Kotlin

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

Java

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

사용자가 뒤로 버튼을 탭하여 검색을 취소하면 검색 대화상자가 닫히고 활동이 입력 포커스를 다시 얻습니다. setOnDismissListener(), setOnCancelListener() 또는 둘 다를 사용하여 검색 대화상자가 닫힐 때 알림을 받도록 등록할 수 있습니다. OnDismissListener는 검색 대화상자가 닫힐 때마다 호출되므로 등록만 하면 됩니다. OnCancelListener는 사용자가 검색 대화상자를 명시적으로 종료하는 이벤트에만 해당하므로 검색이 실행될 때 호출되지 않습니다. 검색이 실행되면 검색 대화상자가 자동으로 사라집니다.

현재 활동이 검색 가능 활동이 아닌 경우 사용자가 검색을 실행할 때 일반 활동 수명 주기 이벤트가 트리거됩니다. 현재 활동은 활동 소개에 설명된 대로 onPause()를 수신합니다. 그러나 현재 활동이 검색 가능 활동인 경우 다음 두 가지 중 하나가 발생합니다.

  • 기본적으로 검색 가능 활동은 onCreate() 호출이 있는 ACTION_SEARCH 인텐트를 수신하며 활동의 새 인스턴스가 활동 스택의 맨 위로 이동합니다. 이제 활동 스택에 검색 가능 활동 인스턴스가 두 개 있으므로 뒤로 버튼을 탭하면 검색 가능 활동을 종료하지 않고 검색 가능 활동의 이전 인스턴스로 돌아갑니다.
  • 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) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleIntent(intent)
    }
    
    private fun handleIntent(intent: Intent) {
        if (Intent.ACTION_SEARCH == intent.action) {
            intent.getStringExtra(SearchManager.QUERY)?.also { query ->
                doMySearch(query)
            }
        }
    }
    

    Java

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.search);
        handleIntent(getIntent());
    }
    
    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(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);
        }
    }
    

    검색 실행 섹션의 코드 예와 비교할 때 이제 검색 인텐트를 처리하는 모든 코드가 handleIntent() 메서드에 있으므로 onCreate()onNewIntent() 모두 실행할 수 있습니다.

    시스템에서 onNewIntent(Intent)를 호출하면 활동이 다시 시작되지 않으므로 getIntent() 메서드는 onCreate()로 수신된 동일한 인텐트를 반환합니다. 따라서 onNewIntent(Intent) 내에서 setIntent(Intent)를 호출해야 합니다. 그래야 향후 getIntent()를 호출할 때 활동에 의해 저장된 인텐트가 업데이트됩니다.

일반적으로 "singleTop" 시작 모드를 사용하는 두 번째 시나리오가 좋습니다. 검색이 완료된 후 사용자가 추가 검색을 할 수도 있고 앱에서 검색 가능한 활동의 인스턴스를 여러 개 만드는 것을 원치 않기 때문입니다. 다음 예와 같이 앱 매니페스트에서 검색 가능 활동을 "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
}

Java

@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

Java

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

검색 위젯 사용

앱 상단 바의 검색 뷰를 보여주는 이미지

그림 1. 앱 바에 작업 뷰로 표시되는 SearchView 위젯

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

검색 위젯 구성

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

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) // Don't iconify the widget. Expand it by default.
    }

    return true
}

Java

@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); // Don't iconify the widget. Expand it by default.

    return true;
}

이제 검색 위젯이 구성되었으며 시스템에서 검색 가능 활동에 검색어를 전달합니다. 검색 위젯에 추천 검색어를 사용 설정할 수도 있습니다.

앱 바의 작업 뷰에 관한 자세한 내용은 작업 뷰 및 작업 제공자 사용을 참고하세요.

기타 검색 위젯 기능

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는 음성 검색 버튼이 변환된 텍스트를 검색 가능 활동에 반환하는 인식기를 실행해야 함을 지정합니다.

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

추천 검색어 추가

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

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

최근 검색어 추천
이러한 추천은 사용자가 이전에 앱에서 검색어로 사용한 단어입니다. 자세한 내용은 맞춤 추천 검색어 추가를 참고하세요.
맞춤 추천 검색어
사용자가 올바른 맞춤법이나 검색 항목을 즉시 선택할 수 있도록 자체 데이터 소스에서 제공하는 추천 검색어입니다. 자세한 내용은 맞춤 추천 검색어 추가를 참고하세요.