# Selector de archivos

> Un campo de ruta con un botón que abre el diálogo de archivos o carpetas del sistema. Componente de Pyzed para GUIs de escritorio en Python, con ejemplos y API.

Source: https://albakore.github.io/pyzed/es/library/file-input/

:::tip[En pocas palabras]
Una casilla con la ubicación de un archivo y un botón que abre la ventana de siempre para buscarlo.
:::

`ui.file_input` muestra una ruta y un botón para buscar. El botón abre el diálogo del propio sistema operativo para abrir un archivo (`mode="open"`), varios (`"open_many"`), una carpeta (`"folder"`) o elegir dónde guardar (`"save"`), y `on_change` recibe lo elegido: una ruta, o una lista de rutas con `open_many`. La ruta también se puede escribir o pegar. `filters` limita los tipos de archivo (`"Imágenes: png, jpg"`).

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

**Código:**

```python
pz.column([
    ui.field("Project folder", ui.file_input("~/projects/notes", on_change, mode="folder")),
    ui.field("Logo", ui.file_input("", on_change, filters="Images: png, jpg, svg", placeholder="Choose an image")),
    ui.field("Export to", ui.file_input("report.pdf", on_change, mode="save", button="Browse…")),
], spacing=12, width=420)
```

:::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 ajustes que apuntan a un archivo o carpeta: la carpeta de un proyecto, un archivo de registro, el destino de una exportación.
- `button="Examinar…"` muestra un texto en lugar del icono de carpeta.
- `ui.system.pick(then, mode=...)` devuelve el mismo diálogo como un `Command`, para tus propios botones.

## Uso

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

class Export(pz.App):
    def __init__(self):
        self.target = ""

    def view(self):
        return ui.file_input(self.target, lambda path: setattr(self, "target", path),
                             mode="save", file_name="report.pdf", filters="PDF: pdf")
```

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

### Modo

```python
ui.file_input("~/notes/todo.md", on_change, width=320)
```

```python
ui.file_input(["a.png", "b.png"], on_change, mode="open_many", width=320)
```

```python
ui.file_input("~/projects", on_change, mode="folder", width=320)
```

```python
ui.file_input("report.pdf", on_change, mode="save", width=320)
```

### Estados

```python
ui.file_input("", on_change, button="Browse…", width=320)
```

```python
ui.file_input("~/notes/todo.md", on_change, editable=False, width=320)
```

```python
ui.file_input("~/missing.txt", on_change, invalid=True, width=320)
```

```python
ui.file_input("~/notes/todo.md", on_change, disabled=True, width=320)
```

## Eventos

Selector de archivos 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 | De | El handler recibe | Cuándo |
| --- | --- | --- | --- |
| `on_change` | `ui.file_input`, `ui.path_input` | `(value)` | Recibe la ruta (una lista con `"open_many"`). |

**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 Export(pz.App):
    def __init__(self):
        self.folder = ""

    def chosen(self, path):              # on_change: the path (a list with mode="open_many")
        self.folder = path

    def view(self):
        return pz.column([
            ui.file_input(self.folder, self.chosen, mode="folder", placeholder="Choose a folder"),
            ui.label(f"Saving to {self.folder or '…'}"),
        ], spacing=8, width=360)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Chosen:
    path: str

class Export(pz.App):
    path = ""

    def update(self, message):
        match message:
            case Chosen(path):
                self.path = path

    def view(self):
        return ui.file_input(self.path, lambda path: Chosen(path), mode="save", file_name="report.pdf")
```

**Funcional:**

```python
from dataclasses import dataclass

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

def view(state, set_state):
    return ui.file_input(state.image, lambda path: set_state(image=path), filters="Images: png, jpg")
```

## Propiedades y API

### `ui.file_input`

```python
file_input(
    value,
    on_change=None,
    *,
    mode='open',
    filters=None,
    title=None,
    directory=None,
    file_name='',
    placeholder=None,
    button=None,
    editable=True,
    disabled=False,
    invalid=False,
    id=None,
    width='fill',
    theme=None,
)
```

Un campo de ruta con un botón que abre el diálogo de archivos del sistema, para que nadie escriba una ruta a mano. Ver la página [Selector de archivos](https://albakore.github.io/pyzed/es/library/file-input/).

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `value` | *obligatorio* | Valor actual. |
| `mode` | `"open"` | `"open"` (un archivo), `"open_many"` (una lista), `"save"` o `"folder"`. |
| `filters` | `None` | Archivos que se muestran: `{"Imágenes": "png jpg"}` o `"Imágenes: png, jpg"`. |
| `title` | `None` | El título del diálogo. |
| `directory` | `None` | Dónde se abre el diálogo (por defecto, la carpeta de la ruta actual). |
| `file_name` | `""` | El nombre que propone al guardar. |
| `placeholder` | `None` | Texto de ayuda cuando está vacío. |
| `button` | `None` | Texto para el botón en lugar de un icono de carpeta. |
| `editable` | `True` | `False` impide escribir la ruta. |
| `disabled` | `False` | Lo deshabilita (ignora los clics). |
| `invalid` | `False` | Pinta el borde con el color de error. |
| `id` | `None` | Identificador estable para enfocarlo o desplazarlo con un `Command`. |
| `width` | `"fill"` | Ancho: píxeles, `"fill"`, `"shrink"` o `"fill:N"` (proporción). |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

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

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

### `ui.path_input`

```python
path_input(
    value,
    on_change=None,
    *,
    folder=False,
    save=False,
    filters=None,
    kind=None,
    directory=None,
    relative_to=None,
    title=None,
    placeholder=None,
    size='md',
    mono=True,
    disabled=False,
    invalid=False,
    theme=None,
)
```

Un campo de texto para la ruta de un archivo o carpeta con un botón que abre el diálogo de archivos del sistema, para no tener que escribirla (aunque se puede).

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `value` | *obligatorio* | Ruta actual. |
| `folder` | `False` | Elige una carpeta en vez de un archivo. |
| `save` | `False` | Muestra el diálogo "Guardar como". |
| `filters` | `None` | Pares `(nombre, extensiones)`: `[("Imágenes", ["png", "jpg"])]`. |
| `kind` | `None` | Filtros comunes por nombre: `"image"`, `"audio"`, `"video"`, `"font"`, `"shader"` o `"data"`. |
| `directory` | `None` | Carpeta donde se abre el diálogo (por defecto, la de la ruta actual). |
| `relative_to` | `None` | Una ruta elegida dentro de esta carpeta se da relativa a ella. |
| `title` | `None` | Título del diálogo. |
| `placeholder` | `None` | Texto que se ve mientras está vacío. |
| `size` | `"md"` | `"sm"`, `"md"` o `"lg"`. |
| `mono` | `True` | Texto monoespaciado. |
| `disabled` | `False` | Lo atenúa. |
| `invalid` | `False` | Pinta el borde con el color de error. |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

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

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

### `ui.system.pick`

```python
pick(then, *, mode='open', title=None, filters=None, directory=None, file_name='')
```

El diálogo de archivos del sistema como un `Command`: devuélvelo desde un callback y `then` recibe lo que eligió el usuario (una ruta, una lista de rutas con `"open_many"`, o `None` si cancela). `ui.file_input` lo usa.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `then` | *obligatorio* | Se llama con el resultado. |
| `mode` | `"open"` | `"open"`, `"open_many"`, `"save"` o `"folder"`. |
| `title` | `None` | El título del diálogo. |
| `filters` | `None` | Archivos que se muestran: `{"Imágenes": "png jpg"}` o `"Imágenes: png, jpg"`. |
| `directory` | `None` | Dónde se abre el diálogo. |
| `file_name` | `""` | El nombre que propone al guardar. |

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

## Relacionados

- [Zona para soltar](https://albakore.github.io/pyzed/es/library/drop-zone/): Un área que recibe archivos arrastrados desde el escritorio o el explorador de archivos.
- [Campo de texto](https://albakore.github.io/pyzed/es/library/input/): Un campo de texto controlado con icono, placeholder y modo contraseña.
- [Campo de formulario](https://albakore.github.io/pyzed/es/library/field/): Una fila de ajustes: título y descripción a la izquierda, control a la derecha.