검색 인터페이스 만들기

Compose 방식으로 시도

Jetpack Compose는 Android에 권장되는 UI 도구 키트입니다. Compose에서 검색 기능을 추가하는 방법을 알아봅니다.

검색창 →

앱에 검색 기능을 추가할 준비가 되면 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 extra에서 쿼리를 검색한 후 데이터를 검색하고 결과를 표시합니다.

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

검색 가능 활동 선언

검색하고 결과를 표시할 Activity가 아직 없다면 만드세요. 검색 기능은 아직 구현하지 않아도 됩니다. 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" 사용)을 포함하고 검색 가능한 구성 파일의 참조와 함께 android:resource 속성을 포함해야 합니다. 앞의 예시에서는 res/xml/searchable.xml 파일을 참조합니다.

검색하기

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

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

쿼리 수신

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

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을 확인하고, 진행률 표시기를 표시하는 방법에 관한 자세한 내용은 ProgressBar를 참고하세요.

결과 표시

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

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

검색 대화상자 사용

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

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

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

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

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

<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() 메서드를 재정의합니다. 시스템에서 이 메서드를 호출하면 이는 입력 포커스가 활동에서 검색 대화상자로 옮겨졌으며 이벤트에 적합한 모든 작업(예: 게임 일시중지)을 할 수 있다는 것을 나타냅니다. 이 문서의 다른 섹션에서 설명한 대로 검색 컨텍스트 데이터를 전달하지 않는 경우 슈퍼클래스 구현을 호출하여 메서드를 종료합니다.

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

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

  자바

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

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

  시스템에서 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()를 호출해 검색 대화상자를 활성화합니다. 예를 들면 다음과 같습니다.

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에서 추가 데이터를 추출하여 검색 범위를 더 좁힐 수 있습니다.

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

검색 위젯 사용

그림 1. 앱 바의 작업 뷰인 SearchView 위젯

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

검색 위젯 구성

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

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

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

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
}

@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 시스템의 지원을 통해 추천 검색어를 제공할 수 있습니다. 시스템에서는 추천 검색어 목록을 관리하고 사용자가 추천 검색어를 선택하면 이벤트를 처리합니다.

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

최근 검색어 추천

이 추천어는 사용자가 이전에 앱에서 검색어로 사용한 단어입니다. 자세한 내용은 맞춤 추천 검색어 추가를 참고하세요.

맞춤 추천 검색어

개발자가 고유의 데이터 소스에서 제공하는 추천 검색어이며 사용자가 찾고 있는 올바른 맞춤법 또는 항목을 즉시 선택하도록 도와줍니다. 자세한 내용은 맞춤 검색어 추천 추가를 참고하세요.