Cómo agregar complicaciones a una cara de reloj

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Una complicación de una cara de reloj muestra datos de una fuente de datos. Con la API de Complications, las caras de reloj pueden seleccionar las fuentes de datos que desean utilizar para obtener los datos subyacentes. Esto permite que las caras de reloj muestren información además de la hora del día, sin necesidad de utilizar código para obtener los datos.

Cómo usar un ComplicationSlotsManager

Para agregar complicaciones a una cara de reloj, usa un ComplicationSlotsManager.

El ComplicationSlotsManager define cuántas complicaciones admite una cara de reloj y dónde se ubican en la pantalla. Para admitir el cambio de ubicación o la cantidad de complicaciones, el ComplicationSlotsManager también usa el CurrentUserStyleRepository, como se muestra en el siguiente ejemplo:

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }

        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

Tipos y campos

En la siguiente tabla, se describen los tipos y los campos del objeto ComplicationData. Si una cara de reloj solicita un campo que no es válido para un tipo de complicación, se mostrará un valor predeterminado. Por ejemplo, si una cara de reloj intenta acceder a un campo LONG_TEXT en un tipo SHORT_TEXT, se muestra el valor predeterminado del campo LONG_TEXT (nulo).

Tipo Campos obligatorios Campos opcionales Notas
SHORT_TEXT Texto corto Ícono
Ícono de protección de pantalla
Título corto
Muestra solo un ícono o título corto si se proporcionan uno o ambos.
ICON Icon Burn-in protection icon Se usa cuando no se necesita texto. Se prevé que el ícono sea de un solo color y el tono puede ajustarse según la cara de reloj.
RANGED_VALUE Valor
Valor mínimo
Valor máximo
Ícono
Ícono de protección de pantalla
Texto corto
Título corto
No se garantiza que se muestren los campos opcionales. Si quieres diseñar tu propia barra de progreso, puedes usar el método isRangedValueProgressHidden() para ocultar la barra de progreso proporcionada por la clase ComplicationDrawable.
LONG_TEXT Texto largo Título largo
Ícono
Ícono de protección de pantalla
Imagen pequeña
Muestra el título largo si está incluido.
SMALL_IMAGE Imagen pequeña Una imagen pequeña puede tener dos estilos: de foto o de ícono. El estilo de foto implica que debe llenar el espacio y se puede recortar; el de ícono, que no se debe recortar y que se puede rellenar. La variabilidad de la imagen puede producir una imagen no apta para mostrar en el modo ambiente en dispositivos con protección de pantalla o en modo ambiente con baja velocidad de bits. Cuando la protección de pantalla o el modo ambiente con baja velocidad de bits están habilitados, la cara de reloj puede usar Burn-in protection small image porque es seguro. De lo contrario, debido a que para una cara de reloj es difícil determinar la aptitud, no debería mostrarse la imagen.
LARGE_IMAGE Large image Se prevé que esta imagen sea suficientemente grande como para llenar la cara de reloj. La variabilidad de la imagen puede producir una imagen no apta para mostrar en el modo ambiente en dispositivos con protección de pantalla o en modo ambiente con baja velocidad de bits. Debido a que es difícil para una cara de reloj determinar si una imagen es apta para mostrar, no debe mostrar una imagen en modo ambiente si se habilita la protección de pantalla o el modo ambiente con baja velocidad de bits.

Los tipos que se indican en la siguiente tabla corresponden a datos vacíos y se pueden enviar para cualquier espacio para complicación. No tienen campos y no es necesario incluirlos en una lista de tipos compatibles. Permiten a las caras de reloj diferenciar entre estos tres casos:

  • No se seleccionó ninguna fuente.
  • El usuario seleccionó "empty" para un espacio.
  • Una fuente no tiene datos para enviar.

Las fuentes no deben enviar TYPE_EMPTY en respuesta a solicitudes de actualización. En su lugar, las fuentes deben enviar TYPE_NO_DATA.

Los detalles correspondientes a los tipos de complicaciones para datos "vacíos" se encuentran en la siguiente tabla:

Tipo de complicación Descripción
TYPE_NOT_CONFIGURED Lo envía el sistema cuando se activa una complicación, pero el usuario no seleccionó una fuente y no se estableció un valor predeterminado.

No lo pueden enviar fuentes.

TYPE_EMPTY Lo envía el sistema cuando se activa una complicación y el usuario seleccionó "empty" en lugar de una fuente, o bien cuando la cara de reloj no seleccionó una fuente ni este tipo como valor predeterminado.

No lo pueden enviar fuentes.

TYPE_NO_DATA Lo envía el sistema cuando se activa una complicación (que tiene una fuente) para borrarla antes de que la fuente envíe datos reales.

Lo deben enviar las fuentes si no tienen datos reales para enviar.

Para obtener más información, consulta el ejemplo de cara de reloj que está en GitHub.