# Campo de formulario

> Una fila de ajustes: título y descripción a la izquierda, control a la derecha. Componente de Pyzed para GUIs de escritorio en Python, con ejemplos y API.

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

:::tip[En pocas palabras]
Una fila de un formulario: el nombre de un ajuste a la izquierda y su control a la derecha.
:::

Una fila de formulario como las de una pantalla de ajustes: el título (y una descripción opcional) a la izquierda y cualquier control a la derecha. Apila varias en una columna o en un [Grupo de ajustes](https://albakore.github.io/pyzed/es/library/settings-group/).

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

**Código:**

```python
pz.column([
    ui.field("Autosave", ui.switch(True, on_toggle), description="Saves when you switch tabs"),
    ui.field("Format on save", ui.checkbox(False, on_toggle)),
    ui.field("Font size", ui.number_field(14, on_change, suffix="px")),
], spacing=14, width=440)
```

## Cuándo usarlo

- Para preferencias y formularios en los que cada control necesita una etiqueta y quizá una pista.
- Alinea interruptores, selects y campos numéricos de anchos distintos.

## Uso

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

pz.column([
    ui.field("Autosave", ui.switch(True, on_toggle), description="Saves when you switch tabs"),
    ui.field("Format on save", ui.checkbox(False, on_toggle)),
    ui.field("Font size", ui.number_field(14, on_change, suffix="px")),
], spacing=14, width=440)
```

## 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.
:::

### Control

```python
pz.container(ui.field("Autosave", ui.switch(True, on_toggle)), width=380)
```

```python
pz.container(ui.field("Font size", ui.number_field(14, on_change, suffix="px")), width=380)
```

```python
pz.container(ui.field("Theme", ui.select(["One Dark", "One Light"], "One Dark", on_select, width=150)), width=380)
```

```python
pz.container(ui.field("Name", ui.input("Pyzed", on_input, width=180)), width=380)
```

### Ayuda y errores

```python
pz.container(ui.field("Autosave", ui.switch(True, on_toggle), description="Saves when you switch tabs"), width=380)
```

```python
pz.container(ui.field("Port", ui.number_field(80, on_change), error="Ports below 1024 need admin rights"), width=380)
```

### Estados y eventos

```python
pz.container(ui.field("Name", ui.input("", on_input, width=180), required=True), width=380)
```

```python
pz.container(ui.field("Email", ui.input("ada@", on_input, invalid=True), vertical=True, required=True,
                      error="Enter a valid email"), width=320)
```

## Eventos

Campo de formulario no tiene eventos propios: muestra lo que le das. 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/).

## Propiedades y API

### `ui.field`

```python
field(
    title,
    control,
    *,
    description=None,
    error=None,
    required=False,
    vertical=False,
    theme=None,
)
```

Una fila de formulario: título y descripción a la izquierda, control a la derecha (como una pantalla de ajustes).

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `title` | *obligatorio* | Título. |
| `control` | *obligatorio* | El control (switch, input…). |
| `description` | `None` | Texto de ayuda. |
| `error` | `None` | Un mensaje de validación que se muestra bajo el título con el color de error (ver `pz.validation_errors`). |
| `required` | `False` | Añade un `*` rojo tras el título. |
| `vertical` | `False` | Pone el control bajo el título. |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

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

## Relacionados

- [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.
- [Interruptor](https://albakore.github.io/pyzed/es/library/switch/): Un interruptor para ajustes que se aplican al momento.
- [Campo numérico](https://albakore.github.io/pyzed/es/library/number-field/): Un número con botones −/+, límites, paso y sufijo.