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¶
每个pin组件函数都对应一个 input 模块中的输入函数。(出于性能原因，没有提供 file_upload() 函数对应的pin组件)
Pin组件函数支持大多数对应的输入函数的参数。这里列举了两者之间的一些不同：
Pin组件函数的第一个参数始终是Pin组件的
name，且当输出了同名的pin组件时，旧的pin组件会不可用。Pin组件函数不支持
on_change、validate回调，也不支持required参数。Pin组件函数多了用于输出控制的
scope和position参数。
-
pywebio.pin.put_input(name, type='text', *, label='', value=None, placeholder=None, readonly=None, datalist=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个文本输入组件。参见
pywebio.input.input()
-
pywebio.pin.put_textarea(name, *, label='', rows=6, code=None, maxlength=None, minlength=None, value=None, placeholder=None, readonly=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个文本域输入组件。参见
pywebio.input.textarea()
-
pywebio.pin.put_select(name, options=None, *, label='', multiple=None, value=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个下拉选择输入组件。参见
pywebio.input.select()
-
pywebio.pin.put_checkbox(name, options=None, *, label='', inline=None, value=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个多选框组件。参见
pywebio.input.checkbox()
-
pywebio.pin.put_radio(name, options=None, *, label='', inline=None, value=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个单选按钮组件。参见
pywebio.input.radio()
-
pywebio.pin.put_slider(name, *, label='', value=0, min_value=0, max_value=100, step=1, required=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一个滑块输入组件。参见
pywebio.input.slider()
-
pywebio.pin.put_actions(name, *, label='', buttons=None, help_text=None, scope=None, position=- 1) → pywebio.io_ctrl.Output[源代码]¶ 输出一组action按钮。参见
pywebio.input.actions()不像
actions()` 函数，``put_actions()不会提交任何表单，它只会设置pin组件的值。put_actions()只接受 ‘submit’ 类型的按钮。1.4 新版功能.
Pin utils¶
-
pywebio.pin.pin¶ 获取与设置Pin组件的值
你可以使用属性或索引来从
pin对象上获取pin组件的当前值。当访问不存在的pin组件时，会得到None而不会抛出异常。还可以使用
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组件的值。
-
pywebio.pin.pin_wait_change(*names, timeout=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()语法来调用此函数。