Tus propios widgets
Crea un widget para Doca
Una carpeta, un widget.json y un script que imprime texto. En PowerShell,
Python, Node o lo que ya usas, sin compilar nada y sin reiniciar Doca.
Tú lo escribes
Una carpeta con el widget.json y el script.
Doca lo ejecuta
El comando, cada cierto tiempo, solo con el widget a la vista.
Se convierte en tile
Lo que imprime el script aparece en el dock y en el panel.
Tu primer widget en tres pasos
El ejemplo cuenta cuántos días faltan para el viernes. Toma dos minutos.
-
Abre la carpeta de tus widgets
En Doca, abre Settings › Your dock. Al final de la Pieces box, haz clic en Open your widgets folder. La primera vez, Doca crea la carpeta con un ejemplo,
exemplo-tempo-ligado, que puedes copiar y cambiar.Cada widget es una subcarpeta. Su nombre es el id del widget: letras, números,
-,_y.. Crea una llamadaviernes. -
Describe el widget
Dentro de
viernes, crea elwidget.json. Solonameycommandson obligatorios:{ "name": "¿Ya es viernes?", "command": "powershell -NoProfile -ExecutionPolicy Bypass -File viernes.ps1", "every": 600, "icon": "🎉", "color": "#B65CF0" } -
Escribe el script
En la misma carpeta, el
viernes.ps1. La primera línea que imprime se convierte en el título del tile; la segunda, en el subtítulo:[Console]::OutputEncoding = [Text.Encoding]::UTF8 $faltan = (5 - [int](Get-Date).DayOfWeek + 7) % 7 if ($faltan -eq 0) { "¡Es viernes!"; "Buen fin de semana" } else { "$faltan día(s)"; "para el viernes" }Vuelve a la Pieces box: ¿Ya es viernes? aparece en el grupo Your widgets. Haz clic en él para ponerlo en el dock. ¿Cambiaste el script? Doca toma el cambio en la siguiente ejecución.
Más que dos líneas
Para elegir colores, mostrar una barra de progreso, una insignia, filas en el panel y botones, el script imprime un objeto JSON en lugar de texto:
{
"title": "US$ 64,100",
"subtitle": "+2.1% hoy",
"icon": "₿",
"color": "#F7931A",
"color2": "#C46A00",
"progress": 0.42,
"badge": "3",
"panel": [
{ "text": "Máximo 24h", "value": "US$ 65,200" },
{ "text": "Mínimo 24h", "value": "US$ 62,300" }
],
"actions": [
{ "label": "Abrir el sitio", "open": "https://example.com" }
]
}
En el dock
En el panel
US$ 64,100 +2.1% hoy
Máximo 24hUS$ 65,200
Mínimo 24hUS$ 62,300
Abrir el sitioSi el script imprime otros mensajes antes, Doca usa el JSON que empieza en una línea nueva y llega hasta el final de la salida.
En cualquier lenguaje
El command se ejecuta en la carpeta del widget, como si lo escribieras en la terminal. Sirve cualquier
cosa que funcione allí:
Python · "command": "python disco.py"
import json, shutil
total, usado, libre = shutil.disk_usage("C:/")
print(json.dumps({"title": f"{libre / 2**30:.0f} GB", "subtitle": "libres en C:",
"progress": usado / total}))
Node · "command": "node estrellas.mjs"
const repo = process.env.DOCA_OPT_REPO || "microsoft/terminal";
const r = await fetch(`https://api.github.com/repos/${repo}`);
const { stargazers_count } = await r.json();
console.log(JSON.stringify({ title: `★ ${stargazers_count}`, subtitle: repo }));
Ejecutable · "command": "mi-widget.exe --doca"
23 °C
Cielo despejado
En Node, la extensión .mjs permite usar await fuera de una función. Y
DOCA_OPT_REPO es una opción que elige quien usa el widget, como muestra la siguiente sección.
Opciones que ajusta quien lo usa
Las options del widget.json aparecen en Adjust widget… (botón
derecho en el tile). El script recibe cada una en una variable de entorno:
"options": [
{ "key": "moneda", "label": "Moneda", "type": "choice", "choices": ["USD", "MXN"], "default": "USD" },
{ "key": "variacion", "label": "Mostrar la variación", "type": "bool", "default": true },
{ "key": "apodo", "label": "Apodo", "type": "text", "default": "" }
]
$moneda = $env:DOCA_OPT_MONEDA # "USD" o "MXN"
$variacion = $env:DOCA_OPT_VARIACION # "true" o "false"
Referencia
El widget.json
| Campo | Qué es |
|---|---|
name | Obligatorio. El nombre en el catálogo y en el dock. |
command | Obligatorio. Lo que Doca ejecuta, en la carpeta del widget, a través de cmd. |
description, author | Aparecen en el catálogo y en el panel. |
every | Cada cuánto ejecutarlo, en segundos: de 5 a 86400. Predeterminado: 60. |
width | El ancho del tile en íconos, de 1 a 4. Predeterminado: 2. Quien lo usa puede cambiarlo en el editor. |
icon, color | El ícono y el color (#RRGGBB) hasta la primera respuesta del script. |
options | Opciones del editor, de los tipos text, bool y choice (con choices). |
El widget.json acepta comentarios (//) y comas sobrantes.
Lo que imprime el script
| Campo | Qué es |
|---|---|
title, subtitle | El texto del tile y del panel. |
icon | Un emoji o un texto corto. Para un símbolo de Windows (Segoe Fluent), glyph:E713. |
color, color2 | El fondo del tile en degradado (#RRGGBB). Sin color2, la parte de abajo queda un poco más oscura. |
progress | Una barra de 0 a 1 debajo del texto, en tiles de 2 íconos o más. |
badge | Una insignia roja en la esquina. |
every | Cambia el intervalo de ahí en adelante, de 5 a 86400 segundos. |
panel | Las filas del panel: texto, o { text, value, icon, open }. |
actions | Hasta 6 botones en el panel: { label, open } abre una dirección o un archivo; { label, run } ejecuta un comando en la carpeta del widget. |
click | Lo que hace el clic en el tile, con { open } o { run }. Sin él, el clic abre el panel. |
Lo que recibe el script
| Variable | Valor |
|---|---|
DOCA_OPT_<CLAVE> | Cada opción, con la clave en mayúsculas. Los booleanos llegan como true o false. |
DOCA_LANG | El idioma de Doca: pt o en. |
DOCA_WIDGET_ID | El id de esta instancia del widget, útil para guardar caché. |
DOCA_WIDTH | El ancho del tile, en íconos. |
Consejos
- Acentos en PowerShell 5: empieza el script con
[Console]::OutputEncoding = [Text.Encoding]::UTF8. Doca lee la salida en UTF-8. - Tiempo límite: el script tiene 30 segundos (las acciones, 5 minutos). Si se pasa, Doca lo detiene y lo avisa en el panel.
- ¿Dio error? El tile muestra
!y el panel muestra la salida de error del script. - Sin internet: si el script falla, Doca sigue mostrando la última respuesta buena.
- Solo cuando se ve: el script no se ejecuta con el tile oculto o en otro entorno.
- Seguridad: el widget se ejecuta con tus permisos, como cualquier programa. Instala solo widgets de gente en quien confías.