服务器-客户端通信协议¶
PyWebIO采用服务器-客户端架构,服务端运行任务代码,通过网络与客户端(也就是用户浏览器)交互。本章介绍PyWebIO服务端与客户端通信的协议。
服务器与客户端有两种通信方式:WebSocket 和 Http 通信。
使用 Tornado或aiohttp 后端时,服务器与客户端通过 WebSocket 通信,使用 Flask或Django 后端时,服务器与客户端通过 Http 通信。
WebSocket 通信:
服务器与客户端通过WebSocket连接发送json序列化之后的PyWebIO消息
Http 通信:
The client polls the backend through Http GET requests, and the backend returns a list of PyWebIO messages serialized in json
When the user submits the form or clicks the button, the client submits data to the backend through Http POST request
为方便区分,下文将由服务器向客户端发送的数据称作command,将客户端发向服务器的数据称作event
以下介绍command和event的格式
Command¶
command由服务器->客户端,基本格式为:
{
"command": ""
"task_id": ""
"spec": {}
}
各字段含义如下:
command
字段表示指令名
task_id
字段表示发送指令的Task id,客户端对于此命令的响应事件都会传递 task_id
spec
字段为指令的参数,不同指令参数不同
需要注意,以下不同命令的参数和 PyWebIO 的对应函数的参数大部分含义一致,但是也有些许不同。
以下分别对不同指令的 spec
字段进行说明:
input_group¶
显示一个输入表单
字段 |
是否必选 |
类型 |
字段说明 |
---|---|---|---|
label |
False |
str |
表单标题 |
inputs |
True |
list |
输入项 |
cancelable |
False |
bool |
表单是否可以取消
若
cancelable=True 则会在表单底部显示一个”取消”按钮,用户点击取消按钮后,触发
from_cancel 事件 |
inputs
字段为输入项组成的列表,每一输入项为一个 dict
,字段如下:
label: 输入标签名。必选
type: 输入类型。必选
name: 输入项id。必选
onchange: bool, whether to push input value when input change
onbulr: bool, whether to push input value when input field
onblur
auto_focus: 自动获取输入焦点. 输入项列表中最多只能由一项的auto_focus为真
help_text: 帮助文字
输入项HTML元素额外的HTML属性
Other attributes of different input types
输入类型目前有:
text: 文本输入
number: 数字输入
password: 密码输入
checkbox: 多选项
radio: 单选项
select: 下拉选择框(可单选/多选)
textarea: 大段文本输入
file: 文件上传
actions: Actions selection.
输入类型与html输入元素的对应关系:
text: input[type=text]
number: input[type=number]
float: input[type=text], and transform input value to float
password: input[type=password]
checkbox: input[type=checkbox]
radio: input[type=radio]
select: select https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select
textarea: textarea https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/textarea
file: input[type=file]
actions: button[type=submit] https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/button
Unique attributes of different input types:
text,number,password: * action: Display a button on the right of the input field.
The format of
action
is{label: button label, callback_id: button click callback id}
textarea:
code: Codemirror 参数, 见
pywebio.input.textarea()
的code
参数
select:
options:
{label:, value: , [selected:,] [disabled:]}
checkbox:
options:
{label:, value: , [selected:,] [disabled:]}
inline
radio:
options:
{label:, value: , [selected:,] [disabled:]}
inline
actions
buttons:
{label:, value:, [type: 'submit'/'reset'/'cancel'], [disabled:]}
.
file:
是否允许多文件上传
单个文件的最大大小(字节),超过限制将会禁止上传
所有文件的最大大小(字节),超过限制将会禁止上传
slider
min_value: The minimum permitted value.
max_value: The maximum permitted value.
step: The stepping interval.
float: If need return a float value
update_input¶
更新输入项,用于对当前显示表单中输入项的 spec
进行更新
命令 spec
可用字段:
target_name: str The name of the target input item.
target_value: str, optional. Used to filter item in checkbox, radio
attributes: dist, fields need to be updated
valid_status: When it is bool, it means setting the state of the input value, pass/fail; when it is 0, it means clear the valid_status flag
value: Set the value of the item
label
placeholder
invalid_feedback
valid_feedback
help_text
options: only available in checkbox, radio and select type
other fields of item’s
spec
// not support theinline
field
close_session¶
指示服务器端已经关闭连接。 spec
为空
set_session_id¶
将当前会话id发送至客户端,客户端可以使用此id来重连会话(仅在websocket连接中可用)。 spec
字段为会话id
output¶
Output content
The spec
fields of output
commands:
type: content type
style: str, Additional css style
container_selector: The css selector of output widget’s container. If empty(default), use widget self as container
container_dom_id: The dom id set to output widget’s container.
scope: str, 内容输出的域的css选择器。若CSS选择器匹配到页面上的多个容器,则内容会输出到每个匹配到的容器
int, 在输出域中输出的位置, 见 输出函数的scope相关参数
不同type时的特有字段
container_selector
and container_dom_id
is used to implement output context manager.
type
的可选值及特有字段:
type: markdown
type: html
content: str
sanitize: bool, 是否使用 DOMPurify 对内容进行过滤来防止XSS攻击。
type: text
content: str
inline: bool, Use text as an inline element (no line break at the end of the text)
type: buttons
callback_id:
buttons:[ {value:, label:, [color:]},…]
small: bool,是否显示为小按钮样式
group: bool, Whether to group the buttons together
link: bool,是否显示为链接样式
outline: bool, Whether enable outline style.
type: file
name: 下载保存为的文件名
content: 文件base64编码的内容
type: table
data: Table data, which is a two-dimensional list, the first row is table header.
span: cell span info. Format: {“[row id],[col id]”: {“row”:row span, “col”:col span }}
type: pin
input: input spec, same as the item of
input_group.inputs
pin_update¶
The spec
fields of pin_update
commands:
name
attributes: dist, fields need to be updated
popup¶
Show popup
The spec
fields of popup
commands:
title
content
size:
large
,normal
,small
implicit_close
closable
dom_id: DOM id of popup container element
toast¶
Show a notification message
The spec
fields of popup
commands:
content
duration
position:
'left'
/'center'
/'right'
color: hexadecimal color value starting with ‘#’
callback_id
set_env¶
Config the environment of current session.
The spec
fields of set_env
commands:
title (str)
output_animation (bool)
auto_scroll_bottom (bool)
http_pull_interval (int)
input_panel_fixed (bool)
input_panel_min_height (int)
input_panel_init_height (int)
input_auto_focus (bool)
output_ctl¶
Output control
The spec
fields of output_ctl
commands:
set_scope: scope name
container: 新创建的scope的父scope的css选择器
position: int, 在父scope中创建此scope的位置.
scope已经存在时如何操作:
null/不指定: 表示立即返回不进行任何操作
’remove’
: 先移除旧scope再创建新scope’clear’
: 将旧scope的内容清除,不创建新scope
clear: 需要清空的scope的css选择器
clear_before
clear_after
clear_range:[,]
- scroll_to
position: top/middle/bottom 与scroll_to一起出现, 表示滚动页面,让scope位于屏幕可视区域顶部/中部/底部
remove: 将给定的scope连同scope处的内容移除
run_script¶
run javascript code in user’s browser
The spec
fields of run_script
commands:
code: 字符串格式的要运行的js代码
args: 传递给代码的局部变量。字典类型,字典键表示变量名,字典值表示变量值(变量值需要可以被json序列化)
eval: bool, whether to submit the return value of javascript code
download¶
Send file to user
The spec
fields of download
commands:
name: str, File name when downloading
content: str, File content in base64 encoding.
Event¶
Event消息由客户端发往服务端。基本格式:
{
event: event name
task_id: ""
data: object/str
}
event
表示事件名称。 data
为事件所携带的数据,其根据事件不同内容也会不同,不同事件对应的 data
字段如下:
input_event¶
表单发生更改时触发
event_name: 目前可用值
’blur’
,表示输入项失去焦点name: 输入项name
value: 输入项值
注意: checkbox radio 不产生blur事件
callback¶
用户点击显示区的按钮时触发
在 callback
事件中,task_id
为对应的 button
组件的 callback_id
字段;
事件的 data
为被点击button的 value