运行时选择

MiniApp 先选运行时，再写代码。运行时选错会让布局难维护、交互不可用、系统能力接不上。

#默认判断

大多数“像 App 一样能点、能输入、能保存状态”的需求，默认选 appui。只有当需求明确是小组件、游戏绘制、Pythonista 兼容 UI 或纯输出脚本时，才换运行时。

#决策表

#AppUI 骨架

import appui

state = appui.State(status="Ready")


def run_action():
    state.status = "Action completed"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("MiniApp", [
                appui.LabeledContent("Runtime", value="appui"),
                appui.LabeledContent("Status", value=state.status),
                appui.Button("Run", action=run_action)
                .button_style("bordered_prominent"),
            ])
        ]).navigation_title("运行时")
    )


appui.run(body, state=state)

预期效果：预览显示一个原生表单页面，点击 Run 后状态变为 Action completed。

#不同运行时的边界

#widget

用于主屏、锁屏和 StandBy 小组件。它没有普通页面输入和长列表交互，适合信息展示、参数配置、时间线刷新和受控桌面按钮。

#console

用于一次性脚本、批处理、日志输出和转换任务。用户只需要看输出时，不要硬做 AppUI。

#scene

用于持续绘制、游戏、精灵、物理和触摸循环。它不是设置页、列表页或表单页的替代品。

#ui

用于 Pythonista 兼容的命令式界面脚本。新 MiniApp 默认不要从 ui 开始；需要原生 App 风格页面时用 appui。

#HTML / WebView

用于已有 Web 页面、必须复用 DOM/CSS/JS 的内容，或需要展示外部网页。普通 iOS 风格工具页不建议用 Web 结构模拟。

#选择规则

• 不确定时先选 appui，因为它覆盖表单、列表、导航、设置和大多数工具页。
• 用户要求“桌面小组件、主屏卡片、锁屏信息”，选 widget。
• 用户要求“小游戏、画布、碰撞、持续动画”，选 scene。
• 只有输出、批处理或转换任务时，选 console。
• 需要设备能力时，先查 原生能力入口。

#失败路径

• 页面像网页而不是原生 App：回到 appui，使用 NavigationStack、Form、List。
• 小组件脚本无法输入文字：这是 widget 的边界；需要输入时做 AppUI 页面。
• 动画不连续：AppUI 适合界面状态动画；游戏循环和持续绘制交给 scene。
• 命令脚本维护成本变高：如果只是输出文本，保持 console，不要额外做页面。

#相关文档