Zona para soltar

ui.DropZone se ilumina cuando se arrastran archivos sobre la ventana y los recibe al soltarlos: on_drop recibe cada ruta y on_files la lista completa. accept limita los tipos (["png", "jpg"], ["*.tar.gz"], ["folder"]) y los archivos de otros tipos van a on_reject. Con browse=True (por defecto) un clic también abre el diálogo de archivos. Si una ventana tiene varias zonas, recibe los archivos la que está bajo el puntero o, si no, la que acepta su tipo.

ui.DropZone · Categoría: Sistema · Referencia completa →

Vista previa
Código

pz.row([
    ui.DropZone(text="Drop images here", hint="PNG or JPG, up to 10 MB", accept=["png", "jpg"],
                on_files=on_files),
    ui.DropZone(icon_name="file-spreadsheet", text="Import a CSV", accept=["csv"], multiple=False,
                show_files=True, files=["~/data/sales-2026.csv"], on_files=on_files),
], spacing=16, width=600)

Cuándo usarlo

Para importar imágenes, documentos o archivos de datos, y adjuntar archivos a un mensaje.
show_files=True lista lo que se soltó, con un botón para quitar cada archivo; multiple=False se queda solo con el último.
Los archivos soltados también llegan a on_file_drop(path) de la ventana, para apps que no necesitan una zona.

Uso

import pyzed as pz
from pyzed import ui

class Gallery(pz.App):
    def __init__(self):
        self.images = []

    def view(self):
        return pz.column([
            ui.DropZone(text="Drop photos", accept=["png", "jpg", "webp"],
                        on_files=lambda e: setattr(self, "images", list(e.value))),
            pz.row([pz.image(path, width=96, height=96) for path in self.images], spacing=8),
        ], spacing=12)

Variantes

Estados

Zona para soltar: Con archivos encima — Con archivos encima

Zona para soltar: Tipo no aceptado — Tipo no aceptado

Zona para soltar: disabled=True — `disabled=True`

Archivos

Zona para soltar: show_files=True — `show_files=True`

Zona para soltar: browse=False — `browse=False`

Eventos

Zona para soltar tiene 5 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 y Eventos de cada componente.

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_drop`	`(event)`	Recibe `event.value`: una ruta soltada (una vez por archivo).
`on_files`	`(event)`	Recibe `event.value`: la lista de archivos.
`on_reject`	`(event)`	Recibe una ruta que no acepta.
`on_enter`	`(event)`	Se arrastran archivos sobre la ventana.
`on_leave`	`(event)`	El arrastre salió sin soltar.

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.

class Attach(pz.App):
    def __init__(self):
        self.files = []

    def received(self, event):           # on_files: event.value is every file so far
        self.files = list(event.value)

    def view(self):
        return pz.column([
            ui.DropZone(text="Drop files to attach", on_files=self.received),
            ui.label(f"{len(self.files)} files"),
        ], spacing=8, width=320)

from dataclasses import dataclass


@dataclass
class Dropped:
    path: str


class Attach(pz.App):
    files = ()

    def update(self, message):
        match message:
            case Dropped(path):
                self.files = (*self.files, path)

    def view(self):
        # on_drop runs once per file
        return ui.DropZone(accept=["png", "jpg"], on_drop=lambda e: Dropped(e.value))

from dataclasses import dataclass


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


def view(state, set_state):
    return pz.column([
        ui.DropZone(text="Drop a CSV", accept=["csv"], multiple=False,
                    on_reject=lambda e: set_state(rejected=e.value)),
        ui.label(f"Not a CSV: {state.rejected}" if state.rejected else ""),
    ], spacing=8, width=320)

Consejos

Propiedades y API

`ui.DropZone`

class DropZone

Un componente que recibe archivos arrastrados desde el explorador de archivos del sistema y soltados en la ventana, y abre el diálogo de archivos con un clic. Se ilumina mientras se arrastran archivos sobre la ventana y guarda las rutas soltadas en files. El gancho on_file_drop de la ventana entrega cada archivo a la zona bajo el puntero, si no a una cuyo accept incluya su tipo. Ver la página Zona para soltar.

Propiedad	Por defecto	Descripción
`text`	`""`	El texto principal (por defecto: Suelta archivos aquí).
`hint`	`""`	La línea de debajo.
`icon_name`	`"upload"`	Su icono.
`accept`	`()`	Extensiones (`["png", "jpg"]`), patrones (`"*.tar.gz"`) o `"folder"`; vacío acepta todo.
`multiple`	`True`	`False` se queda solo con el último archivo.
`browse`	`True`	Un clic abre el diálogo de archivos.
`show_files`	`False`	Lista los archivos bajo el texto (cada uno con una x).
`files`	`()`	Las rutas soltadas.
`disabled`	`False`	No recibe nada.
`live`	`True`	`False` lo dibuja sin recibir archivos (el lienzo del diseñador).

Eventos: on_drop, on_files, on_reject, on_enter, on_leave (eventos).

Referencia completa →

Relacionados

Selector de archivosUn campo de ruta con un botón que abre el diálogo de archivos o carpetas del sistema.

TarjetaUna superficie con borde, título y acciones opcionales.