# Campo de búsqueda

> Un campo con lupa, para filtrar. 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/search-input/

:::tip[En pocas palabras]
Una caja de texto con una lupa, para escribir lo que buscas.
:::

Un `input` con el icono de una lupa y `"Search…"` como placeholder. Acepta el resto de parámetros de [`ui.input`](https://albakore.github.io/pyzed/es/library/input/).

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

**Código:**

```python
pz.column([
    ui.search_input("", on_query),
    ui.search_input("button", on_query, placeholder="Search components…"),
], spacing=10, width=360)
```

## Cuándo usarlo

- Encima de una lista, árbol o tabla para filtrarla mientras escribes.
- Combínalo con `ui.fuzzy_filter` para ordenar primero los mejores resultados.

## Uso

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

class Finder(pz.App):
    def __init__(self):
        self.query = ""
        self.files = ["main.py", "app.py", "theme.py"]

    def view(self):
        matches = ui.fuzzy_filter(self.query, self.files)
        return pz.column([
            ui.search_input(self.query, lambda q: setattr(self, "query", q)),
            *[ui.list_item(name, icon="file") for name, _ in matches],
        ], spacing=6)
```

## 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.search_input("", on_query, width=260)
```

```python
ui.search_input("button", on_query, width=260)
```

```python
ui.search_input("", on_query, placeholder="Search components…", width=260)
```

### Tamaño

```python
ui.search_input("", on_query, size="sm", width=260)
```

```python
ui.search_input("", on_query, size="lg", width=260)
```

```python
ui.search_input("", on_query, borderless=True, width=260)
```

## Eventos

Campo de búsqueda 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_input` | `(text)` | Callable que recibe el texto nuevo en cada pulsación. |

**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 Finder(pz.App):
    def __init__(self):
        self.query = ""
        self.files = ["main.py", "app.py", "theme.py"]

    def search(self, text):              # on_input: every keystroke
        self.query = text

    def view(self):
        matches = ui.fuzzy_filter(self.query, self.files)
        return pz.column([ui.search_input(self.query, self.search),
                          *[ui.list_item(name, icon="file") for name, _ in matches]], spacing=6)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Search:
    query: str

class Finder(pz.App):
    query = ""
    files = ["main.py", "app.py", "theme.py"]

    def update(self, message):
        match message:
            case Search(query):
                self.query = query

    def view(self):
        matches = ui.fuzzy_filter(self.query, self.files)
        return pz.column([ui.search_input(self.query, Search),
                          *[ui.list_item(name, icon="file") for name, _ in matches]], spacing=6)
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    query: str = ""
    files: tuple = ("main.py", "app.py", "theme.py")

def view(state, set_state):
    matches = ui.fuzzy_filter(state.query, list(state.files))
    return pz.column([ui.search_input(state.query, lambda q: set_state(query=q)),
                      *[ui.list_item(name, icon="file") for name, _ in matches]], spacing=6)
```

## Propiedades y API

### `ui.search_input`

```python
search_input(value, on_input=None, *, placeholder='Search…', **kwargs)
```

Un `input` con icono de lupa.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `value` | *obligatorio* | Texto actual. |
| `placeholder` | `"Search…"` | Texto de ayuda cuando está vacío. |
| `**kwargs` | — | Los de `input`. |

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

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

## Relacionados

- [Campo de texto](https://albakore.github.io/pyzed/es/library/input/): Un campo de texto controlado con icono, placeholder y modo contraseña.
- [Buscador](https://albakore.github.io/pyzed/es/library/picker/): Una lista con búsqueda en una superficie flotante, con coincidencia difusa.
- [Paleta de comandos](https://albakore.github.io/pyzed/es/library/command-palette/): Una paleta de comandos con búsqueda difusa y atajos.