calendar_events - PythonIDE Docs

日历与提醒事项：读取/写入 EventKit 事件，管理提醒待办。

边界：事件和提醒是两个独立权限。写日历用 request_access()，写提醒用 request_reminder_access()。时间参数用 Unix timestamp，不是日期字符串。

#模块概览

项	说明
导入	`import calendar_events`
适合做什么	创建会议/专注块、查日程、创建/完成提醒
调用时机	权限、读取、写入都放在按钮回调
推荐顺序	申请对应权限 → 创建/查询 → 保存返回的 `id` 供删除
时间格式	`start` / `end` / `due_timestamp` 均为 Unix 秒级时间戳

#快速开始

下面脚本申请日历权限，创建 1 小时专注块：

python

import time
import calendar_events

status = calendar_events.authorization_status()
if status != "authorized":
    status = calendar_events.request_access()

if status == "authorized":
    now = time.time()
    event = calendar_events.create_event(
        "专注时间",
        now + 3600,
        now + 7200,
        notes="来自 PythonIDE",
    )
    print("已创建:", event)
else:
    print("日历未授权:", status)

#AppUI 示例

权限、创建和查询都放在按钮回调；未授权时展示状态，不继续写入。

python

import time

import appui
import calendar_events

state = appui.State(
    calendar_auth="未查询",
    status="等待操作",
    result="—",
)


def refresh_auth():
    state.calendar_auth = calendar_events.authorization_status()


def create_focus_block():
    status = calendar_events.request_access()
    state.calendar_auth = status
    if status != "authorized":
        state.batch_update(status="日历未授权", result=str(status))
        return

    now = time.time()
    event = calendar_events.create_event(
        "专注时间",
        now + 3600,
        now + 7200,
        notes="来自 PythonIDE",
    )
    state.batch_update(status="事件已创建", result=str(event))


def create_reminder():
    status = calendar_events.request_reminder_access()
    if status != "authorized":
        state.batch_update(status="提醒未授权", result=str(status))
        return

    reminder = calendar_events.create_reminder(
        "整理笔记",
        notes="来自 PythonIDE",
        due_timestamp=time.time() + 3600,
    )
    state.batch_update(status="提醒已创建", result=str(reminder))


def list_today():
    status = calendar_events.request_access()
    state.calendar_auth = status
    if status != "authorized":
        state.batch_update(status="日历未授权", result="—")
        return

    now = time.time()
    events = calendar_events.get_events(now, now + 86400)
    state.batch_update(
        status="查询完成",
        result=f"未来 24 小时共 {len(events)} 个事件",
    )


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("权限", [
                appui.LabeledContent("日历授权", value=state.calendar_auth),
                appui.Button("刷新授权状态", action=refresh_auth),
            ]),
            appui.Section("操作", [
                appui.Button("创建专注块", action=create_focus_block)
                .button_style("bordered_prominent"),
                appui.Button("创建提醒", action=create_reminder),
                appui.Button("查询今日事件", action=list_today),
            ]),
            appui.Section("结果", [
                appui.LabeledContent("状态", value=state.status),
                appui.Text(state.result).font("caption").foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("日历")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`authorization_status()` / `request_access()`	日历事件权限
`request_reminder_access()`	提醒事项权限
`get_calendars()`	可用日历列表
`get_events(start, end)`	查询时间范围内事件
`create_event(title, start, end, ...)`	创建日历事件
`delete_event(event_id)`	删除事件 → `bool`
`get_reminders()`	提醒列表
`create_reminder(title, ...)`	创建提醒
`complete_reminder(id)` / `delete_reminder(id)`	完成/删除提醒

#日历事件

权限：

python

status = calendar_events.authorization_status()
if status != "authorized":
    status = calendar_events.request_access()

get_calendars() — 返回可写入的日历列表，可选 calendar_id 传给 create_event。

get_events(start, end, calendar_id=None) — 查询时间范围内事件，start/end 为 Unix timestamp。

create_event(title, start, end, *, notes=None, location=None, calendar_id=None, all_day=False) — 创建事件；end 必须晚于 start。

python

import time

now = time.time()
event = calendar_events.create_event(
    "团队会议",
    now + 3600,
    now + 5400,
    notes="周会",
    location="会议室 A",
)
event_id = event.get("id")  # 保存 id 供后续删除

delete_event(event_id) — 返回 True/False。

#提醒事项

提醒需要单独申请权限：

python

if calendar_events.request_reminder_access() == "authorized":
    reminder = calendar_events.create_reminder(
        "提交报告",
        notes="下班前",
        due_timestamp=time.time() + 7200,
    )

API	说明
`get_reminders()`	读取提醒列表
`create_reminder(title, notes=None, due_timestamp=None)`	创建提醒
`complete_reminder(reminder_id)`	标记完成
`delete_reminder(reminder_id)`	删除提醒

#常见错误

错误写法	后果	修正
写提醒前只申请日历权限	提醒仍无权限	用 `request_reminder_access()`
传日期字符串给 `create_event`	时间错误	传 Unix timestamp
不保存事件 `id`	后续无法删除	保存 `create_event` 返回的 `id`
`end <= start`	创建失败	确保结束时间晚于开始

#相关文档

文档	用途
notification	本地定时提醒（非日历）
permission	统一权限查询
原生能力入口	MiniApp 场景配方

#预期效果

运行示例后，界面应出现文档描述的目标结果；若与预期不符，先看「失败路径」并按返回值或日志排查。