オートメーションのドキュメント
URLスキームリファレンス
ほかのMacアプリから、カレンダーウインドウ、指定位置のポップアップ、全画面オーバーレイを開きます。
このガイドはpopCalendar 1.3以降を対象としています。一部のアクションには、以下に記載する新しいシステムバージョンが必要です。
別のアプリからカレンダーを開く
このインターフェイスはmacOS 12以降に対応しています。最初に外部アプリとCLIによる操作を有効にしてください。標準版ではpopcalendar、Setapp版ではpopcalendar-setappを使います。URLComponentsとURLQueryItemでURLを構築し、入れ子のコールバックURLは1つの値としてパーセントエンコードします。
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 目次に戻る コマンドとセッション
すべてのURLにはv=1と、ASCII英字、数字、ピリオド、アンダースコア、ハイフンで構成された1から128文字のセッション名が必要です。最大8セッションを開けます。そのうちポップアップまたは全画面オーバーレイは1つです。別の一時表示を開くと前の一時表示を置き換えます。通常のウインドウは開いたままです。
| コマンドまたはオプション | 動作 |
|---|---|
/open | セッションを開くか、既存のセッションを更新して前面に表示します。 |
/toggle | セッションが存在すれば閉じ、存在しなければ開きます。 |
/update | 存在しないセッションを開いたりフォーカスを奪ったりせず、内容や形状を更新します。 |
/move | 存在しないセッションを開いたりフォーカスを奪ったりせず、形状だけを変更します。 |
/close | セッションを閉じます。存在しないセッションには何もしません。 |
内容と配置
| コマンドまたはオプション | 動作 |
|---|---|
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以前にします。 |
selection | clearで選択を解除します。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以外の配置オプションを拒否します。不明または重複したパラメータ、不正な日付、16 KiBを超えるURLは全体が拒否されます。
目次に戻るフォーカスとウインドウの寿命
セッションは独自の日付、表示、選択、フィルタを持ちます。通常のカレンダーウインドウを置き換えず、終了後も復元されません。updateとmoveはアプリをアクティブにしません。ポップアップは外側のクリック、フォーカス喪失、Escape、操作スペースの変更で閉じます。子ポップオーバーが先に閉じます。全画面もアプリ切り替え時に閉じます。
ネイティブアプリからpopup、fullscreen、update、move、closeを呼ぶ場合は、アプリURLを明示してNSWorkspace.openを使い、OpenConfiguration.activatesをfalseにします。呼び出し元ウインドウの移動時には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に使わないでください。結果を受け取る際は、予想するセッションと自分で用意した不透明なトークンを検証してください。URLに認証情報を含めないでください。
| コマンドまたはオプション | 動作 |
|---|---|
pc-session | 元のセッション名。 |
pc-start, pc-end | 選択した最初と最後の暦日。両端を含みます。 |
pc-ranges | 独立した範囲を維持する[start, end]ペアのJSON配列。最大128個です。 |
pc-time-zone | 返された日付のタイムゾーン識別子。 |