dialogs — 易于使用的UI对话框
dialogs
模块提供了易于使用的GUI对话框,用于在iOS上进行简单的数据输入。它主要构建在ui
模块之上,虽然不如ui
直接使用灵活,但使用起来却容易得多,并且在大多数情况下只需要很少的代码行数。
概述
该模块中的大多数功能都会显示一个对话框,并返回用户的输入。支持以下类型的对话框:
- 文本对话框显示多行文本输入区域。字体和某些键盘属性(自动更正…)是可自定义的。(请参阅
text_dialog()
) - 列表对话框显示项目列表,允许选择其中一个或多个。(请参阅
list_dialog()
) - 编辑列表对话框同样显示了一个项目列表,但是用户可以重新排列列表,而不是选择一个项目,并且可以从列表中删除项目。(请参阅
edit_list_dialog()
) - 日期/时间对话框提供了一个日期选择器 – 有多种用于选择日期,时间或两者的变体,还有一种用于选择倒数/持续时间的模式,例如用于计时器。(参见
date_dialog()
,time_dialog()
,datetime_dialog()
,duration_dialog()
) - 表单对话框显示可自定义数据输入框的列表。这些输入框可以包含开关(用于布尔值),文本/电子邮件/密码输入框(用于字符串),日期选择器和选中标记(用于多个选择列表)。这是最灵活的对话框类型,但它也需要最多的配置(请参阅参考资料
form_dialog()
)
对话框函数
dialogs.list_dialog(title=’’, items=None, multiple=False)
列出项目并返回选择的项目。取消对话框后,将返回None
。items
列表可以包含任何可以转换为字符串的对象类型。想更好地控制每个项目在列表中的显示方式,您还可以使用词典列表(有关详细信息,请参见ui.ListDataSource.items
)。
dialogs.edit_list_dialog(title=’’, items=None, move=True, delete=True)
显示可以由用户编辑的项目列表。默认情况下,用户既可以重新排列列表又可以删除项目。可以使用move
和delete
参数控制此行为。
返回值是修改后的项目列表;如果取消了对话框,则返回None
。
dialogs.form_dialog(title=’’, fields=None, sections=None)
显示一个表单对话框,类似于许多设置界面。
对话框中的每个输入框均由字典配置。如果只有一个输入框区域,则可以将这些输入框字典的列表作为fields
参数传递。如果应该有多个区域,则每个区域都由一个元组表示(通常是一个包含该节标题及其输入框列表的2元组;可选的第三项可以包含该区域的页脚文本)。
该函数的返回值是每个输入框的值的字典(如果取消了对话框,则为None
)。
输入框字典应包含以下键:
- ‘
type
‘ - (必需)输入框的类型,这可以是’switch
‘,’text
‘,’url
‘,’email
‘,’password
‘,’number
‘, ‘check
‘,’datetime
‘,’date
‘,或’time
‘ - ‘
key
‘ – 表单返回值中此输入框的关键字 - ‘
value
‘ – 输入框的初始值(对于文本/ URL /电子邮件/密码/数字输入框,应为字符串,对于开关输入框为布尔值(True
/False
),对于日期时间输入框为datetime
对象) - ‘
title
‘ – 该输入框的名称/标签
’type
‘是唯一必需的键。如果’key
‘不存在,则使用’title
‘代替。如果两者都缺失,则在返回的字典中对输入框进行顺序编号。
所有输入框类型的可选键:
- ‘
tint_color
‘ – 输入框的颜色(此效果取决于输入框的类型) - ‘
icon
‘– 内置图像或ui.Image
对象的名称
文本/ URL /电子邮件/密码/数字输入框的可选键:
- ‘
placeholder
‘ – 输入框为空时显示的文本 - ‘
autocorrection
‘ – 是否应为此输入框启用自动校正(True
/False
) - ‘
autocapitalization
‘ – 文本输入框的自动大写行为,有关可能的值,请参见ui.TextField.autocapitalization_type
dialogs.text_dialog(title=’’, text=’’, font=(‘
显示多行文本编辑器表。
编辑器的行为可以用autocorrection
、 autocapitalization
和 spellchecking
参数进行自定义。text
参数控制在编辑器中显示的初始文本。
编辑后的文本以字符串形式返回(如果取消对话框,则返回None
)。
dialogs.date_dialog(title=’’)
显示一个日期选择器对话框,返回值是一个datetime.datetime
对象。
dialogs.time_dialog(title=’’)
显示一个时间选择器对话框,返回值是一个datetime.datetime
对象。
dialogs.datetime_dialog(title=’’)
显示日期/时间选择器对话框,返回值为一个datetime.datetime
对象。
dialogs.duration_dialog(title=’’)
显示一个持续时间选择器对话框(例如用于倒数计时器),返回值为以秒为单位的选定持续时间(例如60.0作为1分钟)。
共享
dialogs.share_image(img)
显示给定图像的系统共享对话框(可以是ui.Image
或PIL Image
)。
dialogs.share_text(text)
显示给定字符串的系统共享对话框。
dialogs.share_url(url)
显示给定URL的系统共享对话框。
导入文件
dialogs.pick_document(types=[‘public.data’])
显示系统的文档选择器以导入文件,并返回文件的路径(如果取消对话框,则返回None
)。
types
指定应该在文档选择器中选择的通用类型标识符(UTI)。默认值(['public.data']
)使所有常规文件均可选。Apple的《统一类型标识符参考》中提供了系统定义的UTI的列表。
返回值是一个临时文件。您可以直接阅读它,但是要保留永久副本,必须将其移到其他地方。
提醒函数
为了方便起见,这些功能是从console
模块导入的。
dialogs.alert()
请参见console.alert()
dialogs.input_alert()
请参见console.input_alert()
dialogs.login_alert()
请参见console.login_alert()
dialogs.password_alert()
请参见console.password_alert()
dialogs.hud_alert()
请参见console.hud_alert()