Документація автоматизації

Довідка схеми URL

Відкривайте вікно календаря, прив'язану спливну панель або повноекранний календар з іншої програми Mac.

Ці посібники описують popCalendar 1.3 та новіші версії. Деякі дії потребують новішої версії системи, як зазначено нижче.

Відкриття календаря з іншої програми

Цей інтерфейс працює на macOS 12 та новіших. Спершу ввімкніть керування із зовнішніх програм і CLI. Використовуйте popcalendar для стандартної версії та popcalendar-setapp для Setapp. Створюйте URL через URLComponents і URLQueryItem, кодуючи вкладені URL зворотного виклику як одне значення.

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
До змісту

Команди та сеанси

Кожен URL потребує v=1 і назви сеансу від 1 до 128 символів ASCII з літерами, цифрами, крапками, підкресленнями чи дефісами. Можна відкрити до восьми сеансів, серед яких одна спливна панель або повноекранний календар. Нова тимчасова панель замінює попередню. Звичайні вікна залишаються відкритими.

Команда або параметрДія
/openВідкриває сеанс або оновлює та виводить на передній план наявний.
/toggleЗакриває наявний сеанс або відкриває, якщо його немає.
/updateОновлює вміст або геометрію без відкриття відсутнього сеансу чи перехоплення фокусу.
/moveЗмінює лише геометрію без відкриття відсутнього сеансу чи перехоплення фокусу.
/closeЗакриває сеанс. Якщо його немає, нічого не відбувається.
До змісту

Вміст і геометрія

Команда або параметрДія
presentationТипово window, також popup або fullscreen. Перед зміною способу показу закрийте активний сеанс.
modemonth, two-months, year, two-years, month-year або month-two-years. Типово year.
dateГригоріанська дата YYYY-MM-DD у часовому поясі програми. Типово перша дата діапазону або сьогодні.
start, endМежі YYYY-MM-DD включно. Укажіть обидві, причому start не пізніше за end.
selectionЗначення clear прибирає виділення. Не поєднується зі start і end.
calendar-setUUID збереженого набору або current для копіювання активного фільтра. Отримуйте ID через CLI чи Швидкі команди. Невідомі ID відхиляються.
displayЛише для повноекранного показу. current використовує дисплей під вказівником, main головний дисплей, або вкажіть UUID. Від'єднаний дисплей замінюється доступним.
width, heightРозміри вмісту в логічних точках, кожен від 240 до 8192. Укажіть обидва. Спливні вікна зберігають запитаний розмір із першого видимого кадру. Звичайні вікна зі змінним розміром можуть збільшуватися до мінімального читабельного розміру. Межі екрана мають пріоритет. CLI також приймає --size WIDTHxHEIGHT.
anchorПрямокутник прив'язки панелі як x,y,width,height у глобальних координатах екрана. Не поєднується з x і y.
x, yЯвна позиція замість прив'язки. Укажіть обидві координати. Панель із явною позицією не має стрілки.
coordinatesappkit починається в нижньому лівому куті головного екрана. top-left відлічує вниз від верхнього лівого. Додаткові дисплеї можуть мати від'ємні координати. Значення задаються в пунктах, а не пікселях.
arrowauto, top, bottom, left, right або none. Називає край панелі зі стрілкою. Розташування може змінитися, щоб панель залишалася видимою.
callbackЗареєстрована власна схема URL для повернення явно підтверджених дат.

CLI використовує ті самі назви з префіксом --, крім selection=clear, що стає --clear-selection. Повноекранний показ відхиляє всі параметри геометрії, крім display. Невідомі чи дубльовані параметри, неправильні дати та URL понад 16 KiB відхиляються цілком.

До змісту

Фокус і час життя вікон

Сеанси мають власні дати, режим показу, виділення й фільтр. Вони не замінюють звичайні вікна та не відновлюються після виходу. update і move не активують програму. Панелі закриваються від кліку зовні, втрати фокусу, Escape або зміни простору. Дочірні панелі закриваються першими. Повноекранний календар також закривається під час перемикання програм.

У нативній програмі використовуйте NSWorkspace.open із явним URL програми й OpenConfiguration.activates зі значенням false для popup, fullscreen, update, move і close. Надсилайте move під час переміщення свого вікна та close під час закриття. Успішна доставка URL не є підтвердженням протоколу. Використовуйте CLI чи Швидкі команди, якщо потрібен підтверджений результат.

До змісту

Отримання вибраних дат

Перед зворотним викликом користувач має підтвердити вибір. Скасування, втрата фокусу та вихід нічого не повертають. Надсилаються лише дати, їхній часовий пояс та ідентифікатор сеансу. Події та вміст календаря не передаються. Зворотні виклики HTTP, HTTPS, file, data, JavaScript і popCalendar відхиляються.

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

Наявні параметри URL зворотного виклику зберігаються. Не використовуйте наведені нижче зарезервовані назви результату. Отримавши результат, перевіряйте очікуваний сеанс і власний непрозорий токен. Ніколи не додавайте облікові дані в URL.

Команда або параметрДія
pc-sessionПочаткова назва сеансу.
pc-start, pc-endПерший і останній вибрані календарні дні включно.
pc-rangesМасив JSON із пар [start, end], що зберігає до 128 окремих діапазонів.
pc-time-zoneІдентифікатор часового поясу повернених дат.
До змісту