Componentes de pantalla: diseño, contenido y acciones¶
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).
Todo lo de esta página necesita "apiVersion": 14. Cada componente que puede dibujar la pantalla de un plugin, una
sección para cada uno: para qué sirve, sus propiedades, un árbol JSON, lo mismo en el JavaScript del plugin, cómo se
comporta en el celular y en la TV, sus límites y los errores que conviene evitar. Acompaña a la
guía de Pantallas, que explica el modelo (el manifiesto, los exports, el estado y los eventos); esta página
y las dos siguientes son el catálogo.
Las tablas de propiedades salen del contrato (contract.json), así que sus nombres, valores por defecto y números son
los que la app hace cumplir; kino.d.ts le da tipo a cada nodo (KinoScreenNode). Para ver todos los componentes
funcionando, instala el ejemplo galería: una pestaña por grupo,
cada componente en su propia sección con su nombre.
Familias de componentes¶
El catálogo se reparte en tres páginas:
| Página | Familias | Componentes |
|---|---|---|
| Esta página | Diseño, Contenido, Acciones | Column · Row · Fila de doce columnas · Stack · Hijos posicionados · Spacer y SizedBox · Divider · Scroll · GridView · ListView · TabBar · ExpansionTile · steps · Card · Scaffold (AppBar, NavigationBar) · PageView · pages · ListTile · Text · Escala de texto · Colores · Image · Icon (nombres) · Badge · CircleAvatar · MaterialBanner · Barra de progreso · Indicador de carga · Skeleton · QrImage (cuenta regresiva) · DataTable (TableRow, TableCell) · emptyState · errorState · titleCard · titleRail · titleGrid · heroCard · Acciones y eventos · Botones (pulsaciones lentas) · FloatingActionButton · Tooltip · Chips · Toasts · Operaciones ui locales |
| Formularios, ventanas y navegación | Formularios, Ventanas emergentes, Navegación | Form, TextField (campos secretos, varias líneas), DropdownButton, RadioGroup, Checkbox, Switch, Slider, NumberStepper, el foco en la TV, validación, patrones, reglas de envío, el nodo de ajustes, bind y config; Dialog, Sheet, Menu, ventanas declaradas y onClose; cada go.* y las rutas |
| Datos, comportamiento y recetas | Datos y comportamiento, Recetas | Estado, entradas, eventos, respuestas, temporizadores, valores por tamaño, nombres al estilo Flutter, estilo, propiedades comunes, compartidas, de caja y de texto, animaciones, tokens, límites; recetas (rejilla de noticias, formulario de ajustes, confirmación, pestañas con chips, matriz de botones, barra de app con pestañas y botón flotante) |
Para empezar¶
Un plugin con pantalla es un manifiesto con la capacidad screen y dos exports. Este muestra una tarjeta con una imagen,
un título y un botón; el evento del botón responde un parche de estado, y Kino vuelve a dibujar la pantalla.
kino-plugin.json:
{
"id": "hello-card",
"name": "Tarjeta",
"version": "1.0.0",
"apiVersion": 14,
"entry": "plugin.js",
"hosts": ["kinotvapp.github.io"],
"capabilities": ["screen"],
"screen": { "label": "Tarjeta", "labelEn": "Card", "icon": "star", "menuOpens": "screen" }
}
plugin.js:
export async function screen({ state }) {
const liked = state.liked === true;
return { type: "SingleChildScrollView", children: [{ type: "Column", padding: 16, gap: 12, children: [
{ type: "Card", key: "film", flush: true, children: [
{ type: "Image", url: "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg", aspect: "16:9", alt: "Big Buck Bunny" },
{ type: "Column", padding: 12, gap: 8, children: [
{ type: "Text", text: "Big Buck Bunny", style: "h3" },
{ type: "Text", text: liked ? "Te gusta" : "Una película libre de 2008", textEn: liked ? "You like it" : "A free film from 2008", color: "muted" },
{ type: "ElevatedButton", key: "like", icon: "heart", labelText: "Me gusta", labelTextEn: "Like", onPressed: "like", enabled: !liked },
] },
] },
] }] };
}
export async function screenEvent({ name }) {
return name === "like" ? { state: { liked: true }, toast: "¡Gracias!", toastEn: "Thanks!" } : null;
}
Pruébalo con el kit antes de usar un aparato (Probar en local): node sdk/validate.mjs <carpeta>,
node sdk/run.mjs <carpeta> screen, node sdk/run.mjs --device tv <carpeta> screen y
node sdk/run.mjs --state '{}' <carpeta> screenEvent like.
Cómo leer esta página¶
- Nombres. Cada sección lleva el nombre al estilo Flutter que usa esta página (
Column,TextField...); el nombre antiguo en minúsculas que Kino lee por dentro (col,textInput...) también se acepta, y las líneas de registro del kit lo usan. Ver Nombres al estilo Flutter. - Tablas de propiedades. Por defecto es lo que Kino usa cuando omites la propiedad; Por tamaño dice si la
propiedad acepta un mapa por tamaño
{ compact, medium, expanded }(Valores por tamaño). Todo nodo acepta además las propiedades comunes y el estilo, que no se repiten. - La validación nunca se cae. Un valor equivocado, un tipo desconocido o una propiedad fuera de lugar se descarta con
una línea de registro y el resto se dibuja. Corre
node sdk/run.mjs <carpeta> screen: se imprime todo lo descartado. - Imágenes. Cuando una sección muestra dos capturas, son el dibujo real del ejemplo galería, en un celular y en una TV.
Diseño¶
Los contenedores colocan a sus hijos; ninguno dibuja nada propio salvo Card, Divider y las pestañas. El lienzo no se
desplaza solo: pon una página larga en un SingleChildScrollView o en un ListView.
Column¶
Hijos uno debajo de otro: la columna vertebral de casi toda pantalla. gap los separa, crossAxisAlignment los coloca
a lo ancho (stretch hace a cada uno tan ancho como la columna) y mainAxisAlignment a lo alto. Un hijo con flex
toma su parte de la altura que sobra.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos[] | ninguno | no | sus hijos, dibujados en orden |
{ "type": "Column", "gap": 8, "crossAxisAlignment": "stretch", "children": [
{ "type": "Text", "text": "Primero", "textEn": "First" },
{ "type": "Text", "text": "Segundo", "textEn": "Second" }
] }
export async function screen() {
const lines = ["Primero", "Segundo", "Tercero"];
return { type: "Column", gap: 8, padding: 16, children: lines.map((text) => ({ type: "Text", text })) };
}
- TV: el foco baja y sube por los hijos enfocables de la columna, hacia el borde más cercano del vecino.
- Celular y TV: el mismo diseño; usa
paddingygappor tamaño para la pantalla grande. - Límites y errores: una
Columnraíz más alta que la ventana se corta, no se desplaza. La profundidad cuenta: como mucho 10 niveles de anidación en un árbol.
Row¶
Hijos uno al lado del otro. flex reparte el ancho (flex: 1 y flex: 2 toman un tercio y dos tercios),
mainAxisAlignment los distribuye (spaceBetween, spaceAround), crossAxisAlignment los alinea en la altura de la
fila. Con stackOnNarrow la fila se vuelve columna en un ancho compacto; con wrap: true es el
diseño de doce columnas.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos[] | ninguno | no | sus hijos, dibujados en orden |
wrap |
boolean | false |
sí | true: el diseño de doce columnas, los hijos colocados por span y offset en líneas de 12 columnas (Fila de doce columnas) |
stackOnNarrow |
boolean | false |
sí | en un ancho compacto los hijos se apilan como una columna; se ignora con wrap |
{ "type": "Row", "gap": 8, "stackOnNarrow": true, "children": [
{ "type": "Card", "flex": 1, "children": [{ "type": "Text", "text": "Uno", "textEn": "One" }] },
{ "type": "Card", "flex": 2, "children": [{ "type": "Text", "text": "Dos", "textEn": "Two" }] }
] }
export async function screen() {
const box = (text, flex) => ({ type: "Card", flex, children: [{ type: "Text", text }] });
return { type: "Row", gap: 8, mainAxisAlignment: "spaceBetween", children: [box("A", 1), box("B", 2)] };
}
- TV: Izquierda y Derecha pasan entre los hijos enfocables de la fila, incluido un
TabBaro unosChipsdentro de ella (Derecha desde su última pestaña llega al control que sigue). En la TV, mantén las filas cortas. - Celular y TV:
stackOnNarrowsolo cambia los anchos compactos (un celular en vertical); una TV esexpanded. - Límites y errores:
stretchen una fila normal se dibuja comostart(una fila no tiene una altura propia a la cual estirarse);flexva de 1 a 12;spanyoffsetno significan nada aquí (solo conwrap).
Fila de doce columnas (wrap: true)¶
La rejilla de Bootstrap dentro de Kino: una Row con wrap: true pone a sus hijos en líneas de 12 columnas. Cada hijo
toma su span (de 1 a 12, o "auto", el valor por defecto) después de su offset; un hijo que no cabe en lo que queda
de la línea empieza la siguiente. Un botón, Badge o Icon en "auto" nunca es más angosto que su etiqueta: cuando no
cabe empieza la línea siguiente, y los "auto" de una línea se reparten lo que queda sin bajar de su propio ancho. Con
spans por tamaño es col-12 col-md-6 col-lg-4: una tarjeta por línea en un celular, dos en una ventana mediana, tres en
una TV. gap va entre celdas y entre líneas.

{ "type": "Row", "wrap": true, "gap": 12, "children": [
{ "type": "Card", "key": "a", "span": { "compact": 12, "medium": 6, "expanded": 4 }, "children": [{ "type": "Text", "text": "A" }] },
{ "type": "Card", "key": "b", "span": { "compact": 12, "medium": 6, "expanded": 4 }, "children": [{ "type": "Text", "text": "B" }] },
{ "type": "Card", "key": "c", "span": 4, "offset": 4, "children": [{ "type": "Text", "text": "C" }] }
] }
export async function screen() {
const cards = ["Uno", "Dos", "Tres", "Cuatro"].map((text, i) => ({
type: "Card", key: "card" + i, span: { compact: 12, medium: 6, expanded: 4 }, children: [{ type: "Text", text }],
}));
return { type: "SingleChildScrollView", children: [{ type: "Row", wrap: true, gap: 12, padding: 16, children: cards }] };
}
- TV: la rejilla retiene Izquierda y Derecha dentro de sí (nunca se escapan después de la última celda); Abajo y Arriba van a la celda más cercana de la línea siguiente, así una matriz de botones conserva sus columnas (ver la receta de la matriz de botones).
- Celular y TV: una línea es tan alta como su celda más alta y, por defecto, cada
Cardo celda contenedora sinwidth/heightfijos se dibuja con esa altura, así una rejilla de tarjetas queda pareja;crossAxisAlignmentstart,centeroenddeja a cada una con su propia altura. Dentro de un desplazamiento lateral, las doce columnas se reparten sobre 600 dp. - Límites y errores:
flex,mainAxisAlignmentystackOnNarrowno significan nada en una fila que envuelve; un hijo toma su ancho natural salvo confill: true.spanyoffseten cualquier otro lugar se ignoran (con registro). Una línea que contiene algo que no se puede medir (una lista perezosa, un riel, pestañas, una tabla, el formulario de ajustes) no se estira. Un hijo oculto no deja hueco.offsetse reduce cuando no le dejaría espacio al span (con registro).
Stack¶
Hijos uno encima del otro, el primero al fondo: una insignia sobre una imagen, una etiqueta sobre un banner. Un hijo sin
positioned empieza en la esquina superior inicial; usa margin y padding para moverlo.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos (uno encima del otro, el primero al fondo)[] | ninguno | no | sus hijos, dibujados en orden |
{ "type": "Stack", "children": [
{ "type": "Image", "url": "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg", "aspect": "banner", "alt": "Big Buck Bunny" },
{ "type": "Badge", "text": "Nuevo", "textEn": "New", "margin": 8 }
] }
export async function screen() {
return { type: "Stack", children: [
{ type: "Image", url: "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg", aspect: "banner", alt: "Big Buck Bunny" },
{ type: "Badge", text: "4K", margin: 8 },
] };
}
- TV: solo un hijo enfocable toma el foco; el stack mismo lo toma cuando tiene un
onTap. - Celular y TV: igual.
- Límites y errores: no hay
alignSelf; unStackes una celda contenedora en una fila de doce columnas (se estira a su línea).
Hijos posicionados (Stack)¶
El Positioned de Flutter, como propiedad de estilo de un hijo de un Stack: positioned: { top?, left?, right?,
bottom?, width?, height? }, cada uno un número de dp (de 0 a 1280, recortado) o una parte del stack escrita "25%" (de
0% a 100%). Con left y right (o top y bottom) el hijo toma el espacio entre ambos; un width (height) dado
además se ignora, con registro. Un hijo sin positioned conserva la alineación del stack y le da su tamaño; un stack
cuyos hijos están todos posicionados toma el ancho que se le ofrece y su propio height (o minHeight; sin ninguno
mide 0 de alto: dale uno). Los hijos se dibujan en su orden (uno posterior encima de uno anterior) y el foco los recorre
en ese orden; todo se recorta al stack y se mantiene dentro de él, así que nada se pulsa fuera de él. En cualquier otro
nodo positioned se ignora, con registro. Acepta valores por tamaño como toda propiedad de estilo.
{ "type": "Stack", "height": 200, "children": [
{ "type": "Image", "url": "https://img.example.com/cover.jpg", "fill": true, "height": 200 },
{ "type": "Badge", "text": "EN VIVO", "textEn": "LIVE", "color": "error", "positioned": { "top": 8, "right": 8 } },
{ "type": "Text", "text": "Final de la copa", "textEn": "Cup final", "style": "h4", "positioned": { "left": 12, "right": 12, "bottom": 12 } }
] }
Spacer y SizedBox¶
Espacio vacío. SizedBox es una caja vacía de su width y height (en la escala de tamaños); Spacer es una caja
vacía que toma su parte flex de una Row o una Column, empujando lo que sigue hasta el final. Los dos son el mismo
nodo antiguo, spacer.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
| (ninguna) | SizedBox es una caja vacía de su width/height; Spacer toma su parte flex de una Row o una Column |
{ "type": "Row", "children": [
{ "type": "Text", "text": "A" },
{ "type": "SizedBox", "width": 48 },
{ "type": "Text", "text": "B" },
{ "type": "Spacer", "flex": 1 },
{ "type": "Text", "text": "C" }
] }
export async function screen() {
return { type: "Row", children: [{ type: "Text", text: "Título" }, { type: "Spacer", flex: 1 }, { type: "Badge", text: "3" }] };
}
- TV: nunca recibe el foco.
- Celular y TV: igual; prefiere
gapen el padre a poner espaciadores entre cada hijo. - Límites y errores:
widthyheightsolo aceptan la escala de tamaños (de 16 a 640); un valor fuera de ella descarta el nodo.
Deslizar: onSwipeLeft y onSwipeRight¶
Cualquier nodo puede responder a un deslizamiento lateral con una acción cada uno (las mismas formas que onTap). La dirección es la del dedo: deslizar a la izquierda es «la página siguiente» y a la derecha «la anterior» (el giro propio del nodo pages sigue la misma regla). Cuenta un arrastre de al menos 64 dp; un desplazamiento vertical nunca se lee como deslizamiento, y un nodo que se desplaza de lado conserva su propio desplazamiento.
En la TV no hay dedo: onSwipeLeft responde a Derecha y onSwipeRight a Izquierda, pero solo cuando el foco ya no tiene a dónde ir en esa dirección, así que el control remoto sigue moviéndose primero entre botones. Deja un botón para el mismo paso (el deslizamiento es un atajo, no la única vía: un Kino anterior ignora ambas propiedades y un lector de pantalla usa los botones).
export async function screen({ state }) {
const page = state.page ?? 0;
return { type: "Column", key: "reader", flex: 1, onSwipeLeft: "next", onSwipeRight: "prev",
children: [{ type: "Text", text: state.pages[page] }, { type: "Row", children: [
{ type: "IconButton", icon: "arrow_back", labelText: "Anterior", onPressed: "prev" },
{ type: "IconButton", icon: "arrow_forward", labelText: "Siguiente", onPressed: "next" } ] }] };
}
Divider¶
Una raya fina a lo ancho de su padre: entre grupos de una columna, bajo un encabezado.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
| (ninguna) | una raya fina a lo ancho de su padre |
{ "type": "Column", "gap": 8, "children": [
{ "type": "Text", "text": "Arriba", "textEn": "Above" },
{ "type": "Divider" },
{ "type": "Text", "text": "Abajo", "textEn": "Below" }
] }
export async function screen() {
return { type: "Column", gap: 8, children: [{ type: "Text", text: "Uno" }, { type: "Divider" }, { type: "Text", text: "Dos" }] };
}
- TV: nunca recibe el foco. Celular y TV: igual. Errores: un divider en una
Rowno dibuja nada útil (es horizontal).
Scroll (SingleChildScrollView)¶
Sus hijos, con desplazamiento: vertical (por defecto) para una página larga, horizontal para una tira de chips o
insignias. La mayoría de las pantallas ponen todo lo que va bajo las partes fijas (un TabBar) en un solo desplazamiento
vertical con flex: 1.

Un lector (manga, webtoon, cómic, un artículo largo) suma dos cosas: zoom (pellizcar, doble toque y arrastrar; el contenido
se dibuja más ancho, así una imagen con fit: "width" se ve nítida y más alta) y onScroll (dónde se detuvo la persona, de 0
a 1, para mostrar «42 %» o guardar el punto). Las dos son aditivas: sin apiVersion nuevo, un Kino más antiguo las ignora.
Mira la receta Un lector.
{ "type": "SingleChildScrollView", "key": "chapter", "flex": 1, "zoom": true, "onScroll": "scrolled",
"children": [{ "type": "Image", "url": "https://example.com/p1.jpg", "fit": "width" }] }
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos[] | ninguno | no | sus hijos, dibujados en orden |
direction |
vertical | horizontal |
vertical |
sí | un ListView o un riel dentro de un desplazamiento de la misma dirección se dibuja todo de una vez |
zoom |
true | { max } |
ninguno | sí | un desplazamiento vertical que la persona puede ampliar pellizcando o con doble toque (hasta 4x, o max de 1,5 a 8) y arrastrar una vez ampliado; el contenido se dibuja más ancho, así una imagen con fit: "width" se ve nítida; se ignora en un desplazamiento lateral |
onScroll |
acción | ninguno | no | el value de su evento es la posición en la que se quedó, de 0 (arriba) a 1 (final), enviada 0,3 s después de que la persona deja de desplazar; un desplazamiento vertical que se desplaza solo |
{ "type": "Column", "children": [
{ "type": "TabBar", "key": "tabs", "tabs": [{ "value": "a", "label": "Uno", "labelEn": "One" }, { "value": "b", "label": "Dos", "labelEn": "Two" }], "onChanged": "tab" },
{ "type": "SingleChildScrollView", "flex": 1, "children": [{ "type": "Column", "padding": 16, "gap": 12, "children": [
{ "type": "Text", "text": "Una página larga", "textEn": "A long page" }
] }] }
] }
export async function screen() {
const badges = ["Acción", "Drama", "Comedia", "Terror"].map((text) => ({ type: "Badge", text }));
return { type: "SingleChildScrollView", direction: "horizontal", children: [{ type: "Row", gap: 8, children: badges }] };
}
- TV: el desplazamiento sigue al foco: pasar a un nodo fuera de pantalla lo trae a la vista, desplazando solo lo
necesario (con un pequeño margen); un nodo que ya está a la vista nunca mete el resto bajo un encabezado. Arriba
(Abajo) solo lleva el foco a un enfocable que ya se ve en esa dirección; cuando todavía no se ve ninguno, el
Scrollse desplaza un 80% de su altura en su lugar, pulsación tras pulsación, hasta que aparece uno (y la siguiente pulsación va ahí) o se llega a su inicio (final). Así un bloque sin nada enfocable (una tarjeta de estado, un pie de texto, una tabla) entre dos enfocables, encima del primero o debajo del último siempre se lee de paso, nunca se salta sin verlo; donde el siguiente enfocable está en pantalla (una lista densa) el foco se mueve enseguida, sin paginar. Solo en el inicio (final) la tecla sale delScroll: en el cuerpo de unScaffold, Arriba llega entonces a la pestaña elegida delAppBar; Abajo al final no hace nada (nunca da la vuelta hasta arriba). Abajo desde elAppBarsiempre entra al cuerpo: su enfocable más cercano toma el foco y se desplaza a la vista, donde sea que el cuerpo haya quedado; un cuerpo sin nada enfocable (texto, tarjetas, tablas) pagina en su lugar. Una pulsación siempre desplaza o mueve el foco, hasta que no queda nada en esa dirección. Lo mismo en el cuerpo de un panel del reproductor. Un bloque en el que el control remoto debería detenerse puede decirlo concanRequestFocus: true. - Celular y TV: arrastrar con el dedo en el celular; el D-pad en la TV.
- Límites y errores: un
ListViewo un riel dentro de un desplazamiento de la misma dirección se dibuja todo de una vez (sin carga perezosa) y con un tope de 60 títulos; una celda de tabla nunca contiene un desplazamiento.
GridView¶
Sus hijos en columns iguales, llenadas fila por fila: una rejilla de mosaicos pequeños donde cada celda tiene el mismo
ancho. Para tarjetas cuya cantidad cambia según el tamaño, prefiere la fila de doce columnas o columns por
tamaño.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos[] | ninguno | no | sus hijos, dibujados en orden |
columns |
de 1 a 8 | 2 |
sí | columnas iguales, llenadas fila por fila |
{ "type": "GridView", "columns": { "compact": 2, "medium": 3, "expanded": 4 }, "gap": 8, "children": [
{ "type": "Card", "children": [{ "type": "Text", "text": "1" }] },
{ "type": "Card", "children": [{ "type": "Text", "text": "2" }] },
{ "type": "Card", "children": [{ "type": "Text", "text": "3" }] }
] }
export async function screen() {
const tiles = Array.from({ length: 8 }, (_, i) => ({ type: "Card", children: [{ type: "Text", text: String(i + 1) }] }));
return { type: "GridView", columns: { compact: 2, expanded: 4 }, gap: 8, children: tiles };
}
- TV: el D-pad se mueve celda por celda. Celular y TV:
columnspor tamaño es la forma habitual de que quepa en los dos. - Límites y errores:
columnsde 1 a 8; unGridViewno es perezoso: para cientos de elementos usa unListViewconcolumns.
ListView¶
Una lista perezosa de items (nodos), dibujados a medida que entran en la vista: la forma de mostrar feeds largos.
empty es lo que se muestra cuando no hay elementos; columns la convierte en rejilla; onEndReached le pide más a tu
plugin.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
items |
nodos[] | ninguno | no | como mucho 500, cada uno con su propia key; dibujados de forma perezosa |
empty |
nodo | ninguno | no | se dibuja cuando no hay elementos |
columns |
de 1 a 8 | 1 |
sí | una rejilla de elementos |
stickToBottom |
boolean | false |
sí | abre en el último elemento y sigue a los nuevos mientras la persona está al final; una columna, en una lista que se desplaza sola (layout fill) |
newItemsHint |
boolean | false |
no | los elementos que se agregan mientras la persona lee más arriba muestran el chip propio de Kino «↓ Nuevos» (su texto, nunca el tuyo); un toque va al final (elementos nuevos) |
onEndReached |
{ event, arg? } |
ninguno | no | se envía una vez cuando el último elemento entra en la vista, y de nuevo solo después de que tu respuesta dibujó una lista más larga (o loadingMore pasó de true a false); nunca más de una vez por segundo |
loadingMore |
boolean | false |
no | true dibuja el indicador de carga de Kino después de los elementos |
done |
boolean | false |
no | true deja de pedir más |
{ "type": "ListView", "key": "feed", "onEndReached": { "event": "more" }, "loadingMore": false, "done": false,
"empty": { "type": "emptyState", "title": "Sin elementos", "titleEn": "No items" },
"items": [
{ "type": "Text", "key": "i1", "text": "Elemento 1", "textEn": "Item 1" },
{ "type": "Text", "key": "i2", "text": "Elemento 2", "textEn": "Item 2" }
] }
export async function screen({ state }) {
const n = Number.isInteger(state.count) ? state.count : 10;
const items = Array.from({ length: n }, (_, i) => ({ type: "Text", key: "row" + i, text: "Elemento " + (i + 1) }));
return { type: "ListView", key: "feed", items, onEndReached: { event: "more" }, loadingMore: state.loading === true, done: n >= 100 };
}
export async function screenEvent({ name, state }) {
if (name === "more") return { state: { count: Math.min(100, (state.count || 10) + 10) } };
return null;
}
- TV:
onEndReachedse dispara cuando el último elemento entra en la vista, igual que en el celular. - Celular y TV: la misma lista perezosa. Con
stickToBottom: trueabre en su último elemento y un nuevo último elemento se desplaza a la vista mientras la persona está al final (o a un elemento de él); cuando sube, la lista se queda quieta hasta que vuelve a bajar (un chat: ver el layout fill del panel del reproductor). Necesita una lista que se desplace sola: una columna, en una pantalla completa o en un panel conlayout: "fill". Dibujada plana (el diseño con desplazamiento por defecto de un panel, dentro de unSingleChildScrollView) no hace nada, con un registro una sola vez. - Límites y errores: 500 elementos; cada uno necesita su propia
key.onEndReachedvuelve a llegar solo después de que tu respuesta dibujó una lista más larga oloadingMorepasó de true a false, como mucho una vez por segundo, nunca mientras la pantalla está oculta. Un temporizador que apagaloadingMoreen cada tic sin nada nuevo hace que Kino pida una vez por tic.
Elementos nuevos (newItemsHint)¶
Con newItemsHint: true, los elementos que se agregan mientras la persona lee más arriba (el antiguo último elemento
sigue en la lista) muestran un chip pequeño propio de Kino sobre la parte baja de la lista, «↓ Nuevos» / «↓ New»: texto
de Kino, nunca el tuyo. Un toque va al final y el chip se oculta en cuanto se ve el final. Junto a stickToBottom el
chip solo aparece cuando la persona subió: al final la lista sigue al elemento nuevo por sí sola. Necesita una lista que
se desplace sola (una columna); una rejilla o una lista plana no dibuja chip.
{ "type": "ListView", "key": "chat", "flex": 1, "stickToBottom": true, "newItemsHint": true,
"items": [{ "type": "Text", "key": "m1", "text": "Hola", "textEn": "Hi" }] }
- TV: el chip es una parada de foco: Abajo desde la zona de la lista (una lista cuyos elementos no toman foco retiene el foco ella misma) llega a él antes que a los controles bajo la lista; OK va al final.
TabBar¶
Una fila de pestañas: el selector principal de una pantalla con varias partes. No es una entrada: su valor no está
en state.inputs. Guarda la pestaña elegida en tu propio estado desde su evento onChanged, y dibuja el cuerpo que le
corresponde.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
tabs |
{ value, label, labelEn?, badge? }[] |
obligatorio | no | de 1 a 500; el badge de una pestaña va junto a su etiqueta (propiedades compartidas) |
value |
string | la primera pestaña | no | la pestaña elegida; NO está en state.inputs: guárdala en tu estado desde onChanged |
onChanged |
acción | ninguno | no | el value de su evento es el valor de la pestaña |
divider |
boolean | true |
no | aditivo, sin apiVersion nuevo: false quita la línea bajo las pestañas |
En la TV las pestañas son texto con una línea bajo la elegida (no píldoras).
{ "type": "TabBar", "key": "section", "value": "news", "onChanged": "tab", "tabs": [
{ "value": "news", "label": "Noticias", "labelEn": "News" },
{ "value": "config", "label": "Configuración", "labelEn": "Settings" }
] }
export async function screen({ state }) {
const tab = state.tab === "config" ? "config" : "news";
return { type: "Column", children: [
{ type: "TabBar", key: "section", value: tab, onChanged: "tab", tabs: [{ value: "news", label: "Noticias" }, { value: "config", label: "Ajustes" }] },
{ type: "Text", text: tab === "news" ? "Las noticias" : "Los ajustes", padding: 16 },
] };
}
export async function screenEvent({ name, value }) {
return name === "tab" ? { state: { tab: value } } : null;
}
- TV: Izquierda y Derecha recorren las pestañas; al final de la barra siguen al próximo enfocable a su lado en la
misma fila (un
IconButtonde actualizar después de las pestañas), y si no hay nada ahí se quedan en la barra, nunca saltan a otra fila ni a la barra de título de Kino. Al entrar en la barra, desde arriba, abajo o el costado, se llega a la pestaña elegida. Lo mismo paraChips. - Celular y TV: un cuerpo bajo el primer
TabBarde la pantalla (en cualquier parte: también unaRowde encabezado) que sea unScroll, unListViewo una rejilla de títulos con unakeytuya conserva su desplazamiento por pestaña: con una key por pestaña (newsBody,settingsBody) o no, al volver a una pestaña está donde la persona la dejó. - Celular y TV: una fila de pestañas en los dos.
- Límites y errores: leer
state.inputs.<key>de una pestaña no da nada; unTabBarsin ninguna pestaña válida se descarta.
ExpansionTile (acordeón)¶
Secciones que se abren y se cierran: preguntas frecuentes, opciones avanzadas. Abrir y cerrar lo hace Kino (sin llamar a
tu plugin); qué elementos están abiertos vive en state.ui.open.<key>, así que sobrevive a un nuevo dibujo. Uno a la vez
salvo con multiple.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
key |
string | obligatorio | no | qué elementos están abiertos vive en state.ui.open.<key> |
items |
{ key, title, titleEn?, children?, open? }[] |
obligatorio | no | de 1 a 500; open es solo el primer vistazo |
multiple |
boolean | false |
no | varios elementos abiertos a la vez |
{ "type": "ExpansionTile", "key": "faq", "items": [
{ "key": "what", "title": "¿Qué es?", "titleEn": "What is it?", "open": true, "children": [{ "type": "Text", "text": "Una sección.", "textEn": "A section." }] },
{ "key": "how", "title": "¿Cómo funciona?", "titleEn": "How does it work?", "children": [{ "type": "Text", "text": "Se abre y se cierra.", "textEn": "It opens and closes." }] }
] }
export async function screen() {
const faq = [["what", "¿Qué es?", "Una galería."], ["who", "¿Quién la dibuja?", "Kino."]];
return { type: "ExpansionTile", key: "faq", items: faq.map(([key, title, text]) => ({ key, title, children: [{ type: "Text", text }] })) };
}
- TV: cada encabezado toma el foco y OK lo abre o lo cierra; Abajo desde un encabezado abierto entra a su contenido.
- Celular y TV: el mismo componente.
- Límites y errores:
keyes obligatoria; elementos de 1 a 500 con keys distintas; cada encabezado cuesta un nodo de los 600, y cuando se acaba el presupuesto el acordeón conserva menos elementos. Nunca en la ventana emergente de una respuesta. Un campo obligatorio en un elemento cerrado no impide el envío de un formulario, pero el envío abre el elemento cuando falla.
steps¶
Un flujo de configuración con el aspecto propio de Kino, para cualquier plugin con pasos que recorrer (iniciar sesión,
un código, una contraseña, listo): cada paso es un encabezado con el círculo numerado de Kino (una marca cuando está
hecho). El paso current está abierto, con sus children dibujados debajo (un Form con un TextField enmascarado, un
QrImage...); un paso done se pliega a su subtitle (o al «Listo» de Kino); uno pending se ve atenuado. Con
onStepTap un paso hecho se puede pulsar, para que la persona vuelva a él.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
items |
{ key, title, titleEn?, subtitle?, subtitleEn?, state, children? }[] |
obligatorio | no | de 1 a 12; state done, current, pending; exactamente un current (sus hijos se dibujan debajo); uno done muestra su subtitle (si no, el «Listo» de Kino) |
onStepTap |
nombre de evento o { event } |
ninguno | no | un paso done se puede pulsar (con el dedo, o con OK en la TV): el evento va con la key del paso como arg |
{ "type": "steps", "key": "login", "onStepTap": "goBack", "items": [
{ "key": "phone", "title": "Tu número", "titleEn": "Your number", "subtitle": "+57 300 •••• 12", "state": "done" },
{ "key": "code", "title": "Código", "titleEn": "Code", "state": "current", "children": [
{ "type": "Form", "key": "codeForm", "onSubmitted": "checkCode", "children": [
{ "type": "TextField", "key": "code", "kind": "number", "labelText": "Código", "required": true, "minLength": 5 },
{ "type": "ElevatedButton", "labelText": "Siguiente", "labelTextEn": "Next", "submit": true }
] }
] },
{ "key": "twofa", "title": "Contraseña", "titleEn": "Password", "state": "pending" }
] }
export async function screenEvent({ name, arg, state }) {
if (name === "goBack") return { state: { step: arg } }; // arg: the done step's key
if (name === "checkCode") return { state: { step: "twofa" } };
return null;
}
- Celular y TV: el mismo flujo. En la TV solo toman el foco un paso hecho que se puede pulsar y los campos propios del
paso actual: Abajo desde un paso hecho entra al paso abierto; OK en un paso hecho envía
onStepTap. Un lector de pantalla lee cada encabezado como «Paso 2 de 3: Código, actual». - Límites y errores: de 1 a 12 pasos, cada uno con una
keyválida y distinta y untitle. Exactamente uncurrent: si no hay ninguno mientras queda un paso por hacer, el primero no hecho pasa a ser el actual; si hay dos, se queda el primero; unstatedesconocido se lee comopending; los hijos de un paso que no es el actual no se dibujan (todo con registro). Cada encabezado cuenta como un nodo del presupuesto del árbol; los hijos del paso abierto quedan un nivel por debajo del nodo.
Card¶
La tarjeta de Kino alrededor de sus hijos: plain (por defecto), outlined o filled. Con flush: true la tarjeta no
tiene relleno propio y recorta a sus hijos a su forma redondeada, así una Image en su parte de arriba llega de borde a
borde (el relleno del texto lo pones tú). Una tarjeta con onTap es entera un objetivo de pulsación.
Los contenedores llevan su propio relleno: un solo valor en todos los lados, los hijos no agregan nada. Sin un
padding tuyo, una tarjeta deja 16 dp en cada lado de su contenido (24 en la TV) y a sus hijos a 8 dp entre sí (12 en la
TV); un padding o un gap que declares gana.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos[] | ninguno | no | sus hijos, dibujados en orden |
variant |
plain | outlined | filled |
plain |
sí | los tres aspectos de tarjeta de Kino |
flush |
boolean | false |
sí | sin relleno propio y con sus hijos recortados a su forma redondeada: una Image en su parte de arriba llega de borde a borde |
{ "type": "Card", "key": "story", "flush": true, "onTap": { "event": "read", "arg": "story-1" }, "children": [
{ "type": "Image", "url": "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg", "aspect": "16:9", "alt": "Big Buck Bunny" },
{ "type": "Column", "padding": 12, "gap": 4, "children": [
{ "type": "Text", "text": "Un titular", "textEn": "A headline", "style": "h4", "maxLines": 3 },
{ "type": "Text", "text": "La fuente", "textEn": "The source", "style": "caption", "color": "muted" }
] }
] }
export async function screen() {
const card = (variant) => ({ type: "Card", variant, children: [{ type: "Text", text: variant }] });
return { type: "Column", gap: 8, padding: 16, children: [card("plain"), card("outlined"), card("filled")] };
}
- TV: una tarjeta con una acción toma el foco con el anillo de Kino; una sin acción se salta.
- Celular y TV: el mismo aspecto;
flushrecorta en los dos. - Límites y errores: con
flushno se usa elpaddingpropio de la tarjeta: ponle relleno a sus hijos de texto. Una tarjeta es una celda contenedora en una fila de doce columnas: se estira a la altura de su línea salvo que tenga unheightfijo.
Scaffold¶
El Scaffold de Flutter: la raíz de una pantalla o de un panel del reproductor con un appBar fijo arriba de tu zona,
un body en la altura que queda, y un floatingActionButton sobre un bottomNavigationBar abajo. Solo como raíz de un
resultado (uno anidado se descarta, con registro); un resultado cuya raíz es un Scaffold se dibuja en
layout: "fill" sin pedirlo (otro layout se ignora, con registro). Su cuerpo tiene límites: un ListView o un
SingleChildScrollView dentro de él se desplaza solo mientras las barras se quedan quietas, y el teclado encoge el
cuerpo, nunca las barras. Un cuerpo con desplazamiento deja espacio bajo su última línea (16 dp, 24 en la TV), así el
final de un texto largo nunca se corta en el borde de la ventana; en la TV, Abajo sin nada más que enfocar pagina el
cuerpo (también el texto de un ExpansionTile abierto) y, en su final, se queda quieto.
La barra de título propia de Kino se queda. Sobre cada pantalla de plugin Kino dibuja la barra con el nombre de tu
plugin y Cerrar (una X sola; un lector de pantalla dice «Cerrar», «Close» en inglés); el AppBar de un Scaffold va
debajo, dentro de tu zona, y nunca la reemplaza ni la tapa (la persona siempre sabe de quién es la pantalla y cómo
salir). En un panel del reproductor el AppBar es compacto (una fila de 48 dp). La barra lleva un solo relleno en todos
los lados (16 dp; 24 en la TV, 16 en un panel) alrededor de su fila de título y de su TabBar bottom juntos, así la
primera pestaña queda alineada con el título y nada toca los bordes de la barra; una línea finísima marca su borde de
abajo, así el cuerpo que se desplaza debajo nunca se confunde con ella. En la TV el D-pad va del leading y las
actions del AppBar al cuerpo, luego a la barra de abajo y al botón; Arriba desde la primera parada del cuerpo llega
al TabBar bottom de la barra en su pestaña elegida (sin bottom, a su última acción), nunca más allá, al Cerrar de
Kino; mientras el cuerpo todavía puede subir, Arriba primero lo pagina. Derecha después de la última pestaña llega a las
acciones de la barra en orden (Izquierda antes de la primera pestaña, a su leading), Abajo desde una acción vuelve a
las pestañas, y Abajo desde las pestañas va al cuerpo. Atrás cierra o regresa como en todas partes. Una excepción a las dos
barras, que tú pides: mergeWithKinoBar las vuelve una sola, y una sola barra compacta es
la configuración recomendada.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
appBar |
un AppBar |
ninguno | no | fijo arriba de tu zona, bajo la barra de título propia de Kino (nunca la reemplaza ni la tapa) |
body |
nodo | obligatorio | no | la altura limitada que queda: un ListView o un desplazamiento dentro de él se desplaza solo mientras las barras se quedan |
floatingActionButton |
un FloatingActionButton |
ninguno | no | sobre la barra de abajo |
bottomNavigationBar |
un NavigationBar |
ninguno | no | abajo |
onBack |
acción | ninguno | no | apiVersion 19: Atrás te la envía a ti en vez de salir (el PopScope de Flutter con canPop: false); sin go; una llamada que falla o vence, o un segundo Atrás mientras tanto, cierra la pantalla |
onBack es el PopScope de Flutter con canPop: false (apiVersion 19). Mientras la pantalla visible la declara, el
Atrás del sistema (el del celular, el del control de la TV) no cierra la pantalla ni saca una ruta: Kino te envía esa acción
como la pulsación de la persona (las mismas formas que onPressed: "event", { event, arg } o { ui: [...], event },
nunca un go) y respondes como siempre. Cuando el siguiente Atrás deba salir, tu siguiente árbol simplemente no declara
onBack. Nunca deja atrapada a la persona: una ventana abierta se cierra primero; una ruta apilada cuya raíz la declara
recibe el Atrás en vez de sacarse; si la llamada falla, vence o su respuesta no es válida, la pantalla se cierra; un segundo
Atrás mientras la primera llamada sigue en curso también la cierra; el Cerrar propio de Kino no cambia. Un panel del
reproductor no tiene un Atrás que retener y la ignora (con registro). Mira la receta
Una vista de búsqueda que Atrás cierra primero.
Ver la receta Una pantalla con barra de app, pestañas y un botón flotante.
AppBar¶
Solo como appBar de un Scaffold (en cualquier otro lugar se descarta, con registro): una fila con un IconButton
leading, el title (que un lector de pantalla lee como encabezado) y hasta cuatro IconButton en actions (el resto
se descarta, con registro; cada uno necesita un labelText, lo que dice un lector de pantalla, y puede llevar un
badge), y luego un TabBar bottom opcional. backgroundColor es un rol de color, elevation la sombra de Kino. Una
barra sin título es una fila de botones.
title es un string o cualquier nodo (a la manera de Flutter): un string es un Text que se lee como encabezado
(titleEn su gemelo); un nodo (un TabBar, una Row de botones, una Image, un Text con su propio estilo; como
mucho 40 nodos, si no se descarta, con registro; localiza sus textos tú) toma el espacio que queda a la izquierda de las
actions en la misma fila: un TabBar ahí se desplaza de lado cuando no cabe, y en la TV sus pestañas y las acciones
son una sola fila para el D-pad (Derecha después de la última pestaña llega a la primera acción, Arriba desde el cuerpo
cae en la pestaña elegida). bottom se queda para la clásica segunda fila. Ver
Pestañas en la barra de app.
Un logo en lugar del nombre: con mergeWithKinoBar la barra es del plugin, así que una Image como title (un data:image/png;base64,… de tu logo, fit: "contain", h: 32, un aspect el propio de la imagen y un Text como fallback para un Kino que no la pueda leer) pone tu logo donde iba el nombre. Pinta la imagen sobre el color propio de la barra (un PNG opaco): uno transparente deja ver el relleno del tema de la app detrás.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
title |
string o un nodo | ninguno | no | un string (titleEn su gemelo) se lee como encabezado; o, a la manera de Flutter, cualquier nodo (un TabBar, una Row de botones...; como mucho 40 nodos) en el espacio a la izquierda de las acciones |
leading |
un IconButton |
ninguno | no | con un labelText (atrás, un menú) |
actions |
IconButton[] |
ninguno | no | como mucho 4, cada uno con un labelText; se permite un badge |
bottom |
un TabBar |
ninguno | no | bajo la fila |
centerTitle |
boolean | false |
no | el título centrado |
dense |
boolean | false |
no | aditivo, sin apiVersion nuevo: en un celular la barra tiene 4 dp arriba y abajo de su fila en vez de 16 (una TV tiene 8 dp en vez de 24; un panel del reproductor conserva el suyo); también es la barra única de mergeWithKinoBar |
divider |
boolean | true |
no | aditivo, sin apiVersion nuevo: false quita la línea fina del borde inferior de la barra |
backgroundColor |
un rol de color | la superficie de Kino | no | su texto y sus iconos en el color legible del rol |
mergeWithKinoBar |
boolean | false |
no | apiVersion 19, solo el del Scaffold raíz: con un leading, Kino dibuja una sola barra, tu leading en el lugar de Cerrar y tu title en el del nombre de tu plugin |
mergeWithKinoBar (apiVersion 19, opcional, solo en la barra del Scaffold raíz y solo el boolean true): con un
IconButton leading, Kino dibuja UNA barra en vez de dos. Tu leading ocupa el lugar del Cerrar de Kino (su pulsación es
tu acción; su labelText es lo que dice un lector de pantalla), tu title (y titleEn) el lugar del nombre de tu plugin,
tus actions se quedan al final y los botones propios de Kino (la campana del plugin) van después; el nombre de tu plugin
sigue siendo la etiqueta de la barra para un lector de pantalla. Sin un leading la marca se ignora (con registro) y se ven
las dos barras, como en todo plugin que no la usa. La salida de la persona es entonces tu leading y el Atrás del sistema
(que cierra la pantalla cuando onBack no está o falla), así que dale al leading una salida real ({ close: true }, o un
regreso a la vista anterior). En la TV igual, con el leading primero en el orden del D-pad. Un panel del reproductor la
ignora (con registro).
Recomendado: una sola barra compacta¶
De fábrica una pantalla de plugin tiene dos barras: la barra de título propia de Kino (el nombre de tu plugin y Cerrar) y,
debajo, tu AppBar. En un celular son unos 150 dp de encabezado antes de la primera línea de contenido. La configuración
recomendada para cada pantalla de un plugin es una sola barra compacta: mergeWithKinoBar: true (una barra, tu leading
donde estaba Cerrar, tu title donde estaba el nombre del plugin) más dense: true (en un celular, 4 dp arriba y abajo de la
fila en vez de 16: 56 dp en total).
{ "type": "Scaffold",
"appBar": { "type": "AppBar", "mergeWithKinoBar": true, "dense": true, "title": "Catálogo", "titleEn": "Catalog",
"leading": { "type": "IconButton", "icon": "arrow_back", "labelText": "Atrás", "labelTextEn": "Back", "onPressed": { "event": "back" } },
"actions": [{ "type": "IconButton", "icon": "search", "labelText": "Buscar", "labelTextEn": "Search", "onPressed": { "event": "search" } }] },
"body": { "type": "SingleChildScrollView", "children": [] } }
Qué hace cada ventana con esos dos booleanos:
| Dónde | mergeWithKinoBar |
dense |
|---|---|---|
| Celular | una barra: tu leading, tu título, tus acciones y los botones propios de Kino (la campana) al final |
la fila tiene 4 dp arriba y abajo (56 dp) |
| TV | la misma barra única, con tu leading primero en el orden del D-pad |
se ignora: la TV conserva sus 24 dp, el anillo de foco necesita el espacio |
| Panel del reproductor | se ignora (con registro) | se ignora: la barra de un panel ya es una sola fila compacta de 48 dp |
Los dos son booleanos simples, no mapas por tamaño. Para elegir según la ventana, arma el árbol con ctx.device y ctx.size
(la sección de valores por tamaño): por ejemplo la barra unida en todas partes y
dense solo donde ctx.size es compact.
- Dale al
leadinguna salida real en cada pantalla:{ close: true }en la portada, un regreso a la vista anterior en todas las demás. Con las dos barras unidas es la única salida visible además del Atrás del sistema. - Ponlos en cada pantalla del plugin, no solo en una: una portada con dos barras y un detalle con una parece un error.
densesolo cambia el relleno; el título, las acciones y unTabBarbottomse dibujan como siempre.densees aditivo (sinapiVersionnuevo): un Kino que no lo conoce dibuja la barra con su altura normal.
NavigationBar¶
Solo como bottomNavigationBar de un Scaffold (en cualquier otro lugar se descarta, con registro): de 2 a 5 items
({ key, icon, label, labelEn?, badge? }; los de más se descartan, con menos de dos se descarta la barra, ambos con
registro). Un celular dibuja la barra de navegación de Material, una TV una fila inferior de elementos enfocables con el
anillo de Kino. Pulsar otro elemento envía onChanged con la key del elemento como value; como en un TabBar, el
elemento elegido no está en state.inputs: guárdalo en tu estado y dibuja el cuerpo que le corresponde.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
items |
{ key, icon, label, labelEn?, badge? }[] |
obligatorio | no | de 2 a 5, keys distintas |
value |
string | el primer elemento | no | la key del elemento elegido (o selectedIndex); NO está en state.inputs: guárdala en tu estado desde onChanged |
selectedIndex |
entero | ninguno | no | el elemento elegido por su posición, cuando no hay value |
onChanged |
acción | ninguno | no | el value de su evento es la key del elemento |
PageView (y el carrusel)¶
El PageView de Flutter: sus children son páginas, que se deslizan de lado en un celular; en una TV, Izquierda y
Derecha en el borde de una página pasan de página (una página sin nada enfocable deja al paginador mismo como parada).
Kino dibuja los puntos de página debajo y un lector de pantalla oye «Página 2 de 5». onPageChanged envía el índice de
la página en la que se quedó como value; initialPage es solo el primer vistazo (la página a la que llegó la persona
sobrevive a tus nuevos dibujos). autoPlayMs (de 3.000 a 60.000) pasa la página sola, en pausa mientras la persona la
toca o la enfoca y cuando las animaciones del aparato están apagadas. Un viewportFraction menor que 1 es el carrusel
de Kino: las páginas vecinas se asoman a los lados (padEnds: false empieza la primera página en el borde). Nunca
dentro de un desplazamiento lateral ni de una celda de tabla (se descarta, con registro); como mucho 24 páginas.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos (las páginas)[] | ninguno | no | sus hijos, dibujados en orden |
initialPage |
entero | 0 |
no | solo el primer vistazo; después de la última página, la última |
onPageChanged |
acción | ninguno | no | el value de su evento es el índice de la página en la que se quedó |
autoPlayMs |
de 3.000 a 60.000 | ninguno | no | pasa la página sola; en pausa mientras se toca o se enfoca y con las animaciones apagadas |
viewportFraction |
de 0,3 a 1 | 1 |
sí | menor que 1, el carrusel de Kino: las páginas vecinas se asoman |
padEnds |
boolean | true |
sí | la primera y la última página centradas en un carrusel |
{ "type": "PageView", "key": "covers", "viewportFraction": 0.8, "autoPlayMs": 5000, "onPageChanged": "page", "children": [
{ "type": "Card", "flush": true, "children": [{ "type": "Image", "url": "https://img.example.com/1.jpg", "aspect": "16:9" }] },
{ "type": "Card", "flush": true, "children": [{ "type": "Image", "url": "https://img.example.com/2.jpg", "aspect": "16:9" }] }
] }
pages¶
Páginas a pantalla completa para recorrer una historia (apiVersion 17): es un nodo propio de Kino, por eso no tiene nombre de
Flutter; PageView sigue siendo el carrusel con puntos. Ponlo como raíz, o en un Column con flex: 1, que le da la altura que
queda. Se desliza en un celular y en un escritorio. En una TV, Izquierda y Derecha pasan de página cuando dentro ya no hay nada
más enfocable en esa dirección, Arriba y Abajo se quedan dentro, y el foco entra en la página nueva; una página sin nada enfocable
también pasa. En la primera página Izquierda no hace nada: el área del plugin conserva el foco, como en todas partes, y Atrás y el
cierre de Kino salen.
Kino dibuja la barra de progreso encima de las páginas, un segmento por página; tú no la dibujas ni la ocultas. Nada pasa solo. La
página a la que se llegó vive en state.inputs.<key> como un número desde 0 (no es un input: sin etiqueta ni reglas de formulario),
así que sobrevive a tus nuevos dibujos; un set de ui o los inputs de tu estado la mueven, y onPageChanged envía el índice
en el que se quedó como value.
De 2 a 8 children (hasta 250 con progress: "bar" o "none") y una key propia; si no, todo el nodo se descarta, con
registro. Nunca dentro de un desplazamiento lateral, de una celda de tabla ni de otro pages (se descarta, con registro).
autoPlayMs, initialPage, viewportFraction y padEnds se ignoran, con registro. Para un capítulo de manga usa
reverse: true y progress: "bar" (mira la receta Un lector). Un Kino más antiguo descarta el nodo: comprueba kino.screen.widgets.includes("pages").
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos (las páginas, de 2 a 8)[] | ninguno | no | sus hijos, dibujados en orden |
onPageChanged |
acción | ninguno | no | el value de su evento es el índice de la página en la que se quedó |
progress |
segments | bar | none |
segments |
no | la barra de Kino sobre las páginas: un segmento por página (hasta 8 páginas), una barra fina o ninguna (hasta 250 páginas: un capítulo, no una historia) |
reverse |
boolean | false |
no | de derecha a izquierda, con la página 0 a la derecha: deslizar hacia la izquierda pasa a la página siguiente, y en una TV también Izquierda (manga) |
{ "type": "pages", "key": "story", "onPageChanged": "page", "children": [
{ "type": "Column", "padding": 24, "children": [{ "type": "Text", "text": "47", "style": "hero" }] },
{ "type": "Column", "padding": 24, "children": [{ "type": "Text", "text": "Lo tuyo es la madrugada", "style": "h2" }] }
] }
ListTile¶
El ListTile de Flutter: una fila de una lista con las alturas de Material (56 dp, 72 con subtitle, 48 con dense):
un leading y un trailing (un nodo pequeño cada uno: un Icon, un CircleAvatar, una Image, un Badge, un
Text o un indicador de carga; nunca se pulsan ellos mismos, sus acciones se ignoran, con registro), el title y el
subtitle. Toda la fila es una sola pulsación (onTap, onLongPress) y, en la TV, una sola parada de foco con el
anillo de Kino (solo con un onTap: una fila que no hace nada nunca muestra el anillo). selected (con un onTap) la
rellena con el primaryContainer de Kino y se lee como seleccionada.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
title |
string | obligatorio | no | titleEn; como mucho dos líneas |
subtitle |
string | ninguno | no | subtitleEn; la segunda línea atenuada de Kino |
leading |
nodo | ninguno | no | uno de Icon, CircleAvatar, Image, Badge, Text, CircularProgressIndicator, nunca se pulsa él mismo |
trailing |
nodo | ninguno | no | como leading, al final |
dense |
boolean | false |
sí | una fila más baja (48 dp en vez de 56, 72 con subtítulo) |
{ "type": "ListView", "items": [
{ "type": "ListTile", "key": "m1", "title": "María", "subtitle": "En línea", "subtitleEn": "Online", "onTap": "chat",
"leading": { "type": "CircleAvatar", "text": "MA" }, "trailing": { "type": "Badge", "text": "2" } }
] }
Contenido¶
Lo que la persona lee y mira.
Text¶
Texto simple en uno de los estilos de Kino. Nunca contiene marcado ni enlaces, conserva los saltos de línea y sigue la
dirección de lectura de la app. Dale a cada texto su gemelo en inglés (textEn): Kino elige según el idioma de la
persona.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
text |
string | obligatorio (opcional con time) |
no | de 1 a 2.000 caracteres, simple (sin marcado, sin enlaces); se conservan los saltos de línea; con un time es su prefijo |
textEn |
string | ninguno | no | el gemelo en inglés, que se muestra cuando la app está en inglés |
style |
hero | h1 | h2 | h3 | h4 | h5 | p | caption | label |
p |
sí | la escala tipográfica de Kino (Escala de texto); display, title, subtitle, body se leen como h1, h3, h4, p |
maxLines |
entero ≥ 1 | ninguno | sí | se corta con puntos suspensivos |
bold |
boolean | false |
sí | los encabezados ya son negrita; false nunca adelgaza uno |
time |
epoch ms | ninguno | no | un número entero de 0 a 253.402.300.799.999: Kino escribe la hora él mismo en el idioma de la app (Texto con una hora) |
timeFormat |
relative | clock | countdown |
relative |
no | relative («hace 2 min», reescrito cada minuto mientras se ve, sin llamarte), clock («18:42», las 12/24 h del aparato) o countdown («0:42» restantes, cada segundo, «0:00» al llegar) |
{ "type": "Column", "gap": 4, "children": [
{ "type": "Text", "text": "Título", "textEn": "Title", "style": "h1" },
{ "type": "Text", "text": "Un párrafo que se corta en dos líneas.", "textEn": "A paragraph cut at two lines.", "maxLines": 2 },
{ "type": "Text", "text": "Importante", "textEn": "Important", "bold": true, "color": "warning" }
] }
export async function screen({ state }) {
const name = typeof state.name === "string" ? state.name : "Ana";
return { type: "Text", text: "Hola, " + name, textEn: "Hello, " + name, style: "h2", crossAxisAlignment: "center" };
}
- TV: nunca recibe el foco por sí solo (un texto dentro de una tarjeta que se puede pulsar va con la tarjeta).
- Celular y TV: cada estilo crece 1,25 en la TV, así el orden de la escala se mantiene a tres metros; la escala de letra de la persona se respeta en los dos.
- Límites y errores: como mucho 2.000 caracteres; un texto vacío se descarta. No hay familia tipográfica, tamaño,
cursiva ni color libre: solo
style,boldy un rol de color.onPrimarynunca se lee sobre una superficie: vuelve al valor por defecto (con registro).
Texto con una hora¶
time (epoch ms) hace que Kino escriba la hora él mismo, en el idioma de la app: timeFormat: "relative" (por defecto:
«ahora», «hace 2 min», «hace 3 h», «ayer», una fecha más allá; «en 5 min» para una hora futura), reescrito una vez por
minuto mientras se ve sin llamar a tu plugin, "clock" («18:42», según el ajuste de 12 o 24 horas del aparato), o
"countdown" (la espera restante, «0:42», «1:02:03», reescrita cada segundo mientras corre, «0:00» al llegar). Con un
time el text es opcional y es su prefijo. Una hora que no es un número entero desde 0 se descarta (con registro), y
el text vuelve a ser obligatorio.
El enabledAt de un elemento que se puede pulsar (un botón, un FloatingActionButton, una tarjeta o un ListTile con
onTap) lo dibuja apagado hasta esa hora del reloj del aparato y lo enciende solo, sin llamar a tu plugin: «Reenviar»
después de un minuto.
{ "type": "Row", "gap": 8, "children": [
{ "type": "TextButton", "labelText": "Reenviar código", "labelTextEn": "Send the code again", "enabledAt": 1761580860000, "onPressed": "resend" },
{ "type": "Text", "text": "en", "textEn": "in", "time": 1761580860000, "timeFormat": "countdown", "style": "caption" }
] }
{ "type": "Column", "children": [
{ "type": "Text", "text": "Actualizado", "textEn": "Updated", "style": "caption", "time": 1761580800000 },
{ "type": "Text", "time": 1761580800000, "timeFormat": "clock", "style": "caption", "color": "muted" }
] }
Escala de texto¶
style corresponde a la escala tipográfica propia de Kino: en el celular h1 es el escalón headline-large, hasta p,
el escalón body-medium; caption es el escalón pequeño y atenuado y label el que usan los botones. En la TV cada
escalón crece 1,25. Los encabezados ya son negrita. Los nombres antiguos display, title, subtitle y body se leen
como h1, h3, h4 y p; un estilo desconocido es p (con registro).
hero (apiVersion 17) es un escalón por encima de h1, para un número grande: 72 sp con interlínea de 72 sp en el celular, 90 sp en la TV, en negrita.
Un Kino anterior a apiVersion 17 no lo conoce y dibuja p, así que comprueba la versión de la API cuando el tamaño importe.

{ "type": "Column", "gap": 4, "children": [
{ "type": "Text", "text": "h1", "style": "h1" }, { "type": "Text", "text": "h2", "style": "h2" },
{ "type": "Text", "text": "h3", "style": "h3" }, { "type": "Text", "text": "h4", "style": "h4" },
{ "type": "Text", "text": "h5", "style": "h5" }, { "type": "Text", "text": "p", "style": "p" },
{ "type": "Text", "text": "caption", "style": "caption" }, { "type": "Text", "text": "label", "style": "label" }
] }
Colores¶
color acepta un rol, nunca un valor: primary, secondary, surface, muted, warning, error, onPrimary,
primaryContainer y surfaceVariant, pintados con la paleta de Kino (el theme de tu manifiesto tiñe primary donde
pasa las reglas de contraste). Un rol que no se leería sobre su superficie se acerca al color de texto propio de esa
superficie hasta que se lee (4,5:1). En un Text colorea el texto; en un contenedor (un Stack, un fallback) es el
relleno.

{ "type": "Column", "gap": 4, "children": [
{ "type": "Text", "text": "primary", "color": "primary" },
{ "type": "Text", "text": "muted", "color": "muted" },
{ "type": "Text", "text": "warning", "color": "warning" },
{ "type": "Text", "text": "error", "color": "error" }
] }
- Errores: un valor hexadecimal (
"#ff0000") está fuera de la lista de roles y se descarta. UsaMaterialBannero elrolede un toast para el color de éxito (successes un rol de esos, no decolor). Una palabra que Kino reconoce recibe el rol más cercano, nombrado en su línea de registro, igual en la app y en el kit:screen: text color "success" is not a color role ("success" is a banner and toast role; the closest color role is "primary"), dropped(tambiéninfo→secondary,danger→error,grey→muted, un rol con otras mayúsculas → ese rol).
Los dos roles de contenedor sirven para una caja que destaca sin ser un banner: primaryContainer (la superficie de
Kino teñida con el primario; el theme del manifiesto la tiñe igual que tiñe primary) y surfaceVariant (la
superficie elevada de Kino). En una caja (Card, Column, Row, Stack) son su relleno, y su texto y sus iconos toman
solos el color "on" que les corresponde; en un Text o un Icon son el color, ajustado para que se lea como todo rol.
La burbuja propia de un chat, como mucho de tres cuartos de ancho, con la esquina de la cola pequeña:
{ "type": "Column", "crossAxisAlignment": "end", "fill": true, "children": [
{ "type": "Card", "key": "mine", "color": "primaryContainer", "maxWidthFraction": 0.75,
"borderRadius": { "topStart": "large", "topEnd": "large", "bottomStart": "large", "bottomEnd": "small" },
"children": [{ "type": "Text", "text": "Ya llegué", "textEn": "I'm here" }] }
] }
Image¶
Una imagen desde una dirección https pública (no hace falta declarar el host, como para toda imagen en Kino). aspect
fija la forma de la caja; fallback es un nodo que se dibuja en esa caja cuando la imagen falla o no hay url, así un
feed roto nunca muestra un hueco.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
url |
URL https | obligatorio sin fallback |
no | un host https público (no hace falta declararlo), o data:image/png\|jpeg\|webp\|gif;base64,… de 200.000 caracteres como máximo (una imagen que tú tienes, como la portada de un libro; nunca svg; un Kino anterior dibuja el fallback); con un fallback, sin url se dibuja el fallback (también con una vacía o rechazada, con registro) |
alt |
string | ninguno | no | lo que dice un lector de pantalla (altEn el de inglés) |
aspect |
16:9 | 2:3 | 1:1 | banner | w:h |
el de la imagen | sí | la forma de la caja; w:h es cualquier ancho sobre alto de 0,2 a 5, como 1.4:1 o 900:1300 |
fit |
cover | contain | width |
cover |
sí | cómo se acomoda la imagen en su caja: cover llena y recorta, contain la muestra entera, width toma el ancho y el alto propio de la imagen (el aspect, o 2:3, guarda su lugar hasta que carga) |
focus |
top | center | bottom |
center |
sí | la parte de la imagen que se conserva cuando cover la recorta |
headers |
{ Referer?, User-Agent? } |
ninguno | no | los encabezados con los que se pide la imagen, para un sitio que solo responde a su propia página: solo Referer (una dirección https) y User-Agent, cada uno un texto de hasta 512 caracteres; se envían solo cuando el host de la imagen está en los hosts de tu manifiesto (y también el del Referer); un Kino anterior la pide sin ellos (Imágenes que necesitan un Referer) |
fallback |
nodo | ninguno | no | se dibuja en la caja de la imagen cuando la imagen falla o no hay url: solo Column, Row, Stack, Card, Spacer, Divider, Text, Icon, Badge, Skeleton, Image, a cualquier profundidad, nunca se pulsa |
{ "type": "Image", "url": "https://kinotvapp.github.io/kino-plugins/missing-picture.png", "aspect": "16:9", "alt": "Sin imagen", "altEn": "No picture",
"fallback": { "type": "Stack", "color": "surface", "children": [
{ "type": "Column", "padding": 12, "children": [{ "type": "Icon", "name": "movie" }, { "type": "Text", "text": "La fuente", "textEn": "The source", "style": "h3" }] }
] } }
export async function screen({ state }) {
const picture = typeof state.picture === "string" && state.picture ? { url: state.picture } : {}; // no url at all: the fallback, no log line
return { type: "Image", ...picture, aspect: "16:9", alt: "Póster", fallback: { type: "Text", text: "Sin imagen", textEn: "No picture", padding: 12 } };
}
fit decide cómo se acomoda la imagen en su caja (aditivo, sin apiVersion nuevo; un Kino más antiguo lee toda imagen como
cover): cover llena la caja y recorta, contain la muestra entera, y width toma el ancho de la caja y el alto propio de
la imagen, así una página o una tira larga nunca se corta. Con width, el aspect (cualquier w:h, como "1.4:1") solo
guarda el lugar hasta que la imagen carga. focus (top, center, bottom) elige la parte que se conserva cuando cover
recorta.
Imágenes que necesitan un Referer¶
Próxima versión de Kino, todavía sin publicar
headers es aditivo (sin apiVersion nuevo) y llega con la próxima versión de Kino. Un Kino anterior pide la imagen sin
ellos, así que con él un sitio que los necesita sigue respondiendo 403 y se dibuja el fallback.
Algunos sitios (sobre todo los lectores de manga) solo entregan sus imágenes a una petición que viene de su propia página, con
un User-Agent de navegador, y a todo lo demás le responden 403: la portada y las páginas se quedan grises. Dale a la Image
los encabezados que pide el sitio:
{ "type": "Image", "url": "https://img.mangasite.example/p/12/001.jpg", "fit": "width", "aspect": "2:3",
"headers": { "Referer": "https://mangasite.example/", "User-Agent": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/126 Mobile Safari/537.36" } }
{ "hosts": ["mangasite.example", "*.mangasite.example"] }
- Solo dos nombres.
Referer(una dirección https) yUser-Agent(con cualquier combinación de mayúsculas), cada uno un texto de 1 a 512 caracteres sin caracteres de control. Todo lo demás se descarta y queda en el registro. - Solo a tus hosts declarados. Se envían solo cuando el host de la imagen es uno de los
hostsde tu manifiesto (un patrón*.example.comcuenta), y elReferersolo cuando su propio host también está declarado (si no, se omite solo elReferer): un plugin no puede hacer que Kino presente una página falsa a un sitio que nunca nombró. Una imagen de un host público no declarado igual carga, sin tus encabezados. - Una
urlhttps. Una imagendata:no lleva encabezados. SinUser-Agent, Kino envíaKino/<versión>. - La descarga Kino. La imagen se sigue descargando en Kino (en caché, cuatro a la vez), no a través de tu código, así que no tiene más límite de tamaño que el de la caché de imágenes.
-
No va por tamaño. Un solo objeto
headerspara todos los tamaños. -
TV: una imagen no recibe el foco salvo que ella (o lo que la contiene) tenga una acción.
- Celular y TV: igual.
- Límites y errores:
http://y las direcciones privadas se rechazan (sin fallback el nodo se descarta; con uno se dibuja el fallback, y unaurlpresente pero vacía o rechazada queda en el registro: omiteurlcuando no la hay). El fallback solo acepta nodos simples (Column,Row,Stack,Card,Spacer,SizedBox,Divider,Text,Icon,Badge,Skeleton,Image) y nada dentro de él se pulsa. Sin fallback, una imagen que falla muestra la marca de Kino.
Icon¶
Uno de los iconos de Kino por su name; color acepta un rol. Los mismos nombres sirven para el icon de un botón
(también un IconButton), el de un elemento de menú, el de los estados vacío y de error, el screen.icon del
manifiesto y el panel.icon del panel del reproductor. Son Material Symbols (outlined), dibujados como vectores: nítidos
a cualquier tamaño, teñidos por el rol de color que los rodea. Un icono no le dice nada a un lector de pantalla: un
IconButton se lee por su labelText.
![]()
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
name |
50 nombres | obligatorio | no | uno de los iconos de Kino (la tabla de iconos): 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; los últimos 34 desde apiVersion 14 |
{ "type": "Row", "gap": 8, "children": [
{ "type": "Icon", "name": "star", "color": "primary" },
{ "type": "Icon", "name": "heart", "color": "error" },
{ "type": "Icon", "name": "movie" }
] }
export async function screen() {
return { type: "Row", gap: 8, children: ["info", "star", "heart"].map((name) => ({ type: "Icon", name })) };
}
- Errores: un nombre fuera de la lista (
"replay", un nombre de icono de Material como"Refresh") descarta el nodo. Los iconos no se pueden enfocar. - apiVersion: los primeros dieciséis nombres funcionan desde apiVersion 9 (el botón del panel del reproductor); el
resto llegó con apiVersion 14. Las pantallas necesitan apiVersion 14, así que una pantalla conoce todos los nombres;
un
panel.iconcon uno de los nombres nuevos en un plugin por debajo de apiVersion 14 es un nombre desconocido (el botón dibujatune).
Nombres de iconos¶
Cada nombre, lo que muestra y desde cuándo. El ejemplo galería los dibuja todos, cada uno con su nombre, en la sección «Todos los iconos» de su pestaña Contenido.
![]()
| Nombre | Lo que muestra | Desde |
|---|---|---|
info |
información, detalles | apiVersion 9 |
tune |
opciones, ajustes finos (el de Kino por defecto) | apiVersion 9 |
settings |
ajustes | apiVersion 9 |
star |
un favorito, una calificación | apiVersion 9 |
bolt |
rápido, en vivo, una acción | apiVersion 9 |
language |
idioma, la web | apiVersion 9 |
subtitles |
subtítulos | apiVersion 9 |
list |
una lista, un índice | apiVersion 9 |
magic |
sugerencias, algo automático | apiVersion 9 |
heart |
me gusta, guardado | apiVersion 9 |
movie |
una película | apiVersion 9 |
tv |
una serie, televisión | apiVersion 9 |
sports |
deporte | apiVersion 9 |
music |
música, audio | apiVersion 9 |
bookmark |
guardado para después | apiVersion 9 |
help |
ayuda, una pregunta | apiVersion 9 |
refresh |
actualizar ahora (una flecha circular) | apiVersion 14 |
sync |
sincronizar entre aparatos | apiVersion 14 |
add |
agregar, nuevo | apiVersion 14 |
remove |
quitar uno, menos | apiVersion 14 |
delete |
borrar (una papelera) | apiVersion 14 |
edit |
editar (un lápiz) | apiVersion 14 |
search |
buscar | apiVersion 14 |
close |
cerrar, descartar | apiVersion 14 |
check |
hecho, confirmado | apiVersion 14 |
share |
compartir | apiVersion 14 |
play |
reproducir | apiVersion 14 |
pause |
pausar | apiVersion 14 |
download |
descargar | apiVersion 14 |
upload |
subir, enviar un archivo | apiVersion 14 |
link |
un enlace | apiVersion 14 |
open_in_new |
se abre afuera (un enlace que sale) | apiVersion 14 |
home |
inicio, el comienzo | apiVersion 14 |
person |
una persona, una cuenta | apiVersion 14 |
lock |
bloqueado, privado | apiVersion 14 |
notifications |
notificaciones, alertas | apiVersion 14 |
warning |
una advertencia (un triángulo) | apiVersion 14 |
error |
un error (un círculo con una marca) | apiVersion 14 |
visibility |
mostrar, visto (un ojo) | apiVersion 14 |
copy |
copiar | apiVersion 14 |
arrow_back |
atrás, anterior | apiVersion 14 |
arrow_forward |
adelante, siguiente | apiVersion 14 |
expand_more |
abrir, más (un chevrón hacia abajo) | apiVersion 14 |
expand_less |
cerrar, menos (un chevrón hacia arriba) | apiVersion 14 |
more_vert |
más acciones (tres puntos) | apiVersion 14 |
filter_list |
filtrar | apiVersion 14 |
calendar |
una fecha, un calendario | apiVersion 14 |
schedule |
una hora, programado (un reloj) | apiVersion 14 |
send |
enviar un mensaje (un avión de papel) | apiVersion 14 |
mood |
una reacción, un sentimiento (una carita) | apiVersion 14 |
{ "type": "ElevatedButton", "labelText": "Actualizar ahora", "labelTextEn": "Refresh now", "icon": "refresh", "onPressed": "refresh" }
Badge¶
Una etiqueta pequeña: un conteo, una etiqueta de calidad, "Nuevo".

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
text |
string | obligatorio | no | una etiqueta corta (textEn la de inglés) |
{ "type": "Row", "gap": 8, "children": [
{ "type": "Badge", "text": "Nuevo", "textEn": "New" },
{ "type": "Badge", "text": "HDR", "color": "warning" }
] }
export async function screen({ state }) {
const unread = Number.isInteger(state.unread) ? state.unread : 3;
return { type: "Row", gap: 8, children: [{ type: "Text", text: "Mensajes" }, { type: "Badge", text: String(unread) }] };
}
- Errores: un
textvacío lo descarta; una insignia no se puede pulsar por sí sola (pon la acción en su padre).
CircleAvatar¶
El CircleAvatar de Flutter: un círculo de radius dp en un rol de color que contiene una imagen (https, por la cadena
de imágenes propia de Kino y sus reglas de hosts), si no unas iniciales (como mucho tres caracteres), si no un icono (la
persona de Kino por defecto). Una imagen que falla muestra las iniciales. Siempre es un círculo: no acepta
borderRadius (su radius es un número). Un lector de pantalla dice su labelText, si no sus iniciales.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
image |
URL https | ninguno | no | una imagen https pública, por la cadena de imágenes de Kino; si falla, las iniciales |
text |
string | ninguno | no | iniciales, como mucho 3 caracteres (textEn) |
icon |
un nombre de icono de Kino | person |
no | sin imagen ni iniciales |
radius |
de 12 a 64 (dp) | 20 |
sí | siempre un círculo: un CircleAvatar no acepta borderRadius |
backgroundColor |
un rol de color | primaryContainer |
no | sus iniciales y su icono en el color legible del rol |
labelText |
string | ninguno | no | lo que dice un lector de pantalla (labelTextEn); si no, las iniciales |
{ "type": "Row", "gap": 8, "children": [
{ "type": "CircleAvatar", "image": "https://img.example.com/me.jpg", "text": "MA", "labelText": "María" },
{ "type": "CircleAvatar", "text": "JP", "backgroundColor": "secondary", "radius": 24 },
{ "type": "CircleAvatar", "icon": "person" }
] }
MaterialBanner¶
Una línea de aviso a lo ancho de la pantalla en el color de Kino para su role: una actualización, una advertencia, un
fallo con «Reintentar». Puede llevar un título, un botón de acción y el cierre de Kino cuando es dismissible.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
text |
string | obligatorio | no | textEn |
role |
info | warning | error | success |
info |
no | el color y el icono de Kino para ese rol |
title |
string | ninguno | no | titleEn |
action |
{ label, labelEn?, onTap } |
ninguno | no | un botón |
dismissible |
boolean | false |
no | el cierre de Kino (necesita una key propia): lo oculta y envía el evento dismiss con la key como arg |
{ "type": "Column", "gap": 8, "children": [
{ "type": "MaterialBanner", "role": "error", "text": "No se pudo cargar.", "textEn": "Could not load.", "action": { "label": "Reintentar", "labelEn": "Retry", "onTap": "retry" } },
{ "type": "MaterialBanner", "key": "tip", "role": "info", "title": "Consejo", "titleEn": "Tip", "text": "Puedes cerrar este aviso.", "textEn": "You can dismiss this notice.", "dismissible": true }
] }
export async function screen({ state }) {
if (!state.failed) return { type: "Text", text: "Todo bien", textEn: "All good" };
return { type: "MaterialBanner", role: "warning", text: "Sin conexión", textEn: "Offline", action: { label: "Reintentar", labelEn: "Retry", onTap: "retry" } };
}
export async function screenEvent({ name }) {
if (name === "dismiss") return null; // a dismissible banner's close: arg is its key, Kino already hid it
if (name === "retry") return { state: { failed: false } };
return null;
}
- TV: la acción y el cierre son paradas de foco en el orden del árbol.
- Celular y TV: a todo lo ancho en los dos.
- Límites y errores:
dismissiblenecesita unakeytuya (una generada se ignora, con registro). El cierre lo oculta enseguida (state.ui.hidden) y envía el eventodismisscon la key comoarg.
LinearProgressIndicator¶
Una barra de progreso: value de 0 a 1, o ninguno para una indeterminada. Un labelText va a su lado.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
value |
número de 0 a 1 | ninguno | no | sin él se dibuja una barra indeterminada; fuera de 0..1 se recorta |
labelText |
string | ninguno | no | una etiqueta junto a la barra (labelTextEn) |
{ "type": "Column", "gap": 8, "children": [
{ "type": "LinearProgressIndicator", "value": 0.6, "labelText": "60 %" },
{ "type": "LinearProgressIndicator" }
] }
export async function screen({ state }) {
const done = Number.isFinite(state.done) ? state.done : 0;
return { type: "LinearProgressIndicator", value: Math.min(1, done / 10), labelText: done + " / 10" };
}
- Errores: un valor fuera de 0..1 se recorta (con registro); algo que no es un número la vuelve indeterminada.
CircularProgressIndicator¶
El indicador de carga de Kino, con una línea opcional debajo. Mientras una pantalla espera datos, un
Skeleton con la forma del contenido se lee mejor.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
text |
string | ninguno | no | una línea bajo el indicador de carga de Kino (textEn) |
{ "type": "CircularProgressIndicator", "text": "Cargando", "textEn": "Loading" }
export async function screen({ state }) {
return state.ready ? { type: "Text", text: "Listo" } : { type: "CircularProgressIndicator", text: "Cargando", textEn: "Loading" };
}
Skeleton¶
Un marcador de lugar mientras algo carga, en el color atenuado de Kino, con un pulso suave (quieto cuando las
animaciones del sistema están apagadas), que se lee como "Cargando…": line (de 1 a 6 barras), block, circle o
card (un póster y sus líneas).

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
shape |
line | block | circle | card |
line |
sí | dale tamaño con width/height |
lines |
de 1 a 6 | 1 |
sí | barras de un line |
{ "type": "Row", "gap": 12, "children": [
{ "type": "Skeleton", "shape": "circle", "width": 48, "height": 48 },
{ "type": "Skeleton", "shape": "line", "lines": 3, "flex": 1 }
] }
export async function screen({ state }) {
if (!Array.isArray(state.items)) return { type: "Column", gap: 12, padding: 16, children: [1, 2, 3].map(() => ({ type: "Skeleton", shape: "card", width: 160 })) };
return { type: "Column", children: state.items.slice(0, 50).map((t, i) => ({ type: "Text", key: "t" + i, text: String(t) })) };
}
- Errores:
linespor encima de 6 se reduce (con registro). Daleheighta unblock, o será una barra delgada.
QrImage¶
Un código QR que Kino dibuja en el aparato (sin red), negro sobre blanco con su zona de silencio: un enlace para que quien ve la TV lo abra en su celular, un código de sala para escanear. Nunca se pulsa ni recibe el foco; puede ir en una ventana emergente.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
value |
string | obligatorio | no | de 1 a 1.000 caracteres, dibujado tal como se escribe; un valor que contiene uno de tus secretos nunca se dibuja |
labelText |
string | ninguno | no | lo que dice un lector de pantalla (labelTextEn) |
size |
small | medium | large |
medium |
sí | uno de los tres tamaños de Kino |
expiresInMs |
de 1.000 a 3.600.000 | ninguno | no | el código deja de servir ese tiempo después de que Kino dibuja este valor por primera vez: Kino lo cuenta hacia atrás bajo el código y lo atenúa en cero (cuenta regresiva) |
expiresAt |
epoch ms | ninguno | no | lo mismo como una hora (el reloj del aparato, leído una vez), como mucho a 3.600.000 ms; se ignora junto a expiresInMs |
onExpire |
nombre de evento o { event, arg? } |
ninguno | no | se envía una vez por valor: renew renewBeforeMs antes del final, si no expired en cero; value es { phase, remainingMs } |
renewBeforeMs |
de 1.000 a 3.600.000 | ninguno | no | con onExpire: pedir un código nuevo ese tiempo antes del final (por debajo de la duración, si no la mitad de ella) |
{ "type": "QrImage", "value": "https://kinotvapp.github.io/kino-plugins/", "size": "medium", "labelText": "Guía de plugins", "labelTextEn": "Plugin guide" }
export async function screen({ device }) {
const link = "https://kinotvapp.github.io/kino-plugins/";
return device === "tv"
? { type: "QrImage", value: link, size: "large", labelText: "Escanéalo con tu teléfono" }
: { type: "ElevatedButton", labelText: "Abrir", onPressed: { go: { url: { href: link } } } };
}
- Celular y TV: la misma imagen; en una TV es la forma de entregar un enlace (una TV no puede escanear:
kino.qr.scanrespondeunavailableahí). - Tamaños:
small,mediumylargeson 160, 200 y 240 dp en un celular y 180, 220 y 300 dp en una TV. En una TV un código nunca es más alto que el 30 % de la ventana, así que en una TV de 1280×720 (540 dp de alto) cada tamaño se dibuja a 162 dp: el encabezado de un paso, la cuenta regresiva y un botón bajo el código todavía caben a la vista y el control remoto llega a ellos. Una página que aun así pueda ser más alta que la ventana va en unSingleChildScrollView: el control remoto la recorre y Kino desplaza cada elemento enfocado a la vista (una raízColumnno se desplaza). - Límites y errores: de 1 a 1.000 caracteres, dibujado tal como se escribe. Nunca armes uno a partir de un secreto: un valor que contiene uno de tus secretos sellados no se dibuja (se muestra el estado vacío de Kino, con registro).
Un código que caduca (expiresInMs, onExpire, renewBeforeMs)¶
Un código de inicio de sesión que deja de servir al rato (el QR de inicio de sesión de una app de mensajería, unos
30 s) recibe la cuenta regresiva propia de Kino: una barra y «Caduca en 23 s» bajo el código, que Kino actualiza solo
entre tus llamadas, y en cero el código se atenúa bajo «Código caducado». Con onExpire Kino además te pide un código
nuevo, una vez por código, sin esperar a tu temporizador every:
{ "type": "QrImage", "value": "myapp://login?token=AbC", "size": "large", "labelText": "Escanéalo con la app",
"expiresInMs": 30000, "renewBeforeMs": 5000, "onExpire": "newCode" }
export async function screenEvent({ name, value }) {
if (name !== "newCode") return null; // value: { phase: "renew" | "expired", remainingMs }
const token = "AbC" + Date.now(); // ask your service for a new token here
return { state: { qr: "myapp://login?token=" + token } }; // a new value: a new countdown, the square keeps its size
}
- Cuándo sale el evento: una vez por valor de código:
renewBeforeMsantes del final (phase: "renew"), o en cero (phase: "expired") cuando no hay anticipación. Una respuesta lenta deja el código viejo contando hasta su aspecto de caducado; una respuesta que nunca llega no se vuelve a pedir para ese código (tu temporizadoreverysigue siendo el respaldo). Una anticipación que no es menor que la duración se recorta a la mitad de ella (con registro). - Relojes:
expiresInMscuenta desde que Kino dibuja ese valor por primera vez;expiresAt(epoch ms) se lee una vez contra el reloj del aparato y luego se cuenta comoexpiresInMs, así un cambio de reloj posterior nunca lo mueve. Volver a enviar el mismo valor (un temporizador que reenvíaexpiresInMs: 30000) nunca reinicia su cuenta regresiva; un valor nuevo siempre la reinicia. - Segundo plano, TV, secretos: la cuenta regresiva sigue el tiempo mientras la pantalla está oculta, pero el evento
espera: uno que se venció sale cuando la pantalla vuelve a mostrarse (
expiredsi el final también pasó). El código y su cuenta regresiva nunca toman el foco. Un código que contiene uno de tus secretos nunca se dibuja, ni se cuenta, ni se pregunta por él. - Su respuesta no viene de una pulsación de nadie: conserva
state,toast,closeyconfig, como la de un temporizador.
DataTable¶
Una tabla con el aspecto propio de Kino: TableRow que contienen TableCell. columns reparte el ancho (flex),
header hace de la primera fila el encabezado, zebra alterna el fondo de las filas; en un ancho compacto la tabla se
desplaza de lado salvo con wrap.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
TableRow[] |
obligatorio | no | de 1 a 200 filas |
columns |
{ key?, flex? }[] |
la cantidad de la fila más ancha | sí | como mucho 20; cada flex de 1 a 12 |
header |
boolean | false |
sí | la primera fila es el encabezado (en negrita, leída como encabezados) |
wrap |
boolean | false |
sí | en un ancho compacto, envolver en vez de desplazarse de lado |
zebra |
boolean | false |
sí | una fila de cada dos sobre la superficie de Kino |
{ "type": "DataTable", "header": true, "zebra": true, "columns": [{ "flex": 2 }, { "flex": 1 }], "children": [
{ "type": "TableRow", "children": [{ "type": "TableCell", "text": "Plan" }, { "type": "TableCell", "text": "Precio", "textEn": "Price" }] },
{ "type": "TableRow", "children": [{ "type": "TableCell", "text": "Gratis", "textEn": "Free" }, { "type": "TableCell", "text": "0" }] },
{ "type": "TableRow", "key": "note", "children": [{ "type": "TableCell", "text": "Precios en dólares", "textEn": "Prices in dollars", "colSpan": 2, "crossAxisAlignment": "center" }] }
] }
export async function screen() {
const rows = [["Lunes", "3"], ["Martes", "5"]].map(([day, n]) => ({ type: "TableRow", children: [{ type: "TableCell", text: day }, { type: "TableCell", text: n, crossAxisAlignment: "end" }] }));
return { type: "DataTable", header: true, children: [{ type: "TableRow", children: [{ type: "TableCell", text: "Día" }, { type: "TableCell", text: "Vistos" }] }, ...rows] };
}
- TV: la tabla no toma el foco; el D-pad recorre solo lo enfocable dentro de sus celdas.
- Celular y TV: al menos 96 dp por columna cuando se desplaza de lado en un celular; una TV tiene espacio para toda la tabla.
- Límites y errores: 200 filas, 20 columnas,
colSpande 1 a 8. Una fila con menos celdas se completa; las celdas después de la última columna se descartan (con registro). Cada fila y cada celda cuesta un nodo. Las celdas nunca contienen unListView, un desplazamiento ni otra tabla.
TableRow¶
Una fila de una DataTable. Su key permite que un show, hide o toggle de ui la nombre (una fila de detalles
que se muestra a pedido).
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
TableCell[] |
ninguno | no | como mucho 20; una fila corta se completa |
key |
string | ninguno | no | permite que show, hide, toggle nombren la fila |
hidden |
boolean | false |
no | empieza oculta; un campo obligatorio en una fila oculta no se revisa |
TableCell¶
Una celda: un text simple, o children (nodos un nivel por debajo de la tabla). colSpan y crossAxisAlignment
pueden ser mapas por tamaño (colSpan: { compact: 1, expanded: 3 }).
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
text |
string | ninguno | no | una celda simple (textEn); con un text los hijos se ignoran |
children |
nodos[] | ninguno | no | nunca ListView, SingleChildScrollView, DataTable a ninguna profundidad |
colSpan |
de 1 a 8 | 1 |
sí | columnas que cubre la celda |
crossAxisAlignment |
start | center | end |
start |
sí | su contenido a lo ancho |
emptyState¶
El estado vacío de Kino (un icono, un título y una línea): una lista sin nada, una búsqueda sin resultados. Es un componente de Kino: su nombre no tiene gemelo en Flutter.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
title |
string | obligatorio | no | titleEn el de inglés |
text |
string | ninguno | no | una línea bajo el título (textEn) |
icon |
un nombre de icono de Kino | el de Kino | no |
{ "type": "emptyState", "title": "Nada por aquí", "titleEn": "Nothing here", "text": "Agrega algo para verlo.", "textEn": "Add something to see it.", "icon": "bookmark" }
export async function screen({ state }) {
const saved = Array.isArray(state.saved) ? state.saved : [];
if (saved.length === 0) return { type: "emptyState", title: "Sin guardados", titleEn: "Nothing saved", icon: "bookmark" };
return { type: "Column", children: saved.slice(0, 50).map((s, i) => ({ type: "Text", key: "s" + i, text: String(s) })) };
}
errorState¶
El estado de error de Kino, con la misma forma que el vacío: una carga fallida sin nada que mostrar. Acompáñalo con un
botón para reintentar, o muestra un MaterialBanner sobre los datos viejos cuando los hay.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
title |
string | obligatorio | no | titleEn el de inglés |
text |
string | ninguno | no | una línea bajo el título (textEn) |
icon |
un nombre de icono de Kino | el de Kino | no |
{ "type": "Column", "gap": 12, "crossAxisAlignment": "center", "children": [
{ "type": "errorState", "title": "Algo falló", "titleEn": "Something failed", "text": "Inténtalo de nuevo.", "textEn": "Try again." },
{ "type": "ElevatedButton", "labelText": "Reintentar", "labelTextEn": "Retry", "onPressed": "retry" }
] }
export async function screen() {
return { type: "errorState", title: "Sin conexión", titleEn: "Offline", icon: "help" };
}
titleCard¶
Una tarjeta de póster del Inicio para un KinoItem (la forma que devuelve una fila de home). Su toque abre el título
como lo hace la tarjeta del Inicio, con ese mismo elemento, así «Continuar viendo», las listas guardadas y el progreso
lo conocen. onTap puede reemplazar eso con un evento, un go u operaciones ui; el open: { screen } de un elemento
vuelve a abrir tu pantalla en su lugar.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
item |
KinoItem |
obligatorio | no | la forma que devuelve una fila de home (id, ref, title, kind, poster...); una serie necesita tu capacidad episodes |
size |
small | medium | large |
medium |
sí | uno de los tres tamaños de Kino |
{ "type": "titleCard", "size": "medium", "item": { "id": "bbb", "ref": "bbb", "title": "Big Buck Bunny", "kind": "movie", "year": 2008, "poster": "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg" } }
export async function screen() {
const item = { id: "bbb", ref: "bbb", title: "Big Buck Bunny", kind: "movie", poster: "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg" };
return { type: "titleCard", item, size: "large" };
}
- TV: recibe el foco como las tarjetas del Inicio.
- Celular y TV: la propia tarjeta del Inicio en cada uno.
- Límites y errores: se lee con las reglas del Inicio: una
seriesnecesita tu capacidadepisodes, los pósters son solo https (si no, el marcador de lugar de Kino), un elemento 18+ solo se muestra mientras el código 18+ de la persona está desbloqueado. Como mucho 1.000 títulos por árbol.
titleRail¶
Una fila del Inicio: un encabezado, una fila lateral de tarjetas de títulos y, con un ref, su «Ver más» (tu browse).
La forma de darle a una pantalla el aspecto del Inicio propio de Kino.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
title |
string | obligatorio | no | el encabezado de la fila (titleEn) |
items |
KinoItem[] |
obligatorio | no | de 1 a 500 (60 cuando se dibuja todo de una vez) |
ref |
string | ninguno | no | con él, el «Ver más» de la fila abre tu browse (como mucho 4.096 caracteres) |
size |
small | medium | large |
medium |
sí | uno de los tres tamaños de Kino |
onEndReached |
{ event, arg? } |
ninguno | no | se envía una vez cuando el último elemento entra en la vista, y de nuevo solo después de que tu respuesta dibujó una lista más larga (o loadingMore pasó de true a false); nunca más de una vez por segundo |
loadingMore |
boolean | false |
no | true dibuja el indicador de carga de Kino después de los elementos |
done |
boolean | false |
no | true deja de pedir más |
{ "type": "titleRail", "title": "Recomendadas", "titleEn": "Recommended", "size": "small", "items": [
{ "id": "bbb", "ref": "bbb", "title": "Big Buck Bunny", "kind": "movie", "poster": "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg" },
{ "id": "sintel", "ref": "sintel", "title": "Sintel", "kind": "movie" }
] }
export async function screen({ state }) {
const items = Array.isArray(state.items) && state.items.length ? state.items : [{ id: "bbb", ref: "bbb", title: "Big Buck Bunny", kind: "movie" }];
return { type: "titleRail", title: "Para ti", titleEn: "For you", items, onEndReached: { event: "more" }, done: items.length >= 60 };
}
- TV: Izquierda y Derecha recorren las tarjetas; el riel se desplaza con el foco.
- Límites y errores: de 1 a 500 elementos (60 cuando el riel está dentro de un desplazamiento lateral, dibujado todo
de una vez). Sin
titleel riel se descarta.
titleGrid¶
Tarjetas del Inicio en una rejilla de columns (3 por defecto): una página de catálogo, resultados de búsqueda.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
items |
KinoItem[] |
obligatorio | no | de 1 a 500 (60 cuando se dibuja todo de una vez) |
columns |
de 1 a 8 | 3 |
sí | |
onEndReached |
{ event, arg? } |
ninguno | no | se envía una vez cuando el último elemento entra en la vista, y de nuevo solo después de que tu respuesta dibujó una lista más larga (o loadingMore pasó de true a false); nunca más de una vez por segundo |
loadingMore |
boolean | false |
no | true dibuja el indicador de carga de Kino después de los elementos |
done |
boolean | false |
no | true deja de pedir más |
{ "type": "titleGrid", "columns": { "compact": 3, "expanded": 6 }, "items": [
{ "id": "bbb", "ref": "bbb", "title": "Big Buck Bunny", "kind": "movie" },
{ "id": "sintel", "ref": "sintel", "title": "Sintel", "kind": "movie" },
{ "id": "tos", "ref": "tos", "title": "Tears of Steel", "kind": "movie" }
] }
export async function screen() {
const items = ["Big Buck Bunny", "Sintel", "Tears of Steel"].map((title, i) => ({ id: "t" + i, ref: "t" + i, title, kind: "movie" }));
return { type: "titleGrid", columns: { compact: 3, expanded: 6 }, items };
}
- Límites y errores: de 1 a 500 elementos, 60 cuando se dibuja todo de una vez (una rejilla dentro de un desplazamiento, una lista, una ventana emergente o una celda de tabla): una rejilla larga pide una página propia en la raíz.
heroCard¶
El banner de una sección: una imagen grande, un título, una línea y como mucho dos botones. La parte de arriba de una página de inicio.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
title |
string | obligatorio | no | titleEn el de inglés |
text |
string | ninguno | no | textEn |
image |
URL https | ninguno | no | una imagen https pública |
logo |
URL https | ninguno | no | aditivo, sin apiVersion nuevo: el logo del título (una imagen https pública) dibujado donde va el texto del título cuando carga; el texto sigue nombrándolo para un lector de pantalla y se ve si el logo no carga |
h |
un tamaño de la escala | el de Kino (240 dp, 320 en TV) | sí | aditivo, sin apiVersion nuevo: la altura del banner; sirve un mapa por tamaño ({ "compact": 200, "expanded": 240 }) |
buttons |
nodos de botón | ninguno | no | como mucho 2 |
{ "type": "heroCard", "title": "Estreno", "titleEn": "Premiere", "text": "Un conejo y tres roedores.", "textEn": "A rabbit and three rodents.",
"image": "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg",
"buttons": [
{ "type": "ElevatedButton", "labelText": "Ver", "labelTextEn": "Watch", "onPressed": { "go": { "titleByIds": { "tmdb": 10378, "kind": "movie" } } } },
{ "type": "TextButton", "labelText": "Más", "labelTextEn": "More", "onPressed": "more" }
] }
export async function screen() {
return { type: "heroCard", title: "Destacado", image: "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg", buttons: [{ type: "ElevatedButton", labelText: "Abrir", onPressed: "open-hero" }] };
}
- Límites y errores: como mucho 2 botones (el resto se descarta, con registro), solo botones; una imagen
httpse descarta.
Acciones¶
Lo que hace una pulsación es una acción: el onTap y el onLongPress de un nodo, el onPressed de un botón, el
onChanged y el onSubmitted de una entrada, el onSubmitted de un formulario, el onTap de un elemento de menú.
Cuatro formas, más un presupuesto de tiempo:
onPressed: "refresh" // an event for screenEvent; its arg is the node's arg
onPressed: { event: "read", arg: "story-42" } // an event with its arg (at most 4,096 characters)
onPressed: { ui: [{ toggle: "details" }], event: "seen" } // local operations first (no plugin call), then the event
onPressed: { go: { url: { href: "https://kinotvapp.github.io/kino-plugins/" } } } // somewhere in Kino, no plugin call
onPressed: { event: "login", timeoutMs: 28000 } // this press's call may take up to 28 s
screenEvent recibe { name, arg, value, state, route, device, lang } y responde qué debe cambiar
(Respuestas). El nombre de evento open está reservado: Kino lo envía una vez cuando se abre la
pantalla. Cada destino de go está en Navegación; las operaciones ui, más
abajo.
Botones¶
ElevatedButton es el botón principal de Kino, Button con variant: "secondary" el secundario, TextButton uno plano
e IconButton un icono (su labelText es lo que dice un lector de pantalla). confirm hace que Kino pregunte antes de
ejecutar la acción; submit: true dentro de un Form lo revisa y lo envía; enabled: false lo
dibuja apagado.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
labelText |
string | obligatorio (no para IconButton) |
no | labelTextEn el de inglés; en un IconButton es lo que dice un lector de pantalla |
icon |
un nombre de icono de Kino | ninguno | no | obligatorio para IconButton (variante icon) |
variant |
primary | secondary | text | icon |
primary |
sí | la fijan ElevatedButton, TextButton, IconButton; secondary solo como Button |
onPressed |
acción | ninguno | no | lo que hace una pulsación (Acciones) |
confirm |
string | ninguno | no | Kino hace esta pregunta (confirmEn) antes de ejecutar la acción |
submit |
boolean | false |
no | dentro de un Form: revisa y envía el formulario (su propio onPressed se ignora) |
{ "type": "Row", "wrap": true, "gap": 8, "children": [
{ "type": "ElevatedButton", "labelText": "Guardar", "labelTextEn": "Save", "icon": "bookmark", "onPressed": "save" },
{ "type": "Button", "variant": "secondary", "labelText": "Compartir", "labelTextEn": "Share", "onPressed": "share" },
{ "type": "TextButton", "labelText": "Borrar", "labelTextEn": "Delete", "confirm": "¿Borrar?", "confirmEn": "Delete it?", "onPressed": "delete" },
{ "type": "IconButton", "icon": "heart", "labelText": "Me gusta", "labelTextEn": "Like", "onPressed": "like" }
] }
export async function screen({ state }) {
return { type: "ElevatedButton", key: "send", labelText: state.sent ? "Enviado" : "Enviar", enabled: !state.sent, onPressed: { event: "send", arg: "now" } };
}
export async function screenEvent({ name }) {
return name === "send" ? { state: { sent: true }, toast: "Enviado", toastEn: "Sent" } : null;
}
- TV: cada botón es una parada de foco con el anillo de Kino; OK lo pulsa. Un botón desactivado se dibuja apagado y no hace nada.
- Celular y TV: las mismas variantes; dale a un botón un
heightfijo por clase de tamaño para un pulgar o un control remoto (una matriz al estilo calculadora usa 80 en un celular, 48 en una TV). - Límites y errores: un botón necesita un
labelText(unIconButton, unicon), si no se descarta.onPressedsolo funciona en botones (en lo demás esonTap).submitfuera de un formulario se ignora (con registro).OutlinedButtonno existe.
Pulsaciones ocupadas y lentas (loading, timeoutMs)¶
Una pulsación cuya llamada tarda muestra la señal de espera propia de Kino: cuando la llamada de la pulsación de la
persona pasa de 400 ms, el botón, FloatingActionButton, tarjeta o ListTile pulsado se dibuja con el aspecto ocupado
de Kino (un indicador de carga en lugar de su icono, sin pulsación, leído como ocupado) hasta tu respuesta.
loading: true en uno de esos nodos dibuja el mismo aspecto desde tu árbol (un inicio de sesión que sigues esperando,
por ejemplo); en la TV el nodo conserva su foco.
Un objeto de acción puede darle a la llamada de su evento un presupuesto propio, timeoutMs (de 1.000 a 30.000 ms; el
valor por defecto sigue siendo 20.000): solo en una pulsación (onPressed, onTap, onLongPress, onSubmitted,
onTrailingTap) y respetado solo cuando lo envía la pulsación o el envío de la propia persona; un cambio, un
temporizador, open o una carga de más conservan el valor por defecto.
{ "type": "ElevatedButton", "key": "send", "labelText": "Enviar código", "labelTextEn": "Send code", "onPressed": { "event": "sendCode", "timeoutMs": 28000 } }
export async function screen({ state }) {
return { type: "ElevatedButton", key: "refresh", labelText: "Actualizar", loading: state.refreshing === true, onPressed: "refresh" };
}
- Límites y errores:
timeoutMsfuera de 1.000..30.000 se recorta; en algo que no es una pulsación o sin evento se ignora (con registro).loadingen otro lugar que un botón, unFloatingActionButton, una tarjeta o unListTilecononTapse ignora (con registro).
FloatingActionButton¶
El FloatingActionButton de Flutter: uno por pantalla (otro se descarta, con registro), dibujado por Kino sobre el
extremo inferior (o el centro, fabPosition) de tu zona, nunca en su lugar del árbol, nunca bajo las barras del sistema
ni el teclado; en un Scaffold sobre su barra de abajo, en un panel del reproductor sobre el cuerpo del cajón. Con un
labelText es la forma extendida. Nunca dentro de una lista, una tabla, una ventana emergente, un ListTile o el
fallback de una imagen (se descarta, con registro). Acepta selected, badge, autofocus y tooltip; en la TV es una
parada de foco con el anillo de Kino, a la que se llega con el D-pad.
| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
icon |
un nombre de icono de Kino | obligatorio | no | dibujado sobre el relleno primario de Kino |
labelText |
string | ninguno | no | la forma extendida: la etiqueta junto al icono (labelTextEn); si no, lo que dice un lector de pantalla es el tooltip, y si no, la palabra propia de Kino |
onPressed |
acción | obligatorio | no | lo que hace una pulsación |
fabPosition |
end | center |
end |
sí | extremo inferior o centro inferior de la zona del plugin, nunca bajo las barras del sistema ni el teclado (botón flotante) |
{ "type": "Column", "children": [
{ "type": "Text", "text": "Tus listas", "textEn": "Your lists", "style": "h3" },
{ "type": "FloatingActionButton", "icon": "add", "labelText": "Nueva", "labelTextEn": "New", "onPressed": "newList" }
] }
Tooltip¶
tooltip (y tooltipEn), en cualquier nodo que hace algo (un botón, un campo, una elección, un FloatingActionButton,
cualquier nodo con onTap o onLongPress; en lo demás se ignora, con registro), como mucho 80 caracteres: la pista
propia de Kino. Un celular la muestra con una pulsación larga (un nodo con su propio onLongPress no muestra ninguna:
gana su acción), una TV después de unos 800 ms de foco (hasta que el foco se va), y un lector de pantalla la recibe como
la etiqueta de la pulsación larga. Nunca toma el foco ni una pulsación. Nunca pongas información esencial en un
tooltip: quien nunca hace una pulsación larga, o una TV en la que se pasa rápido, nunca la ve. Un nodo desactivado
también muestra la tuya (Kino no agrega una pista propia).
{ "type": "IconButton", "icon": "share", "labelText": "Compartir", "labelTextEn": "Share", "tooltip": "Copia el enlace del episodio", "tooltipEn": "Copies the episode's link", "onPressed": "share" }
Chips¶
Una elección (o varias con multiple) entre unas pocas options, dibujadas como chips: filtros sobre una lista,
categorías, etiquetas. Es una entrada: su valor está en state.inputs, y onChanged avisa del cambio.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
key |
string | obligatorio | no | nombra el valor en state.inputs; única en la pantalla |
labelText |
string | ninguno | no | la etiqueta del campo (labelTextEn) |
hintText |
string | ninguno | no | una pista dentro o debajo (hintTextEn) |
onChanged |
acción | ninguno | no | la persona lo cambió; el value del evento es el valor nuevo |
options |
{ value, label, labelEn? }[] |
obligatorio | no | de 1 a 500, valores distintos |
multiple |
boolean | false |
no | se pueden elegir varios chips |
value |
string o string[] | ninguno | no | el valor elegido (una lista con multiple); un valor que no nombra ninguna opción se descarta |
bind |
una clave de ajuste | ninguno | no | muestra y guarda uno de tus ajustes select o text (bind) |
required |
boolean | false |
no | regla de formulario: un texto no vacío, una elección hecha, un interruptor encendido, un chip elegido |
minLength |
entero | ninguno | no | regla de formulario: caracteres (chips: chips elegidos) |
maxLength |
entero | ninguno | no | regla de formulario: caracteres (chips: chips elegidos) |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee bajo el campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto bajo el campo (forceErrorTextEn, como mucho 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "Chips", "key": "genre", "value": "all", "onChanged": "filter", "options": [
{ "value": "all", "label": "Todo", "labelEn": "All" },
{ "value": "movies", "label": "Películas", "labelEn": "Movies" },
{ "value": "series", "label": "Series" }
] }
export async function screen({ state }) {
const picked = Array.isArray(state.inputs?.extras) ? state.inputs.extras : ["hd"];
return { type: "Column", gap: 8, children: [
{ type: "Chips", key: "extras", multiple: true, value: picked, onChanged: "extras", options: [{ value: "hd", label: "HD" }, { value: "sub", label: "Subtítulos" }] },
{ type: "Text", text: "Elegidos: " + picked.join(", ") },
] };
}
- TV: Izquierda y Derecha se quedan dentro de la fila de chips; al entrar se llega al chip elegido; OK elige.
- Límites y errores: de 1 a 500 opciones con valores distintos; un
valueque no nombra ninguna opción se descarta (con registro). En unForm,minLengthymaxLengthcuentan los chips elegidos.
Toasts¶
Un mensaje corto abajo, desde una respuesta: un string, o { text, textEn?, role?, action?, ms? }. Uno a la vez (uno
más nuevo lo reemplaza); su action envía su evento una vez.
{ "toast": { "text": "Elemento borrado", "textEn": "Item deleted", "role": "success", "ms": 6000,
"action": { "label": "Deshacer", "labelEn": "Undo", "event": "undo" } } }
export async function screenEvent({ name, lang }) {
if (name === "save") return { toast: lang === "es" ? "Guardado" : "Saved" };
if (name === "delete") return { toast: { text: "Borrado", textEn: "Deleted", action: { label: "Deshacer", labelEn: "Undo", event: "undo" } } };
return null;
}
- TV: el toast nunca toma el foco por sí solo: Abajo desde la parte de abajo del árbol llega a su acción (Arriba o Atrás lo dejan), y la tecla Menú o Reproducir/Pausa del control remoto la ejecuta; el toast lo dice con palabras.
- Límites y errores:
msde 2.000 a 8.000 (3.500 por defecto). Un toast de tipo string lleva su gemelo en inglés entoastEn; el objeto llevatextEn.
Operaciones ui locales¶
Operaciones que Kino ejecuta enseguida, sin llamar a tu plugin, sobre otros nodos de la misma pantalla por su key:
mostrar un bloque de detalles, desactivar un botón, llenar un campo, abrir una ventana emergente
declarada. Como mucho 8 por acción o respuesta; una key desconocida se ignora (con registro). Lo que hacen queda guardado
en state.ui (hidden, enabled, y open para cada acordeón), así tu siguiente llamada lo ve y un nuevo dibujo lo
conserva.
| Operación | Forma | Lo que hace |
|---|---|---|
show |
{ show: key } |
muestra un nodo oculto |
hide |
{ hide: key } |
lo oculta (guardado en state.ui.hidden) |
toggle |
{ toggle: key, prop? } |
lo muestra o lo oculta; con prop: "selected", invierte el selected de un botón o de una tarjeta que se puede tocar |
enable |
{ enable: key } |
lo enciende |
disable |
{ disable: key } |
lo dibuja apagado (guardado en state.ui.enabled) |
focus |
{ focus: key } |
lleva el foco ahí; se descarta en un onClose |
set |
{ set: { key, value } } |
le da un valor a una entrada: un string (como mucho 2.000 caracteres), un booleano, un número, o hasta 500 strings para Chips; en un botón o una tarjeta que se puede tocar, true o false es su selected; no se dispara ningún evento |
clear |
{ clear: key } |
vacía una entrada |
open |
{ open: key } |
abre una ventana emergente declarada (reemplazando una abierta); en una respuesta espera al árbol nuevo; se descarta en un onClose |
close |
{ close: key } |
la cierra cuando es la que está abierta |
{ "type": "Column", "gap": 8, "children": [
{ "type": "Text", "key": "details", "text": "Detalles", "textEn": "Details", "hidden": true },
{ "type": "TextButton", "labelText": "Más", "labelTextEn": "More", "onPressed": { "ui": [{ "toggle": "details" }] } },
{ "type": "TextField", "key": "q", "labelText": "Buscar", "labelTextEn": "Search" },
{ "type": "TextButton", "labelText": "Limpiar", "labelTextEn": "Clear", "onPressed": { "ui": [{ "clear": "q" }, { "focus": "q" }] } }
] }
- Errores: un valor de
setno dispara ningún evento (léelo destate.inputsen la siguiente llamada);state.uies el registro de Kino, pero puedes fijar sus claves tú mismo en un parche destate. selected(propiedades compartidas):{ toggle: key, prop: "selected" }invierte elselectedde un botón o de una tarjeta que se puede tocar y{ set: { key, value: true } }lo fija, enseguida y sin llamada. Kino conserva ese valor solo hasta que tu siguiente dibujo lo vuelve a decir (no está enstate.ui), así que envía también el evento y guárdalo en tu propio estado. Cualquier otropropdescarta la operación (con registro); sinprop,togglesigue significandohidden.