Campo numérico

Un campo numérico con botones − y +. También se puede escribir el valor: on_change recibe el número ya ajustado a min/max y el texto que no es un número se ignora.

ui.number_field · Categoría: Formularios · Referencia completa →

Vista previa
Código

pz.row([
    ui.number_field(14, on_change, min=8, max=32, suffix="px"),
    ui.number_field(4, on_change, min=1, max=8),
    ui.number_field(0.5, on_change, step=0.1, suffix="s", width=140),
], spacing=12)

Cuándo usarlo

Para valores exactos con límites razonables: tamaño de fuente, ancho de tabulación, puerto, reintentos.
Usa suffix para las unidades ("px", "ms", "%").

Uso

import pyzed as pz
from pyzed import ui

class Settings(pz.App):
    def __init__(self):
        self.font_size = 14

    def view(self):
        return ui.number_field(self.font_size, lambda v: setattr(self, "font_size", v),
                               min=8, max=32, suffix="px")

Variantes

Opciones

Campo numérico: suffix="px" — `suffix="px"`

Campo numérico: align="start" — `align="start"`

Límites

En un límite su botón se atenúa y el valor no puede ir más allá.

Campo numérico: En el mínimo — En el mínimo

Campo numérico: En el máximo — En el máximo

Estados y eventos

Tras pulsarlo, ↑/↓ lo mueven un paso (con Shift, diez) e Inicio/Fin saltan a min/max.

Campo numérico: prefix="$", decimals=2 — `prefix="$", decimals=2`

Campo numérico: invalid=True — `invalid=True`

Campo numérico: disabled=True — `disabled=True`

Eventos

Campo numérico tiene 2 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.

Evento	El handler recibe	Cuándo
`on_change`	`(value)`	Callable que recibe el nuevo valor.
`on_submit`	`()`	Se envía con Enter.

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 Settings(pz.App):
    def __init__(self):
        self.font_size = 14
        self.applied = 14

    def view(self):
        return pz.row([
            ui.number_field(self.font_size, lambda v: setattr(self, "font_size", v),   # on_change
                            min=8, max=32, suffix="px",
                            on_submit=lambda: setattr(self, "applied", self.font_size)),  # Enter
            pz.text("Preview", size=self.applied),
        ], spacing=12, align="center")

from dataclasses import dataclass


@dataclass
class FontSize:
    value: float


class Settings(pz.App):
    font_size = 14

    def update(self, message):
        match message:
            case FontSize(value):
                self.font_size = value

    def view(self):
        return ui.number_field(self.font_size, FontSize, min=8, max=32, suffix="px")

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    font_size: float = 14


def view(state, set_state):
    return pz.row([ui.number_field(state.font_size, lambda v: set_state(font_size=v), min=8, max=32),
                   pz.text("Preview", size=state.font_size)], spacing=12, align="center")

Propiedades y API

`ui.number_field`

number_field(
    value,
    on_change=None,
    *,
    min=None,
    max=None,
    step=1,
    width=120,
    suffix=None,
    prefix=None,
    align='center',
    decimals=None,
    disabled=False,
    invalid=False,
    id=None,
    on_submit=None,
    steppers=True,
    drag=True,
    drag_step=None,
    theme=None,
)

Un campo numérico con botones −/+ que también se puede arrastrar, como en Figma. on_change(valor) recibe el número ya limitado a min/max; lo que no se puede leer como número se ignora. Mantén pulsado y mueve el ratón de lado a lado sobre el número para cambiarlo (sigue aunque salgas de la ventana); haz doble clic para escribir un valor, y Enter, Escape o un clic fuera para terminar. Tras pulsarlo, ↑/↓ lo mueven un paso (con Shift, diez) e Inicio/Fin saltan a min/max.

Propiedad	Por defecto	Descripción
`value`	obligatorio	Valor actual.
`min`	`None`	Mínimo.
`max`	`None`	Máximo.
`step`	`1`	Paso de los botones.
`width`	`120`	Ancho: píxeles, `"fill"`, `"shrink"` o `"fill:N"` (proporción).
`suffix`	`None`	Unidad que se muestra al final (`"px"`, `"%"`…).
`prefix`	`None`	Texto antes del número (`"$"`…).
`align`	`"center"`	Dónde va el número entre los botones: `"center"` (por defecto), `"start"` o `"end"`.
`decimals`	`None`	Decimales que muestra (por defecto, los de `step`).
`disabled`	`False`	Lo atenúa.
`invalid`	`False`	Pinta el borde con el color de error.
`id`	`None`	Identificador estable para enfocarlo o desplazarlo con un `Command`.
`steppers`	`True`	Muestra los botones −/+ (`False`: un campo compacto, como en una rejilla de propiedades).
`drag`	`True`	Deja cambiarlo arrastrando el ratón (`False`: un campo de texto normal).
`drag_step`	`None`	Cuánto suma cada píxel arrastrado (por defecto `step`, hasta 1; los pasos menores de 1 piden tres píxeles cada uno).
`theme`	`None`	Tema a usar en lugar del actual (`pyzed.theme.current()`).

Eventos: on_change, on_submit (eventos).

Referencia completa →

Relacionados

DeslizadorElige un número de un rango arrastrando.

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.