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 tela cheia a partir de outro app 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 outro app
Esta interface exige macOS 12 ou posterior. Ative primeiro o controle por apps externos 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 aninhadas 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
Toda URL exige v=1 e um nome de sessão de 1 a 128 letras ASCII, dígitos, pontos, sublinhados ou hifens. Até oito sessões podem ficar abertas, incluindo um painel ou sobreposição em tela cheia. Abrir outra vista temporária substitui a anterior. 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 padrão, popup ou fullscreen. Feche uma sessão ativa antes de mudar sua apresentação. |
mode | month, two-months, year, two-years, month-year ou month-two-years. O padrão é year. |
date | YYYY-MM-DD gregoriano no fuso horário do app. Por padrã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 salvo ou current para copiar o filtro ativo. Obtenha IDs via CLI ou Atalhos. IDs desconhecidos são rejeitados. |
display | Apenas para tela cheia. current usa o monitor do ponteiro, main usa o principal, ou informe um UUID. Monitores desconectados 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. Informe ambas. Os pop-ups mantêm o tamanho solicitado desde o primeiro quadro visível. Janelas comuns redimensionáveis podem aumentar até atingir o mínimo legível. Os limites da tela 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 monitor principal. top-left mede para baixo a partir do canto superior esquerdo. Monitores secundários podem ter coordenadas negativas. Os valores são pontos, não pixels. |
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 registrado para retornar datas explicitamente confirmadas. |
CLI usa os mesmos nomes com prefixo --, exceto selection=clear, que vira --clear-selection. Sobreposições em tela cheia rejeitam toda 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, layout, seleção e filtro próprios. Não substituem janelas normais nem são restauradas após sair. update e move não ativam o app. Painéis fecham com cliques externos, perda de foco, Escape ou troca de Espaço. Painéis secundários fecham primeiro. Sobreposições em tela cheia também fecham ao trocar de app.
Em apps nativos, use NSWorkspace.open com uma URL explícita do aplicativo e OpenConfiguration.activates definido como false para popup, fullscreen, update, move e close. Envie move quando sua janela se mover e close quando fechar. A entrega de uma 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 usuário precisa confirmar antes de executar o retorno. Cancelar, perder o foco ou sair não retorna 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. 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 da URL de retorno são preservados. Não use os nomes reservados abaixo. Valide a sessão esperada e seu próprio token opaco ao receber um resultado. Nunca inclua credenciais em uma 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 retornadas. |