live_activity - PythonIDE Docs

Live Activity：在锁屏和 Dynamic Island 展示进行中的任务（上传、导出、计时等）。

边界：不是普通通知，也不是长期后台任务；适合有明确开始、更新、结束的短流程。progress 范围 0.0–1.0；任务结束（成功/失败/取消）都要 end()，避免锁屏残留。需要 iOS 16.2+ 且系统允许 Live Activity；控制放在按钮或真实任务回调，不要在 body() 里自动 start()。

#模块概览

项	说明
导入	`import live_activity`
适合做什么	导出进度、同步状态、训练计时、配送跟踪
调用时机	用户启动任务时 `start` → 进度变化时 `update` → 完成时 `end`
推荐顺序	`is_supported()` → `start()` → `update()` → `end()`
敏感信息	锁屏可见，不要展示 token、密码或隐私明细

#快速开始

下面脚本模拟一次导出流程：

python

import live_activity

if not live_activity.is_supported():
    print("当前设备不支持 Live Activity")
else:
    live_activity.start(
        title="导出",
        message="准备中…",
        progress=0.0,
        compact_text="0%",
    )
    live_activity.update(message="进行中", progress=0.5, compact_text="50%")
    live_activity.end(message="完成", dismiss_delay=5)

#AppUI 示例

用按钮模拟开始、更新、结束，并同步页面状态。

python

import appui
import live_activity

state = appui.State(
    message="未开始",
    progress=0.0,
    supported=live_activity.is_supported(),
)


def start_activity():
    if not state.supported:
        state.message = "当前设备不支持 Live Activity"
        return
    live_activity.start(
        title="导出",
        message="开始导出",
        progress=0.0,
        icon="arrow.down.circle.fill",
        compact_text="0%",
    )
    state.batch_update(message="已开始", progress=0.0)


def update_activity():
    if not state.supported:
        return
    live_activity.update(
        message="进行中",
        progress=0.5,
        compact_text="50%",
    )
    state.batch_update(message="进行中", progress=0.5)


def end_activity():
    if not state.supported:
        return
    live_activity.end(message="完成", dismiss_delay=5)
    state.batch_update(message="已结束", progress=1.0)


def body():
    support_text = "支持" if state.supported else "不支持"
    return appui.NavigationStack(
        appui.Form([
            appui.Section("环境", [
                appui.LabeledContent("Live Activity", value=support_text),
            ]),
            appui.Section("模拟任务", [
                appui.ProgressView("进度", value=state.progress),
                appui.Text(state.message).foreground_color("secondaryLabel"),
            ]),
            appui.Section("操作", [
                appui.Button("开始", action=start_activity)
                .button_style("bordered_prominent"),
                appui.Button("更新到 50%", action=update_activity),
                appui.Button("结束", action=end_activity, role="destructive"),
            ], footer="真机 + 系统设置中开启 Live Activity 效果最好。"),
        ]).navigation_title("实时活动")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`is_supported()`	设备与系统是否支持
`start(title, message, progress, icon, compact_text)`	开始活动
`update(...)`	更新字段（只传要改的）
`end(message, dismiss_delay)`	结束活动

#is_supported

is_supported() -> bool — 检查 ActivityKit 是否可用且用户未在系统设置中关闭。

#start

start(title="", message="", progress=None, icon=None, compact_text=None)

python

live_activity.start(
    title="下载中",
    message="正在下载…",
    progress=0.0,
    icon="arrow.down.circle.fill",
    compact_text="0%",
)

参数	说明
`progress`	0.0–1.0，超出会被裁剪
`icon`	SF Symbol 名称
`compact_text`	Dynamic Island 紧凑模式短文案

#update

update(title=None, message=None, progress=None, icon=None, compact_text=None) — 只更新传入的字段，其余保持不变。

#end

end(message=None, dismiss_delay=None) — 结束当前活动。

python

live_activity.end(message="失败", dismiss_delay=3)

dismiss_delay 为结束后在锁屏保留的秒数；省略则尽快消失。

#常见错误

错误写法	后果	修正
普通按钮反馈也 `start()`	打扰用户锁屏	用 AppUI 状态或 notification
`progress > 1.0`	显示异常	限制在 0.0–1.0
只 `start` 不 `end`	锁屏状态残留	成功/失败/取消都 `end()`
展示敏感 token	锁屏泄露	只显示进度与中性文案
在 `body()` 里 `start()`	刷新时重复创建	放进任务/按钮回调

#相关文档

文档	用途
notification	任务完成后的本地通知
background	短时后台任务
原生能力入口	MiniApp 场景配方

#预期效果

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