Selector de archivos

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 · Referencia completa →

Vista previa

Código

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)

Nuevo

Este componente se añadió hace poco. Cuéntanos qué tal te funciona en el gestor de incidencias.

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

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

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

mode="open"

Código

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

mode="open_many"

Código

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

mode="folder"

Código

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

mode="save"

Código

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

Estados

button="Browse…"

Código

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

editable=False

Código

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

invalid=True

Código

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

disabled=True

Código

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 y Eventos de cada componente.

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.

Imperativo

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

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

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

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.

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).

Referencia completa →

ui.path_input

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).

Referencia completa →

ui.system.pick

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 →

Relacionados

Zona para soltarUn área que recibe archivos arrastrados desde el escritorio o el explorador de archivos.

Campo de textoUn campo de texto controlado con icono, placeholder y modo contraseña.

Campo de formularioUna fila de ajustes: título y descripción a la izquierda, control a la derecha.