pywebio.pin
— 持续性输入¶
pin == Persistent input == Pinning input widget to the page
Overview¶
我们已经知道,PyWebIO中的输入函数是阻塞式的,输入表单会在成功提交后被销毁。在大多数场景下,使用这种方式接收用户输入已经够用了。但在一些场景下,你或许希望输入表单在提交后不消失,并且可以继续接收输入。
所以,PyWebIO提供了 pin
模块来实现持续性输入。
pin
模块主要有3部分内容:
首先, pin
模块提供了一些 pin 组件(widgets)。Pin 组件和 pywebio.output
模块中的输出组件并没有什么不同,只不过它还可以接收输入。
以下代码输出了一个最基本的文本框pin组件:
put_input('input', label='This is a input widget')
实际上, pin 组件函数的调用方式和输出函数是一致的,你可以将其作为组合输出的一部分, 也可以将其输出到某个scope中:
put_row([
put_input('input'),
put_select('select', options=['A', 'B', 'C'])
])
with use_scope('search-area'):
put_input('search', placeholder='Search')
然后,你可以使用 pin
对象来获取pin组件的值:
put_input('pin_name')
put_buttons(['Get Pin Value'], lambda _: put_text(pin.pin_name))
Pin组件函数的第一个参数为pin组件的 name
。你可以使用 pin
对象的同名属性来获取对应pin组件的当前值。
另外, pin
对象同样支持以索引的方式获取pin组件的值,即:
pin['pin_name'] == pin.pin_name
Pin模块中还有两个有用的函数: pin_wait_change()
和 pin_update()
。
由于pin组件输出函数是非阻塞的, 所以使用 pin_wait_change()
来等待一组pin组件的值发生变化,它是一个阻塞式函数。
pin_update()
可以用来更新pin组件的输出属性。
Pin widgets¶
Each pin widget function corresponds to an input function of input module.
Pin组件函数支持大多数对应的输入函数的参数。这里列举了两者之间的一些不同:
Pin组件函数的第一个参数始终是Pin组件的
name
,且当输出了同名的pin组件时,旧的pin组件会不可用。Pin functions don’t support the
on_change
andvalidate
callbacks, and therequired
parameter. (There is apin_on_change()
function as an alternative toon_change
)Pin组件函数多了用于输出控制的
scope
和position
参数。
-
pywebio.pin.
put_input
(name: str, type: str = 'text', *, label: str = '', value: Optional[str] = None, placeholder: Optional[str] = None, readonly: Optional[bool] = None, datalist: Optional[List[str]] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个文本输入组件。参见
pywebio.input.input()
-
pywebio.pin.
put_textarea
(name: str, *, label: str = '', rows: int = 6, code: Optional[Union[bool, Dict]] = None, maxlength: Optional[int] = None, minlength: Optional[int] = None, value: Optional[str] = None, placeholder: Optional[str] = None, readonly: Optional[bool] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个文本域输入组件。参见
pywebio.input.textarea()
-
pywebio.pin.
put_select
(name: str, options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, label: str = '', multiple: Optional[bool] = None, value: Optional[Union[List, str]] = None, native: Optional[bool] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个下拉选择输入组件。参见
pywebio.input.select()
注解
Unlike
pywebio.input.select()
, whenmultiple=True
and the user is using PC/macOS,put_select()
will use bootstrap-select by default. Settingnative=True
will force PyWebIO to use native select component on all platforms and vice versa.
-
pywebio.pin.
put_checkbox
(name: str, options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, label: str = '', inline: Optional[bool] = None, value: Optional[List] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个多选框组件。参见
pywebio.input.checkbox()
-
pywebio.pin.
put_radio
(name: str, options: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, *, label: str = '', inline: Optional[bool] = None, value: Optional[str] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个单选按钮组件。参见
pywebio.input.radio()
-
pywebio.pin.
put_slider
(name: str, *, label: str = '', value: Union[int, float] = 0, min_value: Union[int, float] = 0, max_value: Union[int, float] = 100, step: int = 1, required: Optional[bool] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个滑块输入组件。参见
pywebio.input.slider()
-
pywebio.pin.
put_actions
(name: str, *, label: str = '', buttons: Optional[List[Union[Dict[str, Any], Tuple, List, str]]] = None, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一组action按钮。参见
pywebio.input.actions()
不像
actions()` 函数,``put_actions()
不会提交任何表单,它只会设置pin组件的值。put_actions()
只接受 ‘submit’ 类型的按钮。1.4 新版功能.
-
pywebio.pin.
put_file_upload
(name: str, *, label: str = '', accept: Optional[Union[List, str]] = None, placeholder: str = 'Choose file', multiple: bool = False, max_size: Union[int, str] = 0, max_total_size: Union[int, str] = 0, help_text: Optional[str] = None, scope: Optional[str] = None, position: int = - 1) → pywebio.io_ctrl.Output[源代码]¶ Output a file uploading widget. Refer to:
pywebio.input.file_upload()
Pin utils¶
-
pywebio.pin.
pin
¶ 获取与设置Pin组件的值
You can use attribute or key index of
pin
object to get the current value of a pin widget. By default, when accessing the value of a widget that does not exist, it returnsNone
instead of throwing an exception. You can enable the error raising bypin.use_strict()
method.还可以使用
pin
对象设置pin组件的值:put_input('counter', type='number', value=0) while True: pin.counter = pin.counter + 1 # Equivalent to: pin['counter'] = pin['counter'] + 1 time.sleep(1)
注:当使用 基于协程的会话 时,你需要使用
await pin.name
(或await pin['name']
) 语法来获取pin组件的值。Use
pin.pin.use_strict()
to enable strict mode for getting pin widget value. AnAssertionError
will be raised when try to get value of pin widgets that are currently not in the page.
-
pywebio.pin.
pin_wait_change
(*names, timeout: Optional[int] = None)[源代码]¶ pin_wait_change()
监听一组pin组件,当其中任意一个的值发生变化后,函数返回发生变化的组件的name
和值。- 参数
names (str) – Pin组件
name
列表timeout (int/None) – 当
timeout
为正数时,pin_wait_change()
会最多阻塞timeout
秒然后返回None
如果这段时间内监听的pin组件的值没有发生变化的话。 将timeout
设置为None
(默认)来关闭超时。
- Return dict/None
{"name": 发生变化的pin组件的name, "value": 发生变化的pin组件的当前值}
, 当超时发生后,返回None
Example:
put_input('a', type='number', value=0) put_input('b', type='number', value=0) while True: changed = pin_wait_change('a', 'b') with use_scope('res', clear=True): put_code(changed) put_text("a + b = %s" % (pin.a + pin.b))
这里 有一个使用
pin_wait_change()
实现markdown实时预览的demo。注:使用
pin
对象或pin_update()
更新pin组件的值不会引发pin_wait_change()
返回当使用 基于协程的会话 时,你需要使用
await pin_wait_change()
语法来调用此函数。
-
pywebio.pin.
pin_update
(name: str, **spec)[源代码]¶ 更新pin组件的输出属性。
- 参数
name (str) – 目标pin组件的
name
。spec – 需要被更新的pin组件的参数。注意以下参数无法被更新:
type
,name
,code
,multiple
-
pywebio.pin.
pin_on_change
(name: str, onchange: Optional[Callable[[Any], None]] = None, clear: bool = False, init_run: bool = False, **callback_options)[源代码]¶ Bind a callback function to pin widget, the function will be called when user change the value of the pin widget.
The
onchange
callback is invoked with one argument, the changed value of the pin widget. You can bind multiple functions to one pin widget, those functions will be invoked sequentially (default behavior, can be changed byclear
parameter).- 参数
name (str) – pin widget name
onchange (callable) – callback function
clear (bool) – whether to clear the previous callbacks bound to this pin widget. If you just want to clear callbacks and not set new callback, use
pin_on_change(name, clear=True)
.init_run (bool) – whether to run the
onchange
callback once immediately before the pin widget changed. This parameter can be used to initialize the output.callback_options – Other options of the
onclick
callback. Refer to thecallback_options
parameter ofput_buttons()
1.6 新版功能.