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 and validate callbacks, and the required parameter. (There is a pin_on_change() function as an alternative to on_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(), when multiple=True and the user is using PC/macOS, put_select() will use bootstrap-select by default. Setting native=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 returns None instead of throwing an exception. You can enable the error raising by pin.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. An AssertionError 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 by clear 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 the callback_options parameter of put_buttons()

1.6 新版功能.