pywebio.input
— 输入模块¶
本模块提供了一系列函数来从浏览器接收用户不同的形式的输入
输入函数大致分为两类,一类是单项输入:
name = input("What's your name")
print("Your name is %s" % name)
另一类是使用 input_group
的输入组:
info = input_group("User info",[
input('Input your name', name='name'),
input('Input your age', name='age', type=NUMBER)
])
print(info['name'], info['age'])
输入组中需要在每一项输入函数中提供 name
参数来用于在结果中标识不同输入项.
注解
PyWebIO 根据是否在输入函数中传入 name
参数来判断输入函数是在 input_group
中还是被单独调用。所以当你想要单独调用一个输入函数时,请不要设置 name
参数;而在 input_group
中调用输入函数时,务必提供 name
参数。
输入默认可以为空,如果需要用户必须提供值,则需要在输入函数中传入 required=True
(部分输入函数不支持 required
参数)
本模块中的输入函数都是阻塞式的,输入表单会在成功提交后销毁。如果你想让表单可以一直显示在页面上并可以持续性接收输入,你可以考虑使用 pin 模块。
函数清单¶
函数 |
简介 |
文本输入 |
|
多行文本输入 |
|
下拉选择框 |
|
勾选选项 |
|
单选选项 |
|
滑块输入 |
|
按钮选项 |
|
文件上传 |
|
输入组 |
|
更新输入项 |
函数文档¶
-
pywebio.input.
input
(label: str = '', type: str = 'text', *, validate: Optional[Callable[[Any], Optional[str]]] = None, name: Optional[str] = None, value: Optional[Union[str, int]] = None, action: Optional[Tuple[str, Callable[[Callable], None]]] = None, onchange: Optional[Callable[[Any], None]] = None, placeholder: Optional[str] = None, required: Optional[bool] = None, readonly: Optional[bool] = None, datalist: Optional[List[str]] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 文本输入
- 参数
label (str) – 输入框标签
type (str) –
Input type. Currently, supported types are:
TEXT
,NUMBER
,FLOAT
,PASSWORD
,URL
,DATE
,TIME
,DATETIME
,COLOR
The value of
DATE
,TIME
,DATETIME
type is a string in the format ofYYYY-MM-DD
,HH:MM:SS
,YYYY-MM-DDTHH:MM
respectively (%Y-%m-%d
,%H:%M:%S
,%Y-%m-%dT%H:%M
in python strptime() format).validate (callable) –
输入值校验函数。 如果提供,当用户输入完毕或提交表单后校验函数将被调用。
validate
receives the input value as a parameter. When the input value is valid, it returnsNone
. When the input value is invalid, it returns an error message string.For example:
def check_age(age): if age>30: return 'Too old' elif age<10: return 'Too young' input('Input your age', type=NUMBER, validate=check_age)
name (str) – 输入框的名字。与
input_group
配合使用,用于在输入组的结果中标识不同输入项。 在单个输入中,不可以设置该参数!value (str) – 输入框的初始值
action (tuple(label:str, callback:callable)) –
在输入框右侧显示一个按钮,用户可通过点击按钮为输入框设置值。
label
为按钮的显示文本,callback
为按钮点击的回调函数。回调函数需要接收一个
set_value
位置参数,set_value
是一个可调用对象,接受单参数调用和双参数调用。单参数调用时,签名为
set_value(value:str)
,调用set_value即可将表单项的值设置为传入的value
参数。双参数调用时,签名为
set_value(value:any, label:str)
,其中:value
参数为最终输入项的返回值,可以为任意Python对象,并不会传递给用户浏览器label
参数用于显示在用户表单项上
使用双参数调用
set_value
后,用户表单项会变为只读状态。双参数调用的使用场景为:表单项的值通过回调动态生成,同时希望用户表单显示的和实际提交的数据不同(例如表单项上可以显示更人性化的内容,而表单项的值则可以保存更方便被处理的对象)
使用示例
import time def set_now_ts(set_value): set_value(int(time.time())) ts = input('Timestamp', type=NUMBER, action=('Now', set_now_ts)) from datetime import date,timedelta def select_date(set_value): with popup('Select Date'): put_buttons(['Today'], onclick=[lambda: set_value(date.today(), 'Today')]) put_buttons(['Yesterday'], onclick=[lambda: set_value(date.today() - timedelta(days=1), 'Yesterday')]) d = input('Date', action=('Select', select_date), readonly=True) put_text(type(d), d)
Note: 当使用 基于协程的会话实现 时,回调函数
callback
可以为协程函数.onchange (callable) –
A callback function which will be called when user change the value of this input field.
onchange
回调函数接收一个参数——输入项改变后的值。onchange
的典型用途是配合input_update()
来在一个表单中实现相互依赖的输入。placeholder (str) – 输入框的提示内容。提示内容会在输入框未输入值时以浅色字体显示在输入框中
required (bool) – 当前输入是否为必填项,默认为
False
readonly (bool) – 输入框是否为只读
datalist (list) – 输入建议内容列表,在页面上的显示效果为下拉候选列表,用户可以忽略建议内容列表而输入其他内容。仅当输入类型
type
为TEXT
时可用help_text (str) – 输入框的帮助文本。帮助文本会以小号字体显示在输入框下方
other_html_attrs – 在输入框上附加的额外html属性。参考: https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#%E5%B1%9E%E6%80%A7
- 返回
用户输入的值
-
pywebio.input.
textarea
(label: str = '', *, rows: int = 6, code: Optional[Union[bool, Dict]] = None, maxlength: Optional[int] = None, minlength: Optional[int] = None, validate: Optional[Callable[[Any], Optional[str]]] = None, name: Optional[str] = None, value: Optional[str] = None, onchange: Optional[Callable[[Any], None]] = None, placeholder: Optional[str] = None, required: Optional[bool] = None, readonly: Optional[bool] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 文本输入域(多行文本输入)
- 参数
rows (int) – 输入框的最多可显示的文本的行数,内容超出时会显示滚动条
maxlength (int) – 最大允许用户输入的字符长度 (Unicode) 。未指定表示无限长度
minlength (int) – 最少需要用户输入的字符长度(Unicode)
code (dict/bool) –
通过提供 Codemirror 参数让文本输入域具有代码编辑器样式:
res = textarea('Text area', code={ 'mode': "python", 'theme': 'darcula' })
可以直接使用
code={}
或code=True
开启代码编辑样式。代码编辑区支持使用Esc
或F11
切换全屏。这里 列举了一些常用的Codemirror选项
label, validate, name, value, onchange, placeholder, required, readonly, help_text, other_html_attrs (-) – 与
input
输入函数的同名参数含义一致
- 返回
用户输入的文本
-
pywebio.input.
select
(label: str = '', options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, multiple: Optional[bool] = None, validate: Optional[Callable[[Any], Optional[str]]] = None, name: Optional[str] = None, value: Optional[Union[List, str]] = None, onchange: Optional[Callable[[Any], None]] = None, native: bool = True, required: Optional[bool] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 下拉选择框
默认单选,可以通过设置
multiple
参数来允许多选- 参数
options (list) –
可选项列表。列表项的可用形式有:
dict:
{ "label":(str) 选项标签, "value":(object) 选项值, "selected":(bool, optional) 是否默认选中, "disabled":(bool, optional) 是否禁止选中 }
tuple or list:
(label, value, [selected,] [disabled])
单值: 此时label和value使用相同的值
注意:
options
中的value
可以为任意可JSON序列化对象若
multiple
选项不为True
则可选项列表最多仅能有一项的selected
为True
。
multiple (bool) – 是否可以多选. 默认单选
value (list or str) – 下拉选择框初始选中项的值。当
multiple=True
时,value
需为list,否则为单个选项的值。 你也可以通过设置options
列表项中的selected
字段来设置默认选中选项。 最终选中项为value
参数和options
中设置的并集。required (bool) – 是否至少选择一项,仅在
multiple=True
时可用native (bool) – Using browser’s native select component rather than bootstrap-select. This is the default behavior.
label, validate, name, onchange, help_text, other_html_attrs (-) – 与
input
输入函数的同名参数含义一致
- 返回
如果
multiple=True
时,返回用户选中的options
中的值的列表;否则,返回用户选中的options
中的值
-
pywebio.input.
checkbox
(label: str = '', options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, inline: Optional[bool] = None, validate: Optional[Callable[[Any], Optional[str]]] = None, name: Optional[str] = None, value: Optional[List] = None, onchange: Optional[Callable[[Any], None]] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 勾选选项。可以多选,也可以不选。
- 参数
- 返回
用户选中的 options 中的值的列表。当用户没有勾选任何选项时,返回空列表
-
pywebio.input.
radio
(label: str = '', options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, inline: Optional[bool] = None, validate: Optional[Callable[[Any], Optional[str]]] = None, name: Optional[str] = None, value: Optional[str] = None, onchange: Optional[Callable[[Any], None]] = None, required: Optional[bool] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 单选选项
- 参数
- 返回
用户选中的选项的值, 如果用户没有选任何值,返回
None
-
pywebio.input.
actions
(label: str = '', buttons: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, name: Optional[str] = None, help_text: Optional[str] = None)[源代码]¶ 按钮选项
在表单上显示为一组按钮,用户点击按钮后依据按钮类型的不同有不同的表现。
- 参数
buttons (list) –
按钮列表。列表项的可用形式有:
dict:
{ "label":(str) 按钮标签, "value":(object) 按钮值, "type":(str, optional) 按钮类型, "disabled":(bool, optional) 是否禁止选择, "color":(str, optional) 按钮颜色 }
若
type='reset'/'cancel'
或disabled=True
可省略value
tuple or list:
(label, value, [type], [disabled])
单值: 此时label和value使用相同的值
其中,
value
可以为任意可JSON序列化的对象。type
可选值为:'submit'
: 点击按钮后,立即将整个表单提交,最终表单中本项的值为被点击按钮的value
值。'submit'
为type
的默认值'cancel'
: 取消输入。点击按钮后,立即将整个表单提交,表单值返回None
'reset'
: 点击按钮后,将整个表单重置,输入项将变为初始状态。 注意:点击type=reset
的按钮后,并不会提交表单,actions()
调用也不会返回
按钮的
color
值可以为:primary
,secondary
,success
,danger
,warning
,info
,light
,dark
.label, name, help_text (-) – 与
input
输入函数的同名参数含义一致
- 返回
若用户点击点击
type=submit
按钮进行表单提交,返回用户点击的按钮的值; 若用户点击type=cancel
按钮或通过其它方式提交表单,则返回None
当
actions()
作为input_group()
中的最后一个输入项、并且含有type='submit'
的按钮时,input_group()
表单默认的提交按钮会被当前actions()
替换actions() 的使用场景
实现简单的选择操作:
confirm = actions('Confirm to delete file?', ['confirm', 'cancel'], help_text='Unrecoverable after file deletion') if confirm=='confirm': ...
相比于其他输入项,使用
actions()
用户只需要点击一次就可完成提交。替换默认的提交按钮:
info = input_group('Add user', [ input('username', type=TEXT, name='username', required=True), input('password', type=PASSWORD, name='password', required=True), actions('actions', [ {'label': 'Save', 'value': 'save'}, {'label': 'Save and add next', 'value': 'save_and_continue'}, {'label': 'Reset', 'type': 'reset', 'color': 'warning'}, {'label': 'Cancel', 'type': 'cancel', 'color': 'danger'}, ], name='action', help_text='actions'), ]) put_code('info = ' + json.dumps(info, indent=4)) if info is not None: save_user(info['username'], info['password']) if info['action'] == 'save_and_continue': add_next()
-
pywebio.input.
file_upload
(label: str = '', accept: Optional[Union[List, str]] = None, name: Optional[str] = None, placeholder: str = 'Choose file', multiple: bool = False, max_size: Union[int, str] = 0, max_total_size: Union[int, str] = 0, required: Optional[bool] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 文件上传
- 参数
accept (str or list) –
单值或列表, 表示可接受的文件类型。文件类型的可用形式有:
以
.
字符开始的文件扩展名(例如:.jpg, .png, .doc
)。 注意:截至本文档编写之时,微信内置浏览器还不支持这种语法一个有效的 MIME 类型。 例如:
application/pdf
、audio/*
表示音频文件、video/*
表示视频文件、image/*
表示图片文件。 参考 https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types
placeholder (str) – 未上传文件时,文件上传框内显示的文本
multiple (bool) – 是否允许多文件上传,默认关闭
max_size (int/str) –
- 单个文件的最大大小,超过限制将会禁止上传。
默认为0,表示不限制上传文件的大小。
max_size
值可以为数字表示的字节数,或以K
/M
/G
结尾表示的字符串(分别表示 千字节、兆字节、吉字节,大小写不敏感)。例如:max_size=500
,max_size='40K'
,max_size='3M'
max_total_size (int/str) – 所有文件的最大大小,超过限制将会禁止上传。仅在
multiple=True
时可用,默认不限制上传文件的大小。 格式同max_size
参数required (bool) – 是否必须要上传文件。默认为
False
label, name, help_text, other_html_attrs (-) – 与
input
输入函数的同名参数含义一致
- 返回
multiple=False
时(默认),返回dict:{ 'filename': 文件名, 'content':文件二进制数据(bytes object), 'mime_type': 文件的MIME类型, 'last_modified': 文件上次修改时间(时间戳) }
若用户没有上传文件,返回
None
。multiple=True
时,返回列表,列表项格式同上文multiple=False
时的返回值;若用户没有上传文件,返回空列表。
注解
若上传大文件请留意Web框架的文件上传大小限制设置。在使用
start_server()
或path_deploy()
启动PyWebIO应用时, 可通过max_payload_size
参数设置Web框架允许上传的最大文件大小# Upload a file and save to server f = input.file_upload("Upload a file") open('asset/'+f['filename'], 'wb').write(f['content']) imgs = file_upload("Select some pictures:", accept="image/*", multiple=True) for img in imgs: put_image(img['content'])
-
pywebio.input.
slider
(label: str = '', *, name: Optional[str] = None, value: Union[int, float] = 0, min_value: Union[int, float] = 0, max_value: Union[int, float] = 100, step: int = 1, validate: Optional[Callable[[Any], Optional[str]]] = None, onchange: Optional[Callable[[Any], None]] = None, required: Optional[bool] = None, help_text: Optional[str] = None, **other_html_attrs)[源代码]¶ 滑块输入
- 参数
value (int/float) – 滑块的初始值
min_value (int/float) – 滑块最小允许的值
max_value (int/float) – 滑块最大允许的值
step (int) – 滑动的步长。仅当
value
、min_value
和max_value
全为int时有效label, name, validate, onchange, required, help_text, other_html_attrs (-) – 与
input
输入函数的同名参数含义一致
- Return int/float
若
value
,min_value
和max_value
中含有float类型,则返回值为float,否则返回值为int类型
-
pywebio.input.
input_group
(label: str = '', inputs: Optional[List] = None, validate: Optional[Callable[[Dict], Optional[Tuple[str, str]]]] = None, cancelable: bool = False)[源代码]¶ 输入组。向页面上展示一组输入
- 参数
label (str) – 输入组标签
inputs (list) – 输入项列表。列表的内容为对单项输入函数的调用,并在单项输入函数中传入
name
参数。validate (callable) –
输入组校验函数。
函数签名:
callback(data) -> (name, error_msg)
validate
接收整个表单的值为参数,当校验表单值有效时,返回None
,当某项输入值无效时,返回出错输入项的name
值和错误提示. 比如:
def check_form(data): if len(data['name']) > 6: return ('name', 'Name to long!') if data['age'] <= 0: return ('age', 'Age cannot be negative!') data = input_group("Basic info",[ input('Input your name', name='name'), input('Repeat your age', name='age', type=NUMBER) ], validate=check_form) put_text(data['name'], data['age'])
- 参数
cancelable (bool) –
表单是否可以取消。若
cancelable=True
则会在表单底部显示一个“取消”按钮,默认为False
。注意:若
inputs
中最后一项输入为actions()
,则忽略cancelable
- 返回
若用户取消表单,返回
None
,否则返回一个dict
, 其键为输入项的name
值,字典值为输入项的值
-
pywebio.input.
input_update
(name: Optional[str] = None, **spec)[源代码]¶ 更新输入项的属性。本函数仅能在输入函数的
onchange
回调中使用。- 参数
name (str) – 目标输入项的
name
。可选,默认为当前触发onchange
回调的输入项spec – 需要更新的输入项参数。注意一下参数无法被更新:
type
,name
,validate
,action
,code
,onchange
,multiple
一个具有依赖关系的输入项的示例:
country2city = { 'China': ['Beijing', 'Shanghai', 'Hong Kong'], 'USA': ['New York', 'Los Angeles', 'San Francisco'], } countries = list(country2city.keys()) location = input_group("Select a location", [ select('Country', options=countries, name='country', onchange=lambda c: input_update('city', options=country2city[c])), select('City', options=country2city[countries[0]], name='city'), ])