Dokumentation zur Automatisierung
URL-Schema-Referenz
Öffne aus einer anderen Mac-App ein Kalenderfenster, ein verankertes Popup oder eine Vollbildansicht.
Diese Anleitungen gelten für popCalendar 1.3 und neuer. Einige Aktionen benötigen eine neuere Systemversion, wie unten angegeben.
Einen Kalender aus einer anderen App öffnen
Diese Schnittstelle benötigt macOS 12 oder neuer. Aktiviere zuerst die Steuerung durch externe Apps und CLI. Verwende popcalendar für die Standardausgabe und popcalendar-setapp für Setapp. Erstelle URLs mit URLComponents und URLQueryItem. Eingebettete Rückruf-URLs müssen als einzelner Wert prozentkodiert werden.
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 Zurück zum Inhalt Befehle und Sitzungen
Jede URL benötigt v=1 und einen Sitzungsnamen mit 1 bis 128 ASCII-Buchstaben, Ziffern, Punkten, Unterstrichen oder Bindestrichen. Bis zu acht Sitzungen können geöffnet sein, darunter ein Popup oder eine Vollbildansicht. Eine neue vorübergehende Ansicht ersetzt die vorherige. Normale Fenster bleiben geöffnet.
| Befehl oder Option | Funktion |
|---|---|
/open | Öffnet eine Sitzung oder aktualisiert eine vorhandene und bringt sie nach vorn. |
/toggle | Schließt eine vorhandene Sitzung oder öffnet sie andernfalls. |
/update | Aktualisiert Inhalt oder Geometrie, ohne eine fehlende Sitzung zu öffnen oder den Fokus zu übernehmen. |
/move | Ändert nur die Geometrie, ohne eine fehlende Sitzung zu öffnen oder den Fokus zu übernehmen. |
/close | Schließt die Sitzung. Bei einer fehlenden Sitzung passiert nichts. |
Inhalt und Geometrie
| Befehl oder Option | Funktion |
|---|---|
presentation | Standardmäßig window, alternativ popup oder fullscreen. Vor einem Darstellungswechsel die laufende Sitzung schließen. |
mode | month, two-months, year, two-years, month-year oder month-two-years. Standard ist year. |
date | Gregorianisches YYYY-MM-DD in der Zeitzone der App. Standard ist das erste Datum des Bereichs oder heute. |
start, end | Einschließliche Endpunkte als YYYY-MM-DD. Beide angeben, start darf nicht nach end liegen. |
selection | Mit clear die Auswahl entfernen. Nicht mit start und end kombinierbar. |
calendar-set | UUID eines gespeicherten Kalendersets oder current für eine Kopie des aktiven Filters. IDs lassen sich über CLI oder Kurzbefehle abfragen. Unbekannte IDs werden abgelehnt. |
display | Nur für Vollbildansichten. current verwendet den Bildschirm unter dem Zeiger, main den Hauptbildschirm. Alternativ eine Display-UUID angeben. Nicht angeschlossene Displays werden durch ein verfügbares ersetzt. |
width, height | Inhaltsmaße in logischen Punkten, jeweils von 240 bis 8192. Gib beide an. Popups behalten die angeforderte Größe ab dem ersten sichtbaren Bild bei. Normale veränderbare Fenster können auf eine lesbare Mindestgröße wachsen. Bildschirmgrenzen haben Vorrang. Die CLI akzeptiert auch --size WIDTHxHEIGHT. |
anchor | Ankerrechteck für ein Popup als x,y,width,height in globalen Bildschirmkoordinaten. Nicht mit x und y kombinierbar. |
x, y | Explizite Position statt Anker. Beide Werte angeben. Ein Popup mit expliziter Position hat keinen Pfeil. |
coordinates | appkit beginnt unten links auf dem Hauptbildschirm. top-left misst von oben links nach unten. Weitere Displays können negative Koordinaten haben. Die Werte sind Punkte, keine Pixel. |
arrow | auto, top, bottom, left, right oder none. Bezeichnet die Popup-Kante mit dem Pfeil. Die Platzierung kann wechseln, damit das Panel sichtbar bleibt. |
callback | Ein registriertes eigenes URL-Schema für die Rückgabe ausdrücklich bestätigter Daten. |
Die CLI verwendet dieselben Namen mit -- davor. Nur selection=clear wird zu --clear-selection. Vollbildansichten lehnen Geometrieoptionen außer display ab. Unbekannte oder doppelte Parameter, fehlerhafte Daten und URLs über 16 KiB werden vollständig abgelehnt.
Zurück zum InhaltFokus und Lebensdauer der Fenster
Sitzungen haben eigene Daten, Ansichten, Auswahlen und Filter. Sie ersetzen keine normalen Kalenderfenster und werden nach dem Beenden nicht wiederhergestellt. update und move aktivieren die App nicht. Popups schließen bei Außenklicks, Fokusverlust, Escape oder einem Space-Wechsel. Untergeordnete Popups schließen zuerst. Vollbildansichten schließen auch beim App-Wechsel.
Native Aufrufer verwenden NSWorkspace.open mit einer expliziten App-URL und OpenConfiguration.activates gleich false für popup, fullscreen, update, move und close. Sende move beim Bewegen deines Fensters und close beim Schließen. Erfolgreiche URL-Zustellung ist keine Protokollbestätigung. Verwende CLI oder Kurzbefehle, wenn du eine bestätigte Antwort benötigst.
Zurück zum InhaltAusgewählte Daten empfangen
Vor dem Rückruf muss der Benutzer bestätigen. Abbruch, Fokusverlust und Beenden liefern nichts zurück. Es werden nur Daten, Zeitzone und Sitzungskennung gesendet, keine Ereignisse oder Kalenderinhalte. Rückrufe über HTTP, HTTPS, file, data, JavaScript und popCalendar werden abgelehnt.
popcalendar://integration/open?v=1&session=choose-trip&mode=month&callback=my-app%3A%2F%2Fcalendar-selection%3Ftoken%3DexampleVorhandene Abfrageparameter der Rückruf-URL bleiben erhalten. Verwende nicht die unten reservierten Ergebnisnamen. Prüfe beim Empfang die erwartete Sitzung und dein eigenes undurchsichtiges Token. Zugangsdaten gehören nie in eine URL.
| Befehl oder Option | Funktion |
|---|---|
pc-session | Der ursprüngliche Sitzungsname. |
pc-start, pc-end | Erster und letzter ausgewählter Kalendertag, beide eingeschlossen. |
pc-ranges | Ein JSON-Array aus [start, end]-Paaren, das bis zu 128 getrennte Bereiche erhält. |
pc-time-zone | Die Zeitzonenkennung der zurückgegebenen Daten. |