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.

Read in English

1

Tú lo escribes

Una carpeta con el widget.json y el script.

2

Doca lo ejecuta

El comando, cada cierto tiempo, solo con el widget a la vista.

3

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.

  1. 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 llamada viernes.

  2. Describe el widget

    Dentro de viernes, crea el widget.json. Solo name y command son obligatorios:

    {
      "name": "¿Ya es viernes?",
      "command": "powershell -NoProfile -ExecutionPolicy Bypass -File viernes.ps1",
      "every": 600,
      "icon": "🎉",
      "color": "#B65CF0"
    }
  3. 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

₿ US$ 64,100+2.1% hoy 3

En el panel

US$ 64,100 +2.1% hoy

Máximo 24hUS$ 65,200

Mínimo 24hUS$ 62,300

Abrir el sitio

Si 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

CampoQué es
nameObligatorio. El nombre en el catálogo y en el dock.
commandObligatorio. Lo que Doca ejecuta, en la carpeta del widget, a través de cmd.
description, authorAparecen en el catálogo y en el panel.
everyCada cuánto ejecutarlo, en segundos: de 5 a 86400. Predeterminado: 60.
widthEl ancho del tile en íconos, de 1 a 4. Predeterminado: 2. Quien lo usa puede cambiarlo en el editor.
icon, colorEl ícono y el color (#RRGGBB) hasta la primera respuesta del script.
optionsOpciones del editor, de los tipos text, bool y choice (con choices).

El widget.json acepta comentarios (//) y comas sobrantes.

Lo que imprime el script

CampoQué es
title, subtitleEl texto del tile y del panel.
iconUn emoji o un texto corto. Para un símbolo de Windows (Segoe Fluent), glyph:E713.
color, color2El fondo del tile en degradado (#RRGGBB). Sin color2, la parte de abajo queda un poco más oscura.
progressUna barra de 0 a 1 debajo del texto, en tiles de 2 íconos o más.
badgeUna insignia roja en la esquina.
everyCambia el intervalo de ahí en adelante, de 5 a 86400 segundos.
panelLas filas del panel: texto, o { text, value, icon, open }.
actionsHasta 6 botones en el panel: { label, open } abre una dirección o un archivo; { label, run } ejecuta un comando en la carpeta del widget.
clickLo que hace el clic en el tile, con { open } o { run }. Sin él, el clic abre el panel.

Lo que recibe el script

VariableValor
DOCA_OPT_<CLAVE>Cada opción, con la clave en mayúsculas. Los booleanos llegan como true o false.
DOCA_LANGEl idioma de Doca: pt o en.
DOCA_WIDGET_IDEl id de esta instancia del widget, útil para guardar caché.
DOCA_WIDTHEl ancho del tile, en íconos.

Consejos