Componentes de pantalla: formularios, ventanas y navegación¶
Disponible con Kino 0.9.74
Disponible desde Kino 0.9.74. Una versión anterior de Kino rechaza estos
plugins con «Este plugin necesita una versión más nueva de Kino»; para seguir llegando a quien tiene una versión
anterior usa enhancements (ver Pantallas sin subir tu apiVersion).
Esta es la segunda parte del catálogo de componentes de una pantalla: los campos y formularios, las
ventanas emergentes y todo lo que un nodo puede abrir con go. El catálogo tiene tres páginas:
- Disposición, contenido y acciones: de
ColumnaListTile, deTextaheroCard, de los botones a las operacionesui. - Formularios, ventanas y navegación (esta página): de
Formabindyconfig, deDialogaanchor, cada forma degoy las rutas. - Datos, comportamiento y recetas: estado, campos, eventos, respuestas, temporizadores, valores por tamaño, estilo, propiedades comunes, animaciones, límites y las recetas.
Qué es una pantalla, cómo se declara y cómo responde está en la guía, Pantallas.
Formularios¶
Los campos guardan valores que Kino mantiene en state.inputs por clave (Campos). Dentro
de un Form además llevan reglas que Kino revisa antes de que nada llegue a tu código.
Form¶
Campos con un solo envío: un botón con submit: true revisa cada campo, muestra los errores debajo de cada uno que falla
y enfoca el primero; solo un formulario válido corre el onSubmitted del formulario, cuyo value del evento trae cada
campo por clave.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
children |
nodos (entre ellos sus campos)[] | ninguno | no | sus hijos, dibujados en orden |
onSubmitted |
acción | obligatorio | no | corre solo cuando todos los campos pasan; el value de su evento trae cada campo por clave |
{ "type": "Form", "key": "contact", "onSubmitted": "send", "gap": 12, "children": [
{ "type": "TextField", "key": "email", "kind": "email", "labelText": "Correo", "labelTextEn": "Email", "required": true,
"pattern": "^[^@\\s]+@[^@\\s]+\\.[A-Za-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": "Checkbox", "key": "ok", "labelText": "Acepto", "labelTextEn": "I agree", "required": true },
{ "type": "ElevatedButton", "labelText": "Enviar", "labelTextEn": "Send", "submit": true }
] }
export async function screen() {
return { type: "Form", key: "contact", onSubmitted: "send", gap: 12, children: [
{ type: "TextField", key: "name", labelText: "Nombre", required: true, minLength: 2 },
{ type: "ElevatedButton", labelText: "Enviar", submit: true },
] };
}
export async function screenEvent({ name, value }) {
if (name !== "send") return null;
return { state: { sentBy: value.name }, toast: "Enviado", toastEn: "Sent" }; // value: every field by key, already checked
}
- Televisor: el error lleva el foco al primer campo que falla.
- Teléfono y televisor: las mismas reglas; solo cambia cómo se escribe el texto (TextField).
- Límites y errores comunes: un formulario sin
onSubmittedse descarta; los formularios no se anidan (escribe dos hermanos); la ventana de una respuesta no lleva ninguno (una declarada sí). Enter no envía un formulario.
TextField¶
Un campo de texto: un nombre, una caja de búsqueda, un correo. kind elige el teclado (text, number, email, url,
search). onSubmitted es la acción del teclado; onChanged avisa los cambios. Un trailingIcon (uno de los
iconos de Kino) se dibuja dentro de la caja del campo, al final: el «Enviar» de un chat
o la lupa de una búsqueda. Su onTrailingTap se envía como onSubmitted, con lo que el campo tiene en ese momento como
value del evento, y trailingLabel (trailingLabelEn, máximo 40 caracteres) es lo que dice un lector de pantalla para
él.

| 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 |
kind |
text | number | email | url | search |
text |
no | el teclado; no hay tipo contraseña (un campo enmascarado es obscureText) |
value |
string | "" |
no | el texto inicial (gana lo que tenga state.inputs); se ignora en un campo obscureText |
obscureText |
boolean | false |
no | enmascarado como una contraseña en teléfono y televisor, con el mostrar / ocultar de Kino; nunca en tu estado, enviado solo con el toque o el envío de la propia persona, y luego borrado (campos secretos); solo de una línea; solo se vincula a un ajuste password |
maxLength |
1 a 2.000 | 2.000 | no | también es regla de formulario |
onSubmitted |
acción | ninguno | no | la acción del teclado (Enter); en el televisor, el aceptar del diálogo de texto |
trailingIcon |
uno de los 50 iconos | ninguno | sí | dibujado dentro de la caja del campo, al final, teñido con color; nunca en un campo deshabilitado; necesita trailingLabel y onTrailingTap, si no el campo se dibuja sin él (queda en el registro) |
trailingLabel |
1 a 40 caracteres | ninguno | no | lo que dice un lector de pantalla para el icono (trailingLabelEn en inglés); obligatorio con trailingIcon |
onTrailingTap |
acción | ninguno | no | la pulsación del icono: se envía como onSubmitted, con el texto actual del campo como value (una pulsación de la persona); en el televisor el icono es su propia parada de foco, a la derecha del campo |
bind |
una clave de ajuste | ninguno | no | muestra y guarda uno de tus ajustes text (bind) |
required |
boolean | false |
no | regla de formulario: un texto no vacío, una opción elegida, un interruptor encendido, un chip escogido |
minLength |
integer | ninguno | no | regla de formulario: caracteres (chips: chips escogidos) |
pattern |
string | ninguno | no | regla de formulario: tiene que coincidir con el valor entero; el subconjunto seguro propio de Kino, máximo 200 caracteres (Patrones) |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "TextField", "key": "q", "kind": "search", "labelText": "Buscar", "labelTextEn": "Search", "hintText": "Una película", "hintTextEn": "A film", "maxLength": 100, "onSubmitted": "search" }
export async function screen({ state }) {
return { type: "Column", gap: 8, children: [
{ type: "TextField", key: "q", kind: "search", labelText: "Buscar", onSubmitted: "search" },
{ type: "Text", text: state.query ? "Buscaste: " + state.query : "Escribe algo" },
] };
}
export async function screenEvent({ name, state }) {
if (name === "search") return { state: { query: String(state.inputs.q ?? "").trim().slice(0, 100), inputs: { q: "" } } };
return null;
}
El campo de un chat con su icono de enviar adentro (el icono y Enter envían el mismo evento):
{ "type": "TextField", "key": "msg", "hintText": "Escribe un mensaje", "hintTextEn": "Type a message", "maxLength": 300,
"onSubmitted": "send", "trailingIcon": "send", "trailingLabel": "Enviar", "trailingLabelEn": "Send", "onTrailingTap": "send" }
- Icono al final: los tres,
trailingIcon,trailingLabelyonTrailingTap, o el campo se dibuja sin el icono (queda en el registro): un icono desconocido, una etiqueta que falta o es demasiado larga, una acción que falta o es inválida.trailingIconpuede ser un mapa por tamaño (una clase sin él no dibuja icono ahí). Nunca se muestra en un campo deshabilitado. Solo en un campo de una línea: unTextFieldde varias líneas lo ignora (queda en el registro). - Teléfono y televisor: en el teléfono, tocar el icono envía el texto tal como está escrito, primero su cambio pendiente. En el televisor el icono es una parada de foco propia dentro de la caja del campo: Derecha desde el campo llega a él, Izquierda vuelve, Arriba y Abajo salen como desde el campo; OK sobre él envía lo que el campo tiene.
- Televisor: el texto en el televisor es un campo simulado: el campo se dibuja como una fila que muestra su valor
y que, al pulsarla, abre el diálogo de texto de Kino para televisor con su teclado en pantalla.
onChangedy luegoonSubmittedse disparan una vez, al aceptar el diálogo, con el valor final, sin recortar. Un teclado físico en un televisor confirma con Enter o cuando el foco sale. - Teléfono y televisor: el teléfono usa un campo normal y el teclado del teléfono;
onChangedespera una pausa (300 ms). Tu código no puede saber cómo se escribió un valor y nunca lo necesita. - Límites y errores comunes:
keyes obligatoria (una clave de campo que falta o se repite descarta el nodo). No hay tipo contraseña: un campo enmascarado esobscureText: true(campos secretos). Para vaciar o prellenar un campo, responde{ state: { inputs: { q: "" } } }. Kino nunca autocompleta los datos guardados de la persona.
Campos secretos (obscureText)¶
obscureText: true enmascara un TextField de una línea como una contraseña, en el teléfono (puntos, el teclado de
contraseña, el ojo de mostrar / ocultar de Kino cuando no hay trailingIcon) y en el televisor (puntos en el campo, el
diálogo de texto enmascarado con su botón de mostrar / ocultar, el mismo camino con el control que cualquier campo).
Ponlo en un Form para revisar y enviar un token o una contraseña con un «Siguiente»:
{ "type": "Form", "key": "login", "onSubmitted": "next", "children": [
{ "type": "TextField", "key": "token", "obscureText": true, "labelText": "Token", "required": true, "minLength": 20 },
{ "type": "ElevatedButton", "labelText": "Siguiente", "labelTextEn": "Next", "submit": true }
] }
export async function screenEvent({ name, value }) {
if (name !== "next") return null;
const ok = /^[A-Za-z0-9_-]{20,}$/.test(value.token); // what was typed, only in this call
return ok ? { state: { step: "done" } } : { toast: "Token no válido", toastEn: "Invalid token" }; // the field is now empty
}
- A dónde va el texto: solo con el toque o el envío de la propia persona, en
state.inputs.<clave>y, para elonSubmitteddel formulario o del propio campo (oonTrailingTap), envalue. Nunca en un render descreen(), un cambio, el tic de un temporizador,open, un «cargar más» ni elonClosede una ventana. - Nunca se guarda: ni en el estado de la pantalla (así que tampoco en el estado guardado de un panel del reproductor,
en una pantalla restaurada ni en nada que se sincronice), ni en los registros de Kino ni en sus informes de fallos, ni en
las sugerencias del teclado ni en Autofill. Cuando termina la llamada que lo llevó (respondida, fallida o vencida) el
campo vuelve a quedar vacío, salvo que tu respuesta devuelva un texto en
state: { inputs: { <clave>: "..." } }(solo se guarda en memoria) o que la persona haya escrito algo nuevo mientras tanto. Cerrar la pantalla lo olvida. - Sus propias reglas:
valuedel árbol yonChangedse ignoran (queda en el registro); unobscureTextque no estruenifalse, o en un campo de varias líneas, descarta el campo. Las reglas de formulario (required,minLength,pattern) revisan lo que se escribió. bind: solo a un ajustepassword(y una contraseña solo se vincula a un campo secreto): el campo siempre empieza vacío (una contraseña nunca se lee de vuelta) y escribe lo que se escribió al confirmar; un campo vacío nunca borra la contraseña (usaconfig: { <clave>: null }).- Editar un secreto guardado: un secreto guardado nunca se muestra, así que el campo empieza vacío. Déjalo
required: false(unpatternominLengthigual revisa lo que se escribió, y un campo vacío pasa) y lee unvaluevacío como "conservar el guardado": escribeconfigsolo cuando la persona escribió algo, y ofrece un botón aparte que envíeconfig: { <clave>: null }para quitarlo.
TextField de varias líneas¶
Un TextField con multiline: true (o un maxLines mayor que 1 en cualquier clase de tamaño) acepta varias líneas: un
mensaje, una nota. Kino lo lee como el antiguo textArea.

| 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 |
multiline |
boolean | false |
no | true (o maxLines mayor que 1) hace que un TextField tenga varias líneas |
maxLines |
integer | ninguno | no | mayor que 1 en cualquier clase de tamaño: varias líneas |
kind |
text | number | email | url | search |
text |
no | como en un campo de una línea |
value |
string | "" |
no | el texto inicial |
maxLength |
1 a 2.000 | 2.000 | no | también es regla de formulario |
onSubmitted |
acción | ninguno | no | se envía solo en el televisor (el teclado de varias líneas del teléfono no tiene envío: agrega un botón) |
bind |
una clave de ajuste | ninguno | no | muestra y guarda uno de tus ajustes text (bind) |
required |
boolean | false |
no | regla de formulario: un texto no vacío, una opción elegida, un interruptor encendido, un chip escogido |
minLength |
integer | ninguno | no | regla de formulario: caracteres (chips: chips escogidos) |
pattern |
string | ninguno | no | regla de formulario: tiene que coincidir con el valor entero; el subconjunto seguro propio de Kino, máximo 200 caracteres (Patrones) |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "TextField", "key": "note", "labelText": "Nota", "labelTextEn": "Note", "multiline": true, "maxLength": 500 }
export async function screen() {
return { type: "Column", gap: 8, children: [
{ type: "TextField", key: "note", labelText: "Nota", maxLines: 4, maxLength: 500 },
{ type: "ElevatedButton", labelText: "Guardar", onPressed: "saveNote" },
] };
}
- Televisor: el diálogo de texto de varias líneas para televisor;
onSubmittedse envía solo en el televisor. - Errores comunes: el teclado de varias líneas del teléfono no tiene envío: dale siempre un botón al campo.
DropdownButton¶
Una opción entre options en un campo cerrado que abre un selector: un idioma, un orden, una calidad. Su valor es el
value de la opción (o null antes de elegir).

| 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 | 1 a 500, valores distintos |
value |
string | ninguno (null) |
no | el valor de la opción elegida |
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 opción elegida, un interruptor encendido, un chip escogido |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "DropdownButton", "key": "lang", "labelText": "Idioma", "labelTextEn": "Language", "value": "es", "onChanged": "lang", "options": [
{ "value": "es", "label": "Español", "labelEn": "Spanish" },
{ "value": "en", "label": "Inglés", "labelEn": "English" }
] }
export async function screen() {
const sorts = [["new", "Más reciente"], ["title", "Título"]];
return { type: "DropdownButton", key: "sort", labelText: "Ordenar", value: "new", onChanged: "sort", options: sorts.map(([value, label]) => ({ value, label })) };
}
- Televisor: OK abre el selector de Kino; el foco se queda adentro hasta elegir o pulsar Atrás (sobre una ventana abierta, solo el selector recibe foco).
- Límites y errores comunes: 1 a 500 opciones con valores distintos.
bindlleva un ajusteselectotext.
RadioGroup¶
Una opción entre unas pocas options, todas visibles a la vez: de dos a cinco opciones que la persona debería comparar.

| 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 | 1 a 500, valores distintos |
value |
string | ninguno (null) |
no | el valor de la opción elegida |
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 opción elegida, un interruptor encendido, un chip escogido |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "RadioGroup", "key": "plan", "labelText": "Plan", "value": "free", "options": [
{ "value": "free", "label": "Gratis", "labelEn": "Free" },
{ "value": "family", "label": "Familiar", "labelEn": "Family" }
] }
export async function screen() {
return { type: "RadioGroup", key: "quality", labelText: "Calidad", value: "auto", onChanged: "quality", options: ["auto", "720p", "1080p"].map((value) => ({ value, label: value })) };
}
- Errores comunes: en un formulario, el error de un
RadioGroupque falla se muestra en el grupo.
Checkbox¶
Una casilla con su etiqueta: "Acepto las condiciones", un elemento de una lista para escoger. En un formulario,
required significa marcada.

| 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) |
onChanged |
acción | ninguno | no | la persona lo cambió; el value del evento es el valor nuevo |
value |
boolean | false |
no | marcada o no |
bind |
una clave de ajuste | ninguno | no | muestra y guarda uno de tus ajustes toggle (bind) |
required |
boolean | false |
no | regla de formulario: un texto no vacío, una opción elegida, un interruptor encendido, un chip escogido |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "Checkbox", "key": "terms", "labelText": "Acepto las condiciones", "labelTextEn": "I accept the terms", "required": true, "errorText": "Hace falta aceptarlas", "errorTextEn": "You need to accept them" }
export async function screen({ state }) {
return { type: "Checkbox", key: "remember", labelText: "Recordarme", value: state.inputs?.remember === true };
}
Switch¶
Un ajuste de encendido / apagado que se aplica en el acto. Con bind guarda por sí solo uno de tus ajustes toggle.

| 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) |
onChanged |
acción | ninguno | no | la persona lo cambió; el value del evento es el valor nuevo |
value |
boolean | false |
no | encendido o apagado |
bind |
una clave de ajuste | ninguno | no | muestra y guarda uno de tus ajustes toggle (bind) |
required |
boolean | false |
no | regla de formulario: un texto no vacío, una opción elegida, un interruptor encendido, un chip escogido |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "Switch", "key": "autoplay", "labelText": "Reproducir solo", "labelTextEn": "Autoplay", "value": true, "onChanged": "autoplay" }
export async function screen() {
return { type: "Switch", key: "tipsSwitch", labelText: "Mostrar consejos", bind: "tips" }; // "tips" is a toggle setting of the manifest
}
- Televisor: OK lo cambia. Errores comunes: un
Switches un interruptor: para elegir entre dos opciones con nombre usa unRadioGroup.
Slider¶
Un número entre min y max, de step en step: un volumen, un nivel. Su valor en state.inputs es un número.

| 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 |
min |
number | 0 |
no | menor que max |
max |
number | 100 |
no | mayor que min |
step |
number | ninguno (continuo) | no | mayor que 0 y como máximo max - min |
value |
number | min |
no | ajustado a min..max |
bind |
una clave de ajuste | ninguno | no | muestra y guarda uno de tus ajustes text (bind) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "Slider", "key": "volume", "labelText": "Volumen", "labelTextEn": "Volume", "min": 0, "max": 10, "step": 1, "value": 5, "onChanged": "volume" }
export async function screen({ state }) {
const v = Number.isFinite(state.inputs?.level) ? state.inputs.level : 30;
return { type: "Column", gap: 8, children: [
{ type: "Slider", key: "level", min: 0, max: 100, step: 10, value: v, onChanged: "level" },
{ type: "Text", text: "Nivel " + v },
] };
}
- Errores comunes:
mintiene que ser menor quemax(si no, se descarta); unstepfuera de0..max-minse descarta (queda en el registro). No tiene reglas de formulario propias;bindlleva un ajustetext(su número como texto).
NumberStepper¶
Un número dibujado [ − ] valor [ + ]: asientos, porciones, un precio. Cada pulsación lo mueve de step en step, dentro
de min..max y redondeado a decimals; mantener un botón pulsado repite, cada vez un poco más rápido. Su valor en
state.inputs es texto ("2.50"). El Stepper de Flutter es otro widget (un asistente de pasos): ese nombre aquí
no se conoce.

| 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 |
value |
number | min, si no 0 |
no | redondeado a decimals; en state.inputs como texto ("2.50") |
min |
number | ninguno | no | menor que max |
max |
number | ninguno | no | mayor que min |
step |
number > 0 | 1 |
no | redondeado a decimals |
decimals |
0 a 6 | 0 |
no | |
editable |
boolean | false |
no | deja que la persona lo escriba (solo dígitos); solo con decimals: 0 y un min de 0 o más |
bind |
no | no se acepta (se ignora, queda en el registro) | ||
required |
boolean | false |
no | regla de formulario: un texto no vacío, una opción elegida, un interruptor encendido, un chip escogido |
errorText |
string | el texto de Kino | no | regla de formulario: lo que la persona lee debajo del campo que falla (errorTextEn) |
forceErrorText |
string | ninguno | no | tu propio veredicto debajo del campo (forceErrorTextEn, máximo 200 caracteres) hasta que la persona lo edita (validación) |
{ "type": "Column", "gap": 12, "children": [
{ "type": "NumberStepper", "key": "seats", "labelText": "Asientos", "labelTextEn": "Seats", "value": 2, "min": 1, "max": 8, "editable": true },
{ "type": "NumberStepper", "key": "price", "labelText": "Precio", "labelTextEn": "Price", "value": 2.5, "min": 0, "max": 10, "step": 0.25, "decimals": 2 }
] }
export async function screen({ state }) {
const seats = Number(state.inputs?.seats ?? "2"); // text in state.inputs
return { type: "Column", gap: 8, children: [
{ type: "NumberStepper", key: "seats", value: seats, min: 1, max: 8, onChanged: "seats" },
{ type: "Text", text: "Total: " + seats * 5 },
] };
}
- Televisor: Izquierda y Derecha se mueven entre −, el valor (solo con
editable) y +; un botón en su límite sigue recibiendo foco (dibujado apagado), así que mantener OK pulsado nunca pierde el foco.editableabre el teclado de solo dígitos del televisor. - Límites y errores comunes: máximo 6 decimales; números de máximo 1e15 hacia cualquier lado (se ajustan, queda en el
registro).
editablesolo condecimals: 0y unminde 0 o más (si no, se ignora, queda en el registro). Sinbind. Surequiredsiempre pasa (siempre tiene un valor).
Foco en el televisor¶
Kino dibuja en el televisor uno de dos aspectos de foco, según el tipo de nodo; un plugin nunca lo elige.
| Nodo | Foco en el televisor |
|---|---|
Switch, Checkbox, cada fila de un RadioGroup |
fila: un tinte suave sobre toda la fila y un subrayado de acento a lo largo de su borde inferior |
TextField (de una línea o de varias), DropdownButton, Slider |
fila |
botones (ElevatedButton, TextButton, IconButton...), FloatingActionButton |
anillo: un contorno blanco y un relleno suave |
Chips, TabBar, elementos de NavigationBar, botones de NumberStepper |
anillo |
una Card, ListTile, Text o Icon pulsable; tarjetas de títulos |
anillo |
Una fila deja al menos 16 dp entre sus bordes y su texto, así que ni el tinte ni el subrayado tocan una letra. Un lector
de pantalla lee el nodo enfocado como siempre. El nodo settings es el formulario de ajustes propio de Kino: sus filas de
interruptor y de opción también muestran el aspecto de fila, como toda fila y campo de ancho completo de Kino en el
televisor. En el televisor sus filas miden al menos 56 dp de alto (12 dp arriba y abajo de su texto, las opciones de un
select separadas 4 dp, 8 dp bajo su etiqueta), así que el subrayado de una fila enfocada nunca toca la siguiente; en el
teléfono, al menos 48 dp. Sus filas no se quedan con ninguna tecla del control: Arriba y Abajo desde su primera o última
fila siguen como desde cualquier nodo (la fila de arriba, si no una página, si no la pestaña del AppBar), e Izquierda y
Derecha se quedan en una fila de interruptor o de opción.
Cómo se mueve el foco por una pantalla entera está en la guía: Foco en el televisor.
Validación¶
Cada campo de un Form acepta las reglas que lista la tabla de campos:
required: un texto no vacío, una opción elegida, un interruptor o una casilla encendidos, un chip escogido. Un campo vacío que no es obligatorio pasa todas las revisiones.minLength/maxLength: caracteres de un texto; chips escogidos de unChips.pattern: un patrón con el que tiene que coincidir el texto entero.errorText/errorTextEn: lo que la persona lee debajo del campo que falla (en el grupo, para unRadioGroupo unosChips); sin él, el mensaje propio de Kino.
Los valores de los campos hidden o deshabilitados se envían igual, sin revisar; un campo obligatorio dentro de un
TableRow oculto no se revisa.
Tu propio veredicto: forceErrorText (y forceErrorTextEn), el de Flutter, en cualquier campo, desde tu estado: Kino
lo dibuja debajo del campo igual que sus propios errores (el de un envío fallido gana mientras se muestra) y un lector de
pantalla lo lee con el campo. Cuando la persona edita el campo se oculta hasta tu siguiente veredicto: la respuesta a su
siguiente pulsación o envío, o un texto distinto. Máximo 200 caracteres. Nunca bloquea un envío.
{ "type": "TextField", "key": "code", "kind": "number", "labelText": "Código", "labelTextEn": "Code", "forceErrorText": "El código no es válido", "forceErrorTextEn": "That code is not valid" }
Las reglas en un campo fuera de un formulario no se usan. El veredicto de Kino es el que cuenta: vuelve a revisar en tu código solo lo que tu propia lógica necesite.

Patrones (el comparador propio de Kino)¶
El motor de patrones es propio de Kino (un comparador de tiempo lineal, el mismo en la app y en el kit), nunca las
expresiones regulares de la plataforma, así que un patrón hostil no puede congelar el aparato. Un patrón tiene que
coincidir con el valor entero, en un subconjunto seguro: literales, ., ^, $, |, grupos ( ) y (?: ), clases
[...], los escapes \d \D \w \W \s \S \b \B \n \r \t y la puntuación escapada, los cuantificadores
* + ? {n} {n,} {n,m} (opcionalmente perezosos), que se pueden anidar. Sin referencias hacia atrás ni lookarounds. Los
significados son ASCII: \d es [0-9], \w [A-Za-z0-9_], \s espacio en blanco ASCII, . cualquier carácter menos
un salto de línea.
| Límite | Valor |
|---|---|
| Un patrón | máximo 200 caracteres |
Una cuenta ({n,m}) |
máximo 1.000 |
| Pasos una vez expandidas las cuentas | máximo 500 (así que [a-z]{1,600} se rechaza: escribe [a-z]+ y maxLength: 600) |
| Trabajo para leer un patrón | 20.000 unidades |
| Un envío | máximo 16 patrones y 4.000.000 de pasos del comparador; pasado cualquiera de los dos, los patrones restantes pasan |
Un patrón fuera del subconjunto se descarta (queda en el registro) y el campo sigue revisando sus otras reglas.
pattern: "^[^@\\s]+@[^@\\s]+\\.[A-Za-z]{2,}$" // an email (in JSON, every backslash doubled)
pattern: "^\\d{4,6}$" // a code of 4 to 6 digits
pattern: "^[A-Za-z0-9 ]+$" // letters, digits and spaces
Reglas del envío¶
- El botón con
submit: trueenvía; su propioonPressedse ignora. Se dibuja 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 que falla y el foco va al primero.
- Enter no envía un formulario, y el
onSubmittedpropio de un campo dentro de un formulario corre sin la revisión del formulario. - Un campo obligatorio dentro de un elemento cerrado de un
ExpansionTileno deja el botón apagado, pero el envío lo revisa y, si falla, abre el elemento y lo enfoca. - El
onSubmitteddel formulario recibevalue: el valor de cada campo por clave (los mismos tipos questate.inputs).
Nodo settings¶
El formulario de ajustes propio de Kino para tu plugin, el mismo que muestra Ajustes, dentro de tu pantalla: todos los
tipos de ajuste, los dos idiomas, la validación, los campos de Kino para secretos y sus botones para acciones, «Enviar a
otro aparato», su propio guardado. keys muestra solo esos ajustes, en ese orden. Tu código nunca ve lo que se escribe
ahí; con onSaved se entera de que terminó un guardado o un botón de acción, nunca de los valores (onSaved).
El formulario en sí está descrito en El formulario de ajustes; la guía lo muestra dentro de una
pantalla en Ajustes dentro de una pantalla.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
keys |
string[] | todos los ajustes | no | solo esos ajustes, en ese orden; cada ajuste se muestra como máximo una vez por pantalla |
autoSave |
boolean | false |
no | sus ajustes toggle y select se guardan al cambiar (sin validateSettings); si solo tiene esos, no hay Guardar (nodo settings) |
onSaved |
nombre de evento o { event, arg? } |
ninguno | no | se envía después de que el formulario de Kino aquí guardó (Guardar, o un autoguardado) o de que terminó uno de sus botones de acción: value es { kind, ok, keys, action?, reason? }, solo claves de ajustes, nunca un valor (onSaved) |
{ "type": "Column", "gap": 12, "children": [
{ "type": "Text", "text": "Ajustes", "textEn": "Settings", "style": "h3" },
{ "type": "settings", "keys": ["density"] }
] }
autoSave:trueguarda los interruptores y las opciones del nodo a medida que la persona los cambia, por el mismo almacén y la misma sincronización (no se le pregunta a tuvalidateSettings, igual que conbind; tu sesión web se mantiene); una escritura rechazada vuelve a poner el valor guardado. Cuando todos los ajustes con valor que muestra el nodo son interruptores u opciones, Kino no dibuja Guardar ni Descartar; un texto, una dirección, una contraseña o una lista los conservan. Un ajuste bloqueado solo se guarda después de su código.- Solo botones: un nodo cuyas claves no tienen ningún ajuste con valor (
keys: ["logout"]: una acción, un estado, una sección, un enlace, una ayuda, un QR) dibuja solo esos elementos y no dibuja Guardar ni Descartar; la acción corre desde su propio botón, primero suconfirm, exactamente como en Ajustes. - Un ajuste bloqueado (
"unlockWith": "adultCode"en el manifiesto, un interruptor o una opción): moverlo de su valor por defecto aquí pide primero el código +18 del aparato con el aviso propio de Kino (teléfono y televisor); un código equivocado o Cancelar conservan el valor anterior, y volver hacia el valor por defecto nunca lo pide. Solo este nodo (y Ajustes) lo aleja del valor por defecto: nuncabindniconfig(Un ajuste que protege el código +18). - Límites y errores comunes: nunca dentro de un
Formni en la ventana de una respuesta. Cada ajuste se muestra como máximo una vez por pantalla, así que varios nodossettingsno son problema. Un ajusteurlsolo se puede llenar aquí (nunca conbindniconfig). Unpasswordse puede llenar aquí, con elconfigde una respuesta o con un campoobscureTextvinculado a él (campos secretos).
onSaved¶
onSaved (un nombre de evento o { event, arg }) se envía después de que el formulario de Kino en este nodo guardó (su
Guardar, o, con autoSave, un interruptor u opción que se guardó al cambiar: kind: "save" con esa clave; un autoguardado
que no cambió nada no envía ninguno) o de que terminó uno de sus botones de acción (un nodo con solo botones no tiene
Guardar: solo kind: "action"), para que tu pantalla reaccione en el acto en lugar de en el siguiente tic de
every. Los autoguardados rápidos que aún esperan se juntan en un solo evento. El value del
evento:
| Campo | Qué trae |
|---|---|
kind |
"save" o "action" |
ok |
true cuando guardó, o la acción corrió y respondió |
keys |
los ajustes que cambiaron (solo claves, ordenadas): lo que se editó, lo que una acción borró o llenó; nunca un valor |
action |
la clave del botón de acción (solo con kind: "action") |
reason |
cuando no es ok: rejected (tu validateSettings lo rechazó), checkFailed (no pudo revisar), refused (el almacén de Kino lo rechazó), failed (la acción lanzó un error o se le acabó el tiempo) |
export async function screenEvent({ name, value }) {
if (name === "saved" && value.ok && value.keys.includes("twoStepPassword")) return { state: { step: "login" } };
return null;
}
- Orden y ritmo: espera en la cola de la pantalla como los eventos de la propia persona (el tic de un temporizador nunca corre antes). Un guardado mientras el evento de un guardado anterior aún espera se junta con él (las claves de los dos, el último veredicto); los eventos de acción nunca se juntan. No es una pulsación de nadie: su respuesta no abre ninguna página de título ni ningún enlace.
- Una pantalla cerrada: un guardado o una acción que termina después de que la pantalla se cerró (o de que el nodo
salió del árbol) no envía nada; el
opende la siguiente apertura leekino.configcomo siempre. El guardado en sí siempre queda hecho. - Nunca un valor: la clave de una contraseña puede estar en
keys; su texto, nunca.
bind y config¶
bind: "<claveDeAjuste>"en un campo muestra el valor guardado cuando se abre la pantalla y escribe por sí solo el cambio de la persona: una opción al cambiar, un texto al confirmar (la acción del teclado, el foco que sale, el aceptar del diálogo del televisor), solo cuando es distinto. Igual recibes los eventos del campo. Una pestaña de ajustes simple no necesita nada de JavaScript.config: { <claveDeAjuste>: valor }en una respuesta escribe ajustes desde tu código: solo claves que tu manifiesto declara, máximo 32 por respuesta, cada valor acorde a su tipo (textun string,toggleun boolean,selectuno de sus valores,listun arreglo de registros,passwordun string).- Un
passwordse guarda exactamente como llega (nunca se recorta);null,""o solo espacios lo vacían (nunca unorequired); máximo 500 caracteres. Se guarda donde Ajustes guarda uno escrito: una contraseña sincronizada llega a los otros aparatos de la persona (una vaciada se borra también ahí), una con"sync": falsese queda en este aparato. Una pantalla nunca la lee de vuelta (bindnunca la prellena,statenunca la tiene) y Kino nunca escribe su texto en una línea del registro, solo su clave. Vincúlala solo con un campoobscureText(campos secretos). - Nunca desde una pantalla: un ajuste
url, un ajusteactionohelp, un valor que contenga uno de tus secretos sellados, una escritura delistque agregue una dirección, un ajuste conunlockWithalejado de su valor por defecto (ningún campo se vincula a uno). Todo eso se descarta y queda en el registro. - Ritmo y costo: cada ajuste se escribe como máximo una vez cada 500 ms por pantalla (la respuesta de un
temporizador: una vez por minuto); cada escritura reinicia tu runtime para que
kino.configlea el valor nuevo (los interruptores y las opciones conservan tu sesión web; cualquier otra escritura es el Guardar completo de Kino).
{ "type": "Column", "gap": 8, "children": [
{ "type": "TextField", "key": "greetingField", "bind": "greeting", "labelText": "Saludo", "labelTextEn": "Greeting" },
{ "type": "Switch", "key": "tipsField", "bind": "tips", "labelText": "Mostrar consejos", "labelTextEn": "Show tips" },
{ "type": "DropdownButton", "key": "densityField", "bind": "density", "labelText": "Densidad", "labelTextEn": "Density", "options": [
{ "value": "compact", "label": "Compacta", "labelEn": "Compact" }, { "value": "normal", "label": "Normal" }, { "value": "roomy", "label": "Amplia", "labelEn": "Roomy" }
] }
] }
{ "config": { "greeting": "Hola", "tips": false }, "toast": "Guardado", "toastEn": "Saved" }
Ventanas emergentes¶
Una ventana 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 cierre: una X sola (un lector de pantalla dice «Cerrar», «Close» en inglés), al
final de la fila del título o, sin título, al principio (a la izquierda) de la fila de abajo, con tus botones juntos al
final (a la derecha), nunca al lado de tu acción principal; los botones que no caben pasan a más líneas, siempre al
final. Hay dos formas de mostrar una: desde una respuesta (dialog, sheet, menu: las arma screenEvent, con
texto o nodos simples) o declarada en el árbol (un nodo popup, oculto hasta que un open de
ui lo nombra, cuyo cuerpo es parte de tu árbol y puede llevar formularios y campos).
Dialog¶
Una pregunta o un mensaje corto que necesita respuesta. Desde una respuesta: dialog: { title, body, buttons } (máximo 3
botones; uno sin event lo cierra). Declarado: un nodo AlertDialog con children y buttons.

{ "dialog": { "title": "¿Borrar la lista?", "titleEn": "Delete the list?", "body": "No se puede deshacer.", "bodyEn": "It cannot be undone.",
"buttons": [{ "label": "Borrar", "labelEn": "Delete", "event": "deleteList", "variant": "primary" }, { "label": "Cancelar", "labelEn": "Cancel", "variant": "text" }] } }
export async function screenEvent({ name }) {
if (name === "ask") return { dialog: { title: "¿Seguro?", titleEn: "Are you sure?", buttons: [{ label: "Sí", labelEn: "Yes", event: "yes" }, { label: "No" }] } };
if (name === "yes") return { toast: "Hecho", toastEn: "Done" };
return null;
}
- Televisor: el foco se queda dentro del diálogo; su primer foco es su primer nodo enfocable, si no (un cuerpo más alto que el marco sin nada que enfocar) el cuerpo mismo, si no su primer botón, si no su cierre; un cuerpo más alto que el marco se desplaza con Abajo y Arriba (deja un botón al final). Solo el control enfocado dibuja el anillo de Kino: el marco y un cuerpo que se desplaza nunca lo hacen (el desplazamiento es la señal). Izquierda y Derecha se mueven entre la X de Kino y tus botones en la fila de abajo.
- Teléfono y televisor: un diálogo centrado en los dos.
- Límites y errores comunes: con más de uno de
dialog,sheetymenuen una respuesta, gana el diálogo. La ventana de una respuesta nunca lleva unForm, unExpansionTile,bindni el nodosettings(para eso, declara una).
Sheet¶
Más espacio que un diálogo para detalles o unas pocas acciones: una hoja inferior en el teléfono, un panel lateral en el
televisor. Desde una respuesta: sheet: { title, body }; declarada: un nodo BottomSheet.

{ "sheet": { "title": "Compartir", "titleEn": "Share", "body": [
{ "type": "Text", "text": "Escanéalo con tu teléfono.", "textEn": "Scan it with your phone." },
{ "type": "QrImage", "value": "https://kinotvapp.github.io/kino-plugins/", "size": "small" }
] } }
export async function screenEvent({ name }) {
return name === "info" ? { sheet: { title: "Información", body: "Una línea de texto.", bodyEn: "A line of text." } } : null;
}
- Teléfono y televisor: abajo de la pantalla en el teléfono, al costado en el televisor. Atrás la cierra.
Menu¶
Una lista corta de acciones (de 1 a 8 elementos con una etiqueta, un icono opcional y un onTap); el menú se cierra antes
de que corra la acción del elemento. Desde una respuesta: menu: { title, items }; declarado: un nodo PopupMenuButton
que se abre con { open: key }.

{ "menu": { "title": "Ordenar por", "titleEn": "Sort by", "items": [
{ "label": "Más reciente", "labelEn": "Newest", "icon": "star", "onTap": { "event": "sort", "arg": "new" } },
{ "label": "Título", "labelEn": "Title", "icon": "list", "onTap": { "event": "sort", "arg": "title" } }
] } }
export async function screen() {
return { type: "Column", children: [
{ type: "TextButton", labelText: "Ordenar", onPressed: { ui: [{ open: "sortMenu" }] } },
{ type: "PopupMenuButton", key: "sortMenu", items: [{ label: "Título", onTap: { event: "sort", arg: "title" } }, { label: "Año", onTap: { event: "sort", arg: "year" } }] },
] };
}
- Teléfono y televisor: un menú no queda pegado a lo que lo abrió: en el teléfono es una lista de acciones abajo del
lienzo, en el televisor queda centrado (para dibujar uno junto a un nodo, mira
anchor). - Límites y errores comunes: máximo 8 elementos; un elemento de menú lleva
labelyonTap(nuncalabelText/onPressed).
Ventanas declaradas, open y close de ui, onClose¶
Un nodo popup (AlertDialog, BottomSheet, PopupMenuButton, o popup con su kind) con una key, en cualquier
parte del árbol, oculto hasta que un open de ui lo nombra. Su cuerpo es parte de tu árbol, así que puede llevar
formularios y campos, y tu siguiente render lo actualiza.

| Propiedad | Tipo | Por defecto | Por tamaño | Notas |
|---|---|---|---|---|
key |
string | obligatorio | no | lo que nombran { open: key } y { close: key } |
kind |
dialog | sheet | menu |
lo fija el tipo | no | AlertDialog es dialog, BottomSheet sheet, PopupMenuButton menu |
title |
string | ninguno | no | titleEn; sin él (o en blanco) no se dibuja una fila de título vacía |
children |
nodos[] | ninguno | no | el cuerpo de un diálogo o de una hoja: se permiten formularios y campos |
buttons |
{ label, labelEn?, event?, arg?, variant? }[] |
ninguno | no | los de un diálogo, máximo 3; uno sin event lo cierra |
items |
{ label, labelEn?, icon?, onTap }[] |
obligatorio para un menú | no | 1 a 8; el menú se cierra primero |
onClose |
nombre de evento o { ui?, event?, arg? } |
ninguno | no | corre después de que la persona la cerró (Atrás, el cierre de Kino, un toque afuera), nunca después de sus propios botones |
anchor |
la clave de un nodo | ninguno | no | se dibuja junto a ese nodo, sobre el contenido, sin ocupar espacio (ventana anclada); la única ventana que dibuja un panel del reproductor |
La forma segura de abrir una con contenido nuevo es desde la respuesta, no desde el toque: el toque envía el evento,
la respuesta actualiza el estado y lleva ui: [{ open }]; Kino la abre cuando el árbol nuevo ya está dibujado, así que
la ventana nunca muestra el cuerpo del elemento anterior (Atrás antes de eso la cancela). Ciérrala igual después de su
propio Guardar.
{ "type": "AlertDialog", "key": "story", "title": "Una historia", "titleEn": "A story", "onClose": "storyClosed",
"children": [{ "type": "Text", "text": "El texto de la historia.", "textEn": "The story's text." }],
"buttons": [{ "label": "Cerrar", "labelEn": "Close" }] }
export async function screen({ state }) {
return { type: "Column", children: [
{ type: "ElevatedButton", labelText: "Leer", onPressed: { event: "read", arg: "42" } },
{ type: "AlertDialog", key: "story", title: "Historia " + (state.reading || ""), onClose: "storyClosed", children: [{ type: "Text", text: "…" }] },
] };
}
export async function screenEvent({ name, arg }) {
if (name === "read") return { state: { reading: arg }, ui: [{ open: "story" }] }; // opens once the new tree is drawn
if (name === "storyClosed") return { state: { reading: null } }; // the person dismissed it
return null;
}
onClose(un nombre de evento, o{ ui?, event?, arg? }) corre después de que la persona cerró la ventana (Atrás, el cierre de Kino, un toque afuera), nunca después de sus propios botones, de un elemento de menú, de tucloseni de otra ventana que la reemplace. Su evento no es una pulsación: nada dekino.qr.scan, nada dego.titleByIdsnigo.url; su respuesta no abre ninguna ventana, no mueve el foco y no va a ninguna parte (se descarta, queda en el registro).- Televisor: el foco queda atrapado dentro de la ventana abierta; Atrás la cierra y el foco vuelve a lo que la abrió.
- Límites y errores comunes:
titlees opcional (sin él no se dibuja una fila vacía; nunca pases" "). Una ventana cuyo nodo estáhiddenno se puede abrir. Si una ventana está abierta no aparece enstate.ui. En un panel en modo pantalla un nodopopupse descarta (las ventanas son de la pantalla), salvo que tenga unanchor(abajo).
Ventana anclada (anchor)¶
anchor (la clave de un nodo) convierte cualquier ventana declarada en un globo: Kino la dibuja junto a ese nodo,
arriba si hay más espacio arriba, si no abajo, del tamaño de su contenido y como máximo del ancho del área, sobre el
contenido sin oscurecerlo y sin ocupar espacio en la disposición. Se abre y se cierra como cualquier ventana (open y
close de ui, Atrás, un toque afuera) y no tiene botón de cierre propio. Una elección rápida al lado de un botón (una
reacción, una velocidad, un orden):
{ "type": "Row", "children": [
{ "type": "IconButton", "key": "react", "icon": "mood", "labelText": "Reacciones", "labelTextEn": "Reactions",
"onPressed": { "ui": [{ "open": "palette" }] } },
{ "type": "PopupMenuButton", "key": "palette", "anchor": "react", "items": [
{ "label": "Me gusta", "labelEn": "Like", "icon": "heart", "onTap": { "event": "react", "arg": "like" } },
{ "label": "Me encanta", "labelEn": "Love", "icon": "star", "onTap": { "event": "react", "arg": "love" } }] }
] }
- Televisor: el foco entra en ella (su primer elemento enfocable, o su nodo con
autofocus) y se queda adentro mientras está abierta; Atrás la cierra y le devuelve el foco al ancla. - Panel del reproductor: un
popupconanchores la única ventana que dibuja un panel en modo pantalla, dentro del panel. - Alternativa: cuando el ancla no está en pantalla, o no hay espacio ni arriba ni abajo (una ventana compacta, un
cuerpo alto), se dibuja en el lugar propio de su tipo y queda una vez en el registro. Sin
anchorse comporta como siempre.
Navegación¶
La acción de un nodo o una respuesta pueden llevar go: una de diecisiete formas, siempre hacia el contenido propio de este
plugin o hacia una de las páginas propias de Kino. La página de Kino se abre sobre tu pantalla; Atrás vuelve a ella con
su estado. Como máximo un go que abre una página cada 500 ms. Ninguna forma nombra un intent ni una app, y solo
liveChannel, installPlugin y plugin nombran a otro plugin (liveChannel, un proveedor de En vivo, a cuyo canal Kino
sintoniza para un plugin cuya pestaña del reproductor se une a los canales en vivo; installPlugin, un repositorio cuya hoja de
instalación abre Kino; plugin, desde Kino 0.9.84, un repositorio cuya pantalla o búsqueda abre Kino). La guía trata go en Navegar con go.
| Forma | Se escribe | Qué abre | Desde dónde se envía |
|---|---|---|---|
title |
{ title: { ref, kind, id, title, adult } } |
la página de título de este plugin | un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
play |
{ play: { ref, kind, id, title, adult } } |
reproduce el título de este plugin | un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
search |
{ search: { q } } |
la búsqueda de Kino con q (máximo 200 caracteres), con este plugin como única fuente (con scope: "all", apiVersion 17, la búsqueda de Kino en todas las fuentes, solo con el toque de la persona) |
un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
browse |
{ browse: { ref, title?, titleEn? } } |
la lista «Ver más» de este plugin para un ref |
un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
section |
{ section: true } |
la sección de este plugin | un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
categories |
{ categories: true } |
las Categorías de Kino, primero el grupo de este plugin | un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
close |
{ close: true } |
cierra la pantalla | un toque o la respuesta a un evento (nunca la de open, la de un temporizador ni la de un onClose) |
screen |
{ screen: { route?, args? } } |
la pantalla propia de este plugin en route (máximo 64 caracteres) con args (máximo 4.096 bytes) |
un toque o una respuesta, incluida la de open |
titleByIds |
{ titleByIds: { tmdb, imdb, kind, season, episode, title, year } } |
la página de título propia de Kino para ids de TMDB o IMDb, con todas las fuentes que tiene la persona | solo la pulsación o el envío de la propia persona |
url |
{ url: { href, title } } |
un enlace https en el navegador, después de la hoja propia de Kino (un código QR en un televisor) | solo la pulsación o el envío de la propia persona |
copy |
{ copy: { text, label, sensitive } } |
Kino copia text (máximo 500 caracteres, 6 líneas) y muestra su propio aviso «Copiado»; un televisor no puede |
solo la pulsación o el envío de la propia persona |
liveChannel |
{ liveChannel: { provider, code } } |
sintoniza el reproductor en el canal de un proveedor de En vivo (solo para un plugin cuya pestaña del reproductor se une a los canales en vivo) | solo la pulsación o el envío de la propia persona |
syncProvider |
{ syncProvider: true } |
los ajustes de proveedor de sincronización de Kino (Ajustes ▸ Conectar ▸ Proveedor), donde la persona elige este plugin (solo para un plugin con syncProvider) |
solo la pulsación o el envío de la propia persona |
useTheme |
{ useTheme: { theme } } |
activa uno de los appThemes de este plugin como lo hace Apariencia, o vuelve al tema de Kino con theme: null; Kino muestra su propio aviso |
solo la pulsación o el envío de la propia persona en tu pantalla, desde apiVersion 18 |
setExperience |
{ setExperience: "light" \| "full" } |
pide la experiencia ligera o la completa de toda la app; Kino le pregunta antes a la persona y no cambia nada sin su sí | solo la pulsación o el envío de la propia persona en tu pantalla, desde apiVersion 18 |
installPlugin |
{ installPlugin: { repo } } |
la hoja de instalación propia de Kino para repo (un owner/name sin más); nada se instala sin el Instalar de la propia persona |
solo la pulsación o el envío de la propia persona en tu pantalla, desde apiVersion 19 |
plugin |
{ plugin: { repo, route?, args?, query? } } |
la pantalla de otro plugin en route con args, o su búsqueda de query, encontrado por repo (un owner/name[/ruta] de GitHub); Kino 0.9.84 |
solo la pulsación o el envío de la propia persona en tu pantalla, desde apiVersion 20 |

go.title¶
Abre la página de título de este plugin. Un título que está en el lienzo (un
titleCard, o un elemento de una fila o de una cuadrícula) se abre con ese mismo
elemento (pasa su id cuando dos elementos comparten un ref); un título que no está en el lienzo necesita su id y su
title (y adult: true cuando es +18).
{ "go": { "title": { "ref": "movie/123", "kind": "movie", "id": "m123", "title": "Una película" } } }
go.play¶
Reproduce el título de este plugin, escrito como title. Un canal en vivo se reproduce; una serie abre su página; una
película, una pista o un episodio de pódcast se reproducen en el acto. El filtro +18 se mantiene.
{ "type": "ElevatedButton", "labelText": "Reproducir", "labelTextEn": "Play", "onPressed": { "go": { "play": { "ref": "live/1", "kind": "live", "id": "c1", "title": "Canal 1" } } } }
go.search¶
La búsqueda de Kino con q ya escrita y con este plugin como única fuente (la persona ve su chip y lo puede quitar). Se
rechaza para un plugin sin search.
{ "go": { "search": { "q": "big buck bunny" } } }
Con scope: "all" (apiVersion 17) abre en cambio la búsqueda normal de Kino en todas las fuentes, con la puerta +18 de
siempre. Tu plugin no se entera de nada: ni de los resultados ni de qué plugins existen. No necesita un search tuyo.
{ "go": { "search": { "q": "big buck bunny", "scope": "all" } } }
go.browse¶
La lista «Ver más» de este plugin para un ref (tu browse).
{ "go": { "browse": { "ref": "genre/drama", "title": "Drama" } } }
go.section¶
La sección de este plugin (sus filas de tarjetas).
{ "go": { "section": true } }
go.categories¶
Las Categorías de Kino con el grupo de este plugin primero; con screen.replaces: ["categories"]
tu propia pantalla en la ruta categories. Se rechaza, y queda en el registro, para un plugin sin sus propios mosaicos
de Categorías.
{ "go": { "categories": true } }
go.close¶
Cierra la pantalla (lo mismo que close: true en la respuesta).
{ "type": "TextButton", "labelText": "Cerrar", "labelTextEn": "Close", "onPressed": { "go": { "close": true } } }
go.screen¶
La pantalla propia de este plugin en una route con args, desde sus otras superficies (su panel del reproductor, sus
elementos y filas de home/section/browse con open: { screen }, la tarjeta de «Mis plugins») o desde dentro de la
pantalla, que vuelve a empezar en esa ruta (el estado se mantiene). El evento reservado open vuelve a llegar con la ruta
nueva, así que un solo camino carga lo que nombran los args. Como máximo un reinicio por segundo.
{ "type": "Button", "variant": "secondary", "labelText": "Ver los ajustes", "labelTextEn": "See the settings", "onPressed": { "go": { "screen": { "route": "main", "args": { "tab": "config" } } } } }
export async function screenEvent({ name, route }) {
if (name === "open" && route.args?.tab === "config") return { state: { tab: "config" } };
return null;
}
go.titleByIds¶
Cómo llegan al mismo título personas con plugins distintos: 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. Al menos uno de tmdb e imdb; no nombra ningún
plugin, ref ni URL, nunca reproduce y no te devuelve nada. Solo desde la pulsación o el envío de la propia persona.
{ "type": "ElevatedButton", "labelText": "Abrir este título", "labelTextEn": "Open this title", "icon": "movie",
"onPressed": { "go": { "titleByIds": { "tmdb": 10378, "kind": "movie", "title": "Big Buck Bunny", "year": 2008 } } } }
- +18: mientras el código +18 de la persona está bloqueado, solo se abre cuando TMDB dice que el título no es para
adultos. Un
imdbsolo cuesta una búsqueda en TMDB («Buscando el título…»). Una serie se abre entera (todavía sin enfocar un episodio).
go.url¶
Le pide a Kino abrir un enlace https en un navegador: un botón «Ver noticia». Nada se abre solo: Kino muestra primero su
propia hoja (el nombre de tu plugin, el host con su final siempre visible, tu title bajo «Texto del plugin:»,
«Cancelar» enfocado primero y «Abrir», inactivo durante sus primeros 600 ms). En un televisor, o en un teléfono sin
navegador, la hoja muestra el enlace como un código QR para escanear.
{ "type": "ElevatedButton", "labelText": "Ver noticia", "labelTextEn": "Read the story", "icon": "language",
"onPressed": { "go": { "url": { "href": "https://kinotvapp.github.io/kino-plugins/", "title": "Guía de plugins" } } } }
href: solohttps://, máximo 2.048 caracteres de ASCII imprimible, un nombre DNS público con un punto (nunca una IP,localhost,.local,.lan...), sinusuario:contraseña@, sin otro puerto que el 443. Solo desde la pulsación o el envío de la propia persona; una respuesta que llega más de 5 s después del toque lo descarta. No te devuelve nada.
go.copy¶
Un botón «Copiar»: Kino pone tu texto en el portapapeles él mismo y siempre muestra su propio aviso, «Copiado» (o «Copiado:
{ "type": "ElevatedButton", "labelText": "Copiar invitación", "labelTextEn": "Copy invite", "icon": "copy",
"onPressed": { "go": { "copy": { "text": "Sala: luna roja azul\nCódigo: 4821", "label": "Invitación", "sensitive": true } } } }
text: de 1 a 500 caracteres en máximo 6 líneas, una vez quitados los caracteres de control, de dirección y de ancho cero (los saltos de línea se quedan).label(máximo 40) nombra lo copiado en el aviso de Kino.sensitive: truelo oculta de la vista previa del portapapeles en Android 13 y posteriores (un código de sala, una contraseña).- Una copia cada 500 ms y 20 por minuto por plugin. Un televisor no tiene un portapapeles que sirva: Kino muestra «No se
puede copiar en este aparato»; oculta el botón ahí (
kino.device/device: "tv").
go.liveChannel¶
Sintoniza el reproductor de Kino en un canal de En vivo: provider es el id del plugin que lo lista, code el id del
canal en el listado de ese plugin (lo que el contexto de una pestaña en vivo trae como channel). Así un invitado de
Party Chat ve el mismo canal que el anfitrión: la pestaña del anfitrión lee context.channel, lo envía a la sala, y el
invitado pulsa «Ver el mismo canal».
{ "type": "ElevatedButton", "labelText": "Ver el mismo canal", "labelTextEn": "Watch the same channel", "icon": "tv",
"onPressed": { "go": { "liveChannel": { "provider": "tdt", "code": "la1" } } } }
- Solo para un plugin cuya pestaña contribuida y aprobada declara
"kinds": ["live"](panel.contributes,playerPanelTab): el mismo consentimiento; el de cualquier otro plugin se descarta y queda en el registro comoneeds_live_tab. Solo desde la pulsación o el envío de la propia persona. - El proveedor tiene que ser un plugin instalado y usable con canales en vivo (nunca
own, «Mis canales»); un proveedor +18 solo mientras el código +18 está desbloqueado, y un canal +18 no se encuentra mientras está bloqueado (el mensaje de siempre de Kino). - En el panel del reproductor, sobre un canal en vivo, el canal cambia ahí mismo (el panel y su fijación se mantienen); desde cualquier otro lugar el panel o la pantalla se cierran y el reproductor abre el canal. No te devuelve nada: el siguiente contexto dice el canal.
go.syncProvider¶
Abre los ajustes propios de Kino para el proveedor de sincronización (Ajustes ▸ Conectar ▸ Proveedor), donde la persona toca
«Usar true) y no cambia ninguna elección por sí mismo: Kino nunca convierte a un plugin en el proveedor de la persona
por ella.
{ "type": "ElevatedButton", "labelText": "Abrir proveedor de sincronización", "labelTextEn": "Open the sync provider", "icon": "sync",
"onPressed": { "go": { "syncProvider": true } } }
- Solo para un plugin que declara la capacidad
syncProvider; el de cualquier otro plugin se descarta y queda en el registro comonot_sync_provider. Solo desde la pulsación o el envío de la propia persona, igual queurlycopy. - Un Kino anterior a esta forma descarta todo el
go, con registro: deja una instrucción escrita ("Abre Ajustes ▸ Conectar ▸ Proveedor") junto al botón para que el paso se siga entendiendo en un Kino antiguo.
go.useTheme¶
Desde apiVersion 18: un botón en tu propia pantalla que activa uno de tus appThemes, para que la persona no
tenga que ir a Ajustes ▸ Apariencia. Hay un solo tema activo a la vez, así que reemplaza al anterior. theme: null vuelve al
tema de Kino, la salida del tuyo. screen y screenEvent reciben activeTheme, el id de tu tema activo ahora o null, y Kino
vuelve a llamar a screen después de cualquier cambio (también uno hecho en Apariencia), así que un mismo botón puede pasar de
activar a desactivar:
export async function screen({ activeTheme }) {
const on = activeTheme === "noche";
return { type: "ElevatedButton", labelText: on ? "Desactivar" : "Activar", labelTextEn: on ? "Turn off" : "Turn on",
onPressed: { go: { useTheme: { theme: on ? null : "noche" } } } };
}
themees el único campo: uno de los ids deappThemesde tu manifiesto, o null. Hace lo mismo que el botón de Apariencia: la misma elección por perfil, la misma sincronización, y se conservan los ajustes que la persona le hizo a ese tema. Un tema con precio que la persona no ha comprado abre primero la hoja de compra de Kino (Temas con precio).- Solo desde la pulsación o el envío de la propia persona en tu pantalla (un toque, un envío, la respuesta a uno, el botón de una
ventana): se descarta, con registro, desde
open, un temporizador, un cambio, un «cargar más», elonClosede una ventana, un panel o un aviso. Por debajo deapiVersion18 se descarta. - Se rechaza, con registro y sin cambiar nada, cuando Apariencia no muestra ese tema como tuyo (el id de otro plugin, tu plugin
apagado en este perfil, +18 mientras está bloqueado).
theme: nullsolo actúa mientras uno de tus temas está activo, así que nunca puedes quitar el de otro plugin. - Kino muestra su propio aviso, «Tema aplicado» o «Volviste al tema de Kino»; la app se vuelve a pintar al instante, tu pantalla incluida.
go.setExperience¶
Desde apiVersion 18: un botón en tu propia pantalla que pide la experiencia ligera o la completa de toda la app, los dos
modos de Ajustes ▸ Experiencia visual (ligera: sin sombras, sin efectos, esquinas rectas; completa: todos los efectos y esquinas
redondeadas). Un tema que se ve mejor con una de ellas también puede decirlo con su campo experience, y
Kino pregunta igual cuando se activa el tema.
export async function screen() {
return { type: "ElevatedButton", labelText: "Usar la experiencia completa", labelTextEn: "Use the full experience",
onPressed: { go: { setExperience: "full" } } };
}
- El valor es la palabra
"light"o"full". Cualquier otra cosa descarta elgo, con registro. - Kino le pregunta antes a la persona, con sus propias palabras y nombrando tu plugin («Tu plugin» pide la experiencia completa. ¿La usamos?), y no cambia nada sin su sí. Si la app ya tiene esa experiencia, no pregunta nada.
- Solo desde la pulsación o el envío de la propia persona en tu pantalla (un toque, un envío, la respuesta a uno, el botón de una
ventana): se descarta, con registro, desde
open, un temporizador, un cambio, un «cargar más», elonClosede una ventana, un panel o un aviso. Por debajo deapiVersion18 se descarta.
go.installPlugin¶
Desde apiVersion 19 (Kino 0.9.81): un botón en tu propia pantalla que abre la hoja de instalación propia de Kino para el
repositorio de otro plugin (la misma vista previa y hoja de consentimiento de Agregar un plugin: a qué se conecta el
plugin, y después Instalar o Cancelar), para que la persona instale una dependencia tuya, o un hermano de tu catálogo, con un
toque y una confirmación. La hoja se abre encima de tu pantalla: la persona no va a Plugins, y al cerrarla sigue en tu
pantalla. Nada se instala sin el Instalar de la propia persona en esa hoja. Es la puerta de instalación del
protocolo entre plugins: un consumidor la muestra mientras falta su proveedor.
export async function screen() {
// Un botón por dependencia: la persona elige cuál instalar.
const needs = [
{ repo: "kinotvapp/kino-plugin-archive", label: "Instalar Archive", labelEn: "Install Archive" },
{ repo: "kinotvapp/kino-plugin-poster-pro", label: "Instalar Poster Pro", labelEn: "Install Poster Pro" },
];
return { type: "Column", children: needs.map((n) => (
{ type: "ElevatedButton", labelText: n.label, labelTextEn: n.labelEn, onPressed: { go: { installPlugin: { repo: n.repo } } } })) };
}
- El único campo es
repo, unowner/namede GitHub sin más, de máximo 100 caracteres, que se guarda tal como lo escribiste (mayúsculas incluidas). Una URL (cualquier cosa con://), una subcarpeta (owner/name/dir), un@refo cualquier otro campo descartan elgo, con registro. - Si ese plugin ya está instalado, Kino no abre nada y muestra su propio aviso («Ese plugin ya está instalado» / "That plugin
is already installed"). Para mostrar «Instalado» en lugar de un botón, declara los repositorios en el
recommendsdel manifiesto y leeinstalled. - Un
goabre un repositorio. Para ofrecer varias dependencias, muestra un botón para cada una (la lista de arriba es la forma recomendada), nunca un solo botón que intente instalarlas todas: la persona decide cada una. - Solo desde la pulsación o el envío de la propia persona en tu pantalla (un toque, un envío, la respuesta a uno, el botón de
una ventana): se descarta, con registro, desde
open, un temporizador, un cambio, un «cargar más», elonClosede una ventana, un panel o un aviso. Por debajo deapiVersion19 se descarta.
go.plugin¶
Desde apiVersion 20 (Kino 0.9.84, todavía sin publicar): un botón en tu propia pantalla que abre la pantalla de otro
plugin, o su búsqueda, a partir de su repositorio de GitHub. Es la pieza de las tarjetas para compartir.
{ type: "ElevatedButton", labelText: "Ver en Mi anime", labelTextEn: "Open in Mi anime", onPressed: { go: { plugin: {
repo: "tu-usuario/kino-plugin-anime", route: "detail", args: { id: "frieren" }, query: "Frieren" } } } }
repoes unowner/namede GitHub, con una subcarpeta opcional, de máximo 200 caracteres; una URL o un@refdescartan elgo, con registro.routees una ruta dego.screen,argsun objeto JSON con el tope dego.screenyqueryun texto de máximo 200 caracteres. Cualquier otro campo descarta elgo, con registro.- En orden: si no está instalado, Kino muestra su hoja de instalación y sigue cuando la persona lo instala; si es +18 y está
bloqueado, no abre nada y muestra su aviso; si está apagado, pregunta «¿Activar?»; si
routeestá en elopenFrom.routesdel plugin, abre esa pantalla conargs; si mandaste unaqueryy tiene búsqueda, abre la búsqueda solo en ese plugin; si no, su sección o la página por defecto de su pantalla; y si nada se puede, un aviso. Una ruta que el destino no lista nunca se abre. El detalle:go.pluginyopenFrom. - Solo desde la pulsación o el envío de la propia persona en tu pantalla: se descarta, con registro, desde
open, un temporizador, un cambio, un «cargar más», elonClosede una ventana, un panel o un aviso. Por debajo deapiVersion20 se descarta.
Plugins recomendados e installed (Kino 0.9.81)¶
Declara en kino-plugin.json los plugins con los que el tuyo funciona mejor, con cualquier apiVersion (un Kino anterior
ignora el campo):
{ "recommends": ["kinotvapp/kino-plugin-archive", "kinotvapp/kino-plugin-poster-pro"] }
Una lista de máximo 8 textos owner/name de GitHub sin más (sin URL, sin subcarpeta, sin @ref, de máximo 100 caracteres
cada uno; se conservan las mayúsculas que escribiste y un repetido, sin importar mayúsculas, se junta con el primero).
Cualquier otra cosa hace inválido el manifiesto: The "recommends" field must be a list of at most 8 plain GitHub owner/name
repositories.
Desde ahí, screen y screenEvent reciben installed, un objeto con una clave por cada entrada de tu propio
recommends, escrita exactamente como la escribiste, true cuando ese plugin está instalado ahora en este aparato y
false cuando no ({} si no declaras ninguno). Kino nunca te cuenta de ningún otro plugin que tenga la persona. Cuando
cambia con tu pantalla abierta (la persona instala o quita uno), Kino vuelve a llamar a screen, así una fila puede pasar
del botón a «Instalado». Una fila por plugin recomendado:
const NEEDS = [
{ repo: "kinotvapp/kino-plugin-archive", name: "Archive" },
{ repo: "kinotvapp/kino-plugin-poster-pro", name: "Poster Pro" },
];
export async function screen({ installed }) {
return { type: "Column", children: NEEDS.map((n) => installed[n.repo]
? { type: "ListTile", title: n.name, subtitle: "Instalado", subtitleEn: "Installed" }
: { type: "ListTile", title: n.name, subtitle: "Toca para instalar", subtitleEn: "Tap to install",
onTap: { go: { installPlugin: { repo: n.repo } } } }) };
}
En el kit, node sdk/run.mjs <carpeta del plugin> screen pasa installed con cada entrada de recommends en false;
marca algunas como instaladas con --context '{"installed":{"kinotvapp/kino-plugin-archive":true}}'.
Rutas (route: push y pop)¶
Pantallas propias más adentro del lienzo: el route: { push: "detail", params } de una respuesta baja un nivel,
{ pop: true } vuelve; Atrás quita una ruta agregada antes de cerrar el lienzo. screen({ route }) recibe
{ name, params, args? }; name es "main" cuando la pantalla se abrió sin una ruta (desde el Home de Kino, desde una
tarjeta, desde el menú), así que trata "main" como tu portada.

{ "route": { "push": "detail", "params": { "id": "42" } } }
export async function screen({ route }) {
if (route.name === "detail") return { type: "Column", padding: 16, children: [{ type: "Text", text: "Detalle " + route.params.id }, { type: "TextButton", labelText: "Volver", onPressed: "back" }] };
return { type: "ElevatedButton", labelText: "Ver detalle", onPressed: { event: "detail", arg: "42" } };
}
export async function screenEvent({ name, arg }) {
if (name === "detail") return { route: { push: "detail", params: { id: arg } } };
if (name === "back") return { route: { pop: true } };
return null;
}