`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 参数)

函数清单¶

函数	简介
`input`	文本输入
`textarea`	多行文本输入
`select`	下拉选择框
`checkbox`	勾选选项
`radio`	单选选项
`actions`	按钮选项
`file_upload`	文件上传
`input_group`	输入组

函数文档¶

pywebio.input.input(label='', type='text', *, validate=None, name=None, value=None, action=None, placeholder=None, required=None, readonly=None, datalist=None, help_text=None, **other_html_attrs)[源代码]¶

文本输入

参数

label (str) – 输入框标签
type (str) –
输入类型. 可使用的常量：TEXT , NUMBER , FLOAT , PASSWORD , URL , DATE , TIME

其中 DATE , TIME 类型在某些浏览器上不被支持，详情见 https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#Browser_compatibility
validate (Callable) –
输入值校验函数. 如果提供，当用户输入完毕或提交表单后校验函数将被调用. validate 接收输入值作为参数，当输入值有效时，返回 None ，当输入值无效时，返回错误提示字符串. 比如:
```
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 – 输入框的名字. 与 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 可以为协程函数.
placeholder (str) – 输入框的提示内容。提示内容会在输入框未输入值时以浅色字体显示在输入框中
required (bool) – 当前输入是否为必填项
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='', *, rows=6, code=None, maxlength=None, minlength=None, validate=None, name=None, value=None, placeholder=None, required=None, readonly=None, help_text=None, **other_html_attrs)[源代码]¶

文本输入域（多行文本输入）

参数

rows (int) – 输入文本的行数（显示的高度）。输入的文本超出设定值时会显示滚动条
maxlength (int) – 允许用户输入的最大字符长度 (Unicode) 。未指定表示无限长度
minlength (int) – 允许用户输入的最小字符长度(Unicode)
code (dict) –
通过提供 Codemirror 参数让文本输入域具有代码编辑器样式:
```
res = textarea('Text area', code={
    'mode': "python",
    'theme': 'darcula'
})
```
更多配置可以参考 https://codemirror.net/doc/manual.html#config
label, validate, name, value, placeholder, required, readonly, help_text, other_html_attrs (-) – 与 input 输入函数的同名参数含义一致

返回

用户输入的文本

pywebio.input.select(label='', options=None, *, multiple=None, validate=None, name=None, value=None, required=None, help_text=None, **other_html_attrs)[源代码]¶

下拉选择框。

默认单选，设置 multiple 参数后，可以多选。但都至少要选择一个选项。

参数

options (list) –
可选项列表。列表项的可用形式有：
- dict: {label:选项标签, value: 选项值, [selected:是否默认选中,] [disabled:是否禁止选中]}
- tuple or list: (label, value, [selected,] [disabled])
- 单值: 此时label和value使用相同的值
注意：
1. options 中的 value 可以为任意可Json序列化对象
2. 若 multiple 选项不为 True 则可选项列表最多仅能有一项的 selected 为 True。
multiple (bool) – 是否可以多选. 默认单选
value (list or str) – 下拉选择框初始选中项的值。当 multiple=True 时， value 需为list，否则为单个选项的值。你也可以通过设置 options 列表项中的 selected 字段来设置默认选中选项。最终选中项为 value 参数和 options 中设置的并集。
required (bool) – 是否至少选择一项
label, validate, name, help_text, other_html_attrs (-) – 与 input 输入函数的同名参数含义一致

返回

如果 multiple=True 时，返回用户选中的 options 中的值的列表；不设置 multiple 时，返回用户选中的 options 中的值

pywebio.input.checkbox(label='', options=None, *, inline=None, validate=None, name=None, value=None, help_text=None, **other_html_attrs)[源代码]¶

勾选选项。可以多选，也可以不选。

参数

options (list) – 可选项列表。格式与 select 函数的 options 参数含义一致
inline (bool) – 是否将选项显示在一行上。默认每个选项单独占一行
value (list) – 勾选选项初始选中项。为选项值的列表。你也可以通过设置 options 列表项中的 selected 字段来设置默认选中选项。
label, validate, name, help_text, other_html_attrs (-) – 与 input 输入函数的同名参数含义一致

返回

用户选中的 options 中的值的列表。当用户没有勾选任何选项时，返回空列表

pywebio.input.radio(label='', options=None, *, inline=None, validate=None, name=None, value=None, required=None, help_text=None, **other_html_attrs)[源代码]¶

单选选项

参数

options (list) – 可选项列表。格式与 select 函数的 options 参数含义一致
inline (bool) – 是否将选项显示在一行上。默认每个选项单独占一行
value (str) – 单选选项初始选中项的值。你也可以通过设置 options 列表项中的 selected 字段来设置默认选中选项。
required (bool) – 是否至少选择一项
label, validate, name, help_text, other_html_attrs (-) – 与 input 输入函数的同名参数含义一致

返回

用户选中的选项的值

pywebio.input.actions(label='', buttons=None, name=None, help_text=None)[源代码]¶

按钮选项。

在表单上显示为一组按钮，用户点击按钮后依据按钮类型的不同有不同的表现。

当 actions() 作为 input_group() 的 inputs 中最后一个输入项，并且输入项中含有 type=submit 的按钮时，表单默认的提交按钮会被当前 actions() 替换

参数

buttons (list) –
选项列表。列表项的可用形式有：
- dict: {label:选项标签, value:选项值, [type: 按钮类型], [disabled:是否禁止选择]} . 若 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() 调用也不会返回
label, name, help_text (-) – 与 input 输入函数的同名参数含义一致

返回

若用户点击点击 type=submit 按钮进行表单提交，返回用户点击的按钮的值；若用户点击点击 type=callback 按钮，返回值通过回调函数设置；若用户点击 type=cancel 按钮或通过其它方式提交表单，则返回 None

actions使用场景

实现简单的选择操作:

confirm = actions('确认删除文件？', ['确认', '取消'], help_text='文件删除后不可恢复')
if 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': '保存', 'value': 'save'},
        {'label': '保存并添加下一个', 'value': 'save_and_continue'},
        {'label': '重置', 'type': 'reset'},
        {'label': '取消', 'type': 'cancel'},
    ], 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='', accept=None, name=None, placeholder='Choose file', multiple=False, max_size=0, max_total_size=0, required=None, help_text=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，表示不限制上传文件的大小。

可以为数字表示的字节数，或以 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 启动PyWebIO应用时，可通过 websocket_max_message_size 参数设置允许上传的最大文件大小

pywebio.input.input_group(label='', inputs=None, validate=None, cancelable=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', '名字太长！')
    if data['age'] <= 0:
        return ('age', '年龄不能为负数！')

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 则会在表单底部显示一个”取消”按钮。注意：若 inputs 中最后一项输入为 actions() ，则忽略 cancelable
返回: 若用户取消表单，返回 None ,否则返回一个 dict , 其键为输入项的 name 值，字典值为输入项的值

pywebio.input — 输入模块¶

函数清单¶

函数文档¶

`pywebio.input` — 输入模块¶