ui API 参考 - PythonIDE Docs

ui 是 Pythonista 风格的命令式原生 UI。它适合迁移 Pythonista 风格脚本、手动 frame 布局和需要直接控制 UIKit 风格视图的场景。新 MiniApp 的表单、列表、导航和设置页优先用 appui。

#预期效果

示例会展示命令式控件、sender 回调和自定义绘图；API 表用于确认常用控件、布局属性和工具函数。

#最小页面

python

import ui


def tapped(sender):
    sender.title = "Tapped"


view = ui.View(frame=(0, 0, 320, 220))
view.name = "ui demo"

button = ui.Button(frame=(40, 88, 240, 44), title="Tap")
button.action = tapped

view.add_subview(button)
view.present("sheet")

#视图和布局

API	用途
`View(frame=...)`	所有 ui 组件的基类
`view.frame`	`(x, y, width, height)`
`view.flex`	Pythonista 风格自动伸缩规则
`view.add_subview(child)`	添加子视图
`view.remove_from_superview()`	从父视图移除
`view.present(style="sheet")`	展示视图
`view.close()`	关闭视图
`view.layout()`	子类中重写，处理尺寸变化
`view.draw()`	子类中重写，自定义绘制

#常用控件

API	用途
`Button(frame=..., title=...)`	按钮，回调用 `button.action = func`
`Label(frame=..., text=...)`	文本标签
`TextField(frame=..., placeholder=...)`	单行输入
`TextView(frame=..., text=...)`	多行输入
`ImageView(frame=...)`	图片显示
`WebView(frame=...)`	网页显示
`TableView(frame=...)`	表格列表
`Switch(frame=...)`	开关
`Slider(frame=...)`	滑块
`SegmentedControl(frame=...)`	分段控件
`DatePicker(frame=...)`	日期选择
`ProgressView(frame=...)`	进度条
`NavigationView(view)`	命令式导航容器
`ScrollView(frame=...)`	滚动容器

#输入回调

ui 的回调通常接收 sender。按钮点击后修改 sender 或其它已保存的视图引用。

python

import ui


def slider_changed(sender):
    label.text = f"{sender.value:.0%}"


view = ui.View(frame=(0, 0, 320, 180))
label = ui.Label(frame=(40, 40, 240, 32), text="50%")
slider = ui.Slider(frame=(40, 88, 240, 32))
slider.value = 0.5
slider.action = slider_changed

view.add_subview(label)
view.add_subview(slider)
view.present("sheet")

#绘图

自定义绘图通过重写 draw()，或使用离屏图片上下文。

python

import ui


class Badge(ui.View):
    def draw(self):
        ui.set_color("#3478F6")
        ui.fill_rect(0, 0, self.width, self.height)
        ui.draw_string(
            "42",
            rect=(0, 10, self.width, 40),
            font=("<system-bold>", 28),
            color="white",
            alignment=ui.ALIGN_CENTER,
        )


badge = Badge(frame=(0, 0, 96, 64))
badge.present("sheet")

#工具函数

API	用途
`parse_color(value)`	解析颜色
`parse_font(value)`	解析字体
`measure_string(text, ...)`	测量文本尺寸
`delay(seconds, func)`	延迟执行
`cancel_delays()`	取消 delay
`in_background(func)`	后台线程装饰器
`animate(animation, duration=...)`	执行动画
`get_screen_size()`	屏幕尺寸
`get_keyboard_frame()`	键盘 frame
`load_view(...)`	加载 `.pyui`
`dump_view(view)`	调试视图树

#失败路径

情况	应该怎么处理
页面空白	确认已创建根 `ui.View`，设置了非零 `frame`，并调用 `present(...)`。
点击无反应	回调要赋函数对象，例如 `button.action = tapped`，不要写成 `tapped()`。
布局错位	检查 `frame`、`flex` 和父视图尺寸；复杂响应式页面优先改用 `appui`。
输入或列表状态难维护	把新页面迁到 `appui.State`、`Form`、`List` 和 `NavigationStack`。

#使用规则

ui 页面必须显式设置 frame 或 flex。
不要把 ui 组件和 appui 组件放进同一棵界面树。
需要系统原生列表、设置、导航和响应式状态时优先用 appui。
回调传函数本身，例如 button.action = tapped，不要写成 button.action = tapped()。

#预期效果

#最小页面

#视图和布局

#常用控件

#输入回调

#绘图

#工具函数

#失败路径

#使用规则

相关文档