Doca Baixar

Widgets próprios

Crie um widget para o Doca

Uma pasta, um widget.json e um script que imprime texto. Em PowerShell, Python, Node ou o que você já usa, sem compilar nada e sem reiniciar o Doca.

Read in English

1

Você escreve

Uma pasta com o widget.json e o script.

2

O Doca roda

O comando, de tempos em tempos, só com o widget à vista.

3

Vira tile

O que o script imprime aparece no dock e no painel.

Seu primeiro widget em três passos

O exemplo conta quantos dias faltam para sexta-feira. Leva dois minutos.

  1. Abra a pasta dos seus widgets

    No Doca, abra os Ajustes › Seu dock. No fim da Caixa de peças, clique em Abrir a pasta dos seus widgets. Na primeira vez, o Doca cria a pasta com um exemplo, exemplo-tempo-ligado, que você pode copiar e mudar.

    Cada widget é uma subpasta. O nome dela é o id do widget: letras, números, -, _ e .. Crie uma chamada sextou.

  2. Descreva o widget

    Dentro de sextou, crie o widget.json. Só name e command são obrigatórios:

    {
  "name": "Sextou?",
  "command": "powershell -NoProfile -ExecutionPolicy Bypass -File sexta.ps1",
  "every": 600,
  "icon": "🎉",
  "color": "#B65CF0"
}

  3. Escreva o script

    Na mesma pasta, o sexta.ps1. A primeira linha que ele imprime vira o título do tile; a segunda, o subtítulo:

    [Console]::OutputEncoding = [Text.Encoding]::UTF8
$faltam = (5 - [int](Get-Date).DayOfWeek + 7) % 7
if ($faltam -eq 0) { "Sextou!"; "Bom fim de semana" }
else { "$faltam dia(s)"; "para sexta" }

    Volte à Caixa de peças: o Sextou? aparece no grupo Seus widgets. Clique nele para pôr no dock. Mudou o script? O Doca pega a mudança na próxima rodada.

Mais do que duas linhas

Para escolher cores, mostrar uma barra de progresso, um selo, linhas no painel e botões, o script imprime um objeto JSON em vez de texto:

{
  "title": "R$ 342.100",
  "subtitle": "+2,1% hoje",
  "icon": "₿",
  "color": "#F7931A",
  "color2": "#C46A00",
  "progress": 0.42,
  "badge": "3",
  "panel": [
    { "text": "Máxima 24h", "value": "R$ 348.000" },
    { "text": "Mínima 24h", "value": "R$ 331.900" }
  ],
  "actions": [
    { "label": "Abrir no site", "open": "https://exemplo.com" }
  ]
}

No dock

₿ R$ 342.100+2,1% hoje 3

No painel

R$ 342.100 +2,1% hoje

Máxima 24hR$ 348.000

Mínima 24hR$ 331.900

Abrir no site

Se o script imprimir outras mensagens antes, o Doca usa o JSON que começa numa linha nova e vai até o fim da saída.

Em qualquer linguagem

O command roda na pasta do widget, como se você digitasse no terminal. Vale qualquer coisa que funcione lá:

Python · "command": "python disco.py"

import json, shutil
total, usado, livre = shutil.disk_usage("C:/")
print(json.dumps({"title": f"{livre / 2**30:.0f} GB", "subtitle": "livres no C:",
                  "progress": usado / total}))

Node · "command": "node estrelas.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 }));

Executável · "command": "meu-widget.exe --doca"

23 °C
Céu limpo

No Node, o .mjs deixa usar await fora de função. E o DOCA_OPT_REPO é uma opção que a pessoa escolhe, como mostra a próxima seção.

Opções que a pessoa ajusta

As options do widget.json aparecem em Ajustar widget… (botão direito no tile). O script recebe cada uma numa variável de ambiente:

"options": [
  { "key": "moeda", "label": "Moeda", "type": "choice", "choices": ["BRL", "USD"], "default": "BRL" },
  { "key": "variacao", "label": "Mostrar a variação", "type": "bool", "default": true },
  { "key": "apelido", "label": "Apelido", "type": "text", "default": "" }
]
$moeda = $env:DOCA_OPT_MOEDA        # "BRL" ou "USD"
$variacao = $env:DOCA_OPT_VARIACAO  # "true" ou "false"

Referência

O widget.json

CampoO que é
nameObrigatório. O nome no catálogo e no dock.
commandObrigatório. O que o Doca roda, na pasta do widget, pelo cmd.
description, authorAparecem no catálogo e no painel.
everyDe quanto em quanto tempo rodar, em segundos: de 5 a 86400. Padrão: 60.
widthA largura do tile em ícones, de 1 a 4. Padrão: 2. A pessoa pode mudar no editor.
icon, colorO ícone e a cor (#RRGGBB) até a primeira resposta do script.
optionsOpções do editor, dos tipos text, bool e choice (com choices).

O widget.json aceita comentários (//) e vírgula sobrando.

O que o script imprime

CampoO que é
title, subtitleO texto do tile e do painel.
iconUm emoji ou texto curto. Para um símbolo do Windows (Segoe Fluent), glyph:E713.
color, color2O fundo do tile em degradê (#RRGGBB). Sem color2, a parte de baixo fica um pouco mais escura.
progressUma barra de 0 a 1 embaixo do texto, em tiles de 2 ícones ou mais.
badgeUm selo vermelho no canto.
everyMuda o intervalo daqui em diante, de 5 a 86400 segundos.
panelAs linhas do painel: texto, ou { text, value, icon, open }.
actionsAté 6 botões no painel: { label, open } abre um endereço ou arquivo; { label, run } roda um comando na pasta do widget.
clickO que o clique no tile faz, com { open } ou { run }. Sem ele, o clique abre o painel.

O que o script recebe

VariávelValor
DOCA_OPT_<CHAVE>Cada opção, com a chave em maiúsculas. Booleanos chegam como true ou false.
DOCA_LANGO idioma do Doca: pt ou en.
DOCA_WIDGET_IDO id desta instância do widget, bom para guardar cache.
DOCA_WIDTHA largura do tile, em ícones.

Dicas