automating-calendar

Calendar の自動化（JXA と AppleScript によるディスカバリー）

目次

• macOS 自動化スキルとの関係
• 基本的な考え方
• ワークフロー（デフォルト）
• 主な例
• 読み込む内容

macOS 自動化スキルとの関係

• アプリ全般の権限、シェルコマンド、UI スクリプト、アプリ間の自動化パターンには automating-mac-apps を使用します。
• このスキルでは、Calendar のイベント、カレンダー、EventKit ブリッジの機能に特化して扱います。
• PyXA のインストール： このスキルの PyXA の例を使用するには、automating-mac-apps スキルのインストール手順（PyXA Installation セクション）を参照してください。

基本的な考え方

• Calendar の辞書は AppleScript を前提としているため、そこで用語を確認します
• JXA はロジック、データ処理、ObjC／EventKit ブリッジへのアクセスを提供します
• PyXA は、よりすっきりした構文を備えた最新の Python の代替手段です

実装に関する注意事項： automating-calendar/references/calendar-basics.md を参照してください

ワークフロー（デフォルト）

1. Script Editor で Calendar の辞書にある用語を確認します。
2. 最小限の AppleScript コマンドを試作します。
3. 防御的なエラー処理を加えて JXA に移植します。
4. バッチ読み取りを実装します（重い .whose() は避けます）。
5. 高度なクエリに EventKit ブリッジを追加します。
6. サンプルイベントでテストし、結果を検証します。

エラー処理

• 操作を try-catch ブロックで囲みます
• カレンダーへのアクセスを確認します：Calendar.calendars.length > 0
• イベントの作成を確認します：if (!event.id()) throw new Error('Event creation failed')
• デバッグ用に操作をログに記録します

検証チェックリスト

• カレンダーのアクセス許可が付与されている（システム設定 > プライバシーとセキュリティ > カレンダー）
• カレンダーへのアクセスを確認済み：Calendar.calendars.length > 0
• 有効な開始日時と終了日時を指定してイベントを作成した
• 保存後、Calendar UI にイベントが表示される
• EventKit ブリッジのクエリが期待どおりの結果を返す
• すべての操作がエラー処理で囲まれている
• 出力が期待されるイベントのプロパティと一致する

主な例

基本的なイベントの作成（JXA - レガシー）：

const Calendar = Application("Calendar");
const event = Calendar.calendars[0].events.push(Calendar.Event({
  summary: "Meeting",
  startDate: new Date(),
  endDate: new Date(Date.now() + 3600000)
}));

基本的なイベントの作成（PyXA - 推奨）：

import PyXA
from datetime import datetime, timedelta

calendar = PyXA.Calendar()

# Get first calendar
work_calendar = calendar.calendars()[0]

# Create event
event = work_calendar.events().push({
    "summary": "Meeting",
    "start_date": datetime.now(),
    "end_date": datetime.now() + timedelta(hours=1),
    "location": "Conference Room A"
})

print(f"Created event: {event.summary()}")

EventKit を使用した PyObjC（高度な例）：

from EventKit import EKEventStore, EKEvent, EKCalendar
from Foundation import NSDate, NSTimeInterval
import objc

# Initialize event store
store = EKEventStore.alloc().init()

# Request access (async in real implementation)
# store.requestAccessToEntityType_completion_(EKEntityTypeEvent, None)

# Get default calendar
calendars = store.calendarsForEntityType_(EKEntityTypeEvent)
if calendars:
    default_calendar = calendars[0]

    # Create event
    event = EKEvent.eventWithEventStore_(store)
    event.setTitle_("Meeting")
    event.setStartDate_(NSDate.date())
    event.setEndDate_(NSDate.dateWithTimeIntervalSinceNow_(3600))  # 1 hour
    event.setCalendar_(default_calendar)

    # Save event
    error = objc.nil
    success = store.saveEvent_span_error_(event, EKSpanThisEvent, error)

    if success:
        print(f"Event created: {event.title()}")
    else:
        print(f"Error creating event: {error}")

EventKit ブリッジのクエリ（JXA - レガシー）：

ObjC.import('EventKit');
const store = $.EKEventStore.alloc.init;
// See 'eventkit-query.md' for full predicate implementation

EventKit ブリッジのクエリ（PyObjC - モダン）：

from EventKit import EKEventStore, EKEntityTypeEvent, NSPredicate
from Foundation import NSDate

store = EKEventStore.alloc().init()

# Get events for today
start_date = NSDate.date()  # Today
end_date = NSDate.dateWithTimeIntervalSinceNow_(86400)  # Tomorrow

calendars = store.calendarsForEntityType_(EKEntityTypeEvent)
predicate = store.predicateForEventsWithStartDate_endDate_calendars_(
    start_date, end_date, calendars)

events = store.eventsMatchingPredicate_(predicate)

for event in events:
    print(f"Event: {event.title()}, Start: {event.startDate()}")

使用しないケース

• クロスプラットフォームのカレンダー自動化（Google Calendar API または CalDAV を使用します）
• iCloud の同期操作（EventKit を直接使用します）
• macOS 以外のプラットフォーム
• 単純な AppleScript のみのタスク（JXA の複雑さを避けます）
• カレンダーの共有または権限管理（Calendar UI を使用します）

読み込む内容

• Calendar の JXA の基本：automating-calendar/references/calendar-basics.md
• レシピ（イベント、アラーム、繰り返し）：automating-calendar/references/calendar-recipes.md
• 高度なパターン（タイムゾーン、バッチ読み取り、EventKit ブリッジ）：automating-calendar/references/calendar-advanced.md
• 辞書の翻訳表：automating-calendar/references/calendar-dictionary.md
• PyXA API リファレンス（クラス／メソッドの全ドキュメント）：automating-calendar/references/calendar-pyxa-api-reference.md
• EventKit クエリの例：automating-calendar/references/eventkit-query.md
• 繰り返しを指定した EventKit の作成：automating-calendar/references/eventkit-create.md
• EventKit のタイムゾーンの例：automating-calendar/references/eventkit-timezones.md
• EventKit の例外／発生回：automating-calendar/references/eventkit-exceptions.md
• EventKit の発生回をキャンセルする例：automating-calendar/references/eventkit-occurrence-cancel.md