# Selector de hora

> Un campo de hora con columnas de horas y minutos, en 24 o 12 horas. Componente de Pyzed para GUIs de escritorio en Python, con ejemplos y API.

Source: https://albakore.github.io/pyzed/es/library/time-picker/

:::tip[En pocas palabras]
Una casilla para una hora del día, con listas de horas y minutos para elegir.
:::

`ui.TimePicker` es un campo para una hora del día. Su ventana tiene una columna de horas, una de minutos (cada `minute_step` minutos), segundos si el formato tiene `ss` y AM/PM si tiene `A` o `h`. ↑ y ↓ la mueven un paso desde el teclado. `on_change` recibe un `datetime.time`.

`ui.TimePicker` · Categoría: [Fechas y horas](https://albakore.github.io/pyzed/es/library/#fechas-y-horas) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#timepicker)

**Código:**

```python
pz.row([
    pz.container(ui.TimePicker(value="14:30", on_change=on_change), width=140, height=290, align_y="start"),
    pz.container(ui.TimePicker(value="14:30", format="h:mm A", minute_step=15, on_change=on_change),
                 width=140, height=290, align_y="start"),
], spacing=24)
```

:::note[Nuevo]
Este componente se añadió hace poco. Cuéntanos qué tal te funciona en el [gestor de incidencias](https://github.com/albakore/pyzed/issues).
:::

## Cuándo usarlo

- Para alarmas, horarios de apertura, reuniones y recordatorios.
- `format="HH:mm"` es de 24 horas; `"h:mm A"` es de 12 horas con AM/PM; `"HH:mm:ss"` añade segundos.

## Uso

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

import datetime

class Alarm(pz.App):
    def __init__(self):
        self.at = datetime.time(7, 30)

    def view(self):
        return ui.field("Wake me at", ui.TimePicker(value=self.at, format="h:mm A",
                                                    on_change=lambda e: setattr(self, "at", e.value)))
```

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

### Formato

```python
ui.TimePicker(value="14:30", on_change=on_change)
```

```python
ui.TimePicker(value="14:30", format="h:mm A", on_change=on_change)
```

```python
ui.TimePicker(value="14:30:15", format="HH:mm:ss", on_change=on_change)
```

### Abierto

```python
ui.TimePicker(value="06:15:30", format="HH:mm:ss", on_change=on_change)
```

```python
ui.TimePicker(value="14:30", format="h:mm A", minute_step=15, on_change=on_change)
```

## Eventos

Selector de hora tiene **3 eventos 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/).

Es un `pz.Component`, así que también lanza `on_mount` y `on_unmount`, y sus handlers reciben un `pz.Event` cuyo `value` trae el dato.

| Evento | El handler recibe | Cuándo |
| --- | --- | --- |
| `on_change` | `(event)` | Recibe `event.value`: un `datetime.time` o `None`. |
| `on_open` | `(event)` | Se abrió la lista. |
| `on_close` | `(event)` | Se cerró la lista. |

**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
import datetime

class Alarm(pz.App):
    def __init__(self):
        self.at = datetime.time(7, 30)

    def changed(self, event):            # on_change: event.value is a datetime.time
        self.at = event.value

    def view(self):
        return pz.column([
            ui.TimePicker(value=self.at, format="h:mm A", on_change=self.changed),
            ui.label(f"Alarm at {ui.format_time(self.at, 'HH:mm')}"),
        ], spacing=8, width=200)
```

**Declarativo:**

```python
import datetime
from dataclasses import dataclass

@dataclass
class At:
    time: datetime.time

class Alarm(pz.App):
    at = datetime.time(7, 30)

    def update(self, message):
        match message:
            case At(time):
                self.at = time

    def view(self):
        return ui.TimePicker(value=self.at, on_change=lambda e: At(e.value))
```

**Funcional:**

```python
import datetime
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    at: datetime.time = datetime.time(7, 30)

def view(state, set_state):
    return ui.TimePicker(value=state.at, minute_step=15, on_change=lambda e: set_state(at=e.value))
```

## Propiedades y API

### `ui.TimePicker`

```python
class TimePicker
```

Un componente: un campo de hora con columnas de horas y minutos (y segundos, y AM/PM con un `format` de 12 horas) en una ventana emergente. Tras un clic, ↑/↓ la cambian `minute_step` minutos. Ver la página [Selector de hora](https://albakore.github.io/pyzed/es/library/time-picker/).

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `value` | `None` | La hora (`datetime.time`, `"14:30"` o `None`). |
| `format` | `"HH:mm"` | `"HH:mm"`, `"HH:mm:ss"`, `"h:mm A"`... |
| `placeholder` | `""` | Pista mientras está vacío. |
| `minute_step` | `5` | Minutos entre los que se ofrecen. |
| `min` | `None` | La primera hora. |
| `max` | `None` | La última hora. |
| `clearable` | `True` | Muestra una x que lo vacía. |
| `disabled` | `False` | Lo atenúa. |
| `invalid` | `False` | Pinta el borde con el color de error. |

Eventos: `on_change`, `on_open`, `on_close` ([eventos](#eventos)).

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

### `ui.format_time`

```python
format_time(value, fmt='HH:mm')
```

Escribe una hora (o `"14:30"`) con un patrón como `"h:mm A"`.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `value` | *obligatorio* | Un `datetime.time` o texto. |
| `fmt` | `"HH:mm"` | El patrón. |

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

### `ui.parse_time`

```python
parse_time(text, fmt='HH:mm')
```

Lee una hora: `"14:30"`, `"2:30 PM"`, `"14:30:05"`, primero con `fmt`. `None` si no lo es.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `text` | *obligatorio* | El texto. |
| `fmt` | `"HH:mm"` | El patrón. |

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

## Relacionados

- [Selector de fecha](https://albakore.github.io/pyzed/es/library/date-picker/): Un campo de fecha con un calendario desplegable, en el formato que elijas.
- [Campo numérico](https://albakore.github.io/pyzed/es/library/number-field/): Un número con botones −/+, límites, paso y sufijo.