Documentación de automatización

Referencia del esquema URL

Abre una ventana de calendario, un panel anclado o una vista superpuesta a pantalla completa desde otra app de Mac.

Estas guías describen popCalendar 1.3 y versiones posteriores. Algunas acciones requieren una versión más reciente del sistema, como se indica a continuación.

Abre un calendario desde otra app

Esta interfaz requiere macOS 12 o posterior. Activa primero el control desde apps externas y CLI. Usa popcalendar para la edición estándar y popcalendar-setapp para Setapp. Construye las URL con URLComponents y URLQueryItem, codificando las URL de retorno anidadas como un ú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
Volver al índice

Comandos y sesiones

Cada URL requiere v=1 y un nombre de sesión de 1 a 128 letras ASCII, dígitos, puntos, guiones bajos o guiones. Puede haber hasta ocho sesiones abiertas, incluido un panel o una vista a pantalla completa. Abrir otra vista temporal sustituye la anterior. Las ventanas normales permanecen abiertas.

Comando u opciónQué hace
/openAbre una sesión o actualiza y trae al frente una existente.
/toggleCierra la sesión si existe o la abre si no existe.
/updateActualiza el contenido o la geometría sin abrir una sesión ausente ni tomar el foco.
/moveCambia solo la geometría sin abrir una sesión ausente ni tomar el foco.
/closeCierra la sesión. Cerrar una sesión ausente no tiene efecto.
Volver al índice

Contenido y geometría

Comando u opciónQué hace
presentationwindow de forma predeterminada, popup o fullscreen. Cierra una sesión activa antes de cambiar su presentación.
modemonth, two-months, year, two-years, month-year o month-two-years. El valor predeterminado es year.
dateYYYY-MM-DD gregoriano en la zona horaria de la app. Por defecto, la primera fecha del intervalo o el día de hoy.
start, endExtremos inclusivos en formato YYYY-MM-DD. Indica ambos, con start anterior o igual a end.
selectionUsa clear para borrar la selección. No se puede combinar con start y end.
calendar-setUUID de un conjunto guardado o current para copiar el filtro activo. Obtén los identificadores con CLI o Atajos. Los desconocidos se rechazan.
displaySolo para pantalla completa. current usa la pantalla del puntero, main la principal, o indica un UUID. Las pantallas desconectadas se sustituyen por una disponible.
width, heightDimensiones del contenido en puntos lógicos, cada una de 240 a 8192. Indica ambas. Las ventanas emergentes mantienen el tamaño solicitado desde el primer fotograma visible. Las ventanas normales redimensionables pueden crecer hasta alcanzar el mínimo legible. Los límites de la pantalla tienen prioridad. La CLI también acepta --size WIDTHxHEIGHT.
anchorRectángulo de anclaje como x,y,width,height en coordenadas globales. No se puede combinar con x e y.
x, yPosición explícita en lugar de un anclaje. Indica ambas. Un panel con posición explícita no tiene flecha.
coordinatesappkit usa la esquina inferior izquierda de la pantalla principal. top-left mide hacia abajo desde la superior izquierda. Las pantallas secundarias pueden tener coordenadas negativas. Se usan puntos, no píxeles.
arrowauto, top, bottom, left, right o none. Indica el borde del panel que contiene la flecha. La posición puede invertirse para mantenerlo visible.
callbackUn esquema URL personalizado registrado para devolver fechas confirmadas expresamente.

CLI usa los mismos nombres con el prefijo --, excepto selection=clear, que se convierte en --clear-selection. Las vistas a pantalla completa rechazan todas las opciones de geometría salvo display. Los parámetros desconocidos o duplicados, las fechas incorrectas y las URL de más de 16 KiB se rechazan por completo.

Volver al índice

Foco y duración de las ventanas

Cada sesión tiene sus propias fechas, disposición, selección y filtro. No sustituye ventanas normales ni se restaura después de salir. update y move no activan la app. Los paneles se cierran al hacer clic fuera, perder el foco, pulsar Escape o cambiar de espacio. Los paneles secundarios se cierran primero. Las vistas a pantalla completa también se cierran al cambiar de app.

En apps nativas, usa NSWorkspace.open con una URL explícita de la aplicación y OpenConfiguration.activates en false para popup, fullscreen, update, move y close. Envía move cuando se mueva tu ventana y close cuando se cierre. Entregar una URL correctamente no confirma la aceptación del protocolo. Usa CLI o Atajos cuando necesites un resultado confirmado.

Volver al índice

Recibe las fechas seleccionadas

El usuario debe confirmar antes de ejecutar el retorno. Cancelar, perder el foco o salir no devuelve nada. Solo se envían fechas, su zona horaria y el identificador de sesión. No se incluye contenido de eventos ni calendarios. Se rechazan retornos HTTP, HTTPS, file, data, JavaScript y popCalendar.

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

Se conservan los parámetros existentes de la URL de retorno. No uses los nombres reservados indicados abajo. Valida la sesión esperada y tu propio token opaco al recibir el resultado. Nunca incluyas credenciales en una URL.

Comando u opciónQué hace
pc-sessionEl nombre original de la sesión.
pc-start, pc-endEl primer y último día civil seleccionados, incluidos ambos.
pc-rangesUn array JSON de pares [start, end] que conserva hasta 128 intervalos separados.
pc-time-zoneEl identificador de zona horaria de las fechas devueltas.
Volver al índice