Cómo permitir que los usuarios configuren widgets de apps

Los widgets de las apps se pueden configurar. Por ejemplo, un widget de reloj puede permitir que los usuarios configurar la zona horaria que se mostrará.

Si quieres permitir que los usuarios configuren el widget, crea uno. configuración Activity. Esta actividad es iniciar automáticamente el host del widget de la aplicación, ya sea cuando se crea el widget o una posterior, según las opciones de configuración que especificar.

Declara la actividad de configuración

Declara la actividad de configuración como una actividad normal en el manifiesto de Android . El host del widget de la app la inicia con la ACTION_APPWIDGET_CONFIGURE acción, por lo que la actividad debe aceptar este intent. Por ejemplo:

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

Declara la actividad en el archivo AppWidgetProviderInfo.xml con el elemento android:configure. Obtén más información sobre declarar este archivo. Aquí hay un ejemplo de cómo declarar la actividad de configuración:

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

La actividad se declara con un espacio de nombres completamente calificado, ya que el selector hace referencia a él desde fuera del alcance de tu paquete.

Eso es todo lo que necesitas para iniciar una actividad de configuración. A continuación, debes implementar la actividad real.

Implementa la actividad de configuración

Hay dos puntos importantes que debes recordar cuando implementes la actividad:

  • El host del widget de la app llama a la actividad de configuración, y la herramienta siempre debe mostrar un resultado. El resultado debe incluir el widget de la app ID que pasa el intent que inició la actividad (guardado en el intent) extras como EXTRA_APPWIDGET_ID
  • El sistema no envía ACTION_APPWIDGET_UPDATE cuando se lanza una actividad de configuración, lo que significa que no llama al método onUpdate() cuando se cree el widget. Es responsabilidad de la actividad de configuración solicitar una actualización a el AppWidgetManager cuando crees el widget por primera vez. Sin embargo, Se llama a onUpdate() para las actualizaciones posteriores; solo se omite primera vez.

Consulta los fragmentos de código de la siguiente sección para ver un ejemplo de cómo mostrar un resultado de la configuración y actualizan el widget.

Cómo actualizar el widget desde la actividad de configuración

Cuando un widget usa una actividad de configuración, es responsabilidad de la actividad para actualizar el widget cuando se complete la configuración. Puedes hacerlo solicitando una actualización directamente AppWidgetManager

Este es un resumen del procedimiento para actualizar correctamente el widget y cerrar la de configuración de Terraform:

  1. Obtén el ID del widget de la app desde el intent que inició la actividad:

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

  2. Establece el resultado de la actividad en RESULT_CANCELED.

    De esta manera, si el usuario cancela la actividad antes de llegar al final, el notifica al host del widget de la app que se cancela la configuración el host no agrega el widget:

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

  3. Configura el widget según las preferencias del usuario.

  4. Cuando se complete la configuración, obtén una instancia del AppWidgetManager llamando a getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Actualiza el widget con un Diseño de RemoteViews llamando updateAppWidget(int,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);

  6. Crear el intent que se muestra, establecerlo con el resultado de la actividad terminar la actividad:

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

Consulta la ListWidgetConfigureActivity.kt de muestra en GitHub para ver un ejemplo.

Opciones de configuración del widget

De forma predeterminada, el host del widget de la app solo inicia la actividad de configuración una vez. inmediatamente después de que el usuario agrega el widget a su pantalla principal. Sin embargo, especificar opciones que permitan a los usuarios reconfigurar widgets existentes o omitir la configuración inicial del widget proporcionando una configuración predeterminada del widget.

Cómo permitir que los usuarios reconfiguren los widgets colocados

Para permitir que los usuarios vuelvan a configurar los widgets existentes, especifica el reconfigurable marca en la widgetFeatures de appwidget-provider. Consulta la guía para declarar AppWidgetProviderInfo.xml archivo para obtener más información información. Por ejemplo:

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

Los usuarios pueden volver a configurar su widget tocando & Manteniendo presionado el widget y presionando el botón Reconfigurar, que está etiquetado 1 en la figura 1.

El botón aparece en la esquina inferior derecha
Figura 1: Botón para Reconfigurar del widget.

Cómo usar la configuración predeterminada del widget

Puedes proporcionar una experiencia de widget más fluida si permites que los usuarios omitan el el paso de configuración inicial. Para hacerlo, especifica configuration_optional y reconfigurable en el campo widgetFeatures. De esta manera, se evita iniciar la actividad de configuración después de que un usuario agrega el widget. Como se mencionó anteriormente, el usuario aún puede reconfigurar el widget después. Por ejemplo, un widget de reloj puede omitir la configuración inicial y muestra la zona horaria del dispositivo de forma predeterminada.

Este es un ejemplo de cómo marcar tu actividad de configuración como ambas reconfigurables y opcionales:

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