# Cifra

> Una cifra de dashboard con variación y minigráfico. Un componente nativo de Pyzed para GUIs de escritorio en Python, con vista previa, ejemplos y su API.

Source: https://albakore.github.io/pyzed/es/library/stat/

:::tip[En pocas palabras]
Un número grande con su nombre y si subió o bajó, como en un panel de control.
:::

Un panel de dashboard: un título, un valor grande, una variación opcional (`delta`, mostrada como `+4.2%` en verde o rojo) y una `trend` opcional dibujada como minigráfico.

`ui.stat` · Categoría: [Datos](https://albakore.github.io/pyzed/es/library/#datos) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#stat)

**Código:**

```python
pz.row([
    ui.stat("Users", "1,284", delta=12.5, trend=[3, 5, 4, 6, 8, 7, 9], width=200),
    ui.stat("Errors", "37", delta=-8.0, width=200),
    ui.stat("Build time", "1m 12s", width=200),
], spacing=12)
```

## Cuándo usarlo

- Para las cifras clave en la parte de arriba de un dashboard o informe.

## Uso

```python
import pyzed as pz
from pyzed import ui

pz.row([
    ui.stat("Users", "1,284", delta=12.5, trend=[3, 5, 4, 6, 8, 7, 9], width=200),
    ui.stat("Errors", "37", delta=-8.0, width=200),
    ui.stat("Build time", "1m 12s", width=200),
], spacing=12)
```

## Variantes

:::note[Sobre estas capturas]
Cada captura la graba pyzed mismo, fuera de pantalla a 2x, en One Dark o One Light según el tema de este sitio, y recortada al componente para que se vea a su tamaño real. El puntero pasa por encima, pulsa o escribe en él; un componente que no reacciona al puntero recorre algunos temas. Con movimiento reducido ves el primer fotograma. Abre **Código** bajo una captura para ver el fragmento que la dibuja; los nombres libres como `on_save` son tus propios callbacks.
:::

### Contenido

```python
ui.stat("Build time", "1m 12s", width=190)
```

```python
ui.stat("Users", "1,284", delta=12.5, width=190)
```

```python
ui.stat("Errors", "37", delta=-8.0, width=190)
```

```python
ui.stat("Revenue", "$9.4k", delta=4.2, trend=[3, 5, 4, 6, 8, 7, 9], width=190)
```

### Estados y eventos

Con `inverse=True` una bajada es una buena noticia (verde), para errores o latencia.

```python
ui.stat("Errors", "12", delta=-8.0, inverse=True, icon="bug", width=180)
```

```python
ui.stat("Users", "1,204", delta=4.2, icon="users", on_press=on_press, width=180)
```

## Eventos

Cifra tiene **1 evento propios**, en la tabla de abajo. Como todo widget, también tiene los **18 eventos comunes** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), que se conectan con `.on(...)`: mira [Eventos](https://albakore.github.io/pyzed/es/guides/events/) y [Eventos de cada componente](https://albakore.github.io/pyzed/es/library/events/).

| Evento | El handler recibe | Cuándo |
| --- | --- | --- |
| `on_press` | `()` | Hace pulsable la tarjeta. |

**El handler recibe** es lo que Pyzed le pasa a tu función: `()` es nada. Cualquier handler también puede ser un mensaje (un valor que no se puede llamar), que va a `update()`.

### Manejar los eventos

Los mismos eventos escritos de tres formas. **Imperativa**: métodos de la app que cambian `self`. **Declarativa**: los handlers producen mensajes y un único `update()` decide. **Funcional**: una función pura dibuja un estado inmutable y pide cambios con `set_state(...)`. Mira [Imperativo, declarativo y funcional](https://albakore.github.io/pyzed/es/guides/code-styles/).

**Imperativo:**

```python
class Dashboard(pz.App):
    def __init__(self):
        self.detail = None

    def view(self):
        return pz.column([
            pz.row([ui.stat("Users", "1,284", delta=12.5, width=200,
                            on_press=lambda: setattr(self, "detail", "Users")),   # the whole card
                    ui.stat("Errors", "37", delta=-8.0, width=200,
                            on_press=lambda: setattr(self, "detail", "Errors"))], spacing=12),
            ui.muted(f"Details of {self.detail}" if self.detail else "Click a number"),
        ], spacing=8)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Open:
    metric: str

class Dashboard(pz.App):
    detail = None

    def update(self, message):
        match message:
            case Open(metric):
                self.detail = metric

    def view(self):
        return pz.row([ui.stat(m, v, width=200, on_press=Open(m))
                       for m, v in (("Users", "1,284"), ("Errors", "37"))], spacing=12)
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    detail: str = ""

def view(state, set_state):
    return pz.row([ui.stat(m, v, width=200, on_press=lambda m=m: set_state(detail=m))
                   for m, v in (("Users", "1,284"), ("Errors", "37"))], spacing=12)
```

## Propiedades y API

### `ui.stat`

```python
stat(
    title,
    value,
    *,
    delta=None,
    trend=None,
    width=None,
    icon=None,
    inverse=False,
    on_press=None,
    theme=None,
)
```

Un número de panel: título, valor grande, variación opcional (`+4.2%`) y sparkline.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `title` | *obligatorio* | Título. |
| `value` | *obligatorio* | Valor actual. |
| `delta` | `None` | Variación en %; verde si es positiva, roja si no. |
| `trend` | `None` | Valores para la sparkline. |
| `width` | `None` | Ancho: píxeles, `"fill"`, `"shrink"` o `"fill:N"` (proporción). |
| `icon` | `None` | Icono antes del título. |
| `inverse` | `False` | Pinta de verde una bajada y de rojo una subida (errores, latencia…). |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

Eventos: `on_press` ([eventos](#eventos)).

[Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#stat)

## Relacionados

- [Minigráfico](https://albakore.github.io/pyzed/es/library/sparkline/): Un gráfico de líneas diminuto para tendencias.
- [Gráfico de barras](https://albakore.github.io/pyzed/es/library/bar-chart/): Un gráfico de barras verticales con etiquetas.
- [Dona](https://albakore.github.io/pyzed/es/library/donut/): Un gráfico de dona con una etiqueta en el centro.