AppUI API 地图 - PythonIDE Docs

这页按任务组织 AppUI API。还没确定页面结构时，先看 AppUI UI 模式。

#最小正确组合

python

import appui

state = appui.State(name="MiniApp", enabled=True, saved=False)


def set_name(value):
    state.batch_update(name=value, saved=False)


def set_enabled(value):
    state.batch_update(enabled=value, saved=False)


def save():
    state.saved = bool(state.name.strip())


def body():
    footer = "Saved" if state.saved else "Edit values and tap Save"
    form = appui.Form([
        appui.Section("Controls", [
            appui.TextField("Name", text=state.name, on_change=set_name),
            appui.Toggle("Enabled", is_on=state.enabled, on_change=set_enabled),
        ]),
        appui.Section("Output", [
            appui.LabeledContent("Name", value=state.name or "Missing"),
            appui.LabeledContent("Enabled", value=str(state.enabled)),
        ], footer=footer),
    ]).navigation_title("API 地图")

    return appui.NavigationStack(
        form.toolbar([
            appui.ToolbarItem(
                placement="navigation_bar_trailing",
                content=appui.Button("Save", action=save)
                .button_style("bordered_prominent"),
            )
        ])
    )


appui.run(body, state=state)

预期效果：页面显示输入、开关、输出和导航栏保存按钮；修改后点击 Save 会更新保存状态。

#按任务查 API

任务	首选 API	继续阅读
启动 MiniApp	`appui.run`	函数参考
控制呈现方式	`appui.run(..., presentation=...)`	函数参考
程序化弹层	`presentation_present` / `presentation_dismiss`	呈现 API
保存普通界面状态	`State`	状态管理
多字段一起更新	`state.batch_update(...)`	状态管理
高频局部刷新	`ReactiveState`	性能与实时界面
派生数据	`computed`	状态管理
状态变化后的副作用	`effect`	状态管理
双向绑定	`bind`	函数参考
输入设置项	`Form + Section`	布局系统
动态列表	`List + ForEach`	布局系统
列表进详情	`NavigationStack + NavigationLink`	导航与页面结构
程序化跳转	`NavigationPath + destinations`	导航与页面结构
多主分区	`TabView + Tab`	导航与页面结构
底部状态条展开面板	`.tab_view_bottom_accessory` + `.sheet`	导航参考
导航栏按钮	`ToolbarItem`	导航参考
临时弹层	`.sheet` / `.popover`	呈现 API
确认和错误提示	`.alert` / `.confirmation_dialog`	呈现 API
搜索和刷新	`.searchable` / `.refreshable`	交互与回调
空状态	`ContentUnavailableView`	数据展示
加载状态	`ProgressView`	数据展示
输入控件	`TextField`、`SecureField`、`TextEditor`	控件 API
选择控件	`Toggle`、`Picker`、`Slider`、`Stepper`	控件 API
媒体和文件	`PhotoPicker`、`CameraPicker`、`FileImporter`	媒体 API
地图、网页、视频	`MapView`、`WebView`、`VideoPlayer`	媒体 API
图表和绘制	`Chart`、`Canvas`、`DrawingContext`、`Path`	图表 API

#行为契约

API	保证	注意
`appui.run(...)`	启动当前 MiniApp 页面。	一个脚本只保留一个最终入口。
`State`	字段变化后页面重建。	多字段同时更新用 `batch_update(...)`。
`Button(action=...)`	点击后执行命名回调。	不要写 `action=save()`。
`TextField(on_change=...)`	输入变化时把新值交给回调。	回调要写回 `State`。
`ForEach(..., key=...)`	维护动态行身份。	key 必须来自稳定业务 id。
`NavigationLink`	打开目标详情页。	目标页用函数返回 View，避免把复杂逻辑塞进行内。
`.tab_view_bottom_accessory(...)` + `.sheet(...)`	底部常驻 compact 视图点击后打开原生 sheet。	适合播放、下载、录音、导航等持续任务；紧凑条负责常驻状态，完整面板交给系统 sheet 处理下拉关闭、圆角和拖拽手感。
`.sheet(...)` / `.alert(...)`	展示临时页面或提示。	`is_presented` 要由状态控制。
`PhotoPicker` / `FileImporter`	触发系统选择流程。	处理用户取消、权限拒绝和空结果。

#选择顺序

先选容器：NavigationStack、TabView、List、Form、ScrollView。
再选数据流：State、ReactiveState、bind、computed、Timer。
再选控件：输入、选择、按钮、工具栏、弹层。
再选状态反馈：空状态、加载、错误、保存成功、权限拒绝。
最后选视觉：字体、颜色、边距、背景、图表或媒体。

#失败路径

API 名不确定：先按任务查本页，再进入对应 appui-ref-*。
按钮没反应：确认 Button(action=...) 传入命名函数。
输入不更新：确认 on_change 写回 State。
列表错乱：确认 ForEach 使用稳定 key。
页面空白：确认 body() 返回 View，appui.run(...) 在脚本末尾调用。

#相关文档

文档	用途
快速上手	跑通第一个 MiniApp。
运行时选择	判断是否应该使用 AppUI。
AppUI UI 模式	选择页面结构。
MiniApp 开发排错	排查入口、状态、布局和系统能力。