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-01popcalendar://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ção | O que faz |
|---|---|
/open | Abre uma sessão ou atualiza e traz uma sessão existente para a frente. |
/toggle | Fecha a sessão se ela existir ou a abre caso contrário. |
/update | Atualiza conteúdo ou geometria sem abrir uma sessão ausente nem assumir o foco. |
/move | Muda apenas a geometria sem abrir uma sessão ausente nem assumir o foco. |
/close | Fecha a sessão. Fechar uma sessão ausente não tem efeito. |
Conteúdo e geometria
| Comando ou opção | O que faz |
|---|---|
presentation | window por predefinição, popup ou fullscreen. Feche uma sessão ativa antes de mudar a apresentação. |
mode | month, two-months, year, two-years, month-year ou month-two-years. A predefinição é year. |
date | YYYY-MM-DD gregoriano no fuso horário da aplicação. Por predefinição, a primeira data do intervalo ou hoje. |
start, end | Extremos inclusivos em YYYY-MM-DD. Informe ambos, com start anterior ou igual a end. |
selection | Use clear para remover a seleção. Não pode ser combinado com start e end. |
calendar-set | UUID 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. |
display | Apenas 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, height | Dimensõ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. |
anchor | Retângulo da âncora como x,y,width,height em coordenadas globais. Não pode ser combinado com x e y. |
x, y | Posição explícita em vez de uma âncora. Informe ambas. Um painel com posição explícita não tem seta. |
coordinates | appkit 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. |
arrow | auto, 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. |
callback | Um 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 índiceFoco 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 índiceReceba 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%3DexampleOs 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ção | O que faz |
|---|---|
pc-session | O nome original da sessão. |
pc-start, pc-end | O primeiro e o último dia civil selecionados, ambos incluídos. |
pc-ranges | Um array JSON de pares [start, end] preservando até 128 intervalos separados. |
pc-time-zone | O identificador de fuso horário das datas devolvidas. |