앱 위젯은 구성 가능합니다. 예를 들어 시계 위젯을 사용하면 사용자가 표시할 시간대를 구성할 수 있습니다.
사용자가 위젯의 설정을 구성할 수 있도록 하려면 위젯 구성 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>
활동은 정규화된 네임스페이스로 선언됩니다. 런처가 패키지 범위 외부에서 활동을 참조하기 때문입니다.
이것으로 구성 활동을 시작하는 데 필요한 모든 것입니다. 다음으로 실제 활동을 구현해야 합니다.
구성 활동 구현
활동을 구현할 때 기억해야 할 두 가지 중요한 사항이 있습니다.
- 앱 위젯 호스트는 구성 활동을 호출하고 구성 활동은 항상 결과를 반환해야 합니다. 결과에는 활동을 실행한 인텐트에 의해 전달되고 인텐트 추가 항목에
EXTRA_APPWIDGET_ID
로 저장된 앱 위젯 ID가 포함되어야 합니다. - 시스템은 구성 활동이 실행될 때
ACTION_APPWIDGET_UPDATE
브로드캐스트를 전송하지 않습니다. 즉, 위젯이 생성될 때onUpdate()
메서드를 호출하지 않습니다. 위젯을 처음 만들 때AppWidgetManager
에서 업데이트를 요청하는 것은 구성 활동의 책임입니다. 그러나 후속 업데이트에서는onUpdate()
가 호출되며 처음에만 건너뜁니다.
구성에서 결과를 반환하고 위젯을 업데이트하는 방법에 관한 예는 다음 섹션의 코드 스니펫을 참고하세요.
구성 활동에서 위젯 업데이트
위젯이 구성 활동을 사용하는 경우 구성이 완료된 후 위젯을 업데이트하는 것은 활동의 책임입니다. 이렇게 하려면 AppWidgetManager
에서 직접 업데이트를 요청하면 됩니다.
다음은 위젯을 올바르게 업데이트하고 구성 활동을 닫는 절차를 요약한 것입니다.
활동을 실행한 인텐트에서 앱 위젯 ID를 가져옵니다.
Kotlin
val appWidgetId = intent?.extras?.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
Java
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); }
활동 결과를
RESULT_CANCELED
로 설정합니다.이렇게 하면 사용자가 끝에 도달하기 전에 활동을 종료하면 시스템은 앱 위젯 호스트에 구성이 취소되었고 호스트가 위젯을 추가하지 않았음을 알립니다.
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_CANCELED, resultValue)
Java
int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(Activity.RESULT_CANCELED, resultValue);
사용자의 환경설정에 따라 위젯을 구성합니다.
구성이 완료되면
getInstance(Context)
를 호출하여AppWidgetManager
의 인스턴스를 가져옵니다.Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
updateAppWidget(int,RemoteViews)
를 호출하여RemoteViews
레이아웃으로 위젯을 업데이트합니다.Kotlin
val views = RemoteViews(context.packageName, R.layout.example_appwidget) appWidgetManager.updateAppWidget(appWidgetId, views)
Java
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget); appWidgetManager.updateAppWidget(appWidgetId, views);
반환 인텐트를 만들고, 활동 결과로 설정하고, 활동을 완료합니다.
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_OK, resultValue) finish()
Java
Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(RESULT_OK, resultValue); finish();
GitHub의 ListWidgetConfigureActivity.kt
샘플 클래스를 참고하세요.
위젯 구성 옵션
기본적으로 앱 위젯 호스트는 사용자가 위젯을 홈 화면에 추가한 직후 구성 활동을 한 번만 실행합니다. 그러나 기본 위젯 구성을 제공하여 사용자가 기존 위젯을 재구성하거나 초기 위젯 구성을 건너뛸 수 있도록 하는 옵션을 지정할 수 있습니다.
사용자가 배치된 위젯을 재구성할 수 있도록 함
사용자가 기존 위젯을 재구성할 수 있도록 하려면 appwidget-provider
의 widgetFeatures
속성에 reconfigurable
플래그를 지정합니다. 자세한 내용은 AppWidgetProviderInfo.xml
파일 선언 가이드를 참고하세요. 예:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
사용자는 위젯을 길게 터치하고 그림 1에 1로 표시된 재구성 버튼을 탭하여 위젯을 재구성할 수 있습니다.
![버튼이 오른쪽 하단에 표시됨](https://developer.android.google.cn/static/images/appwidgets/widget-reconfigure-button.png?authuser=9&hl=ko)
위젯의 기본 구성 사용
사용자가 초기 구성 단계를 건너뛸 수 있도록 하여 더 원활한 위젯 환경을 제공할 수 있습니다. 이렇게 하려면 widgetFeatures
필드에 configuration_optional
플래그와 reconfigurable
플래그를 모두 지정합니다. 이를 통해 사용자가 위젯을 추가한 후 구성 활동 실행을 우회할 수 있습니다. 앞서 언급했듯이 사용자는 나중에 위젯을 재구성할 수 있습니다. 예를 들어 시계 위젯은 초기 구성을 우회하고 기본적으로 기기 시간대를 표시할 수 있습니다.
다음은 구성 활동을 재구성 가능한 활동과 선택사항으로 표시하는 방법을 보여주는 예입니다.
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>