Documentação de automação

Referência do esquema de URL

Abra uma janela de calendário, um painel ancorado ou uma sobreposição em ecrã completo a partir de outra aplicação do Mac.

Estes guias abrangem o popCalendar 1.3 e versões posteriores. Algumas ações exigem uma versão mais recente do sistema, conforme indicado abaixo.

Abra um calendário a partir de outra aplicação

Esta interface exige macOS 12 ou posterior. Ative primeiro o controlo por aplicações externas e CLI. Use popcalendar para a edição padrão e popcalendar-setapp para Setapp. Crie URLs com URLComponents e URLQueryItem, codificando URLs de retorno aninhados como um único valor.

popcalendar://integration/open?v=1&session=com.example.calendar&presentation=window&mode=two-years&date=2027-01-01
popcalendar://integration/toggle?v=1&session=com.example.picker&presentation=popup&mode=month&anchor=400,850,40,24&width=520&height=720&arrow=top
Voltar ao índice

Comandos e sessões

Todos os URLs exigem v=1 e um nome de sessão de 1 a 128 letras ASCII, dígitos, pontos, sublinhados ou hífenes. Podem estar abertas até oito sessões, incluindo um painel ou uma sobreposição em ecrã completo. Abrir outra vista temporária substitui a anterior. As janelas normais permanecem abertas.

Comando ou opçãoO que faz
/openAbre uma sessão ou atualiza e traz uma sessão existente para a frente.
/toggleFecha a sessão se ela existir ou a abre caso contrário.
/updateAtualiza conteúdo ou geometria sem abrir uma sessão ausente nem assumir o foco.
/moveMuda apenas a geometria sem abrir uma sessão ausente nem assumir o foco.
/closeFecha a sessão. Fechar uma sessão ausente não tem efeito.
Voltar ao índice

Conteúdo e geometria

Comando ou opçãoO que faz
presentationwindow por predefinição, popup ou fullscreen. Feche uma sessão ativa antes de mudar a apresentação.
modemonth, two-months, year, two-years, month-year ou month-two-years. A predefinição é year.
dateYYYY-MM-DD gregoriano no fuso horário da aplicação. Por predefinição, a primeira data do intervalo ou hoje.
start, endExtremos inclusivos em YYYY-MM-DD. Informe ambos, com start anterior ou igual a end.
selectionUse clear para remover a seleção. Não pode ser combinado com start e end.
calendar-setUUID de um conjunto guardado ou current para copiar o filtro ativo. Obtenha IDs através de CLI ou Atalhos. Os IDs desconhecidos são rejeitados.
displayApenas para ecrã completo. current usa o ecrã do ponteiro, main usa o principal, ou indique um UUID. Os ecrãs desligados são substituídos por um disponível.
width, heightDimensões do conteúdo em pontos lógicos, cada uma de 240 a 8192. Indique ambas. As janelas pop-up mantêm o tamanho pedido desde o primeiro fotograma visível. As janelas normais redimensionáveis podem aumentar até atingir o mínimo legível. Os limites do ecrã têm prioridade. A CLI também aceita --size WIDTHxHEIGHT.
anchorRetângulo da âncora como x,y,width,height em coordenadas globais. Não pode ser combinado com x e y.
x, yPosição explícita em vez de uma âncora. Informe ambas. Um painel com posição explícita não tem seta.
coordinatesappkit usa o canto inferior esquerdo do ecrã principal. top-left mede para baixo a partir do canto superior esquerdo. Os ecrãs secundários podem ter coordenadas negativas. Os valores são pontos, não píxeis.
arrowauto, top, bottom, left, right ou none. Nomeia a borda do painel que contém a seta. A posição pode inverter para manter o painel visível.
callbackUm esquema de URL personalizado registado para devolver datas explicitamente confirmadas.

CLI usa os mesmos nomes com o prefixo --, exceto selection=clear, que passa a --clear-selection. As sobreposições em ecrã completo rejeitam toda a geometria exceto display. Parâmetros desconhecidos ou duplicados, datas malformadas e URLs acima de 16 KiB são rejeitados por completo.

Voltar ao índice

Foco e duração das janelas

As sessões têm datas, disposição, seleção e filtro próprios. Não substituem janelas normais nem são restauradas após sair. update e move não ativam a aplicação. Os painéis fecham com cliques externos, perda de foco, Escape ou mudança de Espaço. Os painéis secundários fecham primeiro. As sobreposições em ecrã completo também fecham ao mudar de aplicação.

Em aplicações nativas, use NSWorkspace.open com um URL explícito da aplicação e OpenConfiguration.activates definido como false para popup, fullscreen, update, move e close. Envie move quando a janela se mover e close quando fechar. A entrega de um URL não confirma a aceitação pelo protocolo. Use CLI ou Atalhos quando precisar de uma resposta confirmada.

Voltar ao índice

Receba as datas selecionadas

O utilizador tem de confirmar antes de executar o retorno. Cancelar, perder o foco ou sair não devolve nada. São enviados apenas datas, fuso horário e identificador de sessão. Não são incluídos eventos nem conteúdo do calendário. Os retornos HTTP, HTTPS, file, data, JavaScript e popCalendar são rejeitados.

popcalendar://integration/open?v=1&session=choose-trip&mode=month&callback=my-app%3A%2F%2Fcalendar-selection%3Ftoken%3Dexample

Os parâmetros existentes do URL de retorno são preservados. Não use os nomes reservados abaixo. Valide a sessão esperada e o seu próprio token opaco ao receber um resultado. Nunca inclua credenciais num URL.

Comando ou opçãoO que faz
pc-sessionO nome original da sessão.
pc-start, pc-endO primeiro e o último dia civil selecionados, ambos incluídos.
pc-rangesUm array JSON de pares [start, end] preservando até 128 intervalos separados.
pc-time-zoneO identificador de fuso horário das datas devolvidas.
Voltar ao índice