快捷指令 - PythonIDE Docs

系统快捷指令集成、自动化和 URL 跳转。

#预期效果

示例会展示系统快捷指令入口和 Python shortcuts 模块的最小调用。

#先选入口

目标	推荐方式
从系统快捷指令里运行 Python 脚本	使用“运行 Python 脚本”动作。
从 App 内按钮触发已有快捷指令	在 AppUI 回调里调用 `shortcuts.run_shortcut(...)`。
打开网页、深链或系统设置	调用 `shortcuts.open_url(...)` 或 `shortcuts.open_settings()`。
需要表单、确认和结果展示	用 AppUI 承载页面，把快捷指令能力放进按钮。
需要长期后台自动化	使用系统快捷指令自动化，不把循环写进前台页面。

#什么时候用

想从 Python 脚本触发一个已经存在的系统快捷指令。
想打开 URL、深链或当前 App 的设置页。
想把 PythonIDE 的脚本能力接入 iOS 快捷指令自动化。

#可用动作

动作	用途
运行 Python 代码	执行短代码片段
运行 Python 脚本	执行工作区 .py 文件并传参
在应用中运行	打开 App 运行需要输入或 UI 的脚本
获取脚本输出	读取不等待运行后的输出
创建 Python 脚本	创建 .py 文件后再运行

#测试代码

python

print("hello")

#Python 模块示例

python

import shortcuts

shortcuts.run_shortcut("Daily Log")
shortcuts.open_url("https://www.apple.com")
shortcuts.open_settings()

#AppUI 中的推荐接法

python

import appui
import shortcuts

state = appui.State(status="等待操作")


def run_daily_log():
    ok = shortcuts.run_shortcut("Daily Log")
    state.status = "已触发" if ok else "未能触发"


def open_settings():
    shortcuts.open_settings()
    state.status = "已打开设置"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("快捷指令", [
                appui.Button("运行 Daily Log", action=run_daily_log),
                appui.Button("打开设置", action=open_settings),
            ]),
            appui.Section("状态", [
                appui.Text(state.status).foreground_color("secondaryLabel"),
            ]),
        ]).navigation_title("快捷指令")
    )


appui.run(body, state=state)

预期效果：页面提供两个明确按钮；触发失败不会中断页面，状态区域会显示结果。

#失败路径

情况	应该怎么处理
系统入口不可用	显示不可用状态，不重复触发打开动作。
用户取消或没有配置	保持原页面状态，并提示需要先配置对应系统能力。
回调没有返回预期结果	记录简短状态，避免把长日志或敏感内容展示给用户。
需要复杂界面	用 `appui` 承载页面，把自动化能力放在按钮回调里调用。

#使用规则

run_shortcut(...) 需要用户设备上已经存在同名快捷指令。
打开 URL 和运行快捷指令都应该由明确操作触发，不要在导入模块时自动执行。
如果要做多步骤界面流程，优先用 AppUI；快捷指令适合系统自动化入口。

#发布前检查

检查项	合格标准
快捷指令名称	设备上已经存在同名快捷指令。
触发时机	运行快捷指令和打开 URL 都由按钮、菜单或系统动作触发。
结果反馈	成功、取消、未配置和不可用状态都有简短提示。
页面边界	多步骤交互放在 AppUI，不把 UI 流程塞进系统动作。

#相关文档

文档	用途
shortcuts	运行快捷指令、打开 URL、进入设置。