Cómo agregar complicaciones a una cara de reloj

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 Ícono 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 se espera que llene el espacio y que se pueda recortar. El estilo de ícono indica que no se puede 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 están habilitados la protección de pantalla o el modo ambiente con baja velocidad de bits, la cara de reloj puede usar una imagen pequeña de protección de pantalla, ya que es seguro. De lo contrario, debido a que para una cara de reloj es difícil determinar la aptitud, no se muestra la imagen.
LARGE_IMAGE Imagen grande 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 mostrará una imagen en modo ambiente si se habilita la protección de pantalla o el modo ambiente con baja velocidad de bits.

En la siguiente tabla, se describen los tipos de complicaciones para datos vacíos que se pueden enviar a 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 pueden enviar TYPE_EMPTY en respuesta a solicitudes de actualización. Envía TYPE_NO_DATA en su lugar.

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.

Las fuentes no pueden enviarlo.

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

Las fuentes no pueden enviarlo.

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.

Las fuentes pueden enviarlo si no tienen datos reales para enviar.

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