State y Vars: que los datos dibujen la pantalla

En esta lección guardaremos los datos de los clientes en el State y haremos que la tabla y la insignia se dibujen a partir de esos datos. Es el momento de aprender el concepto más importante de Reflex: la Var.

3-1. Definir la forma de los datos: dataclass (5 min)

import dataclasses


@dataclasses.dataclass
class User:
    name: str
    email: str
    gender: str

• Es el "plano" que define qué campos tiene cada cliente. Se crea con User(name="...", email="...", gender="...").
• También podrías usar un diccionario ({"name": ...}), pero con un dataclass el editor detecta las erratas al escribir los nombres de los campos, y en el código de pantalla puedes acceder con un punto, como user.name.

3-2. La clase State (10 min)

class State(rx.State):
    users: list[User] = [
        User(name="Danilo Sousa", email="danilo@example.com", gender="Male"),
        User(name="Zahra Ambessa", email="zahra@example.com", gender="Female"),
    ]

• Las variables de clase de una clase que hereda de rx.State se convierten en variables de estado (state vars). El valor que escribes aquí es el valor inicial.
• La anotación de tipo (: list[User]) es obligatoria. Reflex se fija en el tipo para decidir en qué formato (JSON) enviarlo al navegador y qué métodos se pueden usar.
• El State existe en la memoria del servidor por separado para cada sesión del navegador. Los clientes que tú añadas no los verá nadie más y, como no es una base de datos, tampoco se guardan de forma permanente. El almacenamiento persistente se trata en los retos de ampliación de la lección 6.

3-3. Var: no es un "valor", sino una "expresión que se envía a la pantalla" (15 min)

En la lección 1 dijimos que "las funciones de pantalla solo se ejecutan una vez, al arrancar la app". Entonces, ¿qué obtienes si usas State.users dentro de una función de pantalla? Si lo imprimes, verás esto:

>>> type(State.users).__name__
'ArrayCastedVar'
>>> print(State.users.length())
reflex___state____state__tutorial_261019___tutorial_261019____state.users_rx_state_.length

No sale la lista de clientes, sino una expresión de JavaScript. Eso es una Var. Cuando se ejecuta la función de pantalla todavía no hay ni usuarios ni datos, así que lo único que se crea es una promesa: "más adelante, lee este valor en el navegador".

Por eso hay parte de la sintaxis de Python que no se puede usar con Vars. Estos son los errores reales que da Reflex 0.10 y sus alternativas:

En cambio, las comparaciones y operaciones aritméticas entre Vars (State.page + 1) o meter una Var en un f-string (f"Total: {State.total} clientes") funcionan sin problema, porque la propia operación se traduce a una expresión de JavaScript.

Ahora cambia la insignia provisional de la cabecera por el número real de clientes.

rx.badge(
    State.users.length(),     # una Var en lugar de "2"
    variant="soft",
    color_scheme="gray",
    radius="full",
),

3-4. Una función que dibuja una fila: show_user (5 min)

def show_user(user: User):
    return rx.table.row(
        rx.table.cell(user.name),
        rx.table.cell(user.email),
        rx.table.cell(user.gender),
        style={"_hover": {"bg": rx.color("gray", 3)}},
        align="center",
    )

• Aunque el tipo indicado es User, lo que llega en realidad es una Var que apunta a un User. user.name también se convierte en una expresión: "lee el name del cliente de esta fila". El acceso con punto funciona gracias a que declaramos los campos con un dataclass.
• style={"_hover": {...}} es el estilo que se aplica al pasar el ratón por encima. Las claves que empiezan por _, como _hover o _focus, son selectores de estado como :hover en CSS.

3-5. La tabla y rx.foreach (10 min)

Debajo de la cabecera, añade la tabla dentro de la tarjeta como segundo hijo.

rx.box(
    rx.table.root(
        rx.table.header(
            rx.table.row(
                rx.table.column_header_cell("Name"),
                rx.table.column_header_cell("Email"),
                rx.table.column_header_cell("Gender"),
            )
        ),
        rx.table.body(rx.foreach(State.users, show_user)),
        variant="ghost",
        size="3",
        width="100%",
    ),
    overflow_x="auto",                                   # desplazamiento horizontal en pantallas estrechas
    width="100%",
    border_top=f"1px solid {rx.color('slate', 4)}",
    border_bottom=f"1px solid {rx.color('slate', 4)}",
    padding_x="12px",
),

• Estructura de la tabla: root > header (fila de títulos) + body (filas de datos) > row > cell. Equivalen a <table>, <thead>, <tbody>, <tr> y <td> en HTML.
• rx.foreach(Var de lista, función) aplica la función a cada elemento de la lista en el navegador. La función se pasa sin llamarla, solo por su nombre (show_user, no show_user()).
• En cambio, para una lista fija como la fila de títulos sí puedes usar un for de Python, porque sus valores ya se conocen en tiempo de compilación. Ejemplo: *[rx.table.column_header_cell(h) for h in ["Name", "Email", "Gender"]]

Compruébalo en el navegador — Dentro de la tarjeta aparece una tabla con 2 clientes, y el 2 de la insignia ahora viene de State.users.length(). Al pasar el ratón sobre una fila, el fondo se vuelve gris claro.

Práctica

1. Añade un cliente más a los valores iniciales y comprueba que el número de la insignia cambia a 3.
2. Usa rx.cond para que, si hay 0 clientes, se muestre "Todavía no hay clientes" en lugar de la tabla. Pista: rx.cond(State.users.length() > 0, tabla, rx.text(...))
3. Escribe len(State.users) a propósito y lee tú mismo el mensaje de error.

Punto de control

• La tabla muestra 2 clientes y la insignia indica 2.
• Puedes explicar qué es una Var y por qué no se pueden usar len/if/for.
• Sabes por qué a rx.foreach hay que pasarle la función sin llamarla.