# Selector de rango de fechas

> Dos fechas en un campo, con dos meses lado a lado y rangos rápidos. Componente de Pyzed para GUIs de escritorio en Python, con ejemplos y API.

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

:::tip[En pocas palabras]
Una casilla para dos fechas, desde y hasta. Haces clic donde empieza el periodo y donde termina.
:::

`ui.DateRangePicker` guarda una fecha de inicio y una de fin. Su ventana muestra dos meses: el primer clic elige el inicio, el puntero previsualiza el rango y el segundo clic elige el fin (en cualquier orden). La columna de la izquierda tiene rangos rápidos (hoy, últimos 7 días, esta semana, este mes, el mes pasado...). `on_change` recibe `(inicio, fin)` como dos `datetime.date`.

`ui.DateRangePicker` · 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/#daterangepicker)

**Código:**

```python
pz.container(
    ui.DateRangePicker(value=("2026-10-05", "2026-10-14"), format="DD/MM/YYYY", on_change=on_change),
    width=260, height=330, align_y="start")
```

:::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 informes, filtros, estancias y todo lo que dura varios días.
- `months=1` muestra un solo mes y `presets=False` oculta los rangos rápidos.
- El campo también se puede escribir: dos fechas en `format` con cualquier separador.

## Uso

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

class Report(pz.App):
    def __init__(self):
        self.period = (None, None)

    def view(self):
        start, end = self.period
        days = (end - start).days + 1 if start and end else 0
        return pz.column([
            ui.DateRangePicker(value=self.period, format="MMM D, YYYY",
                               on_change=lambda e: setattr(self, "period", e.value)),
            ui.label(f"{days} days selected", color="text_muted"),
        ], spacing=8, width=300)
```

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

### Ventana

```python
ui.DateRangePicker(value=("2026-10-05", "2026-10-14"), on_change=on_change)
```

```python
ui.DateRangePicker(months=1, presets=False, on_change=on_change)
```

## Eventos

Selector de rango de fechas 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`: `(inicio, fin)`. |
| `on_open` | `(event)` | Se abrió el calendario. |
| `on_close` | `(event)` | Se cerró el calendario. |

**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 Report(pz.App):
    def __init__(self):
        self.period = ("2026-10-05", "2026-10-14")

    def changed(self, event):            # on_change: event.value is (start, end)
        self.period = event.value

    def view(self):
        start, end = self.period
        return pz.column([
            ui.DateRangePicker(value=self.period, on_change=self.changed),
            ui.label(f"From {ui.format_date(start, 'D MMM')} to {ui.format_date(end, 'D MMM')}"),
        ], spacing=8, width=280)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Period:
    days: tuple

class Report(pz.App):
    period = (None, None)

    def update(self, message):
        match message:
            case Period(days):
                self.period = days

    def view(self):
        return ui.DateRangePicker(value=self.period, on_change=lambda e: Period(e.value))
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    period: tuple = (None, None)

def view(state, set_state):
    return ui.DateRangePicker(value=state.period, months=1, presets=False,
                              on_change=lambda e: set_state(period=e.value))
```

## Propiedades y API

### `ui.DateRangePicker`

```python
class DateRangePicker
```

Un componente: un campo para una fecha de inicio y otra de fin, con dos meses y rangos rápidos (Hoy, Últimos 7 días, Este mes...) en su ventana emergente. El texto escrito son dos fechas separadas por `separator`. Ver la página [Selector de rango de fechas](https://albakore.github.io/pyzed/es/library/date-range-picker/).

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `value` | `None` | `(inicio, fin)`: fechas, texto ISO o `None`. |
| `format` | `"YYYY-MM-DD"` | Cómo se escribe cada fecha. |
| `separator` | `" – "` | Texto entre las dos fechas. |
| `placeholder` | `""` | Pista mientras está vacío. |
| `min` | `None` | La primera fecha. |
| `max` | `None` | La última fecha. |
| `disabled_dates` | `()` | Días que no se pueden elegir. |
| `first_weekday` | `"monday"` | `"monday"`, `"sunday"` o `"saturday"`. |
| `months` | `2` | Meses que se ven uno al lado del otro. |
| `presets` | `True` | Muestra los rangos rápidos. |
| `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/#daterangepicker)

## 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.
- [Calendario](https://albakore.github.io/pyzed/es/library/calendar/): Una cuadrícula del mes para elegir un día, un rango o varios días, siempre a la vista.