`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 模块。

函数清单

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

函数文档

文本输入

参数:

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 of YYYY-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 returns None. 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

返回:

用户输入的值

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

参数:

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选项
other_html_attrs (- label, validate, name, value, onchange, placeholder, required, readonly, help_text,) – 与 input 输入函数的同名参数含义一致

返回:

用户输入的文本

下拉选择框

默认单选，可以通过设置 multiple 参数来允许多选

参数:

options (list) –
可选项列表。列表项的可用形式有：
- dict:
```
{
    "label":(str) 选项标签,
    "value":(object) 选项值,
    "selected":(bool, optional) 是否默认选中,
    "disabled":(bool, optional) 是否禁止选中
}
```
- 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) – 是否至少选择一项，仅在 multiple=True 时可用
native (bool) – Using browser’s native select component rather than bootstrap-select. This is the default behavior.
other_html_attrs (- label, validate, name, onchange, help_text,) – 与 input 输入函数的同名参数含义一致

返回:

如果 multiple=True 时，返回用户选中的 options 中的值的列表；否则，返回用户选中的 options 中的值

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

参数:

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

返回:

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

单选选项

参数:

options (list) – 可选项列表。格式与同 select() 函数的 options 参数
inline (bool) – 是否将选项显示在一行上。默认每个选项单独占一行
value (str) – 可选项列表。格式与同 select() 函数的 options 参数
required (bool) – 是否一定要选择一项（默认条件下用户可以不选择任何选项）
other_html_attrs (- label, validate, name, onchange, help_text,) – 与 input 输入函数的同名参数含义一致

返回:

用户选中的选项的值, 如果用户没有选任何值，返回 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 .
help_text (- label, name,) – 与 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()  

文件上传

参数:

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
other_html_attrs (- label, name, help_text,) – 与 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'])

滑块输入

参数:

value (int/float) – 滑块的初始值
min_value (int/float) – 滑块最小允许的值
max_value (int/float) – 滑块最大允许的值
step (int) – 滑动的步长。仅当 value、 min_value 和 max_value 全为int时有效
other_html_attrs (- label, name, validate, onchange, required, help_text,) – 与 input 输入函数的同名参数含义一致

Return int/float:

若 value, min_value 和 max_value 中含有float类型，则返回值为float，否则返回值为int类型

pywebio.input.input_group(label: str = '', inputs: List | None = None, validate: Callable[[Dict], Tuple[str, str] | None] | None = 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: str | None = 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'),
])

pywebio.input — 输入模块

函数清单

函数文档

`pywebio.input` — 输入模块