Документація автоматизації
Довідка командного рядка
Інтегруйте popCalendar у власну заміну Dock або інші інструменти для Mac. Відкривайте календарі, вибирайте дати, керуйте планами та експортуйте зображення через CLI.
Ці посібники описують popCalendar 1.3 та новіші версії. Деякі дії потребують новішої версії системи, як зазначено нижче.
Повноцінний календар для вашого інструмента
Додайте popCalendar до власної заміни Dock, засобу запуску програм, утиліти для смуги меню чи будь-якого іншого інструмента для Mac. Запропонуйте багаті можливості календаря без потреби створювати його самостійно, використовуючи нативні вікна календаря, прив'язані спливні вікна та вибір дат через CLI.
Розробники можуть звернутися до нас по безкоштовний промокод popCalendar і практичну допомогу під час створення інтеграції.
Напишіть на support@apptrust.app
Кожен інструмент, у якому реалізовано інтеграцію popCalendar, отримає окремий розділ на popcalendar.app як офіційно підтримувана інтеграція. Повідомте нам, коли ваша інтеграція буде готова.
До змістуЗапуск із пакета програми
Якщо popCalendar уже встановлено, окремий пакет CLI не потрібен. Запускайте основний виконуваний файл за повним шляхом. Усі команди починаються з --. Запуск без команди відкриває звичайну програму.
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --helpЗа бажанням додайте каталог виконуваного файла до PATH для поточного сеансу термінала. Той самий рядок можна вручну додати до налаштувань оболонки. Якщо програму переміщено або перейменовано, використовуйте її фактичне розташування. Виконуваний файл Setapp також має назву popCalendar. Якщо встановлено обидві версії, вибирайте потрібну повним шляхом.
export PATH="${PATH:+$PATH:}"'/Applications/popCalendar.app/Contents/MacOS'
popCalendar --help До змісту Показати календар у Терміналі
Використовуйте --terminal, щоб вивести календар без відкриття його вікна. Спочатку ввімкніть календарі в Терміналі в Налаштуваннях > Автоматизація та приватність. Перегляд відкриває панель прикладу з командами, які можна скопіювати. Звичайні календарі працюють локально. Запитані приватні дані читаються через програму у фоновому режимі.
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --interactive
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --year 2027Якщо макет не задано, показується повний рік, коли він уміщується, або місяць. Інтерактивний режим пристосовується до зміни розміру, доки ви не виберете макет або діапазон. Для конвеєрів, JSON і виводу лише списку подій типовим є один місяць.
До змістуПодії, плани та робочі дні
Додайте --events для подій, --agenda для списку подій, --plans для позначення збережених планів і --working-days для робочого графіка. Фільтр набору календарів діє лише для цієї команди й не змінює активний набір. --search шукає в назвах і місцях. Перед запитом подій надайте програмі доступ до календарів.
popCalendar --terminal --events today --agenda
popCalendar --terminal --events week --calendar-set current
popCalendar --terminal --months 3 --plans all --working-days
popCalendar --terminal --events month --search meeting --limit 20
popCalendar --terminal --start 2027-03-01 --end 2027-03-14 --events rangeПараметр week означає наступні сім днів від --date або від сьогодні. Діапазон включає обидві крайні дати. Без явного вибору події для range охоплюють показані місяці. Дати й заголовки використовують григоріанський календар.
До змістуНавігація в інтерактивному режимі
Використовуйте стрілки або h/j/k/l для переходу між днями, n/p для періодів, m/y для місяця чи року та t для сьогодні. Натисніть v, щоб позначити початок і кінець діапазону, c для очищення, g для переходу до дати, / для пошуку та ? для довідки. Для виходу натисніть q або Escape.
Перемикайте події клавішею e, список подій клавішею a, плани клавішею b, робочі дні клавішею d та номери тижнів клавішею w. Натисніть s для наступного набору календарів, r для оновлення, PageUp/PageDown або Space для прокручування.
Команди повними словами також працюють і не залежать від регістру. У режимі миттєвих клавіш спочатку натисніть клавішу двокрапки, введіть команду й натисніть Enter. Якщо нижній рядок просить Enter, одразу введіть команду й натисніть Enter. Escape спершу скасовує активний запит введення, а потім виходить.
month year next previous today
left right up down range clear
events agenda plans working-days sets week-numbers
goto 2027-03-01
search meeting
refresh page-up page-down home end
help quit exit До змісту Параметри виводу в Терміналі
Виберіть дату, місяць, рік, режим або від 1 до 24 місяців. Задавайте --start і --end разом, без іншого параметра дати чи режиму. Налаштовуйте календар через --time-zone, --first-weekday і --week-numbers. --width приймає від 32 до 240 стовпців, --limit від 1 до 500 подій, а --color значення auto, always або never.
popCalendar --terminal --mode two-years --date 2027-01-01 --week-numbers
popCalendar --terminal --month 2027-03 --time-zone Europe/Kyiv --first-weekday monday
popCalendar --terminal --year 2027 --width 120 --color never > calendar.txt
popCalendar --terminal --events today --json > agenda.jsonПереспрямований вивід є звичайним текстом. --json повертає структуровані дані без форматування ANSI й не поєднується з --interactive або --color always. Команди Термінала лише читають дані й не змінюють події, плани чи набори календарів.
До змістуВідкриття та керування календарями
Параметри приймають --option value або --option=value. Типова назва сеансу cli. Повторне використання сеансу оновлює те саме вікно. Для незалежних вікон використовуйте різні назви. Підтримуються всі шість режимів.
popCalendar --open --session work --mode two-years --date 2027-01-01
popCalendar --popup --session picker --mode month --anchor 400,850,40,24 --size 520x720
popCalendar --update --session picker --date 2027-03-01
popCalendar --move --session picker --anchor 600,850,40,24
popCalendar --close --session pickerДля повноекранного календаря використовуйте --presentation fullscreen із --display current, main або UUID дисплея. Він займає один дисплей без створення простору macOS. Escape або повторне перемикання того самого сеансу закриває його. Повноекранні сеанси відхиляють розмір, позицію, прив'язку, стрілку та координати. Перед зміною способу показу закрийте сеанс.
popCalendar --toggle --session overview --presentation fullscreen --mode two-years --display current До змісту Отримання підтвердженого вибору дат
--select відкриває вибір дат і чекає підтвердження. Типовий час очікування становить 300 секунд. --timeout можна встановити від 1 до 86400. Escape, закриття вікна вибору або Control-C скасовує дію. Повертається до 128 окремих діапазонів з останньої використаної панелі календаря. Без --json кожен рядок містить START END. Обидві дати включено.
popCalendar --select --session picker --mode month --date 2027-03-01 --json --timeout 300{"version":1,"status":"selected","session":"picker","timeZone":"America/Los_Angeles","ranges":[{"start":"2027-03-01","end":"2027-03-07"}]} До змісту Плани, робочі дні та зображення
Замініть SET_UUID і PLAN_UUID ідентифікаторами, які повертають --sets і --plans. Використовуйте різні UUID для REQUEST_UUID і NEW_REQUEST_UUID. Вимоги до дозволів описано в огляді автоматизації.
| Команда або параметр | Дія |
|---|---|
--help | Виводить повну довідку команд і параметрів. |
--version | Виводить версію та номер збірки програми. |
--capabilities [--json] | Повертає підтримувані команди й обмеження без відкриття програми. |
--doctor [--json] [--timeout SECONDS] | Перевіряє ідентифікацію програми, дозволи та зв'язок із нею. |
--sets [--json] | Повертає назви й ідентифікатори збережених наборів календарів. |
--sessions [--json] | Повертає ідентифікатори відкритих сеансів інтеграції на Mac. |
--plans [--name SEARCH] [--id UUID] [--json] | Повертає збережені плани, їхні діапазони та інформацію про повторення. Можна фільтрувати за назвою або ідентифікатором. |
--create-plan --name NAME --start YYYY-MM-DD --end YYYY-MM-DD [--request-id UUID] | Зберігає іменований діапазон дат включно з обома межами та повертає ідентифікатор плану. |
--duplicate-plan --id UUID --name NAME [--request-id UUID] | Дублює збережений план під новою назвою та повертає його ідентифікатор. |
--open-plan --id UUID | Відкриває збережений план із поточними діапазонами та налаштуваннями повторення. |
--activate-set --calendar-set UUID | Змінює активний набір календарів зі збереженням поточної дати й режиму показу. |
--working-days --start YYYY-MM-DD --end YYYY-MM-DD | Рахує робочі дні за ввімкненим графіком і календарями відсутності з подіями на весь день. Обидві межі враховуються. |
--shift-working-days --start YYYY-MM-DD --count INTEGER | Переміщує дату вперед або назад на робочі дні. Початковий день не враховується. |
--pause-chimes --minutes INTEGER | Призупиняє сигнали на вказану кількість хвилин, щонайбільше на сім днів. |
--resume-chimes | Завершує паузу зі збереженням налаштованого розкладу й стану ввімкнення сигналів. |
--export --start YYYY-MM-DD --end YYYY-MM-DD [--calendar-set UUID] [--plans UUID,UUID] [--events] | Експортує PNG щонайбільше за два календарні роки. Включає лише запитані плани. Кружечки подій додаються лише за запитом. |
Дати API використовують григоріанський формат YYYY-MM-DD у часовому поясі програми. Обчислення робочих днів потребують увімкненого робочого графіка. Запити дат обмежено десятьма роками, а зсуви 2600 робочими днями. Помилка читання подій повертає помилку, а не нуль днів відсутності.
Повторюючи створення або дублювання плану, використовуйте той самий UUID запиту й ідентичні дані. Повтор поверне вже наявний ідентифікатор. Інші дані спричинять помилку. Не використовуйте UUID повторно після редагування чи видалення результату. Завершення часу очікування або скасування не відкочує вже застосовану зміну.
popCalendar --sets --json
popCalendar --plans --name Holiday --json
popCalendar --create-plan --name Holiday --start 2027-08-02 --end 2027-08-13 --request-id REQUEST_UUID
popCalendar --duplicate-plan --id PLAN_UUID --name Variation --request-id NEW_REQUEST_UUID--export записує байти PNG у стандартний вивід. Перенаправте їх у файл. Запитаний діапазон буде виділено, а звичайні вікна й збережені налаштування не зміняться. CLI експортує PNG, а не PDF.
popCalendar --export --start 2027-01-01 --end 2027-12-31 --calendar-set SET_UUID --plans PLAN_UUID --events > calendar.png До змісту Результати та помилки
Команди керування типово чекають прийняття до 60 секунд. --wait необов'язковий. --no-wait підтверджує лише доставку, не поєднується з --timeout і не застосовується до вибору дат, даних або діагностики. Прийняття не означає, що завантаження подій завершилося.
Команди даних повертають JSON. Із --json успіх або помилка є одним об'єктом JSON у стандартному виводі. Помилки містять errorCode, message і exitCode. Без --json помилки надходять у стандартний вивід помилок. --export повертає байти зображення й не підтримує --json.
{"version":1,"status":"error","errorCode":"invalid_arguments","message":"Unknown option --example.","exitCode":64,"command":"open"}| Код завершення | Дія |
|---|---|
0 | Успіх |
2 | Вибір скасовано |
3 | Час очікування минув |
4 | Не вдалося запустити програму або встановити зв'язок |
5 | Програма відхилила запит |
64 | Неправильна команда або аргументи |
70 | Внутрішня помилка або помилка каналу відповіді |
128 + signal | Перервано сигналом, зокрема 130 для Control-C |
Діагностика з'єднання
--doctor може запустити програму у фоні. Типовий час очікування становить десять секунд. Команда не змінює дозволи й не повертає вміст календаря. Успішна JSON-діагностика міститься в result.diagnostics із connection зі значенням connected і permissionSource зі значенням app. Невдалі перевірки містять об'єкт diagnostics верхнього рівня з локальними дозволами, які можуть відрізнятися від незбереженого стану програми, що не відповідає.
popCalendar --doctor --json До змісту Вміст і геометрія
| Команда або параметр | Дія |
|---|---|
--presentation | Типово window, також popup або fullscreen. Перед зміною способу показу закрийте активний сеанс. |
--mode | month, two-months, year, two-years, month-year або month-two-years. Типово year. |
--date | Григоріанська дата YYYY-MM-DD у часовому поясі програми. Типово перша дата діапазону або сьогодні. |
--start, --end | Межі YYYY-MM-DD включно. Укажіть обидві, причому start не пізніше за end. |
--clear-selection | Очистити вибір дат. Не можна поєднувати з --start і --end. |
--calendar-set | UUID збереженого набору або current для копіювання активного фільтра. Отримуйте ID через CLI чи Швидкі команди. Невідомі ID відхиляються. |
--display | Лише для повноекранного показу. current використовує дисплей під вказівником, main головний дисплей, або вкажіть UUID. Від'єднаний дисплей замінюється доступним. |
--width, --height | Розміри вмісту в логічних точках, кожен від 240 до 8192. Укажіть обидва. Спливні вікна зберігають запитаний розмір із першого видимого кадру. Звичайні вікна зі змінним розміром можуть збільшуватися до мінімального читабельного розміру. Межі екрана мають пріоритет. CLI також приймає --size WIDTHxHEIGHT. |
--anchor | Прямокутник прив'язки панелі як x,y,width,height у глобальних координатах екрана. Не поєднується з x і y. |
--x, --y | Явна позиція замість прив'язки. Укажіть обидві координати. Панель із явною позицією не має стрілки. |
--coordinates | appkit починається в нижньому лівому куті головного екрана. top-left відлічує вниз від верхнього лівого. Додаткові дисплеї можуть мати від'ємні координати. Значення задаються в пунктах, а не пікселях. |
--arrow | auto, top, bottom, left, right або none. Називає край панелі зі стрілкою. Розташування може змінитися, щоб панель залишалася видимою. |
--callback | Зареєстрована власна схема URL для повернення явно підтверджених дат. |
CLI використовує ті самі назви з префіксом --, крім selection=clear, що стає --clear-selection. Повноекранний показ відхиляє всі параметри геометрії, крім display. Невідомі чи дубльовані параметри, неправильні дати та URL понад 16 KiB відхиляються цілком.
До змісту