PythonIDE Docs
中文
简体中文
appui / API 参考

入口函数

run、dismiss、animate、bind、grid item 等模块级函数。

本页只查 appui 的模块级入口函数和网格辅助函数。页面结构、控件、导航和媒体视图分别看对应 API 参考。

#什么时候用

目标API
启动 AppUI 页面run
关闭当前 AppUI 呈现dismiss
包一组状态变化动画animate
简单周期刷新auto_refresh
降低首次启动延迟preload
为值控件创建双向绑定bind
声明派生数据computed
状态变化后触发副作用effect
定义网格列/行flexible、fixed、adaptive、grid_item
使用自定义字体custom_font

#最小正确示例

run 只在脚本末尾调用一次。bind 适合 Slider 这类 value + on_change 控件。网格列用 flexible、adaptive 或 fixed。

python 
import appui

state = appui.State(volume=0.4, selected="Volume")


def select_card(name):
    state.selected = name


def card(name, value):
    def select_current():
        select_card(name)

    return (
        appui.Button(
            action=select_current,
            content=appui.VStack([
                appui.Text(name).font("caption").foreground_color("secondaryLabel"),
                appui.Text(value).font("title3").bold(),
            ], alignment="leading", spacing=4),
        )
        .button_style("plain")
        .frame(max_width=appui.infinity, min_height=84, alignment="leading")
        .padding(12)
        .background("secondarySystemBackground", corner_radius=8)
    )


@appui.computed(state, depends_on=["volume"])
def volume_text():
    return f"{state.volume:.0%}"


def body():
    grid = appui.LazyVGrid(
        columns=[appui.flexible(minimum=120), appui.flexible(minimum=120)],
        spacing=12,
        content=[
            card("Volume", volume_text()),
            card("Selected", state.selected),
        ],
    )

    return appui.NavigationStack(
        appui.Form([
            appui.Section("bind", [
                appui.Slider(**appui.bind(state, "volume"), minimum=0, maximum=1),
            ]),
            appui.Section("Grid helpers", [
                grid,
            ]),
        ]).navigation_title("Functions")
    )


appui.run(body, state=state)

#函数签名

API签名
runrun(body_func: Optional[Union[Callable[[], View], Callable[[Union[State, ReactiveState, None]], View]]] = None, state: Optional[Union[State, ReactiveState]] = None, hot_reload: bool = False, presentation: str = 'sheet', body: Optional[Union[Callable[[], View], Callable[[Union[State, ReactiveState, None]], View]]] = None) -> None
dismissdismiss() -> None
presentation_presentpresentation_present(field_name: str, *, state: Optional[Union[State, ReactiveState]] = None, value: bool = True) -> bool
presentation_dismisspresentation_dismiss(field_name: str, *, state: Optional[Union[State, ReactiveState]] = None) -> bool
presentation_dismiss_allpresentation_dismiss_all(*, state: Optional[Union[State, ReactiveState]] = None) -> bool
dismiss_alldismiss_all(*, state: Optional[Union[State, ReactiveState]] = None) -> bool
animateanimate(action: Callable[[], None], type: str = 'default') -> None
auto_refreshauto_refresh(interval: float = 1.0) -> None
preloadpreload() -> None
bindbind(state: Union[State, ReactiveState], field_name: str, *, parse: Optional[Callable[[Any], Any]] = None, format: Optional[Callable[[Any], Any]] = None, validate: Optional[Callable[[Any], bool]] = None) -> Dict[str, Any]
computedcomputed(state: Union[State, ReactiveState], depends_on: Sequence[str]) -> Callable
effecteffect(state: Union[State, ReactiveState], depends_on: Sequence[str]) -> Callable
flexibleflexible(minimum: float = 10, maximum: Optional[float] = None) -> Dict[str, Any]
fixedfixed(size: float) -> Dict[str, Any]
adaptiveadaptive(minimum: float = 50, maximum: Optional[float] = None) -> Dict[str, Any]
grid_itemgrid_item(type: str = 'flexible', minimum: Optional[float] = None, maximum: Optional[float] = None, count: Optional[int] = None) -> Dict[str, Any]
custom_fontcustom_font(name: str, size: float = 17) -> str

#相邻 API 区别

API用法边界
bind vs on_changeSlider 这类 value 控件可以用 bind；TextField、Toggle、Picker 通常直接传当前值和 on_change。
computed vs 手动字段派生数据用 computed，不要维护第二份 state.filtered_items。
effect vs body() 副作用状态变化后的日志或同步用 effect；不要在 body() 里做副作用。
auto_refresh vs Timer简单原型可用 auto_refresh；正式页面用模块级 Timer 或明确回调。
flexible vs adaptive固定列数用多个 flexible；根据宽度自动改变列数用 adaptive。

#常见错误

错误后果修正
在按钮回调里再次调用 run运行时状态混乱run 只在脚本末尾调用一次。
在 body() 里调用 dismiss()页面构建时直接关闭放到按钮或工具栏回调里。
把 bind 传给 TextField.text参数类型不对TextField(text=state.name, on_change=set_name)。
用 auto_refresh 做复杂业务轮询刷新不可控使用 Timer、后台任务或明确刷新按钮。
普通页面绕过公开 API 更新界面可维护性差先查公开 AppUI API。

#相关文档

文档用途
快速上手最小 body()、State 和 run。
状态管理computed、effect、Timer 和 ReactiveState。
布局系统网格列、Stack、ScrollView 和 safe area。