服务器-客户端通信协议

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

显示一个输入表单

`spec` 可用字段
字段	是否必选	类型	字段说明
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参数或 bool, 同 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:], [color:]} .
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 the inline field

close_session

指示服务器端已经关闭连接。 spec 为空

set_session_id

将当前会话id发送至客户端，客户端可以使用此id来重连会话(仅在websocket连接中可用)。 spec 字段为会话id

destroy_form

Destroy the current form. spec of the command is empty.

表单在页面上提交之后不会自动销毁，需要使用此命令显式销毁

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 content slot. If empty(default), use widget self as container
container_dom_id: The dom id need to be set to output widget’s content slot.
scope: str, 内容输出的域的css选择器。若CSS选择器匹配到页面上的多个容器，则内容会输出到每个匹配到的容器
int, 在输出域中输出的位置, 见输出函数的scope相关参数
click_callback_id:
不同type时的特有字段

container_selector and container_dom_id is used to implement output context manager.

type 的可选值及特有字段：

type: markdown
- content: str
- options: dict, marked.js options
- sanitize: bool, 是否使用 DOMPurify 对内容进行过滤来防止XSS攻击。
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:], [disabled:]},…]
- 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
type: scope
- dom_id: the DOM id need to be set to this widget
- contents list: list of output spec
type: scrollable
- contents:
- min_height:
- max_height:
- keep_bottom:
- border:
type: tabs
- tabs:
type: custom_widget
- template:
- data:

pin_value

命令 spec 可用字段：

name

pin_update

命令 spec 可用字段：

name
attributes: dist, fields need to be updated

pin_wait

命令 spec 可用字段：

names: list,
timeout: int,

pin_onchange

set a callback which is invoked when the value of pin widget is changed

The spec fields of pin_onchange commands:

name: string
callback_id: string, if None, not set callback
clear: bool

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
  
  'blank': Clear the contents of the old scope and keep the height, don’t create a new scope
loose: css selector of the scope, set the scope not to keep the height (i.e., revoke the effect of set_scope(if_exist='blank'))
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

from_submit

用户提交表单时触发

事件 data 字段为表单 name -> 表单值的字典

from_cancel

表单取消输入

The data of the event is None

js_yield

submit data from js. It’s a common event to submit data to backend.

事件 data 字段为相应的数据

服务器-客户端通信协议

Command

input_group

update_input

close_session

set_session_id

destroy_form

output

pin_value

pin_update

pin_wait

pin_onchange

popup

toast

close_popup

set_env

output_ctl

run_script

download

Event

input_event

callback

from_submit

from_cancel

js_yield