사용자가 앱 위젯을 구성하도록 사용 설정

앱 위젯은 구성 가능합니다. 예를 들어 시계 위젯을 사용하면 사용자가 표시할 시간대를 구성합니다.

사용자가 위젯 설정을 구성할 수 있도록 하려면 위젯을 만드세요. 구성 Activity 이 활동은 지정된 구성 옵션에 따라 위젯이 생성될 때 또는 그 이후에 앱 위젯 호스트에 의해 자동으로 실행됩니다.

구성 활동 선언

Android 매니페스트 파일에서 구성 활동을 일반 활동으로 선언합니다. 앱 위젯 호스트는 ACTION_APPWIDGET_CONFIGURE 작업으로 이를 실행하므로 활동에서 이 인텐트를 수락해야 합니다. 예를 들면 다음과 같습니다.

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

android:configure 속성을 사용하여 AppWidgetProviderInfo.xml 파일에 활동을 선언합니다. 다음에 대해 자세히 알아보기 이 파일을 선언합니다. 이 예시에서는 방법은 다음과 같습니다.

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

런처가 완전히 자격을 갖춘 네임스페이스로 선언되는 이유는 패키지 범위 밖에서 이를 참조할 수 있습니다.

구성 활동을 시작하기 위해 필요한 작업은 이게 전부입니다. 다음으로 실제 활동을 구현할 수 있습니다.

구성 활동 구현

활동을 구현할 때 기억해야 할 두 가지 중요한 사항이 있습니다.

• 앱 위젯 호스트가 구성 활동을 호출하고 활동은 항상 결과를 반환해야 합니다. 결과에는 활동을 실행한 인텐트에 의해 전달된 앱 위젯 ID(추가 인텐트에 EXTRA_APPWIDGET_ID로 저장됨)가 포함되어야 합니다.
• 시스템은 구성 활동이 실행될 때 ACTION_APPWIDGET_UPDATE 브로드캐스트를 전송하지 않으므로 위젯이 생성될 때 onUpdate() 메서드를 호출하지 않습니다. 구성 활동의 책임은 AppWidgetManager에서 발생해야 합니다. 하지만 onUpdate()는 후속 업데이트를 위해 호출되며 확인할 수 있습니다

를 반환하는 방법의 예는 다음 섹션의 코드 스니펫을 참조하세요. 결과를 가져와 위젯을 업데이트합니다.

구성 활동에서 위젯 업데이트

위젯이 구성 활동을 사용하는 경우 구성 완료 시 위젯을 업데이트하기 위한 활동 AppWidgetManager에서 직접 업데이트를 요청하여 그렇게 할 수 있습니다.

다음은 위젯을 올바르게 업데이트하고 구성 활동:

1. 활동을 실행한 인텐트에서 앱 위젯 ID를 가져옵니다.

   Kotlin

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

   자바

   Intent intent = getIntent();
   Bundle extras = intent.getExtras();
   int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
   if (extras != null) {
       appWidgetId = extras.getInt(
               AppWidgetManager.EXTRA_APPWIDGET_ID,
               AppWidgetManager.INVALID_APPWIDGET_ID);
   }
   

2. 활동 결과를 RESULT_CANCELED로 설정합니다.

   이렇게 하면 사용자가 끝에 도달하기 전에 활동을 취소하면 시스템은 앱 위젯 호스트에 구성이 취소되었음을 알리고 호스트는 위젯을 추가하지 않습니다.

   Kotlin

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

   자바

   int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(Activity.RESULT_CANCELED, resultValue);
   

3. 사용자의 환경설정에 따라 위젯을 구성합니다.

4. 구성이 완료되면 getInstance(Context)를 호출하여 AppWidgetManager 인스턴스를 가져옵니다.

   Kotlin

   val appWidgetManager = AppWidgetManager.getInstance(context)
   

   자바

   AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
   

5. updateAppWidget(int,RemoteViews)를 호출하여 RemoteViews 레이아웃으로 위젯을 업데이트합니다.

   Kotlin

   val views = RemoteViews(context.packageName, R.layout.example_appwidget)
   appWidgetManager.updateAppWidget(appWidgetId, views)
   

   자바

   RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
   appWidgetManager.updateAppWidget(appWidgetId, views);
   

6. 반환 인텐트를 만들고 활동 결과로 설정합니다. 마무리:

   Kotlin

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

   자바

   Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
   setResult(RESULT_OK, resultValue);
   finish();
   

자세한 내용은 ListWidgetConfigureActivity.kt 를 참조하세요.

위젯 구성 옵션

기본적으로 앱 위젯 호스트는 구성 활동을 한 번만 시작합니다. 를 표시할 수 있습니다. 하지만 사용자가 기존 위젯을 재구성할 수 있도록 하거나 기본 위젯 구성을 제공하여 초기 위젯 구성을 건너뛰도록 하는 옵션을 지정할 수 있습니다.

참고: 이 옵션은 Android 12(API 수준 31)부터만 사용할 수 있습니다. 나 이전 버전의 Android에 대해 지정할 수는 있지만 이를 무시하고 기본 동작을 따릅니다.

사용자가 배치된 위젯을 재구성할 수 있도록 함

사용자가 기존 위젯을 재구성할 수 있도록 하려면 reconfigurable 플래그 widgetFeatures 속성 appwidget-provider. 자세한 내용은 AppWidgetProviderInfo.xml 파일 선언 가이드를 참고하세요. 예를 들면 다음과 같습니다.

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

사용자는 위젯을 길게 터치하고 그림 1에서 1로 라벨이 지정된 재구성 버튼을 탭하여 위젯을 재구성할 수 있습니다.

그림 1. 위젯 재구성 버튼

를 통해 개인정보처리방침을 정의할 수 있습니다.

참고: reconfigurable 플래그는 Android 9 (API 수준 28)에서 도입되었지만 Android 12까지는 널리 지원되지 않았습니다.

위젯의 기본 구성 사용

사용자가 초기 구성 단계 이렇게 하려면 configuration_optional widgetFeatures 필드에 reconfigurable 플래그를 포함합니다. 이를 통해 사용자가 위젯을 추가한 후 구성 활동 실행을 우회할 수 있습니다. 앞서 언급했듯이 이전에도 사용자가 계속 위젯을 재구성할 수 있습니다. 있습니다. 예를 들어 시계 위젯은 초기 구성을 우회하고 기본적으로 기기 시간대를 표시할 수 있습니다.

다음은 구성 활동을 재구성 가능 및 선택사항으로 모두 표시하는 방법을 보여주는 예입니다.

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>