dialogs - PythonIDE Docs

阻塞式原生对话框：确认、输入、列表选择、简单表单和日期选择。

边界：调用会阻塞脚本直到用户响应；取消时抛出 KeyboardInterrupt。适合短脚本临时交互；复杂页面、多步骤流程请用 AppUI Form / .sheet / .alert，不要在 AppUI 回调里连续弹多个阻塞对话框。

#模块概览

项	说明
导入	`import dialogs`
适合做什么	脚本开始前问一个值、危险操作确认、少量字段收集
调用时机	放在明确动作后；AppUI 里仅在按钮回调中偶尔使用
推荐顺序	`try` 调用 → 处理返回值 → `except KeyboardInterrupt` 处理取消
取消行为	用户点取消会抛 `KeyboardInterrupt`，不是返回空值

#快速开始

下面脚本依次弹出输入框和列表选择：

python

import dialogs

try:
    name = dialogs.input_alert("名称", placeholder="例如：Ada")
    mode = dialogs.list_dialog("模式", ["快速", "精确"])
    print(name, "→", mode)
except KeyboardInterrupt:
    print("用户取消")

#AppUI 示例

在按钮回调里触发对话框；用 try/except 处理取消，结果写回 State。

python

import appui
import dialogs

state = appui.State(
    message="点击按钮体验对话框",
    last_result="—",
)


def show_confirm():
    try:
        index = dialogs.alert(
            "确认操作",
            "这是一个演示对话框",
            "继续",
            "取消",
        )
        state.batch_update(
            message="用户点了确认" if index == 1 else "用户选了其他按钮",
            last_result=f"alert 返回 {index}",
        )
    except KeyboardInterrupt:
        state.batch_update(message="用户取消", last_result="alert 已取消")


def ask_name():
    try:
        name = dialogs.input_alert("你的名字", placeholder="请输入")
        state.batch_update(
            message=f"你好，{name}",
            last_result=name,
        )
    except KeyboardInterrupt:
        state.batch_update(message="输入已取消", last_result="—")


def pick_color():
    try:
        color = dialogs.list_dialog("选择颜色", ["红色", "绿色", "蓝色"])
        state.batch_update(
            message=f"已选择 {color}",
            last_result=color,
        )
    except KeyboardInterrupt:
        state.batch_update(message="选择已取消", last_result="—")


def show_hud():
    dialogs.hud_alert("已保存！", duration=1.2)
    state.message = "HUD 提示已显示"


def body():
    return appui.NavigationStack(
        appui.Form([
            appui.Section("对话框", [
                appui.Button("确认框", action=show_confirm)
                .button_style("bordered_prominent"),
                appui.Button("输入框", action=ask_name),
                appui.Button("列表选择", action=pick_color),
                appui.Button("HUD 提示", action=show_hud),
            ]),
            appui.Section("结果", [
                appui.LabeledContent("状态", value=state.message),
                appui.LabeledContent("返回值", value=state.last_result),
            ]),
        ]).navigation_title("对话框")
    )


appui.run(body, state=state)

#API 参考

#速查

API	作用
`alert(title, message, *buttons)`	确认框 → 按钮序号（1-based）
`input_alert(title, ...)`	文本输入 → `str`
`list_dialog(title, items, multiple=False)`	列表选择
`form_dialog(title, fields)`	简单表单 → `dict`
`date_dialog(title, mode="date")`	日期/时间选择 → ISO 字符串
`hud_alert(message, duration=1.0)`	短暂 HUD 提示

#选择与确认

alert(title, message="", *button_titles, hide_cancel_button=False) — 原生确认框。

python

if dialogs.alert("删除？", "不可撤销", "删除", "取消") == 1:
    do_delete()

返回按下的按钮索引（1-based）。取消抛 KeyboardInterrupt。

input_alert(title, message="", placeholder="", secure=False, default_text="") — 文本输入；secure=True 为密码模式。

python

name = dialogs.input_alert("API Key", secure=True, placeholder="sk-...")

#列表与表单

list_dialog(title, items, multiple=False) — 单选返回 str，多选返回 list。

python

color = dialogs.list_dialog("颜色", ["红", "绿", "蓝"])
tags = dialogs.list_dialog("标签", ["A", "B", "C"], multiple=True)

form_dialog(title, fields) — 一次收集多个字段：

python

result = dialogs.form_dialog("新建笔记", [
    {"type": "text", "key": "title", "title": "标题", "value": "每日笔记"},
    {"type": "switch", "key": "pinned", "title": "置顶", "value": True},
])
print(result["title"], result["pinned"])

字段 type 支持：text、password、number、email、url、switch。

#日期与 HUD

date_dialog(title="", mode="date") — mode 可选 date / time / datetime，返回 ISO 8601 字符串。

python

when = dialogs.date_dialog("选择日期", mode="date")

hud_alert(message, duration=1.0) — 自动消失的成功提示，不阻塞。

python

dialogs.hud_alert("已保存！", duration=1.5)

#选型

需求	API
简单确认	`alert`
单个文本输入	`input_alert`
从几个选项中选	`list_dialog`
一次收集少量字段	`form_dialog`
日期或时间	`date_dialog`
短暂成功提示	`hud_alert`

#常见错误

错误写法	后果	修正
不捕获 `KeyboardInterrupt`	取消时脚本中断	`try/except KeyboardInterrupt`
用 `form_dialog` 做复杂动态表单	难维护	改用 AppUI `Form`
AppUI 回调里连弹多个对话框	页面卡顿	合并流程或用 sheet
假设取消返回空字符串	逻辑错误	取消会抛异常

#相关文档

文档	用途
appui 列表与表单	AppUI 内建表单与交互
haptics	操作成功后的触觉反馈
原生能力入口	MiniApp 场景配方

#预期效果

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