Pantallas (screen, apiVersion 14)¶
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.
Un plugin puede tener su propio lienzo de pantalla completa dentro de Kino: una mini-app. La persona toca tu entrada en el menú (o un botón en tu página de ajustes) y lo que se abre es una pantalla en blanco con la barra de título de Kino (el nombre de tu plugin y un botón para cerrar), cuyo cuerpo entero describe tu JavaScript: columnas, filas, tarjetas, listas, imágenes, campos de texto, listas desplegables, formularios, pestañas, tablas, las mismas tarjetas de póster y filas de Inicio, ventanas emergentes. Kino lo dibuja con su propio aspecto, en el celular (táctil) y en la TV (el control remoto y su foco), a partir del mismo JSON: el contrato no nombra ningún tipo de Android ni ninguna unidad de píxel que solo entienda una plataforma.
Tres ideas sostienen toda la guía:
- Tú describes, Kino dibuja.
screen()devuelve un árbol de objetos simples (nodos). Kino lo valida, descarta lo que está mal con una línea en el registro (nunca un cierre de la app) y dibuja el resto. Nunca tocas una vista, un valor de color ni una fuente. - El estado vive en Kino. Tu entorno de ejecución se cierra después de un rato sin uso, así que nada de lo que guardes
en una variable sobrevive. Kino guarda el estado de la pantalla, se lo pasa a cada llamada y vuelve a llamar a
screen()cada vez que una respuesta lo cambia. - La persona siempre puede salir. El botón de cerrar y Atrás son de Kino y siempre funcionan, responda lo que responda tu código o mientras todavía esté corriendo.
En un Kino anterior, kino.screen es undefined. Esta página es la guía; cada componente, con sus propiedades, un árbol
JSON, su comportamiento en celular y TV y sus límites, está en la referencia: Diseño, contenido y
acciones, Formularios, ventanas y navegación y Datos, comportamiento y
límites. El ejemplo galería los dibuja todos en un aparato.
Una primera pantalla¶
kino-plugin.json:
{
"id": "hello-screen",
"name": "Hola",
"version": "1.0.0",
"apiVersion": 14,
"entry": "plugin.js",
"hosts": ["example.org"],
"capabilities": ["screen"],
"screen": { "label": "Hola", "labelEn": "Hello", "icon": "star", "menuOpens": "screen" }
}
plugin.js:
export async function screen({ state, lang }) {
const children = [
{ type: "Text", text: "Hola", textEn: "Hello", style: "h1" },
{ type: "TextField", key: "name", labelText: "Tu nombre", labelTextEn: "Your name", onSubmitted: "greet" },
{ type: "ElevatedButton", labelText: "Saludar", labelTextEn: "Greet", onPressed: "greet" },
];
if (state.greeting) children.push({ type: "Text", text: state.greeting, style: "h3", color: "primary" });
return { type: "Column", padding: { compact: 16, expanded: 32 }, gap: 12, children };
}
export async function screenEvent({ name, state, lang }) {
if (name !== "greet") return null; // the reserved "open" event comes first: nothing to load here
const who = String(state.inputs.name ?? "").trim(); // every input's value, by its key
if (!who) return { toast: lang === "es" ? "Escribe tu nombre" : "Type your name" };
return { state: { greeting: (lang === "es" ? "Hola, " : "Hello, ") + who } }; // Kino merges it and calls screen() again
}
node sdk/validate.mjs .
node sdk/run.mjs . screen
node sdk/run.mjs --state '{"inputs":{"name":"Ana"}}' . screenEvent greet
node sdk/run.mjs --device tv . screen
Un plugin con screen no necesita resolve, search ni home: esa capacidad puede ser la única que declare, y no
agrega ninguna línea de consentimiento (no llega a nada a lo que tus hosts no llegaran ya). hosts igual necesita una
entrada cuando no hay un ajuste url, aunque la pantalla nunca haga peticiones (el ejemplo de la calculadora nombra su
sitio de documentación).
Configuración recomendada: una sola barra compacta¶
De fábrica una pantalla tiene dos barras: la barra de título propia de Kino (el nombre de tu plugin y Cerrar) y, debajo, tu
AppBar. En cada pantalla de tu plugin, pon como raíz un Scaffold cuyo AppBar tenga mergeWithKinoBar: true (una barra:
tu leading donde estaba Cerrar, tu title donde estaba el nombre del plugin; apiVersion 19) y dense: true (en un
celular, 4 dp arriba y abajo de la fila en vez de 16). Dale al leading una salida real: { close: true } en la portada, un
regreso a la vista anterior en las demás. La TV ignora dense y un panel del reproductor ignora las dos. La ruta sin nombre
es main: trátala como tu portada. El comportamiento completo, la tabla por ventana y las recetas (un lector, un carrusel,
una tarjeta del Home que abre una pantalla, búsqueda en el campo, filtros en una hoja) están en
Diseño, contenido y acciones y en las recetas.
{ "type": "Scaffold",
"appBar": { "type": "AppBar", "mergeWithKinoBar": true, "dense": true, "title": "Catálogo", "titleEn": "Catalog",
"leading": { "type": "IconButton", "icon": "close", "labelText": "Cerrar", "labelTextEn": "Close", "onPressed": { "close": true } } },
"body": { "type": "SingleChildScrollView", "children": [] } }
Prefiere un Skeleton a un spinner mientras algo carga, y una hoja inferior con un campo de búsqueda a una fila larga de
chips. Una pantalla dibuja como mucho 600 nodos: mira los límites de pantalla.
El bloque screen del manifiesto¶
| Campo | Regla |
|---|---|
label |
Obligatorio, de 1 a 20 caracteres: el nombre de la entrada del menú (labelEn, el nombre en inglés). |
icon / iconFile |
Uno de los nombres de ícono de Kino (los 50 de la tabla de íconos, refresh entre ellos) o un PNG de 96×96 px con fondo transparente, de máximo 24 KB; nunca los dos. No hace falta sin "menu" en opensFrom. |
menuOpens |
Qué abre la entrada del menú: "section" (las filas de tarjetas de Kino, necesita tu section), "screen" (el lienzo) o "both" (dos entradas, necesita section). Por defecto: "section" cuando declaras una section (nada cambia para un plugin que ya existe); si no, "screen". Un destino sin su export se rechaza al instalar. |
opensFrom |
Desde dónde se abre la pantalla: "menu" (el ícono: la barra lateral de la TV, la franja de Inicio del celular) y/o "settings" (un botón arriba de la página de ajustes de tu plugin). Por defecto ["menu"], nunca vacío. Sin "menu" no hay ícono ni entrada: icon, iconFile y menuOpens se ignoran. |
settingsButton |
{ "label", "labelEn" }, cada uno de 1 a 40 caracteres: el nombre de ese botón de la página de ajustes (por defecto, el de Kino: «Abrir pantalla» / "Open screen"). |
settingsIn |
Dónde se muestran tus ajustes: "settings" (el formulario de Kino en Ajustes), "screen" (solo tu pantalla: Kino esconde su formulario en tu pestaña, en tu tarjeta de «Mis plugins» y en el Configurar de un proveedor de sincronización mientras la pantalla pueda abrirse, y esos lugares abren tu pantalla) o "both" (por defecto). "screen" necesita una forma de entrar (menuOpens "screen"/"both", o "settings" en opensFrom); ver Ajustes dentro de una pantalla. |
replaces |
["categories"]: tu pantalla toma el lugar de tu grupo en las Categorías de Kino; ver go. Necesita la capacidad browse y el export categories. |
every |
Temporizadores que corren mientras la pantalla está abierta, como el every de la raíz de un árbol. Uno mal escrito se descarta y queda en el registro; nunca se rechaza el plugin. |
adult |
true: la entrada solo se ve mientras el código 18+ de la persona está desbloqueado. |
Dónde aparece la entrada: en la barra lateral de la TV, después de Categorías y de las secciones (las 3 primeras pantallas
de plugins directamente, las demás dentro de «Más pantallas»), y como un chip en la franja de Inicio del celular; solo para
un plugin activado que no necesita configuración, como una section. Con opensFrom: ["settings"] el plugin no tiene
ícono: su página de ajustes muestra el botón arriba y, con settingsIn: "screen", ese botón es todo lo que muestra la
página además de los interruptores propios de Kino (el formulario vuelve cuando la pantalla no puede abrirse: pantallas
apagadas, 18+ bloqueado, ajustes por llenar). Atrás vuelve a la página de ajustes. Kino tiene un interruptor remoto para
todas las pantallas de plugins: apagado, las entradas se esconden en el acto y una pantalla abierta se cierra; el mismo
interruptor detiene las salas y los trabajos en segundo plano.
Los exports: screen y screenEvent¶
export async function screen({ state, route, device, size, lang, activeTheme, installed }) { return /* the root node */; }
export async function screenEvent({ name, arg, value, state, route, device, lang, activeTheme, installed }) { return /* an answer, or null */; }
screenes una vista pura. Con el estado, devuelve el árbol. Kino la llama cuando se abre la pantalla, después de cada respuesta que trae un parche destate, después de un cambio de ruta y cuando la ventana cambia de clase de tamaño (al girar, al redimensionar). No hagas trabajo de red aquí: devuelve lo que tiene el estado (unSkeletonmientras carga).screenEventreacciona. Kino la llama cuando la persona actúa sobre un nodo que nombra un evento. La primera llamada después de abrir la pantalla es el evento reservadoopen: carga tus datos ahí (conkino.fetch, tu caché) y responde un parche destate.openestá reservado: ningún nodo puede usar ese nombre.state: la copia de Kino, en JSON: tus propias claves, másinputs(cada campo de la pantalla por su clave, ver Acciones, eventos y estado) yui(lo que Kino hizo localmente:hidden,enabled,open). Máximo 64 KB. Vive solo mientras la pantalla está abierta: cerrarla lo borra, así que guarda enkino.storagelo que tenga que sobrevivir.route:{ name, params, args? }; en la raíz,{ name: "main", params: {} }. Una respuesta conroute: { push: "detail", params }entra una pantalla más adentro de tu lienzo y{ pop: true }vuelve; Atrás saca una ruta empujada antes de cerrar el lienzo.argsviene de ungo.screenque la abrió.device"phone","tv"o"desktop";size{ widthClass, heightClass, orientation }con las clases de ventana de Material (compactpor debajo de 600 dp,mediumde 600 a 839,expandedde 840 en adelante);lang"es"o"en";activeTheme(apiVersion 18) el id de tu tema deappThemesactivo ahora, o null (screenEventtambién lo recibe);installed(Kino 0.9.81){ "<owner/name>": true | false }por cada entrada delrecommendsde tu manifiesto ({}si no hay ninguna): si ese plugin está instalado ahora; Kino vuelve a llamar ascreencuando cambia (la puerta de instalación del protocolo entre plugins). Puedes devolver un árbol distinto por aparato, pero los valores por tamaño suelen hacerlo mejor.- Un entorno de ejecución por plugin.
kino.storage,kino.config, las cookies y los secretos se comparten con tus otros exports, así que un catálogo (home,search...) puede alimentar la pantalla y al revés; las llamadas se ponen en fila con tus otras llamadas. - Fallas. Una llamada que se pasa del tiempo (20 s), o un primer dibujo que Kino no puede hacer, muestra el estado de error de la pantalla (tu nombre, «Reintentar», cerrar), nunca una pantalla en blanco; después, un dibujo que se pasa del presupuesto conserva el último cuadro bueno y tres fallas seguidas muestran el estado de error. El tiempo agotado de una pantalla nunca cuenta para "No responde": una mini-app rota nunca apaga tu catálogo, ni al revés.
Mezclar. screen es una capacidad entre las demás, nunca un tipo de plugin: un mismo manifiesto puede declarar un
catálogo, channels, subtitles, una section, el panel del reproductor y screen a la vez. Los exports tienen nombres
distintos, así que nada choca; con menuOpens: "both" la persona recibe tu sección y tu pantalla como dos entradas.
Nodos y widgets¶
Cada nodo es { type, ...properties }. Estas propiedades funcionan en cualquier nodo (la lista completa está en
propiedades comunes y propiedades compartidas):
key: su id, único en la pantalla. Obligatorio en los campos (nombra el valor enstate.inputs), en unpopup, unExpansionTiley unMaterialBannerque se puede descartar; los demás nodos reciben una clave generadaauto-<n>(el prefijoauto-es de Kino: no lo uses). Un campo sin clave o con una clave repetida se descarta.onTap,onLongPress(el toque de un botón esonPressed),arg: lo que hace un toque, ver Acciones, eventos y estado.enabled,hidden: cómo se ve el nodo al empezar; las operaciones localesuiy los árboles siguientes lo cambian.devices(["tv"],["phone", "desktop"]) ysizes(["expanded"]): el nodo solo se dibuja ahí. Un nombre desconocido descarta el nodo.testKey(de 1 a 64 caracteres): para pruebas y herramientas; nunca se dibuja.- Compartidas por una familia de nodos, con un solo significado en todas partes:
autofocus(un nodo que toma el foco: adonde va el foco cuando un dibujo lo dejó en ninguna parte; el control remoto de la TV cae ahí),selected(un botón o una tarjeta cononTap: el aspecto de seleccionado de Kino;setytoggledeuiconprop: "selected"lo cambian) ybadge("dot"o{ text, textEn?, color? }en un botón, una tarjeta cononTap, una pestaña deTabBary la pestaña del cajón de un panel). visible: false(lo esconde, igual quehidden: true) ytooltip(tooltipEn; en un nodo que hace algo: la pista de Kino al mantener presionado, tras un momento de foco en la TV y para un lector de pantalla, máximo 80 caracteres, nunca información esencial) (tooltip).- Las propiedades de estilo de la siguiente sección, entre ellas
alignSelf,textAlign,border,elevation,background,minWidth/maxWidth/maxHeight,positioneden el hijo de unStack,opacityyanimate.
Los textos de Kino son siempre suyos; los tuyos llevan un gemelo en inglés con el sufijo En (text/textEn,
labelText/labelTextEn, title/titleEn...), elegido según el idioma de la persona.
| Nombre | Nombre anterior | Qué es | Sus propiedades | Como campo |
|---|---|---|---|---|
Column |
col |
sus hijos en una columna | ||
Row |
row |
sus hijos en una fila; wrap: true es la cuadrícula de doce columnas |
stackOnNarrow, wrap |
|
Stack |
box |
sus hijos apilados uno sobre otro | ||
Card |
card |
la tarjeta de Kino alrededor de sus hijos | variant, flush |
|
Spacer, SizedBox |
spacer |
espacio vacío (SizedBox, su width/height; Spacer, su parte de flex) |
||
Divider |
divider |
una línea fina | ||
SingleChildScrollView |
scroll |
sus hijos, con desplazamiento | direction |
|
GridView |
grid |
sus hijos en columns |
columns |
|
Text |
text |
texto simple (text, textEn) |
style, maxLines, bold, time, timeFormat |
|
Image |
image |
una imagen https en un host público (url, alt, fallback) |
aspect |
|
Icon |
icon |
uno de los íconos de Kino (name) |
||
Badge |
badge |
una etiqueta pequeña (text) |
||
LinearProgressIndicator |
progress |
una barra de progreso (value, labelText) |
||
CircularProgressIndicator |
loading |
el indicador de carga de Kino (text) |
||
ListView |
list |
una lista perezosa de items (nodos), empty cuando no hay ninguno, cargar más |
columns, stickToBottom, onEndReached, loadingMore, done, newItemsHint |
|
Button, ElevatedButton, TextButton, IconButton |
button |
un botón (labelText, icon, onPressed, confirm, submit) |
variant |
|
TextField |
textInput |
un campo de texto (kind, maxLength, value, onSubmitted; un trailingIcon adentro con trailingLabel y onTrailingTap; obscureText lo enmascara) |
trailingIcon, obscureText |
valor en state.inputs; reglas de formulario: required, minLength, maxLength, pattern, errorText; bind guarda un ajuste text |
TextField (varias líneas) |
textArea |
un campo de texto de varias líneas (multiline: true o maxLines mayor que 1) |
valor en state.inputs; reglas de formulario: required, minLength, maxLength, pattern, errorText; bind guarda un ajuste text |
|
DropdownButton |
dropdown |
una elección entre options |
valor en state.inputs; reglas de formulario: required, errorText; bind guarda un ajuste select o text |
|
Switch |
toggle |
un interruptor de encendido y apagado | valor en state.inputs; reglas de formulario: required, errorText; bind guarda un ajuste toggle |
|
Checkbox |
checkbox |
una casilla | valor en state.inputs; reglas de formulario: required, errorText; bind guarda un ajuste toggle |
|
RadioGroup |
radioGroup |
una elección entre options |
valor en state.inputs; reglas de formulario: required, errorText; bind guarda un ajuste select o text |
|
Slider |
slider |
un número entre min y max (step) |
valor en state.inputs; bind guarda un ajuste text |
|
Chips |
chips |
una o varias (multiple) elecciones entre options |
valor en state.inputs; reglas de formulario: required, minLength, maxLength, errorText; bind guarda un ajuste select o text |
|
TabBar |
tabs |
una fila de pestañas (tabs, value, onChanged); su valor NO está en state.inputs |
||
emptyState |
emptyState |
el estado vacío de Kino (title, text, icon) |
||
errorState |
errorState |
el estado de error de Kino (title, text, icon) |
||
titleCard |
titleCard |
una tarjeta de póster de Inicio para un item |
size |
|
titleRail |
titleRail |
una fila de Inicio: title, items, ref para su "Ver más" |
size, onEndReached, loadingMore, done |
|
titleGrid |
titleGrid |
tarjetas de Inicio en una cuadrícula (items) |
columns, onEndReached, loadingMore, done |
|
heroCard |
heroCard |
el banner de una sección: title, text, image, máximo 2 buttons |
||
popup, AlertDialog, BottomSheet, PopupMenuButton |
popup |
una ventana emergente declarada en el árbol (key, kind), abierta con una operación ui |
onClose, buttons, items, anchor |
|
Form |
form |
campos con un solo envío, revisados por Kino antes de tu código (onSubmitted) |
||
settings |
settings |
el formulario de ajustes propio de Kino para tu plugin (keys, onSaved) |
onSaved |
|
MaterialBanner |
banner |
una línea de aviso en el color de un rol (role, title, text, action, dismissible) |
||
ExpansionTile |
accordion |
secciones que se abren y se cierran (key, items, multiple) |
||
Skeleton |
skeleton |
un marcador de lugar mientras algo carga | shape, lines |
|
QrImage |
qr |
un código QR que Kino dibuja en el aparato (value; expiresInMs o expiresAt con la cuenta regresiva de Kino, onExpire, renewBeforeMs) |
size, expiresInMs, expiresAt, renewBeforeMs, onExpire |
|
NumberStepper |
stepper |
un número dibujado [ − ] valor [ + ] (min, max, step, decimals, editable) |
valor en state.inputs; reglas de formulario: required, errorText; sin bind |
|
DataTable |
table |
una tabla de TableRow con TableCell (text o children, colSpan, crossAxisAlignment) |
header, wrap, zebra, columns |
|
FloatingActionButton |
fab |
el botón flotante de Kino sobre la parte de abajo de la pantalla (icon, labelText, onPressed), uno por pantalla |
fabPosition |
|
ListTile |
listTile |
una fila de una lista: leading, title, subtitle, trailing, un toque |
dense, leading, trailing, subtitle |
|
CircleAvatar |
avatar |
un círculo con una imagen, iniciales o un ícono (image, text, icon, backgroundColor) |
borderRadius, backgroundColor |
|
PageView |
pageView |
páginas que se deslizan, con los puntos de Kino (initialPage, onPageChanged, autoPlayMs); viewportFraction < 1 es un carrusel |
viewportFraction, padEnds, initialPage, onPageChanged, autoPlayMs |
|
Scaffold |
scaffold |
la raíz de una pantalla con un appBar, un body, un floatingActionButton y un bottomNavigationBar (dibujado en modo de llenado) |
||
AppBar |
appBar |
la barra de arriba de un Scaffold: title, leading, hasta cuatro actions, un TabBar en bottom |
||
NavigationBar |
navigationBar |
la barra de abajo de un Scaffold, de 2 a 5 items (value, onChanged) |
||
steps |
steps |
un flujo de configuración con el aspecto de Kino: items hechos, el actual (abierto, con sus children) o pendientes; onStepTap deja tocar un paso hecho |
items, onStepTap |
|
pages |
pages |
páginas a pantalla completa bajo la barra de progreso de Kino, que se deslizan o se mueven con Izquierda y Derecha; el lugar queda en state.inputs; sin reproducción automática (apiVersion 17, pages) |
onPageChanged |
Un TextField enmascarado (obscureText: true) es la excepción de su fila: solo se ata a un ajuste password (ver
campos secretos). La barra del Scaffold va debajo de la barra de título de Kino, que
ningún plugin reemplaza ni tapa (Scaffold).
Un type desconocido se descarta con una línea en el registro y el resto se dibuja. Revisa que exista un widget antes
de depender de uno que agrega un Kino más nuevo: kino.screen.names lista los nombres de tipo que dibuja este Kino tal
como los escribe esta guía, kino.screen.widgets los mismos con sus nombres anteriores, y kino.screen.version es el
número propio del contrato de pantallas (1 por ahora).
const has = (name) => typeof kino.screen === "object" && kino.screen.names.includes(name);
const table = has("DataTable") ? { type: "DataTable", /* ... */ } : { type: "Column", /* the same rows as text */ };
No están en esta versión: deslizar para actualizar, botones segmentados, autocompletado y cuadros combinados, selectores de fecha y hora, un control deslizante de rango, una calificación, elementos de lista que se descartan o se reordenan, texto enriquecido, gráficos, tarjetas de continuar viendo y de canales, y campos de archivo.
Nombres al estilo de Flutter y los anteriores¶
Quien conoce Flutter encuentra los mismos nombres: Column, Row, Text, TextField, Switch, ListView,
AlertDialog, y las propiedades width, height, mainAxisAlignment, crossAxisAlignment, flex, borderRadius,
onPressed, onChanged, onSubmitted, hintText, labelText. Son la escritura documentada (esta guía, kino.d.ts, los
ejemplos). Los nombres anteriores en minúscula (col, row, textInput, w, justify, onTap en un botón...) se
siguen aceptando como alias: las dos escrituras se leen como el mismo árbol. La tabla completa de alias está en
Nombres al estilo de Flutter. Las reglas:
- Usa una sola escritura. Cuando un nodo tiene las dos, gana la de Flutter y el choque queda en el registro (un
nullen la de Flutter cuenta como ausente). - Un tipo que implica algo lo fija:
ElevatedButton,TextButton,IconButtonson unButtonconvariantprimary,text,icon;AlertDialog,BottomSheet,PopupMenuButtonson unpopupconkinddialog,sheet,menu. Un valor distinto que pongas se reemplaza y queda en el registro.secondaryno tiene otro nombre:{ type: "Button", variant: "secondary" }. - Un
TextFieldconmultiline: trueo conmaxLinesmayor que 1 en cualquier clase de tamaño tiene varias líneas. onPressedes solo de los botones; en otros nodos se ignora y queda en el registro.- Solo se renombran nodos. Los campos de
dialog,sheetymenude una respuesta, losbuttonsde un diálogo, lositemsde un menú, laactionde un banner y las entradas deoptionsytabsconservanlabelyonTap. - Los componentes propios de Kino conservan sus nombres (
titleCard,titleRail,titleGrid,heroCard,emptyState,errorState,popup,settings). - El
Stepperde Flutter es otro widget (un asistente): ese nombre aquí es desconocido (se descarta); el control[−] n [+]esNumberStepper.OutlinedButtonyWrapno existen (unRowconwrap: truees la cuadrícula de doce columnas). - Las líneas del registro usan la escritura anterior ("button dropped", "textInput needs a key"), la que Kino lee por dentro.
Diseño, estilo y valores por tamaño¶
El estilo sale de escalas fijas, nunca de valores libres; un valor fuera de su escala se descarta y queda en el registro.
| Propiedad | Nombre anterior | Valores |
|---|---|---|
padding |
0, 4, 8, 12, 16, 24, 32, 48, o por lado (x, y, top, end, bottom, start) |
|
margin |
0, 4, 8, 12, 16, 24, 32, 48, o por lado | |
gap |
0, 4, 8, 12, 16, 24, 32, 48 | |
borderRadius |
radius |
none, small, medium, large, full, o por esquina (topStart, topEnd, bottomStart, bottomEnd; la que falte, medium) |
width |
w |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 |
height |
h |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 |
minHeight |
minH |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 |
fill |
true: todo el ancho del padre |
|
flex |
weight |
de 1 a 12: su parte de un Row o un Column |
crossAxisAlignment |
align |
start, center, end, stretch: a través del eje principal (en un Text, el párrafo) |
mainAxisAlignment |
justify |
start, center, end, spaceBetween, spaceAround: a lo largo del eje principal |
color |
primary, secondary, surface, muted, warning, error, onPrimary, primaryContainer, surfaceVariant |
|
span |
de 1 a 12 o "auto", en un Row con wrap: true |
|
offset |
de 0 a 11, en un Row con wrap: true |
|
maxWidthFraction |
de 0.25 a 1 en pasos de 0.05: como mucho esa fracción del ancho del padre (exactamente, con fill) |
|
alignSelf |
start, center, end, stretch: este hijo a través de su Row o Column |
|
textAlign |
start, center, end, justify: el párrafo de un texto |
|
border |
{ width?, color? } en una caja: de 0 a 8 dp, un rol de color |
|
elevation |
de 0 a 24 en un Card o un Stack: la sombra de Kino |
|
background |
un rol de color: el relleno de una caja | |
minWidth |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | |
maxWidth |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | |
maxHeight |
16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 | |
positioned |
{ top?, left?, right?, bottom?, width?, height? } en un hijo de Stack, en dp o "25%" |
|
opacity |
de 0 a 1 | |
animate |
{ duration?, curve? }: los cambios se deslizan |
Cada una está explicada en detalle en Estilo.
Toda propiedad de estilo o de diseño de cualquier nodo puede ser un mapa por tamaño: { compact?, medium?, expanded? }.
Una clase que falte en el mapa toma la siguiente más pequeña que esté; si no hay ninguna, el valor por defecto de Kino.
Kino resuelve los mapas antes de dibujar, así que quien dibuja solo ve valores simples
(valores por tamaño):
{ type: "GridView", columns: { compact: 1, medium: 2, expanded: 3 }, gap: { compact: 8, expanded: 16 }, children }
Dos consecuencias: un nodo con un valor inválido en una sola clase de tamaño se descarta entero (en todas las clases),
y un mapa por tamaño que mezcla clases con otras claves se descarta. Usa devices/sizes para dibujar un nodo solo en
algunos lugares.
crossAxisAlignmenten un contenedor alinea sus hijos a través de su eje principal (la altura de unRow, el ancho de unColumn); en unTextes la alineación del párrafo.stretchen unRowsimple se dibuja comostart(las filas no miden su contenido).- El lienzo no se desplaza solo: un
Columnraíz más alto que la ventana se corta. Pon una página larga dentro de unSingleChildScrollView(o de unListView, que es perezoso). UnListViewo una fila de títulos dentro de algo que se desplaza en la misma dirección se dibuja entero de una vez (con tope: 60 títulos). - La cuadrícula de doce columnas (la de Bootstrap, fila de doce columnas): un
Rowconwrap: truepone sus hijos en líneas de 12 columnas. Cada hijo ocupa suspan(de 1 a 12, o"auto", el valor por defecto) después de suoffset; uno que no cabe en lo que queda de una línea empieza la siguiente; losautode una línea se reparten lo que dejan losspanfijos, y un botón,BadgeoIconenautonunca queda más angosto que su propio ancho (empieza la línea siguiente en su lugar, sin cortar su texto);gapva entre celdas y entre líneas; un hijo escondido no deja hueco. Una línea es tan alta como su celda más alta y, por defecto (o concrossAxisAlignment: "stretch"), cadaCardo celda contenedora (Column,Row,Stack,GridView,Form) sinwidth/heightfijo se dibuja con esa altura, así que una cuadrícula de tarjetas queda pareja; un botón, una etiqueta o una imagen con tamaño conserva su propia altura arriba;start,centeroenddejan cada celda con su propia altura. Una línea con algo que no se puede medir (una lista perezosa, una fila de títulos, pestañas, una tabla, el formulario de ajustes) no se estira. En una fila que envuelve,flex,mainAxisAlignmentystackOnNarrowno significan nada; un hijo toma su ancho natural salvo confill: true.spanyoffseten cualquier otro lugar se ignoran y quedan en el registro. Dentro de un desplazamiento lateral, las doce columnas se reparten sobre 600 dp. Cardconflush: truequita su propio relleno y recorta sus hijos a su forma redondeada, así que unaImagearriba va de borde a borde; pon tú el relleno de los hijos de texto (Card).
Una cuadrícula de tarjetas, una por línea en un celular, dos en una ventana mediana, tres en una TV:
{ type: "Row", wrap: true, gap: 12, children: stories.map((s) => ({
type: "Card", key: "story-" + s.id, flush: true, span: { compact: 12, medium: 6, expanded: 4 },
onTap: { event: "read", arg: s.id },
children: [
// No picture: leave url out and the fallback is drawn (an empty url draws it too, but logs).
{ type: "Image", ...(s.image ? { url: s.image } : {}), aspect: "16:9", alt: s.title,
fallback: { type: "Stack", color: "surface", children: [{ type: "Text", text: s.source, style: "h3" }] } },
{ type: "Column", padding: 12, gap: 4, children: [
{ type: "Text", text: s.title, style: "h4", maxLines: 3 },
{ type: "Text", text: s.source, style: "caption", color: "muted" },
] },
],
})) }
Una Image solo acepta URL https en un host público (sin declararlo, como toda imagen en Kino). Su fallback es un nodo
que se dibuja en la caja de la imagen cuando la imagen falla o no hay url (con un fallback, una imagen cuya url falta
o se rechaza se conserva): solo Column, Row, Stack, Card, Spacer, SizedBox, Divider, Text, Icon,
Badge, Skeleton e Image, a cualquier profundidad, y nada adentro se puede tocar. Sin él, una imagen que falla muestra
la marca de Kino (Image).
Texto y colores¶
- El
stylede unTexteshero(apiVersion 17: 72 sp con interlínea de 72 sp en el celular, 90 sp en la TV, en negrita, un escalón por encima deh1, para un número grande; un Kino anterior a apiVersion 17 no lo conoce y dibujap, con registro, así que comprueba la versión de la API o deja el número legible enp), deh1ah5,p(el valor por defecto),captionolabel; los nombres anterioresdisplay,title,subtitleybodyse leen comoh1,h3,h4yp, y uno desconocido esp, con una línea en el registro. Kino los pasa a su propia escala tipográfica (en el celular, deh1headlineLarge hastapbodyMedium) y en la TV cada paso crece 1.25, así que el orden se mantiene a tres metros. Se respeta la escala de fuente de la persona. - Los títulos ya son negrita;
bold: truepone en negrita cualquier estilo,bold: falsenunca adelgaza un título.maxLinescorta con puntos suspensivos. - Un plugin nunca fija una familia de fuente, un tamaño, cursiva ni un color libre.
colorrecibe un rol (primary,secondary,surface,muted,warning,error,onPrimary, y los roles contenedoresprimaryContainerysurfaceVariant, cuya caja le da a su texto el color de encima correspondiente), pintado con la paleta de Kino (elthemede tu manifiesto tiñeprimarycuando cumple las reglas de contraste). Un rol que no se leería sobre su superficie se acerca al color de texto propio de la superficie hasta que se lee (4.5:1);onPrimary, que no se lee sobre una superficie simple, vuelve al valor por defecto, con una línea en el registro una vez por nodo. - El texto es simple: nada en él es un enlace ni marcado, y los saltos de línea se conservan. La escritura de derecha a izquierda sigue a la app.
El detalle está en Text y Colores.
Acciones, eventos y estado¶
Lo que hace un toque es una acción: el onTap, onLongPress u onPressed de un nodo, el onChanged y el
onSubmitted de un campo, el onSubmitted de un formulario. Cuatro formas:
onTap: "refresh" // an event for screenEvent; its arg is the node's arg
onTap: { event: "read", arg: "story-42" } // an event with its arg (at most 4,096 characters)
onTap: { ui: [{ toggle: "details" }], event: "seen" } // local operations first (no plugin call), then the event
onTap: { go: { title: { ref, kind: "movie" } } } // somewhere in Kino, no plugin call (also { ui, go } and a bare go object)
Las operaciones locales ui corren en el acto, sin ida y vuelta, sobre nodos de la misma pantalla por su key:
show, hide, toggle, enable, disable, focus, set ({ set: { key, value } }: un texto de hasta 2.000
caracteres, un booleano, un número, o hasta 500 textos para Chips), clear (el valor de un campo), y open / close
(una ventana emergente declarada). Máximo 8 por acción; una clave desconocida se ignora y queda en el registro. Lo que hacen
se guarda en state.ui (hidden y enabled por clave, open con los elementos abiertos de cada ExpansionTile), así
que lo ves en tu siguiente llamada y un nuevo dibujo lo conserva; tú mismo puedes fijar esas claves en un parche de
state. El selected de un botón o de una tarjeta que se toca es la única excepción: { toggle: key, prop: "selected" }
lo invierte y set con true o false lo fija, y dura solo hasta que tu siguiente dibujo lo vuelva a decir
(operaciones locales ui).
screenEvent recibe name (el evento), arg, value (el valor del campo que lo disparó), state, route, device
y lang.
state.inputs tiene cada campo de la pantalla por su clave: lo que fijó la persona o tu código; si no, el valor que
muestra el árbol (se llena en cada llamada y nunca se guarda, así que un árbol que cambia un valor por defecto es lo que
trae la siguiente llamada). Tipos: un TextField, un texto; Switch y Checkbox, un booleano; Slider, un número;
DropdownButton y RadioGroup, el valor de la opción (o null); Chips, un valor (o una lista con multiple);
NumberStepper, su valor como texto ("2.50"). Para fijar lo que muestra un campo (vaciar un buscador, llenar de
antemano un formulario, elegir una opción), responde { state: { inputs: { <key>: value } } }: se ve en el acto y no
dispara ningún evento. Un TabBar no es un campo: su value no está en state.inputs; guarda la pestaña elegida, que
llega en el value de su evento onChanged, en una clave de estado tuya.
Cómo fluyen los eventos:
- Un evento a la vez por pantalla; el siguiente espera (máximo 8 en espera) y van separados por 100 ms, nunca se descartan
por llegar rápido. Un
onChangedmás nuevo del mismo campo reemplaza a uno anterior que todavía espera. Una respuesta que llega después de cerrar la pantalla se descarta. - En el celular, el
onChangedde un campo de texto espera a que la persona deje de escribir (300 ms); en la TV se dispara una vez, cuando la persona acepta el diálogo de texto (En la TV). - Un parche de
statese mezcla clave por clave (nullborra una clave) con el estado a partir del cual se calculó tu respuesta; un parche que llevaría el estado por encima de 64 KB se rechaza y se conserva el estado anterior, con una línea en el registro.screen()vuelve a correr solo después de una respuesta que traestate(o de un cambio de ruta). - Una llamada que se pasa del tiempo muestra el estado de error en el acto. Una llamada que lanza un error o responde algo que Kino no puede leer cuenta: tres seguidas muestran el estado de error (la primera ya lo muestra mientras no hay ningún cuadro); una respuesta buena pone la cuenta en cero.
Lo que puede traer una respuesta¶
Todos los campos son opcionales; null significa nada que hacer.
| Campo | Qué hace |
|---|---|
state |
Un parche que se mezcla con el estado; después screen() vuelve a correr. |
toast / toastEn |
Un mensaje corto abajo: un texto, o { text, textEn?, role?, action?: { label, labelEn?, event, arg? }, ms? } (ms de 2.000 a 8.000, por defecto 3.500). Uno a la vez: uno más nuevo lo reemplaza; su acción manda su evento una vez. |
dialog, sheet, menu |
Una ventana emergente armada por la respuesta (Ventanas emergentes). Si hay más de una, gana el diálogo y después la hoja. |
ui |
Operaciones locales, las mismas que en una acción (máximo 8): { open: "story" } abre una ventana emergente declarada, { close: "story" } la cierra. |
go |
Algún lugar de Kino (go). |
route |
{ push: "<name>", params? } o { pop: true }: una pantalla tuya más adentro del lienzo. |
focus |
La key del nodo que debe tomar el foco. |
close |
true cierra la pantalla. |
config |
Tus ajustes para escribir (Ajustes dentro de una pantalla). |
enableJob |
Un id de tarea (apiVersion 17): enciende la fila propia de Kino de esa tarea, solo después del toque de la persona; véase Las filas de Kino en Ajustes. |
share |
{ key } (apiVersion 17): Kino dibuja ese nodo como una imagen de 1080×1350, con su propia línea que nombra a tu plugin, y abre la hoja de compartir del sistema (Compartir una imagen). Solo después del toque o envío de la propia persona; una TV lo rechaza, con registro, así que oculta el botón según device. |
Algunas respuestas no vienen de un toque de la persona, así que conservan menos: la respuesta al open reservado pierde su
go (salvo go.screen), así que abrir una pantalla nunca reproduce ni abre nada por sí solo; la de un
temporizador conserva solo state, toast, close y config; la de cargar más nunca cambia la ruta; la de
un onClose de una ventana emergente no conserva ventanas emergentes, focus, go, route, share ni enableJob. Los campos descartados
quedan en el registro.
Ventanas emergentes, avisos y banners¶
Una ventana emergente a la vez; abrir otra la reemplaza; Atrás la cierra antes que cualquier otra cosa; nunca tapa la barra de título de Kino, y Kino siempre dibuja su botón de cerrar: una X sola (un lector de pantalla dice «Cerrar», «Close» en inglés). Dos formas de mostrar una:
- Desde una respuesta:
dialog(title,bodycomo texto o nodos, máximo 3buttons; un botón sineventla cierra),sheet(una hoja inferior en el celular, un cajón lateral en la TV;bodycomo texto o nodos) omenu(de 1 a 8items:label,icon,onTap; el menú se cierra primero). La ventana de una respuesta nunca lleva unForm, unExpansionTile,bindni el nodosettings. Ver Dialog, Sheet y Menu. - Declarada en el árbol: un nodo
popup(AlertDialog,BottomSheet,PopupMenuButton) con unakey, escondido hasta que una operaciónuilo abre. Su cuerpo es parte de tu árbol: puede tener formularios y campos, y tu siguiente dibujo lo actualiza (ventanas declaradas).
La forma segura de abrir una ventana declarada con contenido nuevo es desde la respuesta, no desde el toque: el toque
manda el evento, la respuesta parcha el estado y trae ui: [{ open: "story" }]; Kino la abre cuando ya dibujó el árbol
nuevo, así que la ventana nunca muestra el cuerpo de la noticia anterior (un Atrás antes de eso lo cancela). Después del
Guardar de la propia ventana, ciérrala de la misma forma:
// tap: { type: "Card", onTap: { event: "read", arg: s.id }, ... }
// in screenEvent: case "read": return { state: { reading: arg }, ui: [{ open: "story" }] };
// case "saved": return { state: { terms }, ui: [{ close: "addTerm" }], toast: "Guardado" };
{ type: "AlertDialog", key: "story", onClose: "storyClosed", children: [/* built from state.reading */],
buttons: [{ label: "Cerrar", labelEn: "Close" }] }
onClose(un nombre de evento, o{ ui?, event?, arg? }) corre después de que la persona cerró la ventana (Atrás, el botón de cerrar de Kino, un toque afuera), nunca después de sus propios botones, un elemento de menú, tucloseu otra ventana que la reemplace. Úsalo para vaciarstate.reading. Su evento no es un toque: nada dekino.qr.scan, nigo.titleByIdsnigo.url, y su respuesta no abre ventanas, no mueve el foco ni va a ninguna parte (se descarta, con una línea en el registro); ungo,openofocusdentro del propioonClosese descarta.titlees opcional: con uno, la X de Kino cierra la fila del título; sin él (uno en blanco cuenta como ninguno) no se dibuja una fila vacía y la X empieza (a la izquierda) la fila de abajo, con tus botones juntos al final (a la derecha), así que la X nunca queda al lado de tu acción principal; los botones que no caben pasan a más líneas, siempre al final. No pases" "para esconderlo.- Una ventana cuyo nodo está
hiddenno se puede abrir. Si una ventana está abierta o no, no aparece enstate.ui. - Un menú no queda pegado a lo que lo abrió: en el celular es una lista de acciones abajo del lienzo; en la TV va centrado.
- En la TV, un cuerpo largo se desplaza con Abajo y Arriba; deja un botón al final (el D-pad cae ahí después del texto).
Un MaterialBanner es una línea de aviso a lo ancho de la pantalla en el color de Kino para su role (info,
warning, error, success), con un title opcional, un botón action y, cuando es dismissible (necesita una
key), el botón de cerrar de Kino: lo esconde en el acto (state.ui.hidden) y manda el evento dismiss con la clave del
banner como arg (MaterialBanner). Un aviso (toast) con action se alcanza en la TV
sin robar el foco: Abajo desde el final del árbol llega a él (Arriba o Atrás salen), y la tecla Menú o Play/Pausa del
control lo ejecuta; el aviso lo dice en palabras (Avisos).
Listas, cargar más y las tarjetas de Kino¶
Un ListView es perezoso: dale items (nodos, cada uno con su propia key, máximo 500), un nodo empty para cuando no
hay elementos, y columns para una cuadrícula. Carga más con onEndReached en un ListView, un titleRail o un
titleGrid (ListView):
{ type: "ListView", items, onEndReached: { event: "more" }, loadingMore: state.loading === true, done: state.done === true }
Kino lo manda una vez cuando el último elemento entra a la vista, y de nuevo solo después de que respondiste, se dibujó el
árbol que pediste, y la lista creció o su loadingMore pasó de true a false (una carga que terminó sin nada nuevo). Nunca
más de una vez por segundo por lista, nunca mientras la pantalla está escondida (una página de título o el reproductor
encima, la app en segundo plano: pregunta cuando la pantalla vuelve a verse), nunca para una lista vacía, nunca con 500
elementos (o 60 para una fila o cuadrícula de títulos dibujada entera). loadingMore: true dibuja el indicador de carga de
Kino después de los elementos; done: true deja de preguntar. Dos consecuencias: un temporizador que apaga loadingMore
en cada tic sin nada nuevo hace que Kino vuelva a preguntar una vez por tic, y una lista que el dibujo de un temporizador
achica no vuelve a preguntar hasta que la persona haga algo.
Los componentes propios de Kino reciben datos, nunca estilo, con la misma forma que devuelve una fila de home o
browse (KinoItem: id, ref, title, kind, poster, backdrop, year, rating, badges, progress,
adult), leídos con las mismas reglas: una serie necesita tu capacidad episodes, los pósters y fondos son solo https (si
no, el marcador de Kino), y los elementos 18+ solo se ven mientras el código 18+ de la persona está desbloqueado.
titleCard(una tarjeta de póster de Inicio;sizesmall, medium o large),titleRail(una fila de Inicio con untitley, con unref, su "Ver más"),titleGrid(tarjetas encolumns, 3 por defecto),heroCard(el banner de una sección:title,text, unaimagehttps, máximo 2 botones). Ver titleCard, titleRail, titleGrid y heroCard.- El toque de una tarjeta abre su título como lo hace la tarjeta de Inicio, con ese mismo elemento, así que "Continuar
viendo", las listas guardadas y el progreso lo reconocen;
onTappuede reemplazarlo por un evento, ungou operacionesui. Elopen: { screen }de un elemento vuelve a abrir tu pantalla en esa ruta. - Máximo 1.000 títulos en un árbol, y 60 en una cuadrícula o fila dibujada entera (dentro de un desplazamiento, una lista, una ventana emergente o una celda de tabla).
Formularios y validación¶
Un Form agrupa campos y les da un solo envío, revisado por Kino antes de que algo llegue a tu código
(Form, Validación):
{ type: "Form", key: "contact", onSubmitted: "send", children: [
{ type: "TextField", key: "email", kind: "email", labelText: "Correo", labelTextEn: "Email", required: true,
pattern: "^[^@\\s]+@[^@\\s]+\\.[a-z]{2,}$", errorText: "Revisa el correo", errorTextEn: "Check the email" },
{ type: "TextField", key: "msg", labelText: "Mensaje", labelTextEn: "Message", multiline: true, maxLength: 500, required: true },
{ type: "ElevatedButton", labelText: "Enviar", labelTextEn: "Send", submit: true },
] }
- Campos:
TextField(required,minLength,maxLength,pattern,errorText),DropdownButton,Switch,Checkbox,RadioGroup,NumberStepper(required,errorText),Chips(required, yminLength/maxLengthcuentan los chips elegidos).requiredsignifica un texto que no está en blanco, una opción elegida, un interruptor encendido, un chip elegido; un campo vacío que no es obligatorio pasa todas las revisiones.errorText/errorTextEnes lo que la persona lee debajo de un campo que falla; si no, el texto propio de Kino; el error de unRadioGroupo deChipsse muestra en el grupo. - El botón con
submit: trueenvía (su propioonPressedse ignora); está apagado mientras un campo obligatorio esté vacío. Un formulario inválido nunca llama a tu código: los errores se muestran debajo de cada campo y el foco va al primero. Uno válido corre elonSubmitteddel formulario, cuyovaluetrae el valor de cada campo por su clave. - Enter no envía un formulario, y el
onSubmittedpropio de un campo dentro de un formulario corre sin la revisión del formulario. Las reglas de un campo fuera de un formulario no se usan. Un formulario sinonSubmittedse descarta; los formularios no se anidan (la regla es estricta: reescribe un formulario anidado como dos hermanos); la ventana de una respuesta no lleva ninguno. - Los valores de los campos
hiddeno apagados igual se mandan, sin revisar; un campo obligatorio dentro de unTableRowescondido no se revisa; un campo obligatorio dentro de un elemento cerrado de unExpansionTileno deja el botón apagado, pero el envío lo revisa y, si falla, abre el elemento y le pone el foco. UnNumberSteppersiempre tiene un valor, así que surequiredsiempre pasa. - El motor de patrones es propio de Kino (uno de tiempo lineal, el mismo en la app y en el kit), nunca la expresión
regular de la plataforma, así que un patrón hostil no puede congelar el aparato. Un patrón (máximo 200 caracteres) tiene
que coincidir con el valor completo, en un subconjunto seguro: literales,
.,^,$,|, grupos( )y(?: ), clases[...], los escapes\d \D \w \W \s \S \b \B \n \r \ty la puntuación escapada, los cuantificadores* + ? {n} {n,} {n,m}(cuentas de hasta 1.000, opcionalmente perezosos), que se pueden anidar. Sin referencias hacia atrás ni búsquedas alrededor. Los significados son ASCII:\des[0-9],\w[A-Za-z0-9_],\sel espacio en blanco ASCII,.cualquier carácter salvo un salto de línea. Un patrón puede expandirse a máximo 500 pasos una vez expandidas sus cuentas, así que[a-z]{1,600}se rechaza: escribe[a-z]+y ponmaxLength: 600. Un patrón fuera del subconjunto se descarta, con una línea en el registro (el campo sigue revisando sus otras reglas). Un envío corre máximo 16 patrones y 4.000.000 de pasos del motor; pasado cualquiera de los dos, los patrones que faltan pasan. El veredicto de Kino es el que cuenta: vuelve a revisar en tu código solo lo que necesite tu propia lógica (Patrones).
Ajustes dentro de una pantalla: settings, bind y config¶
Tu pantalla puede ser la ventana de ajustes de tu plugin, o tenerla como una pestaña de una interfaz más grande. Los
valores siguen siendo tus ajustes reales (el mismo almacén, la misma sincronización entre los aparatos de la persona,
leídos con kino.config); nada se copia a kino.storage. La referencia está en
el nodo settings y bind y config.
- El nodo
settingsdibuja el formulario de ajustes propio de Kino para tu plugin, el mismo que muestra Ajustes, en celular y TV: todos los tipos de ajuste,devices, los dos idiomas, la validación, los campos de Kino para secretos y sus botones para acciones (unaactioncorre como allá), "Enviar a otro aparato", su propio guardar.keys: [...]muestra solo esos ajustes, en ese orden. No te manda ningún evento y tu código nunca ve lo que se escribe en él (suonSavedsolo te avisa que la persona guardó). Cada ajuste se muestra máximo una vez por pantalla, así que varios nodossettingsestán bien. Nunca dentro de unFormni de la ventana de una respuesta. bind: "<settingKey>"en un campo muestra el valor guardado al abrir la pantalla y escribe solo el cambio de la persona: una elección al cambiar, un texto al confirmar (la acción del teclado, cuando el foco sale, al aceptar el diálogo de la TV), nunca letra por letra, y solo cuando es distinto; igual recibes los eventos del campo. Lo que puede guardar cada campo está en la última columna de la tabla de widgets. Una pestaña de ajustes simple no necesita nada de JavaScript.config: { <settingKey>: value }en una respuesta escribe ajustes desde tu código: solo claves que declara tu manifiesto, máximo 32 por respuesta, cada valor acorde a su tipo (text, un texto; en blanco onulllo vacía salvo que sea obligatorio;toggle, un booleano;select, uno de sus valores de opción;list, un arreglo de registros con sus campos;password, un texto).- Un
passwordse guarda exactamente como llega (nunca se recorta);null,""o espacios en blanco lo vacían (nunca unorequired); máximo 500 caracteres. Una pantalla nunca lo vuelve a leer (bindnunca lo prellena,statenunca lo tiene) y Kino nunca escribe su texto en el registro, solo su clave. Átalo solo a un campo enmascarado (campos secretos). - Nunca desde una pantalla: un ajuste
url(una dirección que la persona guarda se vuelve un servidor al que tu plugin puede llegar, la red de la casa incluida, así que solo la persona la escribe, en el nodosettings), un ajusteactionohelp, un valor que contiene uno de tus secretos sellados, una escritura delistque agrega una dirección a un campourl(las entradas se pueden quitar, reordenar o renombrar), y un ajuste conunlockWith(lo protege el código 18+) movido de su valor por defecto (un campo nunca se ata a uno; el nodosettingslo muestra y pide el código). Todo eso se descarta, con una línea en el registro. - Ritmo: cada ajuste se escribe máximo una vez cada 500 ms por pantalla (gana el valor más nuevo, y el último siempre
llega, aunque la pantalla se cierre a mitad de la escritura); la respuesta de un temporizador escribe cada uno máximo
una vez por minuto.
kino.config, en el dibujo que pidió una respuesta, todavía puede leer el valor anterior de una clave escrita hace menos de 500 ms; cuando necesites el valor nuevo en el acto, léelo de tu propio estado. - Lo que cuesta una escritura: cada escritura reinicia tu entorno de ejecución para que
kino.configlea el valor nuevo. Una escritura que solo trae interruptores y selecciones conserva la sesión web de tu plugin (las cookies); cualquier otra es el Guardar completo de Kino, y la sesión se olvida (un inicio de sesión con cookies se cierra).
Adónde manda la pantalla a la persona: go¶
La acción de un nodo o una respuesta puede traer go: una de diecisiete formas, siempre hacia el contenido de este mismo
plugin o hacia una página propia de Kino. Ninguna forma nombra un intent ni una app, y solo liveChannel,
installPlugin y plugin nombran otro plugin (un proveedor de En vivo, para un plugin cuya pestaña del reproductor declara
"kinds": ["live"]; un repositorio cuya hoja de instalación abre Kino; un repositorio cuya pantalla o búsqueda abre Kino);
cualquier otra cosa se descarta. Cada forma tiene su entrada en la referencia, de go.title a
go.plugin.
go |
Qué abre | Desde dónde se manda |
|---|---|---|
title |
la página de título de este plugin (ref, kind; id, title y adult para un título que no está en el lienzo) |
un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
play |
reproduce el título de este plugin (ref, kind, como title) |
un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
search |
la búsqueda de Kino con q (máximo 200 caracteres), solo con este plugin como fuente; con "scope": "all" (apiVersion 17; un plugin con una versión menor se rechaza, con registro; cualquier otro scope descarta el go) la búsqueda normal de Kino en todas las fuentes, que no necesita un search tuyo y no te devuelve nada: ni resultados ni la lista de fuentes. La puerta +18 funciona como en la búsqueda de Kino. |
un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
browse |
la lista "Ver más" de este plugin para un ref |
un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
section |
la sección de este plugin | un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
categories |
las Categorías de Kino con el grupo de este plugin primero (su propia pantalla con screen.replaces) |
un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
close |
cierra la pantalla | un toque, o la respuesta a un evento (nunca la respuesta a open, a un temporizador o al onClose de una ventana emergente) |
screen |
la pantalla propia de este plugin en route (máximo 64 caracteres) con args (máximo 4.096 bytes de JSON) |
un toque, o una respuesta, incluida la respuesta al open reservado (nunca la de un temporizador ni el onClose de una ventana emergente) |
titleByIds |
la página de título propia de Kino para ids de TMDB o IMDb, donde la persona elige cualquiera de sus fuentes | solo un toque o envío de la propia persona (un toque, un envío, la respuesta a uno, el botón de una ventana emergente, un toque en un panel) |
url |
un enlace https en el navegador, después de la hoja de confirmación propia de Kino (un código QR en una TV) | solo un toque o envío de la propia persona (un toque, un envío, la respuesta a uno, el botón de una ventana emergente, un toque en un panel) |
copy |
Kino pone el texto del plugin en el portapapeles y siempre muestra su propio aviso «Copiado» (una TV no puede copiar) | solo un toque o envío de la propia persona (un toque, un envío, la respuesta a uno, el botón de una ventana emergente, un toque en un panel) |
liveChannel |
el reproductor sintoniza el canal de un proveedor de En vivo (provider, code), solo para un plugin cuya pestaña del reproductor declara "kinds": ["live"] |
solo un toque o envío de la propia persona (un toque, un envío, la respuesta a uno, el botón de una ventana emergente, un toque en un panel) |
syncProvider |
los ajustes de proveedor de sincronización de Kino (Ajustes ▸ Conectar ▸ Proveedor), donde la persona elige este plugin; solo para un plugin que declara syncProvider, véase go.syncProvider |
solo un toque o envío de la propia persona (un toque, un envío, la respuesta a uno, el botón de una ventana emergente, un toque en un panel) |
useTheme |
activa uno de los appThemes de este plugin como lo hace Apariencia, o con theme: null vuelve al tema de Kino mientras uno de los suyos está activo; no abre nada, Kino muestra su propio aviso y vuelve a llamar a screen, véase go.useTheme |
solo un toque o envío de la propia persona en tu pantalla (un toque, un envío, la respuesta a uno, el botón de una ventana emergente), nunca un panel; desde apiVersion 18 |
setExperience |
"light" o "full": pide esa experiencia para toda la app; Kino le pregunta antes a la persona y no cambia nada sin su sí, véase go.setExperience |
solo un toque o envío de la propia persona en tu pantalla, nunca un panel ni un aviso; desde apiVersion 18 |
installPlugin |
la hoja de instalación propia de Kino para repo (un owner/name sin más), encima de tu pantalla; nada se instala sin el Instalar de la propia persona, véase go.installPlugin |
solo un toque o envío de la propia persona en tu pantalla, nunca un panel ni un aviso; desde apiVersion 19 |
plugin |
la pantalla de otro plugin (repo) en una route que ese plugin lista en su openFrom.routes, con args; si no, su búsqueda de query, o su sección; ofrece instalarlo si falta (Kino 0.9.84), véase go.plugin y Compartir |
solo un toque o envío de la propia persona en tu pantalla, nunca un panel ni un aviso; desde apiVersion 20 |
- La página de Kino se abre encima de tu pantalla; Atrás vuelve a ella con su estado. Máximo un
goque abre una página cada 500 ms (uno segundo en ese lapso se descarta, con una línea en el registro). - El candado 18+ vale en todas partes: un
titleoplayde un elementoadultqueda escondido mientras el código 18+ de la persona está bloqueado. UntitleByIdscon el código bloqueado solo abre cuando TMDB dice que el título no es para adultos; para adultos, desconocido, una falla o 12 s de espera muestran el mensaje de bloqueo de Kino ("Contenido para adultos: desactiva el control parental en Ajustes"). title/play: un título que está en el lienzo se abre con ese mismo elemento (pasa suidcuando dos elementos comparten unref). Un título que NO está en el lienzo necesita suidy sutitle(yadult: truecuando es 18+), o Kino no puede saber cuál es y muestra su error de siempre. Un canal en vivo se reproduce; una serie abre su página (kind: "episode"solo y unaseriesde un plugin sinepisodesmuestran el error); una película, una canción o un episodio de podcast se reproduce en el acto.searchabre la búsqueda de Kino con solo tu plugin como fuente (la persona ve su chip y puede quitarlo); a un plugin sinsearchse le rechaza.categoriesse rechaza, con una línea en el registro, para un plugin sin sus propios mosaicos en Categorías.screen: { route?, args? }abre la pantalla de este plugin desde sus otras superficies: su panel del reproductor (respuesta o botón), los elementos y filas de suhome,sectionybrowse(open: { screen }), la tarjeta de «Mis plugins». La pantalla reciberoute: { name, params: {}, args }(namees"main"sin ruta). Desde dentro de la pantalla, vuelve a empezar en esa ruta (las rutas empujadas y una ventana abierta se van, el estado se queda) y elopenreservado vuelve a llegar con la ruta nueva, así que un mismo camino carga lo que nombran losargssin importar por dónde entró la persona; máximo un reinicio por segundo. Con las pantallas apagadas, una tarjeta o una fila hace lo que hacía antes (go.screen).screen.replaces: ["categories"]: mientras tu pantalla pueda abrirse, un mosaico de tu grupo en las Categorías de Kino y ungocategoriesabren tu pantalla en la rutacategoriesconargs: { from, category? }(fromescategories,screenopanel;categoryes elrefdel mosaico tocado). Ármala contitleRail,titleGrid,heroCard,TabBar,Chipsygo. Las Categorías de Kino quedan de respaldo: con las pantallas apagadas, la pantalla escondida, o una PRIMERA apertura que falla (Kino muestra entonces la lista "Ver más" del propio mosaico y se salta tu pantalla durante esa sesión de la app). Ungocategoriesmandado desde la rutacategoriesabre las de Kino (sin bucle).titleByIds({ tmdb?, imdb?, kind, season?, episode?, title?, year? }, al menos un id) es la forma en que personas con plugins distintos llegan al mismo título: abre la página de título propia de Kino (la que abre una tarjeta de TMDB en Inicio), con todas las fuentes que tiene la persona. No nombra ningún plugin, ref ni URL (cualquier otro campo lo descarta), nunca reproduce, no te devuelve nada; unimdbsolo cuesta una búsqueda en TMDB ("Buscando el título…", una a la vez); la serie se abre entera (todavía sin foco en un episodio) (go.titleByIds).url({ href, title? }, un botón "Ver noticia") le pide a Kino abrir un enlace https en un navegador. Nada se abre solo: Kino muestra primero su propia hoja («Abrir un enlace», «Lo pide:», el host con su final siempre visible, un host internacional como su punycode con una advertencia, tu titlebajo «Texto del plugin:», y después «Cancelar» con el foco primero y «Abrir», inactivo durante sus primeros 600 ms). En una TV, o en un celular sin navegador, la hoja muestra el enlace como un código QR para escanear con un celular.href: solohttps://, máximo 2.048 caracteres ASCII imprimibles (codifica el resto con porcentajes), un nombre DNS público con un punto (nunca una dirección IP,localhost,.local,.internal,.lan,.home.arpa,nip.io,sslip.ioy parecidos), sinuser:password@, sin otro puerto que el 443. Una respuesta que llega más de 5 s después del toque pierde el enlace, y las ventanas emergentes de esa misma respuesta se descartan para que nada tape la hoja de Kino. Nada vuelve a ti, ni siquiera si la persona lo abrió. No hace falta ninguna capacidad (go.url).- Desde la pantalla abierta encima del reproductor (el
go.screende un panel):closela cierra; cualquier otrogoprimero la cierra y sigue; el video hace entonces lo que hace cuando cualquier página de Kino lo tapa (la TV pausa, una transmisión en vivo se detiene).
Temporizadores: every¶
La raíz de un árbol (o el screen.every del manifiesto) puede traer { ms, event } o una lista de ellos: Kino manda
screenEvent { name: event } cada ms mientras la pantalla está abierta, visible y Kino al frente (una ventana emergente
no lo detiene; una página de título o el reproductor encima, o la app en segundo plano, lo pausan). ms de al menos 1.000
(uno más corto se sube, con una línea en el registro) y máximo un día; máximo 3 temporizadores por pantalla (primero los del
manifiesto; un evento nombrado dos veces conserva el primero).
- Los tics nunca le cuestan nada a la persona: un tic corre solo mientras ningún evento de la persona espera o corre, un
tic en espera se descarta cuando llega uno, y la siguiente espera empieza cuando el tic y su dibujo terminaron (el doble
de tiempo cuando tardó más que
ms). - Un tic no es un toque de nadie. Su respuesta conserva solo
state,toast,closeyconfig(cada ajuste máximo una vez por minuto); sus ventanas emergentes,focus,go,routeyuise descartan, con una línea en el registro. No puede abrir el escáner de QR, preguntarle a la IA, ni abrir o entrar a una sala. - Un tic que falla o se pasa del tiempo cuenta solo para su temporizador; 3 seguidos apagan ese temporizador mientras dure esta apertura (queda en el registro). Los tics nunca cuentan para "No responde".
- Usos típicos: actualizar un feed, revisar el
inboxde una sala, avanzar un paso pequeño de una cola de trabajo.
Acordeón, esqueleto, QR, selector numérico y tabla¶
ExpansionTile(keyobligatoria):items(de 1 a 500, cada uno{ key, title, children, open? }), uno abierto a la vez salvo conmultiple. Cuáles están abiertos vive enstate.ui.open.<key>, así que sobrevive a un nuevo dibujo;openes solo el aspecto inicial. Abrir y cerrar es cosa de Kino (sin llamada). El encabezado de cada elemento cuesta un nodo. Cuando el presupuesto de nodos se acaba justo después, el acordeón se dibuja con menos elementos (quizá ninguno) (ExpansionTile).Skeleton:shapeline(conlines, de 1 a 6),block,circleocard, con tamaño porwidth/height; el color atenuado de Kino, con un pulso suave, quieto cuando las animaciones del sistema están apagadas; se lee como "Cargando…" (Skeleton).QrImage:valuede 1 a 1.000 caracteres, dibujado tal cual por el generador propio de Kino (en el aparato, sin red, negro sobre blanco con su margen),sizesmall, medium o large. Un valor que contiene uno de los secretos de tu plugin nunca se dibuja (se muestra el estado vacío de Kino, con una línea en el registro); Kino solo reconoce el secreto tal como está guardado, no partido ni recodificado, así que nunca armes un QR con un secreto. Nunca se toca ni toma el foco; puede ir dentro de una ventana emergente (QrImage).NumberStepper(un campo):value,min,max(min menor que max),step(1 por defecto),decimals(de 0 a 6), dibujado[ − ] valor [ + ]; un botón en su límite está apagado; mantenerlo presionado repite, cada vez un poco más rápido. Su valor enstate.inputses texto ("2.50").editable: truedeja que la persona lo escriba con la entrada de solo dígitos de Kino, solo condecimals: 0y unminde 0 o más (si no, se ignora, con una línea en el registro). Números de máximo 1e15 hacia cualquier lado (se recortan, con una línea en el registro). Sinbind(NumberStepper).DataTable: suschildrensonTableRow(de 1 a 200, cada una{ key?, hidden?, children: [TableCell...] }); una celda es untextsimple (textEn) ochildren, concolSpan(de 1 a 8) ycrossAxisAlignment.columns(máximo 20, cada una con unflex) o tantas como la fila más ancha;header: truehace de la primera fila el encabezado;zebra: truealterna el color de las filas; en un ancho compacto la tabla se desplaza de lado (al menos 96 dp por columna) salvo conwrap: true. Toda propiedad acepta mapas por tamaño (colSpan: { compact: 1, expanded: 3 }). Una celda nunca tiene unListView, unSingleChildScrollViewni unDataTable(nada dentro de una celda se desplaza; las tablas no se anidan); unExpansionTilesí puede ir en una. Una fila con menos celdas se completa; las celdas que pasan de la última columna se descartan (queda en el registro). Cada fila y cada celda cuesta un nodo. Lakeyde una fila deja queuila muestre, la esconda o la alterne. No toma el foco: en la TV el D-pad recorre lo que se puede enfocar dentro de sus celdas (DataTable).
En la TV: escribir texto y el foco¶
El texto en la TV es una entrada simulada, no un campo real: un TextField se dibuja como una fila que muestra su
valor y que, al presionarla, abre el diálogo de texto de Kino para TV con su teclado en pantalla (de varias líneas para un
TextField de varias líneas; el teclado de solo dígitos para un NumberStepper editable). El evento se dispara una
vez, al aceptar el diálogo: onChanged y después onSubmitted, con el valor final; no hay un evento por cada letra. Un
teclado físico en una TV confirma una vez con Enter o al perder el foco, con los mismos eventos. El celular usa campos
normales (el teclado del celular, un onChanged que espera a que termines de escribir). Tu código no puede saber cómo se
escribió un valor y nunca lo necesita: solo lee device. Dos diferencias que conviene saber: la TV manda el texto sin
recortar, y un TextField de varias líneas manda onSubmitted solo en la TV (el teclado de varias líneas del celular no
tiene botón de enviar: dale un botón). El título del diálogo es el nombre de tu plugin, dibujado por Kino. Kino nunca
autocompleta ni sugiere los datos guardados de la persona en un campo de un plugin.
El foco es de Kino. No nombras ningún orden de foco; el D-pad sigue el árbol, moviéndose según lo que está dibujado:
- El primer foco va al primer nodo que se puede enfocar en el orden del árbol. El
focusde una respuesta o unfocusdeuilo mueve. - Un
TabBary una fila deChipsrecorren sus elementos con Izquierda y Derecha; al final siguen al siguiente elemento enfocable de al lado en la misma fila (las pestañas, después unIconButtonpara actualizar) y, si no hay nada ahí, se quedan quietos: nunca otra fila, nunca la barra de título de Kino. La cuadrícula de doce columnas mantiene Izquierda y Derecha dentro de sí misma. Entrar a unTabBaro a una fila deChips, desde cualquier lado, cae en el elemento elegido. - Un
Scroll,ListViewo cuadrícula de títulos con una clave tuya debajo del primerTabBarde la pantalla (unRowde encabezado cuenta) conserva su desplazamiento por pestaña, también cuando le pones una clave distinta al cuerpo de cada pestaña (newsBody,settingsBody). - Moverse a un nodo desplaza solo lo necesario para mostrarlo entero: un nodo que ya está a la vista no desplaza nada, así
que la primera línea bajo un encabezado nunca queda medio tapada. Arriba (Abajo) sin nada más que enfocar en esa
dirección dentro de un
Scroll(o del cuerpo de un panel del reproductor) lo desplaza casi una página hasta su inicio (final), así que el texto arriba del primer elemento enfocable o abajo del último se lee solo con el D-pad; en el inicio (final), la tecla sale como antes. - Los hijos apilados (un
Columnde botones y campos) llevan Abajo y Arriba al borde más cercano del vecino, así que un botón angosto debajo de una fila de ancho completo nunca se salta; las matrices de botones conservan sus columnas. - Una ventana emergente mantiene el foco adentro (solo la de arriba, cuando el selector de una lista desplegable está encima); su primer foco es su primer nodo enfocable; si no, un cuerpo más alto que el marco (se desplaza con Abajo y Arriba); si no, su primer botón; si no, su botón de cerrar. Izquierda y Derecha van entre la X de Kino y tus botones; Atrás la cierra y el foco vuelve a lo que la abrió.
- Cada acción enfocada tiene el anillo de Kino, y solo ella: nunca el marco de una ventana emergente, un cuerpo que se
desplaza ni ningún otro contenedor. Lo mismo en cualquier panel del reproductor, clásico o en modo pantalla: un texto,
una sección, un estado, una imagen o un QR no toman el foco en la TV (Arriba y Abajo pasan página). Un
NumberStepperse mueve entre −, el valor (solo si es editable) y + con Izquierda y Derecha, y sus botones en el límite siguen siendo enfocables (dibujados apagados), así que mantener OK nunca pierde el foco. El encabezado de unExpansionTiletoma el foco y OK lo abre o cierra; Abajo desde un encabezado abierto entra a su contenido. UnQrImagey unDataTablesimple no lo toman. - La acción de un aviso se alcanza con Abajo desde el final del árbol, o se ejecuta con la tecla Menú o Play/Pausa del control.
- Un cuadro nuevo que quitó el nodo enfocado (la vista nueva de una respuesta): el foco va al elemento enfocable que ahora
está en su lugar o después; si no, al último antes; si no hay ninguno, un
Scroll(o el cuerpo de un panel del reproductor) que se desplaza toma el foco él mismo, sin anillo, para que el D-pad lo siga leyendo. Gana elfocusde una respuesta. Dentro de un panel del reproductor, el texto de la TV es un paso más pequeño que el de una pantalla completa (h1del tamaño deh3...p15 sp); en el celular no cambia. - Atrás: primero la ventana abierta, después una ruta empujada, después la pantalla.
Diseña primero para la TV: pocas paradas de foco, la acción importante primero, filas cortas, y onLongPress solo para
extras a los que la persona también puede llegar de otra forma.
Límites de las pantallas¶
| Qué | Límite |
|---|---|
| Un árbol | profundidad 10, 600 nodos (el encabezado de un acordeón, la fila y la celda de una tabla cuentan como uno cada uno); en un panel en modo pantalla, profundidad 6 y 200 nodos |
| Listas | 500 elementos en una lista, fila de títulos, cuadrícula, acordeón o en las options de una elección; 1000 títulos en todo un árbol, 60 en una fila o cuadrícula dibujada entera (dentro de un desplazamiento, una lista, una ventana emergente o una celda de tabla) |
| Textos y claves | un texto, 2.000 caracteres; testKey, 64; el trailingLabel de un campo de texto, 40; un ref, 4.096; el label de la entrada del menú, 20; el del botón de ajustes, 40 |
| Estado | 64 KB en JSON (un parche más grande se rechaza y se conserva el estado anterior) |
| Llamadas | screen y screenEvent, 20 s cada una; eventos de a uno, separados al menos 100 ms, máximo 8 en espera |
| Respuestas | 8 operaciones ui por acción o respuesta; 32 ajustes por config; 1 ventana emergente a la vez; 3 botones en un diálogo; 8 elementos en un menú; 2 botones en un heroCard |
| Diseño | flex de 1 a 12; columns de 1 a 8; la fila de doce columnas: 12 columnas |
| Patrones (formularios) | un patrón de máximo 200 caracteres, una cuenta de máximo 1.000, 500 pasos con las cuentas expandidas (y 20.000 unidades de trabajo para leerlo); un envío corre máximo 16 patrones y 4.000.000 de pasos del motor (pasado cualquiera, el resto pasa) |
Temporizadores (every) |
3 por pantalla, cada 1.000 ms a 86.400.000 ms (un día); 3 fallas seguidas apagan uno; el config de un tic escribe un ajuste máximo una vez cada 60 s |
| Avisos | se muestran de 2.000 a 8.000 ms (por defecto 3.500) |
QrImage |
value de 1 a 1.000 caracteres |
NumberStepper |
máximo 6 decimales; números de máximo 1.000.000.000.000.000 hacia cualquier lado |
Skeleton |
de 1 a 6 líneas |
DataTable |
200 filas, 20 columnas, colSpan de 1 a 8 |
go |
route 64 caracteres, args 4.096 bytes; titleByIds: tmdb de 1 a 2.147.483.647, season de 0 a 999, episode de 1 a 9999, year de 1870 a 2100, title 120; url: href 2.048, title 60, un enlace por segundo para todos los plugins y 10 por minuto por plugin, un código QR de hasta 1.000 caracteres; copy: text de 500 caracteres en 6 líneas, label 40, una copia cada 500 ms y 20 por minuto por plugin; máximo un go que abre una página cada 500 ms |
| Búsqueda | q de 200 caracteres |
Todo lo demás (kino.fetch, kino.storage, la memoria) son los límites habituales del plugin
(Límites del motor). Todos los números de las pantallas juntos también están en
Límites.
Capacidades que van con las pantallas¶
Una pantalla no agrega ninguna línea de consentimiento. Las capacidades de abajo sí agregan alcance, así que Kino se lo pregunta a la persona con sus propias palabras, que no puedes cambiar ni esconder:
| Capacidad | Lo que lee la persona | En rojo, espera aprobación | El interruptor de la persona (tu pestaña en Ajustes) |
|---|---|---|---|
screen |
nada: no tiene línea propia | no | ninguno |
library |
"Podrá leer lo que has visto y guardado en Kino, cuánto lo ves y a qué hora, y enviarlo a sus servicios" | sí | "Dejar que lea lo que he visto y guardado" |
playerPanelTab |
"Su pestaña en el reproductor verá lo que estás viendo (título, año, identificadores y posición, o el canal en vivo) mientras la tengas abierta, y podrá enviarlo a sus servicios" | sí | "Mostrar en el reproductor" |
playerControl |
"Podrá pausar, reanudar y mover tu video por sí solo" | sí | "Dejar que pause y mueva mi video" |
room |
"Podrá abrir una sala a la que se entra por internet a través de este aparato, y enviar los mensajes de la sala a quienes entren" | sí | "Dejar que abra salas por internet" |
schedule |
"Podrá ejecutarse en segundo plano cada cierto tiempo para actualizar sus datos, usando internet y batería" | sí | "Dejar que trabaje en segundo plano" |
ai |
"Podrá enviar texto a un servicio de IA de terceros (Kilo) para que lo resuma o clasifique; lo que envíe sale de tu aparato" | sí | "Dejar que use la IA de texto" |
shared |
"Guarda unos pocos resultados que se sincronizan entre tus aparatos vinculados" | no | ninguno |
playerSlot |
con un elemento fixed: "Mostrará algo suyo de forma permanente en el reproductor mientras ves un video" |
sí, solo cuando un elemento es fixed (un hueco con solo overlay no pregunta nada) |
"Dejar que muestre algo en el reproductor" |
- Una línea en rojo se pregunta al instalar y otra vez en la actualización que la agrega, y Kino nunca la aprueba por su
cuenta; la importación del kit la deja sin marcar. Hasta que la persona la aprueba, la API se niega
(
permission_denied,refused), así que maneja siempre la negativa y funciona sin ella. - Cada interruptor está en la pestaña de tu plugin en Ajustes, vale para todo el aparato y todos los perfiles, y se sincroniza con los otros aparatos de la persona; apagado, la API se niega en el acto (una sala se cierra, el trabajo de un job se cancela).
- Sé honesto también en tu propia interfaz: di qué mandas y adónde (los ajustes del ejemplo de noticias dicen "Los titulares se envían al servicio de IA de terceros de Kino").
- Estas líneas son la salvaguarda, no un muro técnico: un plugin que puede hacer peticiones puede mandar a sus hosts lo que lee. Por eso la hoja muestra tus hosts junto a la línea.
Cada capacidad tiene su propia página:
| Capacidad | Qué da | Dónde |
|---|---|---|
room |
Un buzón de corta vida alojado en el propio aparato de la persona y alcanzable por internet: una sala a la que otros entran. | Salas |
library |
Lo que el perfil activo vio y guardó (títulos e ids, nunca streams ni 18+). | Biblioteca |
playerControl |
Pausar, reanudar y mover el video desde un panel (el tuyo o una pestaña que aportas). | Control del reproductor |
schedule (jobs, job(ctx)) |
Trabajos en segundo plano que actualizan lo que muestran tu pantalla o tu catálogo. | Trabajos |
shared |
Unos pocos resultados que se sincronizan entre los aparatos vinculados de la persona. | Compartido |
ai |
Un texto corto a la IA de texto de Kino, para resumir o clasificar. | IA |
qrScan |
kino.qr.scan desde un screenEvent que sigue a un toque o envío de la persona. |
QR |
playerPanelTab |
Tu pestaña en el panel del reproductor del título de cualquier plugin. | Pestaña aportada |
playerSlot (slot, apiVersion 23) |
Hasta tres elementos pequeños (texto, ícono, imagen, botón) en la esquina superior derecha del reproductor de la TV. | El hueco del reproductor |
kino.fetch maxBytes / stopAt |
Leer solo el principio de una página. | kino.fetch |
enhancements |
Pantallas y las demás funciones de apiVersion 14 para un plugin que conserva un apiVersion anterior; en una actualización, los consentimientos nuevos primero. | Pantallas sin subir tu apiVersion |
Probar pantallas con el kit¶
node sdk/validate.mjs <folder> # the manifest, the exports, every consent line, enhancements
node sdk/run.mjs <folder> screen # the tree as Kino reads it (aliases resolved, drops logged)
node sdk/run.mjs --device tv <folder> screen # as a TV
node sdk/run.mjs --state '{"inputs":{"q":"dune"}}' <folder> screenEvent search
node sdk/run.mjs --context '{"route":{"name":"categories","params":{},"args":{"from":"categories"}}}' <folder> screen
node sdk/run.mjs <folder> panel <ref> # a panel (legacy or screen format)
node sdk/run.mjs --state '{}' --screen <folder> panelAction <ref> <name> press
node sdk/run.mjs --foreign latino:Latino <folder> panel <ref> # a tab you contribute to another plugin's title
node sdk/run.mjs --device phone <folder> job refresh manual # one job run, with Kino's caps
node sdk/run.mjs --device tv <folder> screen # ...then read what the job shared, as the TV
node sdk/run.mjs <folder> shared # what the simulated phone and TV hold
run.mjs imprime el árbol después de las reglas de Kino (con los nombres anteriores que Kino lee por dentro, y los valores
por tamaño resueltos en byClass), cada nodo y campo descartado, y los campos de la respuesta; validate.mjs revisa el
árbol y los objetos go como lo hace la app. Las variables de entorno KINO_LIBRARY_FIXTURE, KINO_LIBRARY_REVOKED,
KINO_ROOM_REVOKED, KINO_PLAYER_CONTROL_REVOKED, KINO_AI_REPLY, KINO_AI_ERROR y KINO_AI_REVOKED simulan los datos
y las decisiones de la persona. En archivos de node --test, importa las ayudas del kit (createKino,
createKitRoom...) como lo hacen las pruebas de los ejemplos. Los archivos de casos compartidos en sdk/test/
(screen-cases.json, room-cases.json, job-cases.json, ai-cases.json, shared-cases.json,
player-control-cases.json, panel-foreign-cases.json, qr-origin-cases.json) son los mismos casos que corren las
pruebas propias de Kino. Más sobre el kit en Probar en local.
Patrones¶
- Arma con funciones simples. Una pantalla son datos: una función por pestaña o tarjeta (
newsTab(state),card(story)), un mapa de manejadores parascreenEvent(const on = { open, read, more, save }; return on[name]?.(ev) ?? null;). El plugin sigue siendo un solo archivo al correr (pártelo ensrc/y empaquétalo cuando crezca). - Mantén pequeño el estado. Viaja en cada llamada y tiene un tope de 64 KB: guarda ahí ids y elecciones, y lo
voluminoso (un feed, artículos) en
kino.storageokino.shared, leído enscreen()por los ids. - Trabaja en pasos pequeños. Nunca hagas todo en una llamada: una llamada tiene 20 s, y un job 20 s y 10 peticiones.
Escribe una función pura,
step(cache, fetch, settings, clock, budget), que avance un poco una cola de trabajo (el siguiente lote de búsquedas, unas pocas imágenes) y se detenga en su presupuesto, guardando un cursor en la caché. Llámala desde el job, desde elopende la pantalla y desde un tic deevery; cada llamada sigue donde se detuvo la anterior. Con el reloj y el presupuesto como parámetros, tus pruebas demuestran que se detiene y sigue. Un presupuesto más liviano en una TV (kino.device). - Cachés detrás de un adaptador. Lee y escribe a través de un objeto pequeño (
get,set) que intentakino.sharedy cae akino.storagecuando falta o se niega, así el mismo código corre con o sin la capacidad, en un Kino anterior y en las pruebas. - Mostrar lo guardado mientras se actualiza. Muestra la caché en el acto en
openy después pide solo lo que está viejo; unSkeletonpara lo que todavía no está; unMaterialBannercon «Reintentar» cuando falla la red, con los datos viejos todavía a la vista. - Toda entrada es poco confiable: lo que responden
kino.sharedy una sala, una respuesta de la IA, una página que pediste, un valor de una versión anterior de tu plugin. Revisa formas, tamaños y campos; limpia los caracteres de control y de dirección de los nombres. - Textos en español e inglés. Cada nodo de texto lleva su gemelo
En; tus avisos leenlang. Las palabras de Kino son suyas (en los dos idiomas). - Nada de secretos donde viajan: nunca en
kino.shared, un mensaje de sala, unQrImage, una pregunta a la IA ni una línea del registro. - Revisa qué existe (
kino.screen.names,typeof kino.library === "object"...) y ten un camino sin cada capacidad: la persona puede negarla o apagarla. - La lógica vive en el plugin. Kino trae piezas genéricas (el kit de pantallas, el anfitrión de pestañas, las salas,
el control del reproductor,
titleByIds,library, los jobs,shared,ai); una función como una Watch Party es por completo un protocolo del plugin encima de ellas.
Los ejemplos¶
Cinco plugins muestran esta guía en acción; cada uno tiene un README (en español e inglés) y pruebas que corren sin red.
Galería¶
kinotvapp/kino-plugin-ui-gallery (Kino 0.9.74 y posteriores):
todos los componentes de la referencia en una sola pantalla, una pestaña por grupo (Layout, Content, Actions, Forms,
Overlays, Navigation, Data), cada componente en una sección con la clave de su ancla en la referencia, con demostraciones
interactivas (ventanas emergentes desde una respuesta y declaradas, avisos, validación de formularios, operaciones ui,
bind y config, go.url, go.titleByIds y go.screen con destinos inofensivos, un temporizador). Su
screenshot-map.json dice dónde está cada componente, para capturar las imágenes de la referencia desde el dibujo real.
Noticias¶
kinotvapp/kino-plugin-news («Solo noticias»): dos pestañas.
Noticias: noticias sobre las películas y series que vio la persona y sobre sus propios términos, desde el RSS de Google
News, como una cuadrícula de doce columnas de tarjetas flush (una, dos o tres por línea) con chips de categoría; el toque
de una tarjeta lee la noticia y la respuesta abre una ventana declarada (ui: [{ open }]) con la imagen, el texto leído de
la página del medio (maxBytes) y «Ver noticia» (go.url; en una TV, también un QR). Configuración: la frecuencia,
imágenes y textos, ordenar con IA, «Usar lo que he visto» con filas que se pueden quitar, títulos de muestra, y los
términos propios de la persona agregados desde una ventana con un formulario. Muestra library, un job de schedule con
runOn: "preferPhone" que escribe en kino.shared a través de un adaptador de caché con kino.storage de respaldo, la
clasificación con ai en el job o después de «Clasificar ahora» con validación estricta y un respaldo por palabras clave,
el fallback de una imagen, card.flush, la cuadrícula de doce columnas, bind, un temporizador every que avanza la
cola de trabajo y un presupuesto para TV. Muestra sus límites con honestidad: los enlaces de los artículos de Google se
resuelven con una llamada no oficial que puede romperse. Su código está partido en src/ y empaquetado en plugin.js (ver
Estructura).
Watch Party¶
kinotvapp/kino-plugin-watch-party: «Party Chat», una pestaña
aportada al panel del reproductor del título de cualquier plugin (playerPanelTab), con room, qrScan y
playerControl. Un chat (texto de hasta 300 caracteres y ocho reacciones) y la reproducción sincronizada: el anfitrión
transmite su posición; un invitado lo sigue solo cuando su plugin de origen (ctx.source) y los ids del título
coinciden; si no, «Abrir este título» (go.titleByIds). Para compartir están las palabras y el código de la sala y un QR
con los dos. Muestra el protocolo de sala que maneja un plugin: instantáneas cada 10 s, puertas de respaldo
(open({ code })), una elección con un toque para cambiarse (porque join necesita un toque), replicación incremental
del chat, un puesto en la TV vinculado desde un celular, pares no confiables, y por qué hay que fijar la pestaña (durante
la reproducción) para que siga corriendo. Su código está partido en src/ y empaquetado en plugin.js (ver
Estructura).
Calculadora¶
El otro extremo: sin red, sin job, sin ajustes. Una tarjeta de pantalla y veinte botones en un Row con wrap: true
(span: 3), con tamaños por mapas por tamaño para celular, ventana mediana y TV; una vista pura sobre state.calc y
funciones exportadas puras para la lógica, probadas con una tabla de 94 filas y una prueba de propiedades. En una TV el
D-pad recorre la matriz de botones: una guarda contra regresiones del foco en una cuadrícula. Cada tecla es una ida y
vuelta a JS, así que también mide la latencia del kit de pantallas.
Flujo de configuración¶
Un inicio de sesión en tres pasos sin red: el nodo steps de Kino (tocar un paso hecho vuelve a él), un QrImage que
vence (la cuenta regresiva propia de Kino y un onExpire cinco segundos antes del final que dibuja un código nuevo), un
Form con un TextField enmascarado (obscureText) cuyo texto se escribe en el ajuste password propio del plugin a
través de config y nunca queda en el estado, y un nodo settings cuyo onSaved le avisa a la pantalla que la persona
guardó. Funciones exportadas puras, probadas con el kit.
Límites conocidos¶
Lo que esta versión no hace:
- El cuerpo de una ventana declarada no se puede llenar con una segunda respuesta: una respuesta no puede encadenar un evento, así que una noticia que necesita una petición lenta se lee antes de abrir su ventana (nada de esqueleto y después texto dentro de una misma ventana).
- La respuesta de cargar más todavía puede abrir una ventana emergente.
- Una pestaña aportada (una Watch Party) no funciona en listas M3U, canales propios ni otro contenido que no sea de un plugin, y solo corre mientras está elegida en un cajón abierto o fijado.
go.titleByIdsabre una serie entera (todavía sin foco en una temporada o episodio).- Sin
binden unNumberStepper; el estado de la pantalla se borra al cerrarla. UnTextFieldenmascarado (obscureText) guarda lo que se escribió solo en memoria y solo hasta que el siguiente toque o envío de la persona lo lleve (campos secretos). - Una pantalla cuyos tamaños fijos son más altos que la ventana no se desplaza sola: pon la raíz dentro de un
scroll(o dale tamaños porheightClass), como hace el ejemplo de la calculadora en horizontal. - En un celular en horizontal, el panel fijado ocupa el 32 % del ancho pero nunca menos de 360 dp, así que un celular angosto queda cerca de 59/41 (video/panel) en vez de 68/32.
- La fijación dura una reproducción: salir del reproductor la olvida.
- Cuando ni siquiera las filas apiladas de botones del reproductor caben (un área de video muy angosta), los botones menos importantes pasan a una fila más debajo de ellas, no a un menú «⋮».