shortcuts - PythonIDE Docs

系统快捷指令与外链：运行快捷指令、打开 URL、进入本 App 设置页。

边界：run_shortcut() / open_url() 会离开当前 App 或跳转系统界面，必须由用户点击触发，不要在 body() 或页面加载时自动调用。run_shortcut(name) 依赖用户在「快捷指令」App 中已存在同名指令。

#模块概览

项	说明
导入	`import shortcuts`
适合做什么	衔接系统自动化、打开网页/Deep Link、跳转设置
调用时机	按钮回调里调用
推荐顺序	确认用户意图 → `run_shortcut` / `open_url` / `open_settings` → 更新状态
返回值	三个 API 均返回 `bool` 表示是否成功发起

#快速开始

下面脚本打开网页并进入 App 设置：

python

import shortcuts

ok = shortcuts.open_url("https://www.apple.com")
print("打开 URL:", ok)

ok = shortcuts.open_settings()
print("打开设置:", ok)

运行已创建的快捷指令（名称须完全一致）：

python

import shortcuts

ok = shortcuts.run_shortcut("每日记录")
print("已启动:", ok)

#AppUI 示例

外跳操作全部放在按钮回调；结果写回 State。

python

import appui
import shortcuts

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


def open_website():
    ok = shortcuts.open_url("https://www.apple.com")
    state.status = "已打开网页" if ok else "打开 URL 失败"


def open_settings():
    ok = shortcuts.open_settings()
    state.status = "已打开设置" if ok else "打开设置失败"


def run_daily_log():
    ok = shortcuts.run_shortcut("每日记录")
    state.status = "已启动快捷指令" if ok else "启动失败（检查名称是否存在）"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("外链", [
                appui.Button("打开 Apple 官网", action=open_website)
                .button_style("bordered_prominent"),
                appui.Button("打开本 App 设置", action=open_settings),
            ]),
            appui.Section("快捷指令", [
                appui.Button("运行「每日记录」", action=run_daily_log),
                appui.Text(
                    "需先在系统「快捷指令」App 中创建同名指令"
                ).font("caption").foreground_color("secondaryLabel"),
            ]),
            appui.Section("状态", [
                appui.Text(state.status).foreground_color("secondaryLabel"),
            ], footer="所有外跳必须由用户点击触发。"),
        ]).navigation_title("快捷指令")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`run_shortcut(name)`	按名称运行快捷指令 → `bool`
`open_url(url)`	打开网页 / Deep Link / App Scheme → `bool`
`open_settings()`	打开本 App 系统设置页 → `bool`

#run_shortcut

run_shortcut(name) -> bool

python

ok = shortcuts.run_shortcut("My Workflow")

会跳转到「快捷指令」App 执行；名称不匹配时可能打开但不执行目标流程。

#open_url

open_url(url) -> bool

python

shortcuts.open_url("https://example.com")
shortcuts.open_url("mailto:support@example.com")
shortcuts.open_url("pythonide://some-path")  # 示例 scheme

支持 https://、mailto:、tel: 及第三方 App 的 URL Scheme。

#open_settings

open_settings() -> bool — 打开当前 App 在 iOS 设置中的页面。

#常见错误

错误写法	后果	修正
在 `body()` 里 `open_url()`	页面一加载就跳走	放进按钮回调
猜测快捷指令名称	无法执行	使用用户已有的精确名称
用 Shortcuts 做核心业务	难维护、难调试	优先 PythonIDE 原生模块
不告知用户将离开 App	体验突兀	按钮文案写清楚

#相关文档

文档	用途
dialogs	App 内确认后再外跳
network	App 内 HTTP 请求
原生能力入口	MiniApp 场景配方

#预期效果

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