# Tarjeta

> Una superficie con borde, título y acciones opcionales. 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/card/

:::tip[En pocas palabras]
Una caja con borde que mantiene juntas las cosas relacionadas, como una ficha sobre una mesa.
:::

Una superficie redondeada con borde que agrupa contenido. `title` y `actions` añaden una fila de cabecera; `padding` y `width` controlan su caja.

`ui.card` · Categoría: [Visualización](https://albakore.github.io/pyzed/es/library/#visualización) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#card)

**Código:**

```python
ui.card(
    pz.column([
        ui.muted("Pyzed draws the UI with Iced, in Rust."),
        pz.row([pz.hspace(), ui.button("Cancel", on_cancel, variant="ghost"),
                ui.button("OK", on_ok, variant="solid")], spacing=8),
    ], spacing=12),
    title="Card",
    actions=[ui.icon_button("ellipsis", on_menu, size="sm")],
    width=380,
)
```

## Cuándo usarlo

- Para agrupar contenido relacionado: un resumen, una sección de formulario, un panel de un dashboard.
- Para un diálogo encima de la interfaz usa [Modal](https://albakore.github.io/pyzed/es/library/modal/).

## Uso

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

ui.card(
    pz.column([
        ui.muted("Pyzed draws the UI with Iced, in Rust."),
        pz.row([pz.hspace(), ui.button("Cancel", on_cancel, variant="ghost"),
                ui.button("OK", on_ok, variant="solid")], spacing=8),
    ], spacing=12),
    title="Card",
    actions=[ui.icon_button("ellipsis", on_menu, size="sm")],
    width=380,
)
```

## 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.card(ui.muted("A bordered surface."), width=260)
```

**} alt={**

```python
ui.card(ui.muted("Three files changed."), title="Changes", width=260)
```

```python
ui.card(ui.muted("Three files changed."), title="Changes",
        actions=[ui.icon_button("ellipsis", on_menu, size="sm")], width=260)
```

### Relleno

```python
ui.card(ui.label("Compact"), padding=8)
```

```python
ui.card(ui.label("Default"))
```

```python
ui.card(ui.label("Roomy"), padding=28)
```

### Estados y eventos

```python
ui.card(ui.muted("Python app with a window"), title="Desktop app", on_press=on_press,
        selected=True, width=260)
```

```python
ui.card(ui.muted("3 files changed"), title="Commit", footer=[ui.button("Push", on_press)],
        elevated=True, width=260)
```

## Eventos

Tarjeta 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 toda 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 Plans(pz.App):
    def __init__(self):
        self.plan = "Pro"

    def view(self):
        return pz.row([
            ui.card(ui.muted(f"Plan {name}"), title=name, width=160, selected=name == self.plan,
                    on_press=lambda name=name: setattr(self, "plan", name))   # the whole card
            for name in ("Free", "Pro", "Team")
        ], spacing=8)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Choose:
    plan: str

class Plans(pz.App):
    plan = "Pro"

    def update(self, message):
        match message:
            case Choose(plan):
                self.plan = plan

    def view(self):
        return pz.row([ui.card(ui.muted(name), title=name, width=160, selected=name == self.plan,
                               on_press=Choose(name)) for name in ("Free", "Pro", "Team")], spacing=8)
```

**Funcional:**

```python
from dataclasses import dataclass

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

def plan_card(name, selected, choose):        # a small function component
    return ui.card(ui.muted(name), title=name, width=160, selected=selected, on_press=choose)

def view(state, set_state):
    return pz.row([plan_card(n, n == state.plan, lambda n=n: set_state(plan=n))
                   for n in ("Free", "Pro", "Team")], spacing=8)
```

## Propiedades y API

### `ui.card`

```python
card(
    content,
    *,
    title=None,
    actions=(),
    padding=16,
    width=None,
    footer=(),
    on_press=None,
    selected=False,
    elevated=False,
    theme=None,
)
```

Una superficie con borde para agrupar contenido, con título y acciones opcionales.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `content` | *obligatorio* | Contenido: un `Widget`, un texto o un número (se convierte en texto). |
| `title` | `None` | Título. |
| `actions` | `()` | Widgets extra (normalmente botones) que se muestran como acciones. |
| `padding` | `16` | Relleno interior. |
| `width` | `None` | Ancho: píxeles, `"fill"`, `"shrink"` o `"fill:N"` (proporción). |
| `footer` | `()` | Widgets abajo a la derecha (botones). |
| `selected` | `False` | La resalta con el color de acento. |
| `elevated` | `False` | Añade una sombra. |
| `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/#card)

## Relacionados

- [Modal](https://albakore.github.io/pyzed/es/library/modal/): Una superficie de diálogo con título, contenido y botones al pie.
- [Grupo de ajustes](https://albakore.github.io/pyzed/es/library/settings-group/): Un bloque con título de filas de ajustes, para pantallas de ajustes.
- [Estado vacío](https://albakore.github.io/pyzed/es/library/empty-state/): Un marcador centrado para listas y búsquedas vacías.