# Fila de lista

> Una fila de lista con icono, texto y un hueco al final. Un componente nativo de Pyzed para GUIs de escritorio en Python, con vista previa, ejemplos y su API.

Source: https://albakore.github.io/pyzed/es/library/list-item/

:::tip[En pocas palabras]
Una fila de una lista: un icono, un nombre y quizá algo a la derecha.
:::

Una fila de lista: un icono, el texto y huecos `start`/`end` para cualquier widget. Admite `selected`, `focused` (borde de foco), `disabled`, anidar con `indent` y `on_right_press` para un menú contextual.

`ui.list_item` · Categoría: [Listas y menús](https://albakore.github.io/pyzed/es/library/#listas-y-menús) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#list_item)

**Código:**

```python
pz.column([
    ui.list_item("main.py", on_open, icon="file-code", icon_color="#3572a5", selected=True, inset=True),
    ui.list_item("README.md", on_open, icon="file-text", inset=True, end=ui.badge("M", tint="warning")),
    ui.list_item("Cargo.toml", on_open, icon="file-cog", inset=True, end=ui.kbd("ctrl-1", size="xs")),
    ui.list_item("old.txt", on_open, icon="file", inset=True, disabled=True),
], width=320)
```

## Cuándo usarlo

- Para cualquier lista vertical: archivos recientes, resultados, categorías de ajustes, personas.
- Usa `inset=True` dentro de paneles para que el resaltado tenga margen.

## Uso

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

class Recent(pz.App):
    def __init__(self):
        self.files = ["main.py", "app.py", "README.md"]
        self.current = "main.py"

    def view(self):
        return pz.column([
            ui.list_item(f, lambda f=f: setattr(self, "current", f), icon="file",
                         selected=f == self.current, inset=True)
            for f in self.files
        ])
```

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

### Contenido

```python
pz.container(ui.list_item("README.md", on_open), width=240)
```

```python
pz.container(ui.list_item("README.md", on_open, icon="file-text"), width=240)
```

```python
pz.container(ui.list_item("main.py", on_open, icon="file-code", icon_color="#3572a5"), width=240)
```

```python
pz.container(ui.list_item("app.py", on_open, icon="file-code", end=ui.badge("M", tint="warning")), width=240)
```

```python
pz.container(ui.list_item("Buy milk", on_open, start=ui.checkbox(True, on_toggle)), width=240)
```

```python
pz.container(ui.list_item("Delete project", on_open, icon="trash-2", color="error"), width=240)
```

### Estado

```python
pz.container(ui.list_item("main.py", on_open, icon="file-code", selected=True), width=240)
```

```python
pz.container(ui.list_item("main.py", on_open, icon="file-code", focused=True), width=240)
```

```python
pz.container(ui.list_item("old.txt", on_open, icon="file", disabled=True), width=240)
```

```python
pz.container(ui.list_item("main.py", on_open, icon="file-code", selected=True, inset=True), width=240)
```

```python
pz.container(ui.list_item("button.rs", on_open, icon="file-code", indent=24), width=240)
```

### Estados y eventos

`on_right_press` abre un menú contextual y `tooltip=` aparece al pasar el ratón.

```python
pz.container(ui.list_item("main.py", on_press, icon="file", description="src/app"), width=300)
```

```python
pz.container(ui.list_item("Rename me", on_press, icon="pencil", on_double_press=on_rename), width=300)
```

## Eventos

Fila de lista tiene **3 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](https://albakore.github.io/pyzed/es/guides/events/) y [Eventos de cada componente](https://albakore.github.io/pyzed/es/library/events/).

| Evento | El handler recibe | Cuándo |
| --- | --- | --- |
| `on_press` | `()` | Mensaje o callable que se envía al pulsar. `None` deshabilita el control. |
| `on_right_press` | `()` | Clic derecho. |
| `on_double_press` | `()` | Se envía con un doble clic (abrir, renombrar…). |

**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 Recent(pz.App):
    def __init__(self):
        self.files = ["main.py", "app.py", "README.md"]
        self.current = "main.py"
        self.opened = None

    def view(self):
        return pz.column([
            ui.list_item(f, lambda f=f: setattr(self, "current", f), icon="file",   # on_press
                         selected=f == self.current, inset=True,
                         on_double_press=lambda f=f: setattr(self, "opened", f),
                         on_right_press=lambda f=f: print("menu for", f))
            for f in self.files
        ], width=280)
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class Select:
    path: str

@dataclass
class Open:
    path: str

class Recent(pz.App):
    files = ["main.py", "app.py", "README.md"]
    current, opened = "main.py", None

    def update(self, message):
        match message:
            case Select(path):
                self.current = path
            case Open(path):
                self.opened = path

    def view(self):
        return pz.column([ui.list_item(f, Select(f), icon="file", selected=f == self.current,
                                       on_double_press=Open(f)) for f in self.files], width=280)
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    files: tuple = ("main.py", "app.py", "README.md")
    current: str = "main.py"

def file_row(name, selected, select):
    return ui.list_item(name, select, icon="file", selected=selected, inset=True)

def view(state, set_state):
    return pz.column([file_row(f, f == state.current, lambda f=f: set_state(current=f))
                      for f in state.files], width=280)
```

## Propiedades y API

### `ui.list_item`

```python
list_item(
    content,
    on_press=None,
    *,
    icon=None,
    icon_color=None,
    start=None,
    end=None,
    selected=False,
    focused=False,
    indent=0,
    height=26,
    color=None,
    inset=False,
    disabled=False,
    on_right_press=None,
    on_double_press=None,
    description=None,
    tooltip=None,
    theme=None,
)
```

Una fila de lista: icono, texto y un hueco al final.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `content` | *obligatorio* | Texto o widget. |
| `icon` | `None` | Nombre de un icono de Lucide (`pyzed icons` los lista). |
| `icon_color` | `None` | Color del icono: un token del tema o un color hex. |
| `start` | `None` | Widgets al inicio (izquierda). |
| `end` | `None` | Widgets al final (derecha). |
| `selected` | `False` | Lo marca como seleccionado. |
| `focused` | `False` | Dibuja un borde de foco. |
| `indent` | `0` | Sangría a la izquierda, en píxeles. |
| `height` | `26` | Alto de la fila. |
| `color` | `None` | Color del texto. |
| `inset` | `False` | Con margen y esquinas redondeadas (menús, paletas). |
| `disabled` | `False` | Lo deshabilita (ignora los clics). |
| `description` | `None` | Una segunda línea atenuada (la fila crece a 40 px salvo que fijes `height`). |
| `tooltip` | `None` | Texto al pasar el ratón. |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

Eventos: `on_press`, `on_right_press`, `on_double_press` ([eventos](#eventos)).

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

## Relacionados

- [Cabecera de lista](https://albakore.github.io/pyzed/es/library/list-header/): Un título pequeño de sección para listas, con hueco al final.
- [Árbol](https://albakore.github.io/pyzed/es/library/tree/): Un árbol de archivos plegable con iconos y colores de git.
- [Menú](https://albakore.github.io/pyzed/es/library/menu/): Un menú contextual con iconos, atajos y marcas.