Referencia de pantallas: datos, estilo y recetas¶
Disponible con Kino 0.9.74
Disponible desde Kino 0.9.74. Una versión anterior de Kino rechaza estos
plugins con «Este plugin necesita una versión más nueva de Kino»; para seguir llegando a quien tiene una versión
anterior usa enhancements (ver Pantallas sin subir tu apiVersion).
Esta es la tercera parte del catálogo de componentes de las pantallas de un plugin:
- Disposición, contenido y acciones:
Column,Row,Card,Text,Image, botones,ListTile, las tarjetas de títulos de Kino y las operaciones localesui. - Formularios, superpuestos y navegación:
Form, las entradas,bindyconfig, ventanas emergentes, avisos ygo. - Esta página: cómo fluyen los datos y los eventos (estado, entradas, eventos, respuestas, temporizadores), los valores por tamaño, los nombres al estilo Flutter, cada propiedad de estilo y cada token, los límites y recetas para copiar.
La guía, Pantallas, explica el bloque screen del manifiesto, las exportaciones screen() y
screenEvent(), el foco en la TV y cómo probar con el kit. El
ejemplo de la galería pone en marcha todos los componentes.
Datos y comportamiento¶
Estado¶
El estado vive en Kino. Tu entorno de ejecución se cierra tras un rato sin actividad, así que nada de lo que guardes en
una variable sobrevive: Kino guarda el estado de la pantalla, lo entrega en cada llamada y vuelve a llamar a screen()
después de cada respuesta que trae un parche de state. Un parche se fusiona clave por clave (null borra una clave). Como
máximo 64 KB; vive solo mientras la pantalla está abierta esta vez (lo que deba sobrevivir, guárdalo en kino.storage).
screen() es una vista pura: nada de red ahí.
{ "state": { "count": 3, "selected": null } }
Entradas (state.inputs)¶
state.inputs guarda cada entrada de la pantalla por su clave: lo que fijó la persona o tu código, o si no, el valor que
muestra el árbol. Para fijar lo que muestra un campo, responde { state: { inputs: { <key>: value } } }: se ve al instante y
no dispara ningún evento.
| Entrada | Valor en state.inputs |
Reglas del formulario | bind guarda |
|---|---|---|---|
TextField |
texto | required, minLength, maxLength, pattern, errorText |
text |
TextField (varias líneas) |
texto | required, minLength, maxLength, pattern, errorText |
text |
DropdownButton |
el valor de la opción o null |
required, errorText |
select o text |
Switch |
booleano | required, errorText |
toggle |
Checkbox |
booleano | required, errorText |
toggle |
RadioGroup |
el valor de la opción o null |
required, errorText |
select o text |
Slider |
número | ninguna | text |
Chips |
un valor o null (una lista con multiple) |
required, minLength, maxLength, errorText |
select o text |
NumberStepper |
su valor como texto ("2.50") |
required, errorText |
sin bind |
Eventos¶
- Un evento a la vez por pantalla; el siguiente espera (como máximo 8 en espera), separados 100 ms, y nunca se descarta por
llegar rápido. Un
onChangedmás nuevo del mismo campo reemplaza a uno anterior que siga esperando. - La primera llamada después de abrir la pantalla es el evento reservado
open: carga ahí tus datos y responde un parche destate. - Una llamada tiene 20 s. Una llamada que se pasa del tiempo muestra el estado de error de la pantalla; tres fallos seguidos también. El tiempo agotado de una pantalla nunca cuenta para el «No responde» del plugin.
Respuestas¶
Lo que puede responder screenEvent (y un temporizador, el onClose de una ventana emergente, el panelAction de un panel).
Todos los campos son opcionales; null significa que no hay nada que hacer. Algunas respuestas no son de la persona, así que
conservan menos: la respuesta al evento reservado open descarta su go (salvo go.screen), y la de un «cargar más» nunca
cambia la ruta.
| Campo | Qué hace | En la respuesta de un temporizador | En una respuesta de onClose |
En un panel en modo pantalla |
|---|---|---|---|---|
state |
un parche fusionado clave por clave (null borra una clave); luego screen() corre de nuevo |
se conserva | se conserva | se conserva |
dialog |
un diálogo emergente: title, body (texto o nodos), como máximo 3 buttons |
se descarta | se descarta | se descarta |
sheet |
una hoja inferior en el teléfono, un cajón lateral en la TV: title, body |
se descarta | se descarta | se descarta |
menu |
una lista de 1 a 8 acciones: items de { label, icon?, onTap } |
se descarta | se descarta | se descarta |
toast |
un mensaje corto: un texto o { text, textEn?, role?, action?, ms? } (ms de 2.000 a 8.000, por defecto 3.500) |
se conserva | se conserva | se conserva |
toastEn |
el gemelo en inglés de un toast de texto |
se conserva | se conserva | se conserva |
go |
algún lugar de Kino (Navegación) | se descarta | se descarta | se conserva |
route |
{ push: name, params? } o { pop: true }: una pantalla tuya más adentro del lienzo |
se descarta | se descarta | se descarta |
close |
true cierra la pantalla |
se conserva | se conserva | se conserva |
focus |
la clave del nodo que toma el foco | se descarta | se descarta | se conserva |
config |
tus ajustes a escribir, como máximo 32 claves (bind y config) | se conserva | se conserva | se conserva |
ui |
operaciones locales (como máximo 8); un open espera al árbol que pide la respuesta |
se descarta | se conserva, sin open ni focus |
se conserva |
share |
{ key }, apiVersion 17: ese nodo como imagen en la hoja de compartir del sistema (Compartir una imagen); solo la respuesta al toque o envío de la persona |
se descarta | se descarta | se descarta |
enableJob |
un id de tarea, apiVersion 17: enciende la fila propia de Kino de esa tarea (Las filas de Kino en Ajustes), solo después del toque de la persona; ninguna respuesta la apaga | se descarta | se descarta | se descarta |
Compartir una imagen (share)¶
share: { key } en una respuesta dibuja un nodo de la pantalla como imagen y abre la hoja de compartir del sistema: una
tarjeta para enviar, no una captura de pantalla. Pide apiVersion 17; un plugin con una versión menor se rechaza y queda en
el registro.
screenEvent(event) {
if (event.name === "share") return { share: { key: "card" } };
}
- Solo después del toque o envío de la propia persona. La respuesta al
openreservado, a un temporizador, a un «cargar más», a un cambio o a unonCloselo descarta, y también un panel; igual una respuesta o un árbol nuevo que llega más de 5 s después del toque, y Atrás, un reinicio, un fallo, una ventana emergente más nueva o un dibujo que no pinta nada entre medias. Cada caso queda en el registro. - El nodo tiene que ser uno que la persona ve ahora: en el árbol actual o en el cuerpo de una ventana emergente abierta;
con
stateorouteen la misma respuesta, en el árbol que esa respuesta pide. Un nodohidden, uno en una ventana emergente o un elemento de acordeón cerrados, uno en otra página depages, una clave que nombra una ventana emergente y una clave desconocida se descartan, con registro. - Un
pageViewnunca se comparte entero. Kino no sabe a qué página deslizó la persona, así que un nodo que contiene unpageView, su propia clave o la de un ancestro, se rechaza, con registro. Dentro de uno, solo se puede compartir su primera página, y solo cuandoinitialPagees 0. - Los títulos +18 nunca van en una imagen, ni con el código desbloqueado:
TitleCard,TitleRailyTitleGridlos pierden. Un nodo que se queda sin nada se descarta, con registro. - La imagen es un PNG de 1080×1350 píxeles, siempre dibujado a 360 dp de ancho y con escala de fuente 1, así que tu diseño no cambia con el teléfono ni el tamaño de fuente de la persona. Tu nodo recibe el área sobre la línea propia de Kino, recortado a ella, con el tema de tu pantalla. La línea de Kino nombra a tu plugin (máximo 24 caracteres), así que una tarjeta nunca pasa por una de Kino; nada tuyo puede taparla.
- Las imágenes esperan 3 s como máximo; después, el marcador de Kino (o tu
fallback). Las animaciones saltan a su final. Los botones y los campos se dibujan, pero no hacen nada; un nodosettingsno se dibuja. - De una en una: un segundo toque mientras se hace una se descarta. Si falla, Kino lo dice en su propio aviso.
- El título de la hoja de compartir nombra a tu plugin; no se añade nada a lo que escribe la persona. El archivo queda en la caché privada de Kino, de solo lectura para la app que elija la persona, y se borra en el siguiente compartir. Sin capacidad ni línea de permiso: la persona toca y elige la app.
- Una TV no tiene hoja de compartir: rechaza
share, con registro y sin aviso. Oculta el botón ahí (kino.device,device: "tv").
Temporizadores (every)¶
La raíz de un árbol (o el screen.every del manifiesto) puede llevar { ms, event } o una lista de ellos: Kino envía ese
evento cada ms mientras la pantalla está abierta, visible y Kino en primer plano. Un tic no es la pulsación de nadie: su
respuesta conserva solo state, toast, close y config; 3 fallos seguidos apagan ese temporizador; los tics nunca
cuentan para «No responde» y nunca corren mientras espera un evento de la persona.
{ "type": "Column", "every": { "ms": 30000, "event": "refresh" }, "children": [{ "type": "Text", "text": "Se actualiza cada 30 s", "textEn": "Refreshes every 30 s" }] }
Valores por tamaño¶
Cualquier propiedad de estilo o de disposición puede ser un mapa por tamaño { compact?, medium?, expanded? } (las
clases de ventana de Material: compact por debajo de 600 dp, medium de 600 a 839, expanded de 840 en adelante; una TV
es expanded). Una clase que falta en el mapa toma la siguiente más pequeña presente, o si no, el valor por defecto de Kino.
Un nodo cuyo valor no es válido en una sola clase se descarta entero, y un mapa que mezcla clases con otras claves se
descarta. devices y sizes dibujan un nodo solo en algunos sitios; ctx.device y ctx.size le permiten a screen()
devolver otro árbol.
{ "type": "GridView", "columns": { "compact": 1, "medium": 2, "expanded": 3 }, "gap": { "compact": 8, "expanded": 16 }, "padding": { "compact": 16, "expanded": 32 }, "children": [
{ "type": "Text", "text": "Solo en la TV", "textEn": "TV only", "devices": ["tv"] },
{ "type": "Text", "text": "Solo en ventanas anchas", "textEn": "Wide windows only", "sizes": ["expanded"] }
] }
Nombres al estilo Flutter¶
Quien conoce Flutter encuentra los mismos nombres. Son la forma documentada; los nombres anteriores en minúsculas se siguen
aceptando y los dos dan el mismo árbol. Usa una sola forma: si un nodo trae las dos, gana la de Flutter y el choque queda en
el registro. Solo se renombran los nodos: los campos del dialog, sheet y menu de una respuesta, los buttons de un
diálogo, los items de un menú, la action de un aviso y las entradas de options y tabs conservan label y onTap.
Los componentes propios de Kino (titleCard, titleRail, titleGrid, heroCard, emptyState, errorState, popup,
settings) conservan sus nombres.
| Nombre al estilo Flutter | Nombre anterior | Implica |
|---|---|---|
Column |
col |
|
Row |
row |
|
Stack |
box |
|
Card |
card |
|
Spacer |
spacer |
|
SizedBox |
spacer |
|
Divider |
divider |
|
SingleChildScrollView |
scroll |
|
GridView |
grid |
|
Text |
text |
|
Image |
image |
|
Icon |
icon |
|
Badge |
badge |
|
LinearProgressIndicator |
progress |
|
CircularProgressIndicator |
loading |
|
ListView |
list |
|
Button |
button |
|
ElevatedButton |
button |
variant: "primary" |
TextButton |
button |
variant: "text" |
IconButton |
button |
variant: "icon" |
TextField |
textInput |
|
DropdownButton |
dropdown |
|
Switch |
toggle |
|
Checkbox |
checkbox |
|
RadioGroup |
radioGroup |
|
Slider |
slider |
|
Chips |
chips |
|
TabBar |
tabs |
|
AlertDialog |
popup |
kind: "dialog" |
BottomSheet |
popup |
kind: "sheet" |
PopupMenuButton |
popup |
kind: "menu" |
Form |
form |
|
MaterialBanner |
banner |
|
ExpansionTile |
accordion |
|
Skeleton |
skeleton |
|
QrImage |
qr |
|
NumberStepper |
stepper |
|
DataTable |
table |
|
TableRow |
tr |
|
TableCell |
td |
|
FloatingActionButton |
fab |
|
ListTile |
listTile |
|
CircleAvatar |
avatar |
|
PageView |
pageView |
|
Scaffold |
scaffold |
|
AppBar |
appBar |
|
NavigationBar |
navigationBar |
|
TextField con multiline: true o maxLines > 1 |
textArea |
| Propiedad al estilo Flutter | Nombre anterior | Dónde |
|---|---|---|
width |
w |
cualquier nodo |
height |
h |
cualquier nodo |
minHeight |
minH |
cualquier nodo |
mainAxisAlignment |
justify |
cualquier nodo |
crossAxisAlignment |
align |
cualquier nodo |
flex |
weight |
cualquier nodo |
borderRadius |
radius |
cualquier nodo |
onChanged |
onChange |
cualquier nodo |
onSubmitted |
onSubmit |
cualquier nodo |
hintText |
hint |
cualquier nodo |
hintTextEn |
hintEn |
cualquier nodo |
labelText |
label |
cualquier nodo |
labelTextEn |
labelEn |
cualquier nodo |
obscureText |
secret |
cualquier nodo |
onPressed |
onTap |
solo un botón (en otro lado se ignora y queda en el registro) |
flex |
weight |
una columna de DataTable |
Estilo¶
El estilo sale de escalas fijas, nunca de valores libres; un valor fuera de su escala se descarta y queda en el registro. Todos los nodos aceptan estas propiedades.
| Propiedad | Nombre anterior | Valores | Por tamaño |
|---|---|---|---|
padding |
0, 4, 8, 12, 16, 24, 32, 48, o por lado { x, y, top, end, bottom, start } |
sí | |
margin |
0, 4, 8, 12, 16, 24, 32, 48, o por lado | sí | |
gap |
0, 4, 8, 12, 16, 24, 32, 48 | sí | |
borderRadius |
radius |
none, small, medium, large, full, o por esquina { topStart, topEnd, bottomStart, bottomEnd } (la que se omite, medium) |
sí |
width |
w |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | sí |
height |
h |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | sí |
minHeight |
minH |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | sí |
fill |
true: todo el ancho del padre |
sí | |
flex |
weight |
de 1 a 12: su parte de un Row o un Column |
sí |
crossAxisAlignment |
align |
start, center, end, stretch: a lo ancho del eje principal (en un Text, el párrafo) |
sí |
mainAxisAlignment |
justify |
start, center, end, spaceBetween, spaceAround: a lo largo del eje principal |
sí |
color |
primary, secondary, surface, muted, warning, error, onPrimary, primaryContainer, surfaceVariant |
sí | |
span |
de 1 a 12 o "auto" (por defecto), solo en un Row con wrap: true |
sí | |
offset |
de 0 a 11, solo en un Row con wrap: true |
sí | |
maxWidthFraction |
de 0.25 a 1 en pasos de 0.05: como máximo esa parte del ancho del padre (exactamente, con fill) |
sí | |
alignSelf |
start, center, end, stretch: este hijo a lo ancho de su Row o Column, por encima del crossAxisAlignment del padre (propiedades de caja y texto) |
sí | |
textAlign |
start, center, end, justify: el párrafo de un nodo que dibuja texto (Text, Button, Chips, TextField, TextField, ListTile) |
sí | |
border |
{ width?, color? } en una caja: ancho de 0 a 8 dp (por defecto 1), un rol de color (por defecto el contorno de Kino) |
sí | |
elevation |
de 0 a 24 en un Card o un Stack: la sombra de Kino (también la elevación tonal de una tarjeta) |
sí | |
background |
un rol de color: el relleno de una caja (su contenido se lee en el color «sobre» de ese rol) | sí | |
minWidth |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | sí | |
maxWidth |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | sí | |
maxHeight |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | sí | |
positioned |
{ top?, left?, right?, bottom?, width?, height? } en un hijo de Stack: dp o "25%" del Stack (Stack posicionado) |
sí | |
opacity |
de 0 a 1; por debajo de 0.38 el nodo no acepta pulsaciones ni foco (animaciones) | sí | |
animate |
{ duration?, curve? } en una caja o un hijo posicionado: los cambios se deslizan (animaciones) |
sí |
Propiedades comunes¶
Todos los nodos aceptan estas, además de las suyas y las de estilo.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
key |
texto | auto-<n> |
no | única en la pantalla; obligatoria en entradas, ventanas emergentes, un ExpansionTile y un aviso que se puede descartar; el prefijo auto- es de Kino |
onTap |
acción | ninguna | no | una pulsación (la de un botón es onPressed) |
onLongPress |
acción | ninguna | no | una pulsación larga; úsala para extras a los que se llega de otra forma |
onSwipeLeft, onSwipeRight |
acción | ninguna | no | aditivo, sin apiVersion nuevo: un deslizamiento lateral (a la izquierda = la página siguiente); en la TV, Derecha / Izquierda cuando el foco ya no tiene a dónde ir (Deslizar) |
arg |
texto | ninguno | no | el arg del evento cuando la acción es solo el nombre de un evento (como máximo 4.096 caracteres) |
enabled |
booleano | true |
no | false lo dibuja desactivado; ui enable/disable lo cambian |
hidden |
booleano | false |
no | true lo empieza oculto; ui show/hide/toggle lo cambian |
devices |
phone, tv, desktop (una lista) |
en todas partes | no | se dibuja solo ahí; un nombre desconocido descarta el nodo |
sizes |
compact, medium, expanded (una lista) |
todos los tamaños | no | se dibuja solo en esas clases de ancho |
testKey |
texto | ninguno | no | de 1 a 64 caracteres, para pruebas, nunca se dibuja |
autofocus |
booleano | false |
no | un nodo que toma foco: adonde va el foco cuando un dibujado lo dejó en ninguna parte (propiedades compartidas) |
selected |
booleano | ninguno | no | un botón o una tarjeta con onTap: el aspecto de seleccionado de Kino; ui set y toggle (prop: "selected") lo cambian |
badge |
"dot" o { text, textEn?, color? } |
ninguno | no | un botón, una tarjeta con onTap, una pestaña: un número (como máximo 12 caracteres) o un punto en su esquina superior final |
visible |
booleano | true |
no | false lo oculta igual que hidden: true (animaciones) |
tooltip |
texto | ninguno | no | un nodo que hace algo: la pista de Kino (tooltipEn), como máximo 80 caracteres; nunca información esencial (tooltip) |
enabledAt |
epoch ms | ninguno | no | un botón, un FloatingActionButton, una tarjeta o un ListTile con onTap: desactivado hasta esa hora en el reloj del aparato, luego se activa solo, sin llamarte (texto con una hora) |
canRequestFocus |
booleano | false |
no | cualquier nodo: en la TV, una parada del D-pad donde el control se detiene para leerlo (el aspecto de fila de Kino, sin pulsación); se ignora donde el nodo ya toma foco y en el teléfono (propiedades compartidas) |
loading |
booleano | false |
no | un botón, un FloatingActionButton, una tarjeta o un ListTile con onTap: el aspecto de ocupado de Kino (un indicador giratorio, sin pulsación, se lee como ocupado); Kino también lo dibuja en el nodo pulsado mientras su llamada tarda (pulsaciones ocupadas y lentas) |
Propiedades compartidas¶
Kino nunca agrega un componente por cada necesidad: una familia de nodos comparte una propiedad con un mismo significado en todas partes.
autofocus: trueen un nodo que toma foco (un botón, una entrada, unTabBar, untitleCard, o cualquier nodo cononTapuonLongPress): en un dibujado (un tic o una respuesta) que dejó el foco en ninguna parte, o en un nodo que ya no está, el foco va al primer nodo conautofocusen el orden del árbol. Elfocuspropio de una respuesta gana, y un nodo que todavía tiene el foco lo conserva. Esto es sobre todo para la TV: una pantalla que cambia con un temporizador (una descarga terminada, un evento en vivo que acabó) pone el control en su único camino para seguir. En un teléfono un campo de texto nunca recibe autofoco (ningún teclado se abre solo). En otro lado se ignora y queda en el registro.canRequestFocus: true(el nombre de Flutter) en cualquier nodo que no toma foco por sí mismo (unCardde estado, unText, unRow, unColumn, unDataTable, unMaterialBannersin acción): en la TV se vuelve una parada del D-pad donde el control se detiene para leerlo, con el aspecto de fila de Kino (un tinte tonal y un subrayado de acento, nunca el anillo blanco), sin pulsación (OK no hace nada). Participa en Arriba, Abajo, Izquierda, Derecha y las reglas delScaffoldcomo cualquier parada, y un lector de pantalla lee su contenido. Se ignora en un nodo que ya toma foco y en el teléfono; nunca por tamaño. Receta, una tarjeta de estado como parada de lectura en la TV:{ "type": "Card", "key": "status", "canRequestFocus": true, "children": [ ... ] }. Sin ella la TV igual muestra la tarjeta: un cuerpo con desplazamiento avanza por páginas (80 % de su alto) antes de que el foco pase de largo un bloque que todavía no se ha mostrado.selected: true | falseen un botón (cualquier variante) o una tarjeta cononTap: el aspecto de seleccionado de Kino (tonal relleno; una tarjeta recibe un contorno en el color primario), que un lector de pantalla lee como seleccionado. Es estado, no una acción;uisetytoggleconprop: "selected"lo cambian sin llamarte (Operaciones ui locales).ChipsyTabBardicen cuál está seleccionado con suvalue. En la TV el foco no cambia.badge: el valor del nodoBadge,"dot"o{ text, textEn?, color? }(un número o una palabra corta, como máximo 12 caracteres;colorun rol de color, por defecto el primario de Kino), en un botón, una tarjeta cononTap, una pestaña deTabBar(en su entrada detabs) y una pestaña del cajón de un panel (en lostabsdel resultado del panel). Se pone en la esquina superior final del nodo (junto a la etiqueta de una pestaña) y un lector de pantalla lo lee después del nombre del nodo («Chat, 3»; un punto se lee «nuevo»). Ponlo en cada dibujado.
{ "type": "Column", "children": [
{ "type": "TabBar", "key": "tabs", "value": "chat", "onChanged": "tab", "tabs": [
{ "value": "room", "label": "Sala", "labelEn": "Room" },
{ "value": "chat", "label": "Chat", "badge": { "text": "3" } }] },
{ "type": "Row", "gap": 8, "children": [
{ "type": "IconButton", "key": "mute", "icon": "close", "labelText": "Silencio", "labelTextEn": "Mute", "selected": true,
"onPressed": { "ui": [{ "toggle": "mute", "prop": "selected" }], "event": "mute" } },
{ "type": "IconButton", "key": "downloads", "icon": "download", "labelText": "Descargas", "labelTextEn": "Downloads", "badge": "dot", "onPressed": "downloads" },
{ "type": "ElevatedButton", "key": "retry", "labelText": "Reintentar", "labelTextEn": "Try again", "autofocus": true, "onPressed": "retry" }] }
] }
maxWidthFraction (de 0.25 a 1 en pasos de 0.05) y borderRadius por esquina son de estilo: todos los nodos
aceptan el primero, y todo nodo que dibuja una caja el segundo; el anillo de foco de la TV sigue las esquinas.
Propiedades de caja y texto¶
Propiedades de estilo, todas por tamaño, cada una un token o un rol de color, nunca un valor libre:
| Propiedad | La aceptan | Qué hace |
|---|---|---|
alignSelf |
un hijo de un Row, Column, Card, Form o desplazamiento |
start, center, end, stretch a lo ancho de su padre, por encima del crossAxisAlignment del padre; en una fila stretch se dibuja como start (Kino no mide alturas intrínsecas); en otro lado, también la celda de una fila que se ajusta, se ignora y queda en el registro |
textAlign |
Text, la etiqueta de un botón, Chips, TextField, ListTile |
start, center, end, justify; en un Text gana sobre la lectura anterior de crossAxisAlignment como párrafo. La TV dibuja sus propias entradas de campos y acciones, ajustadas a su texto: ahí se nota en un Text |
border |
una caja: Column, Row, Stack, Card, desplazamiento, GridView, Form, ListTile, PageView |
{ width?, color? }: de 0 a 8 dp (por defecto 1; fuera de rango se ajusta al límite), un rol de color (por defecto el contorno de Kino); sigue borderRadius; una tarjeta seleccionada conserva el contorno primario de Kino |
elevation |
Card, Stack |
de 0 a 24 (ajustado al límite): la sombra de Kino, que sigue la forma; una tarjeta simple además se eleva tonalmente. Sin sombras libres |
background |
una caja | un rol de color: el relleno (por encima de color, que una caja sigue leyendo como su relleno); el texto y los iconos de adentro se leen en el color «sobre» de ese rol, y un Text o Icon coloreado con un rol que no se leería sobre ese relleno se dibuja en el color legible del relleno |
minWidth, maxWidth, maxHeight |
cualquier nodo | la escala de tamaños, junto a minHeight; un mínimo mayor que su máximo descarta el máximo y queda en el registro |
{ "type": "Column", "crossAxisAlignment": "start", "children": [
{ "type": "Card", "border": { "width": 2, "color": "primary" }, "elevation": 3, "maxWidth": 320, "alignSelf": "center",
"children": [{ "type": "Text", "text": "Centrado", "textEn": "Centred", "textAlign": "center", "fill": true }] },
{ "type": "Stack", "background": "primaryContainer", "padding": 12, "children": [{ "type": "Text", "text": "Destacado", "textEn": "Highlighted" }] }
] }
Animaciones (animate, opacity, visible)¶
AnimatedContainer, AnimatedOpacity y AnimatedSwitcher de Flutter reunidos en una sola propiedad de estilo:
animate: { duration?, curve? } en una caja (o un hijo positioned): los cambios de su tamaño, su opacity, su relleno, su
lugar en un Stack y su visibilidad entre dos dibujados se deslizan durante duration ms (de 100 a 600, por defecto 250,
ajustado al límite) siguiendo curve (standard, ease, decelerate). opacity (de 0 a 1, cualquier nodo) lo desvanece;
por debajo de 0.38 el nodo no acepta pulsaciones ni foco. visible: false oculta un nodo igual que hidden: true (ui
show y hide siguen funcionando); con animate aparece y desaparece desvaneciéndose y plegándose, y mientras se va no
acepta nada. La opción «quitar animaciones» del aparato (escala de duración de animación 0) vuelve cada una un salto; una
animación nunca retrasa una pulsación ni el foco; como máximo 24 nodos animándose por pantalla (el resto descarta animate
y queda en el registro).
{ "type": "Card", "key": "details", "animate": { "duration": 300, "curve": "decelerate" }, "visible": true,
"background": "surfaceVariant", "children": [{ "type": "Text", "text": "Más información", "textEn": "More details" }] }
Tokens¶
| Token | Valores |
|---|---|
Espaciado (padding, margin, gap) |
0, 4, 8, 12, 16, 24, 32, 48 |
Tamaños (width, height, minHeight) |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 |
Esquinas (borderRadius) |
none, small, medium, large, full (uno para todas las esquinas, o un mapa por esquina) |
Roles de color (color) |
primary, secondary, surface, muted, warning, error, onPrimary, primaryContainer, surfaceVariant |
Roles (MaterialBanner, un toast) |
info, warning, error, success |
Estilos de texto (Text.style) |
hero, h1, h2, h3, h4, h5, p, caption, label |
Tamaños de tarjeta (titleCard, titleRail, QrImage) |
small, medium, large |
Clases de ancho (mapas por tamaño, sizes) |
compact, medium, expanded |
Aparatos (devices, ctx.device) |
phone, tv, desktop |
Iconos (Icon.name, el icon de un botón) |
info, tune, settings, star, bolt, language, subtitles, list, magic, heart, movie, tv, sports, music, bookmark, help, refresh, sync, add, remove, delete, edit, search, close, check, share, play, pause, download, upload, link, open_in_new, home, person, lock, notifications, warning, error, visibility, copy, arrow_back, arrow_forward, expand_more, expand_less, more_vert, filter_list, calendar, schedule, send, mood |
No están en esta versión: deslizar para actualizar, botones segmentados, autocompletado y cuadros combinados, selectores de
fecha y hora, un control deslizante de rango, una calificación, elementos de lista que se descartan o se reordenan, texto
enriquecido, gráficos, tarjetas de «seguir viendo» y de canales, y entradas de archivo. Detecta un componente que agregue un
Kino más nuevo con kino.screen.names.includes("DataTable").
Límites¶
| Límite | Valor | Qué |
|---|---|---|
maxConfigKeys |
32 | ajustes que escribe un config |
maxDepth |
10 | profundidad de un árbol |
maxNodes |
600 | nodos en un árbol |
maxListItems |
500 | elementos de una lista, fila, cuadrícula, acordeón o de las opciones de una elección |
maxStateBytes |
65.536 (64 KB) | bytes del estado, como JSON |
maxTextChars |
2.000 | caracteres de un texto |
minEventIntervalMs |
100 | ms entre dos eventos |
callTimeoutMs |
20.000 | ms por llamada a screen o screenEvent |
maxPopups |
1 | ventana emergente abierta a la vez |
maxRefChars |
4.096 | caracteres de un ref o un arg |
maxSearchQueryChars |
200 | caracteres del q de un go.search |
eventQueue |
8 | eventos en espera |
maxUiOps |
8 | operaciones ui por acción o respuesta |
maxDialogButtons |
3 | botones en un diálogo |
maxWeight |
12 | el mayor flex |
maxGridColumns |
8 | el mayor columns |
maxTestKeyChars |
64 | caracteres de un testKey |
maxTrailingLabelChars |
40 | caracteres del trailingLabel de un campo de texto |
maxHeroButtons |
2 | botones en un heroCard |
maxMenuItems |
8 | elementos de un menú |
maxTitles |
1.000 | títulos en todo un árbol |
maxFlatTitles |
60 | títulos en una fila o cuadrícula dibujada de una vez |
maxPatternChars |
200 | caracteres de un pattern |
maxPatternRepeat |
1.000 | la mayor repetición en un patrón |
maxPatternStates |
500 | pasos de un patrón con las repeticiones expandidas |
maxPatternFields |
16 | patrones que corre un envío |
maxPatternCompileWork |
20.000 | unidades de trabajo para leer un patrón |
maxPatternMatchWork |
4.000.000 | pasos del comparador que corre un envío |
minTimerMs |
1.000 | temporizador más corto, ms |
maxTimerMs |
86.400.000 | temporizador más largo, ms |
maxTimers |
3 | temporizadores por pantalla |
timerMaxFailures |
3 | fallos seguidos que apagan un temporizador |
toastMinMs |
2.000 | toast más corto, ms |
toastMaxMs |
8.000 | toast más largo, ms |
toastDefaultMs |
3.500 | duración por defecto de un toast, ms |
timerConfigWriteIntervalMs |
60.000 | ms entre dos escrituras de un mismo ajuste desde un temporizador |
maxQrChars |
1.000 | caracteres del valor de un QrImage |
maxStepperDecimals |
6 | decimales de un NumberStepper |
maxStepperAbs |
1.000.000.000.000.000 | el mayor número de un NumberStepper, en positivo o negativo |
maxSkeletonLines |
6 | líneas de un Skeleton |
maxTableColumns |
20 | columnas de un DataTable |
maxTableRows |
200 | filas de un DataTable |
maxColSpan |
8 | el mayor colSpan |
gridColumns |
12 | columnas de la fila de doce columnas |
maxGoRouteChars |
64 | caracteres del route de un go.screen |
maxGoArgsBytes |
4.096 (4 KB) | bytes de los args de un go.screen, como JSON |
Panel del reproductor¶
El panel del reproductor se puede armar con los mismos nodos: panel(context) puede devolver
{ format: "screen", root, ... }, un árbol de pantalla dentro del cajón de Kino. Todo lo que hace falta está en
El panel del reproductor:
- el panel en modo pantalla: el resultado, el texto más pequeño en la TV, qué campos de la respuesta conserva;
- pestañas aportadas (
playerPanelTab): tu pestaña en el panel del título de cualquier plugin; - el panel fijado: acoplado junto al video;
layout: "fill"y unListViewconstickToBottom: una pestaña de chat cuya fila de escritura se queda abajo del panel.
Recetas¶
Copia, pega, adapta. Cada una es un screen completo (y su screenEvent cuando tiene eventos); el
ejemplo de la galería pone en marcha la mayoría.
Cuadrícula de tarjetas de noticias¶
Una tarjeta por línea en un teléfono, dos en una ventana mediana, tres en una TV; tarjetas sin margen interno con una imagen y un respaldo; un toque lee la noticia en una ventana emergente declarada que abre la respuesta.
const STORIES = [
{ id: "a", title: "Un estreno", source: "Kino", image: "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg" },
{ id: "b", title: "Otra noticia", source: "Guía", image: "" },
];
export async function screen({ state }) {
const reading = STORIES.find((s) => s.id === state.reading);
const card = (s) => ({
type: "Card", key: "story-" + s.id, flush: true, span: { compact: 12, medium: 6, expanded: 4 }, onTap: { event: "read", arg: s.id },
children: [
{ type: "Image", ...(s.image ? { url: s.image } : {}), aspect: "16:9", alt: s.title, fallback: { type: "Stack", color: "surface", children: [{ type: "Text", text: s.source, style: "h3", padding: 12 }] } },
{ type: "Column", padding: 12, gap: 4, children: [{ type: "Text", text: s.title, style: "h4", maxLines: 3 }, { type: "Text", text: s.source, style: "caption", color: "muted" }] },
],
});
return { type: "Column", children: [
{ type: "SingleChildScrollView", flex: 1, children: [{ type: "Row", wrap: true, gap: 12, padding: 16, children: STORIES.map(card) }] },
{ type: "AlertDialog", key: "story", title: reading ? reading.title : "", onClose: "closed", children: [{ type: "Text", text: reading ? reading.source : "…" }] },
] };
}
export async function screenEvent({ name, arg }) {
if (name === "read") return { state: { reading: arg }, ui: [{ open: "story" }] };
if (name === "closed") return { state: { reading: null } };
return null;
}
Formulario de ajustes con validación¶
Un formulario cuyo envío Kino revisa primero; la respuesta escribe tus ajustes con config (el manifiesto declara greeting
como un ajuste text y density como un select).
export async function screen() {
return { type: "SingleChildScrollView", children: [{ type: "Form", key: "prefs", onSubmitted: "save", gap: 12, padding: 16, children: [
{ type: "TextField", key: "greeting", labelText: "Saludo", labelTextEn: "Greeting", required: true, maxLength: 40, pattern: "^[A-Za-z ]+$", errorText: "Solo letras", errorTextEn: "Letters only" },
{ type: "RadioGroup", key: "density", labelText: "Densidad", value: "normal", options: [{ value: "compact", label: "Compacta" }, { value: "normal", label: "Normal" }, { value: "roomy", label: "Amplia" }] },
{ type: "ElevatedButton", labelText: "Guardar", labelTextEn: "Save", submit: true },
] }] };
}
export async function screenEvent({ name, value }) {
if (name !== "save") return null;
return { config: { greeting: value.greeting, density: value.density }, toast: "Guardado", toastEn: "Saved" };
}
Ventana de confirmación¶
La forma rápida es el confirm de un botón (Kino pregunta y luego corre la acción); la forma a tu medida es un diálogo desde
la respuesta.
export async function screen({ state }) {
return { type: "Column", gap: 12, padding: 16, children: [
{ type: "Text", text: state.deleted ? "Lista borrada" : "Tu lista" },
{ type: "TextButton", labelText: "Borrar (rápido)", confirm: "¿Borrar la lista?", confirmEn: "Delete the list?", onPressed: "delete" },
{ type: "Button", variant: "secondary", labelText: "Borrar (diálogo)", onPressed: "ask" },
] };
}
export async function screenEvent({ name }) {
if (name === "ask") return { dialog: { title: "¿Borrar la lista?", body: "No se puede deshacer.", buttons: [{ label: "Borrar", event: "delete", variant: "primary" }, { label: "Cancelar", variant: "text" }] } };
if (name === "delete") return { state: { deleted: true }, toast: { text: "Borrada", role: "success" } };
return null;
}
Pestañas con chips¶
Un TabBar cuyo valor guardas en tu estado, y Chips que filtran la lista de la pestaña.
const ALL = [{ t: "Big Buck Bunny", k: "movies" }, { t: "Sintel", k: "movies" }, { t: "Una serie", k: "series" }];
export async function screen({ state }) {
const tab = state.tab === "saved" ? "saved" : "all";
const filter = typeof state.inputs?.kind === "string" ? state.inputs.kind : "any";
const list = ALL.filter((x) => filter === "any" || x.k === filter);
return { type: "Column", children: [
{ type: "TabBar", key: "tabs", value: tab, onChanged: "tab", tabs: [{ value: "all", label: "Todo", labelEn: "All" }, { value: "saved", label: "Guardado", labelEn: "Saved" }] },
{ type: "Chips", key: "kind", value: filter, padding: 8, options: [{ value: "any", label: "Todo" }, { value: "movies", label: "Películas" }, { value: "series", label: "Series" }], onChanged: "filter" },
{ type: "ListView", key: "list", flex: 1, items: list.map((x, i) => ({ type: "Text", key: "x" + i, text: x.t, padding: 12 })), empty: { type: "emptyState", title: "Nada", titleEn: "Nothing" } },
] };
}
export async function screenEvent({ name, value }) {
if (name === "tab") return { state: { tab: value } };
if (name === "filter") return { state: {} }; // the chip's value is already in state.inputs: just draw again
return null;
}
Matriz de botones (estilo calculadora)¶
Botones en una fila de doce columnas, tres columnas cada uno (cuatro por línea), cada uno con su propia key y con tamaño
por clase: en una TV el D-pad la recorre como una matriz. Un plugin de calculadora completo se arma de la misma forma.
const KEYS = ["7", "8", "9", "÷", "4", "5", "6", "×", "1", "2", "3", "−", "C", "0", ".", "+"];
export async function screen({ state }) {
const shown = typeof state.shown === "string" ? state.shown : "0";
return { type: "Column", gap: 12, padding: 16, children: [
{ type: "Card", variant: "filled", children: [{ type: "Text", text: shown, style: "h1", crossAxisAlignment: "end" }] },
{ type: "Row", wrap: true, gap: 8, children: KEYS.map((k, i) => ({
type: "Button", key: "k" + i, variant: /\d|\./.test(k) ? "secondary" : "primary", labelText: k,
onPressed: "key", arg: k, span: 3, fill: true, height: { compact: 80, medium: 64, expanded: 48 },
})) },
] };
}
export async function screenEvent({ name, arg, state }) {
if (name !== "key") return null;
const now = typeof state.shown === "string" ? state.shown : "0";
return { state: { shown: arg === "C" ? "0" : (now === "0" ? "" : now) + arg } };
}
Una pantalla con barra superior, pestañas y botón flotante¶
Una raíz Scaffold: la barra con un botón para volver, una acción de búsqueda y dos pestañas; una lista perezosa en el
cuerpo; un botón «Nueva» encima de una barra inferior de tres secciones. Tu estado guarda la pestaña y la sección (ninguna
está en state.inputs).
export async function screen({ state }) {
const tab = state.tab === "saved" ? "saved" : "all";
const section = ["home", "lists", "me"].includes(state.section) ? state.section : "home";
const rows = (tab === "saved" ? ["Guardado 1"] : ["Uno", "Dos", "Tres"]).map((t, i) => ({ type: "ListTile", key: "r" + i, title: t, onTap: "show", arg: String(i) }));
return {
type: "Scaffold",
appBar: {
type: "AppBar", title: "Mis listas", titleEn: "My lists",
leading: { type: "IconButton", icon: "arrow_back", labelText: "Atrás", labelTextEn: "Back", onPressed: { close: true } },
actions: [{ type: "IconButton", icon: "search", labelText: "Buscar", labelTextEn: "Search", onPressed: "search" }],
bottom: { type: "TabBar", key: "tabs", value: tab, onChanged: "tab", tabs: [{ value: "all", label: "Todo", labelEn: "All" }, { value: "saved", label: "Guardado", labelEn: "Saved" }] },
},
body: { type: "ListView", key: "rows", items: rows },
floatingActionButton: { type: "FloatingActionButton", icon: "add", labelText: "Nueva", labelTextEn: "New", onPressed: "newList" },
bottomNavigationBar: { type: "NavigationBar", value: section, onChanged: "section", items: [
{ key: "home", icon: "home", label: "Inicio", labelEn: "Home" },
{ key: "lists", icon: "list", label: "Listas", labelEn: "Lists" },
{ key: "me", icon: "person", label: "Yo", labelEn: "Me" },
] },
};
}
export async function screenEvent(e) {
if (e.name === "tab") return { state: { tab: e.value } };
if (e.name === "section") return { state: { section: e.value } };
return null;
}
Pestañas en la barra superior¶
La barra de título propia de Kino ya nombra la pantalla, así que la barra superior puede llevar las pestañas mismas: un
TabBar como title, junto a las acciones, de una fila de alto.
export async function screen({ state }) {
const tab = ["account", "connection", "help"].includes(state.tab) ? state.tab : "account";
return {
type: "Scaffold",
appBar: {
type: "AppBar",
title: { type: "TabBar", key: "tabs", value: tab, onChanged: "tab", tabs: [
{ value: "account", label: "Cuenta", labelEn: "Account" },
{ value: "connection", label: "Conexión", labelEn: "Connection" },
{ value: "help", label: "Inicio y ayuda", labelEn: "Start and help" },
] },
actions: [
{ type: "IconButton", icon: "refresh", labelText: "Actualizar", labelTextEn: "Refresh", onPressed: "refresh" },
{ type: "IconButton", icon: "help", labelText: "Ayuda", labelTextEn: "Help", onPressed: "help" },
],
},
body: { type: "SingleChildScrollView", children: [{ type: "Column", padding: 16, gap: 12, children: [{ type: "Text", text: "Pestaña: " + tab }] }] },
};
}
export async function screenEvent(e) {
return e.name === "tab" ? { state: { tab: e.value } } : null;
}
Una vista de búsqueda que Atrás cierra primero¶
Una sola barra (mergeWithKinoBar: tu leading donde estaba Cerrar, tu título en lugar del nombre del plugin) y un Atrás
que primero sale de la búsqueda y luego de la pantalla: mientras state.searching es verdadero el árbol declara onBack, y
su respuesta apaga la marca, así el siguiente Atrás cierra la pantalla.
export async function screen({ state }) {
const searching = state.searching === true;
return {
type: "Scaffold",
// Declared only while there is something for Back to undo.
onBack: searching ? "close_search" : undefined,
appBar: {
type: "AppBar", mergeWithKinoBar: true,
title: searching ? "Buscar" : "Mis listas", titleEn: searching ? "Search" : "My lists",
leading: searching
? { type: "IconButton", icon: "arrow_back", labelText: "Cerrar la búsqueda", labelTextEn: "Close search", onPressed: "close_search" }
: { type: "IconButton", icon: "close", labelText: "Cerrar", labelTextEn: "Close", onPressed: { close: true } },
actions: searching ? [] : [{ type: "IconButton", icon: "search", labelText: "Buscar", labelTextEn: "Search", onPressed: "open_search" }],
},
body: { type: "Column", padding: 16, gap: 12, children: [
searching
? { type: "TextField", key: "q", labelText: "Buscar", labelTextEn: "Search", autofocus: true }
: { type: "Text", text: "Tus listas", textEn: "Your lists" },
] },
};
}
export async function screenEvent(e) {
if (e.name === "open_search") return { state: { searching: true } };
if (e.name === "close_search") return { state: { searching: false } };
return null;
}
Un lector: páginas que se ajustan al ancho, zoom y un punto que se guarda¶
Para manga, webtoons, cómics y documentos largos. Cuatro piezas pequeñas, cada una útil por sí sola:
Imageconfit: "width": la imagen toma el ancho de su caja y su alto propio, así una página nunca se corta (sin medir bytes, sin tabla de tamaños). Elaspect(cualquier"w:h", como"1.4:1") solo guarda el lugar hasta que carga.zoom: trueen el desplazamiento vertical: pellizcar, doble toque y arrastrar; el contenido se dibuja más ancho, así la imagen se ve nítida.onScroll: dónde se detuvo la persona, de0(arriba) a1(final), 0,3 s después de que se detiene. Guárdalo enkino.storage.pagesconreverse: trueyprogress: "bar": una página a la vez, deslizada de izquierda a derecha, o de derecha a izquierda para manga, hasta 250 páginas, con una barra fina en vez de un segmento por página. Una página que contiene un desplazamiento con zoom lo amplía; un dedo sobre una página sin ampliar sigue deslizando.
export async function screen({ state }) {
const pages = state.pages ?? []; // [{ url }]
if (state.mode === "paged") {
return { type: "pages", key: "pgs", flex: 1, reverse: state.rtl === true, progress: "bar", onPageChanged: "page",
children: pages.map((p, i) => ({ type: "SingleChildScrollView", key: "z" + i, zoom: true, children: [
{ type: "Image", url: p.url, fit: "width", aspect: "2:3", alt: "Página " + (i + 1), altEn: "Page " + (i + 1) } ] })) };
}
return { type: "SingleChildScrollView", key: "strip", flex: 1, zoom: true, onScroll: "scrolled",
children: [{ type: "Column", crossAxisAlignment: "center",
children: pages.map((p, i) => ({ type: "Image", key: "p" + i, url: p.url, fit: "width", aspect: "2:3" })) }] };
}
export async function screenEvent({ name, value }) {
if (name === "scrolled" || name === "page") { kino.storage.set("at", String(value)); return null; } // the place to resume
return null;
}
- Un nodo
pagesnecesita unakeypropia y 2 o más hijos; conprogress: "segments"(el valor por defecto), 8 como máximo. onScrolles para un desplazamiento vertical que se desplaza solo (la tira); dentro depages, la página a la que llegó la persona viene deonPageChanged.- Retoma una página con un
setdeuisobre lakeydelpagesen la respuesta que abre el capítulo:ui: [{ set: { key: "pgs", value: 4 } }]. - A la tira vertical no se le puede ordenar que se desplace a una posición guardada: guarda el punto, muéstralo y deja que la persona se desplace.
Un carrusel arriba de una portada¶
PageView con viewportFraction menor que 1: la página siguiente asoma por el lado, pasa sola y Kino dibuja los puntos.
const page = (it, i) => ({ type: "Card", key: "car-" + i, variant: "filled", radius: "large", margin: 8,
onTap: { event: "series", arg: it.url },
children: [{ type: "Row", gap: 16, padding: 16, crossAxisAlignment: "center", children: [
{ type: "Card", flush: true, radius: "medium", elevation: 6, children: [
{ type: "Image", url: it.poster, width: 120, aspect: "2:3", alt: it.title } ] },
{ type: "Column", gap: 8, flex: 1, crossAxisAlignment: "start", children: [
{ type: "Badge", text: "#" + (i + 1), color: "primary" },
{ type: "Text", text: it.title, style: "h3", maxLines: 3 },
{ type: "ElevatedButton", icon: "play", radius: "full", labelText: "Ver", labelTextEn: "See", onPressed: { event: "series", arg: it.url } },
] } ] }] });
// placeholders until your data loads: a PageView with no pages draws nothing
const DEMO = [{ url: "/a", title: "Uno", poster: "https://example.com/a.jpg" }, { url: "/b", title: "Dos", poster: "https://example.com/b.jpg" }];
export async function screen({ state }) {
return { type: "SingleChildScrollView", children: [
{ type: "Text", text: "Tendencias", textEn: "Trending", style: "h3", padding: 16 },
{ type: "PageView", key: "carousel", viewportFraction: { compact: 0.9, medium: 0.6, expanded: 0.42 }, padEnds: false,
autoPlayMs: 5000, children: (state.trending ?? DEMO).slice(0, 6).map(page) } ] };
}
Cada página cuenta para los 600 nodos de una pantalla: una página como esta son unos 9 nodos, así que seis páginas cuestan 54. Deja el carrusel en 6 a 8 páginas y recorta los rieles que van debajo.
Una tarjeta del Home de Kino que abre tu pantalla, con una portada a la que volver¶
Un elemento de una fila de home() lleva open: { screen }: al tocarlo abre tu pantalla en vez de la página del título,
desde las filas del Home de Kino y desde sus estantes de categorías. Dale args, no una ruta, para que la pantalla se
abra en tu portada (ruta main) y apiles el detalle encima: así Atrás cae en tu portada en vez de no hacer nada.
export async function home() {
return [{ id: "trending", title: "Mangas populares", items: titles.map((t) => ({
id: t.slug, ref: t.url, title: t.title, kind: "movie", poster: t.poster,
open: { screen: { args: { open: t.url } } }, // no route: the screen opens as "main"
})) }];
}
export async function screenEvent({ name, route }) {
if (name === "open" && typeof route?.args?.open === "string") {
const detail = await loadSeries(route.args.open); // your own loader
return { state: { detail }, route: { push: "detail", params: { url: route.args.open } } }; // front page below, detail on top
}
return null;
}
- Un plugin que no reproduce nada declara
"catalogOnly": true; dale a sus elementoskind: "movie"(un elementoseriesnecesitaepisodes). - Comprueba tú
route.args.open(una ruta que reconozcas): viene de una fila guardada que escribió una versión anterior del plugin. - Kino guarda las filas de
home()6 horas y las descarta cuando cambia la versión del plugin.
Buscar dentro del campo, con esqueletos mientras carga¶
Un TextField puede llevar su propio icono de búsqueda (trailingIcon, trailingLabel, onTrailingTap), así que no hace
falta un botón aparte ni un Form. Muestra al instante una cuadrícula de esqueletos oculta con una operación ui
local, y ocúltala en la respuesta: la pantalla nunca se queda congelada mientras tu screenEvent consulta.
const SEARCH = { ui: [{ show: "loading" }, { hide: "results" }], event: "search" };
const card = (r) => ({ type: "Card", key: "r-" + r.id, onTap: { event: "series", arg: r.id }, children: [{ type: "Text", text: r.title, padding: 8 }] });
export async function screen({ state }) {
return { type: "SingleChildScrollView", children: [{ type: "Column", children: [
{ type: "TextField", key: "q", kind: "search", padding: 16, labelText: "Buscar", labelTextEn: "Search",
trailingIcon: "search", trailingLabel: "Buscar", trailingLabelEn: "Search", onSubmitted: SEARCH, onTrailingTap: SEARCH },
{ type: "Column", key: "loading", hidden: true, padding: 12, children: [{ type: "GridView", columns: 3, gap: 12,
children: [0, 1, 2, 3, 4, 5].map((i) => ({ type: "Column", key: "sk" + i, gap: 8, children: [
{ type: "Skeleton", shape: "block", height: 200 }, { type: "Skeleton", shape: "line", lines: 2 } ] })) }] },
{ type: "Column", key: "results", children: (state.results ?? []).map(card) },
] }] };
}
export async function screenEvent({ name, value }) {
if (name !== "search") return null;
const results = await find(String(value ?? "").trim()); // the field's text arrives as `value`
return { state: { results }, ui: [{ hide: "loading" }, { show: "results" }] }; // also in the answer to a failure
}
Aquí los esqueletos le ganan al spinner: conservan la forma de la cuadrícula, así nada salta cuando llegan los resultados.
Filtros en una hoja inferior, con un campo de búsqueda¶
Tres o cuatro filtros como botones (Género: Todos ▾) que abren una BottomSheet; una lista larga (géneros) lleva un campo
de búsqueda. Elegir una fila cierra la hoja y muestra esqueletos mientras carga la página nueva, todo con operaciones ui
locales en el toque.
const BUSY = [{ show: "skeleton" }, { hide: "grid" }];
const sheet = (key, title, options, current, event, q) => ({ type: "BottomSheet", key, title, children: [
options.length > 8 ? { type: "TextField", key: "gq", kind: "search", value: q, padding: 8, labelText: "Buscar", onChanged: "gq" } : null,
{ type: "ListView", key: key + "-list", items: options.filter((o) => !q || o[1].toLowerCase().includes(q.toLowerCase())).map((o) => ({
type: "ListTile", key: key + "-" + o[0], dense: true, title: o[1],
trailing: o[0] === current ? { type: "Icon", name: "check" } : undefined,
onTap: { ui: [{ close: key }].concat(BUSY), event, arg: o[0] } })) },
].filter(Boolean) });
// the button that opens it
const button = (sheetKey, label, value) => ({ type: value ? "ElevatedButton" : "TextButton", radius: "full", icon: "expand_more",
labelText: label + ": " + (value || "Todos"), onPressed: { ui: [{ open: sheetKey }] } });
gqes tu propio estado:screenEventresponde{ state: { gq: value } }y el siguiente dibujo filtra la lista; la hoja sigue abierta.- Una fila de
Chipssirve para 3 a 5 opciones cortas; con más, desplazarse de lado oculta casi todas. Usa una hoja. - Una opción con valor vacío no puede ser el
valuede un chip: usa una palabra como"all"y léela de vuelta como vacía.