bricks/docs/cn/descjson.md

482 lines
13 KiB
Markdown
Raw Normal View History

2023-12-18 18:15:22 +08:00
# 创建控件的Json文件格式说明
2024-05-13 12:47:08 +08:00
Bricks在服务器端使用Json文件格式存储控件描述文件前端获得json文件后转化为json对象并用此json对象调用widgetBuild函数创建Bricks控件。
2023-12-18 18:15:22 +08:00
控件描述json文件必须含有“widgettype” 和”options“两个属性。“subwidgets”属性用来定义此控件包含的子控件。“binds”用于定义此控件或其子控件的事件处理
2024-05-13 14:34:07 +08:00
## id
id是一个可选项定义控件的id 缺省不定义控件id bricks提供根据控件id查找控件的机制详情请看[控件id](widgetid.md)
2023-12-18 18:15:22 +08:00
## widgettype说明
widgettype是一个字符串属性。其值为Bricks中的所有控件类型或"urlwidget"
2024-05-13 12:47:08 +08:00
可用的控件类型可以在[控件类型清单](widgets.md)中查找
2023-12-18 18:15:22 +08:00
## options
对象类型每个控件有特定的options属性清参看每个控件的说明
## subwidgets
数组类型数组中的每个元素必须是一个对象类型数据与desc作用一样。
参见widgetBuild函数的desc说明
## binds
2024-05-13 13:04:47 +08:00
列表属性,定义控件的事件处理,在列表中的每一项,定义一个事件处理, Bricks支持5种事件处理方法分别是urlwidget, method, script, registedfunction和event
2024-05-13 14:34:07 +08:00
每种事件处理类型都支持下述属性
2023-12-18 18:15:22 +08:00
### wid
字符串类型或控件类型绑定事件的控件缺省是binds坐在的构造控件。
### event
字符串类型,事件名称, 绑定针对的事件字符串名称
### actiontype
绑定类型支持“urlwidget", "method", "script", "registerfunction", "event"
### conform
对象类型确认控件的options如存在则此绑定需要用户确认后再执行
### 获取实时数据作为参数
绑定任务获取实时数据作为参数,需要给定以下属性:
* datawidget字符串或控件类型获取实时数据的控件
* datamethod字符串类型控件的方法使用params作为参数调用
获取实时数据的方法
* datascript字符串类型 js脚本使用return返回数据
* dataparams参数
datamethod 优先datascript从datawidget控件中通过datamethod
### target
字符串或控件实例目标控件实例如果是字符串使用”getWidgetById“函数获得目标控件实例
2024-05-13 13:32:18 +08:00
### conform
2024-05-13 13:04:47 +08:00
如果一个事件处理需要用户确认可以在事件处理中指定一个conform属性来引发当此事件发生时会弹出一个确认窗口用户确认后才会处理此事件否则不处理
2023-12-18 18:15:22 +08:00
### urlwidget绑定
2024-05-13 13:04:47 +08:00
urlwidget事件处理方法是从后台获取一个控件描述文件动态生成bricks控件并将控件添加添加添加或替换到事件处理指定的控件中。
2023-12-18 18:15:22 +08:00
urlwidget绑定需要一个options属性和一个mode属性在此属性中需要
* url字符串类型 获取desc数据的url
* mehtod字符串类型url调用的方法缺省”GET“
* params对象类型调用的参数
绑定创建的控件添加到target控件中
2024-05-13 13:04:47 +08:00
请参考[例子](../../examples/urlwidget.ui)
```
{
"widgettype":"VBox",
"options":{
"width":"100%",
"height":"100%"
},
"subwidgets":[
{
"widgettype":"HBox",
"options":{
"height":"40px"
},
"subwidgets":[
{
"id":"replace",
"widgettype":"Button",
"options":{
"width":"80px",
"i18n":true,
"label":"replace mode"
}
},
{
"id":"insert",
"widgettype":"Button",
"options":{
"width":"80px",
"i18n":true,
"label":"insert mode"
}
},
{
"id":"append",
"widgettype":"Button",
"options":{
"width":"80px",
"i18n":true,
"label":"append mode"
}
}
]
},
{
"id":"main",
"widgettype":"Filler"
}
],
"binds":[
{
"wid":"replace",
"event":"click",
"actiontype":"urlwidget",
"target":"main",
"options":{
"url":"{{entire_url('replace_text.ui')}}",
"params":{
"text":"Insert before"
}
}
},
{
"wid":"insert",
"event":"click",
"actiontype":"urlwidget",
"target":"main",
"options":{
"url":"{{entire_url('insert_text.ui')}}",
"params":{
"text":"Insert before"
}
},
"mode":"insert"
},
{
"wid":"append",
"event":"click",
"actiontype":"urlwidget",
"target":"main",
"options":{
"url":"{{entire_url('subtext.ui')}}",
"params":{
"text":"Append After"
}
},
"mode":"append"
}
]
}
```
在上述例子中我们使用了一个竖向排列的容器VBox并在此容器中添加了两个字控件分别是一个横向排列的容器HBox和一个填充器Filler
并在横向排列的子控件中添加了3个按钮控件, 每个Button定义了id 分别是replaceinsert和append在主控件VBox的binds中分别定义了三个事件处理分别对应于3个Button的click事件演示了三种子控件在target控件中插入的模式替换所有子控件插入在已有子控件之前添加到已有子控件之后
2023-12-18 18:15:22 +08:00
### method
需要指定target参数和method参数
* target类型为字符串或控件类型
如果是字符串使用“getWidgetById”函数获取控件实例。
* method字符串target实例的方法
* params传递给方法的参数
method绑定方法将事件绑定到target控件的一个方法并用params传递参数
2024-05-13 13:04:47 +08:00
例子
```
{
"widgettype":"VBox",
"options":{
"width":"100%",
"height":"100%"
},
"subwidgets":[
{
"widgettype":"HBox",
"options":{
"height":"40px"
},
"subwidgets":[
{
"id":"changetext",
"widgettype":"Button",
"options":{
"dynsize":false,
"width":"80px",
"i18n":true,
"label":"Change text"
}
},
{
"id":"smaller",
"widgettype":"Button",
"options":{
"dynsize":false,
"width":"80px",
"i18n":true,
"label":"Small size"
}
},
{
"id":"larger",
"widgettype":"Button",
"options":{
"dynsize":false,
"width":"80px",
"i18n":true,
"label":"larger size"
}
}
]
},
{
"widgettype":"Filler",
"options":{},
"subwidgets":[
{
"id":"text_1",
"widgettype":"Text",
"options":{
"dynsize":true,
"text":"original text"
}
}
]
}
],
"binds":[
{
"wid":"changetext",
"event":"click",
"actiontype":"method",
"target":"text_1",
"params":"new text",
"method":"set_text"
},
{
"wid":"smaller",
"event":"click",
"actiontype":"method",
"target":"app",
"method":"textsize_smaller"
},
{
"wid":"larger",
"event":"click",
"actiontype":"method",
"target":"app",
"method":"textsize_bigger"
}
]
}
```
上述例子中三个Button分别驱动app中textsize_smaller()textsize_bigger()来改变bricks字符大小从而影响到text_1控件的显示大小
2023-12-18 18:15:22 +08:00
### script
绑定脚本,此方法将事件绑定到一个脚本,支持以下属性
* script字符串脚本正文
* params对象类型脚本可以访问params变量来获取参数。
2024-05-13 13:04:47 +08:00
脚本中可以使用以下变量:
* this 事件处理中target对应的控件实例
* params参数对象datawidget获得的数据会添加到params中
例子
```
{
"id":"insert",
"widgettype":"Button",
"options":{
"width":"80px",
"i18n":true,
"label":"click me"
},
"binds":[
{
"wid":"self",
"event":"click",
"actiontype":"script",
"target":"self",
"script":"console.log(this, params, event);"
}
]
}
```
在上述例子中定义了使用“script”事件处理方法来处理Button的“click事件” 在click后在控制台上把事件传过来的参数显示出来
2023-12-18 18:15:22 +08:00
### registerfunction
事件绑定一个注册函数, 参看[RegisterFunction](registerfunction.md)
支持以下属性:
rfname字符串已注册的函数名称
params对象类型调用注册函数时作为参数传递给注册函数。
2024-05-13 13:04:47 +08:00
```
<link rel="stylesheet" href="http://localhost:80/bricks/css/bricks.css">
<!-- support IE8 (for Video.js versions prior to v7) -->
<script src="http://localhost:80/bricks/3parties/videojs-ie8.min.js"></script>
</head>
<body>
<script src="http://localhost:80/bricks/3parties/marked.min.js"></script>
<script src="http://localhost:80/bricks/3parties/xterm.js"></script>
<script src="http://localhost:80/bricks/3parties/video.min.js"></script>
<script src="http://localhost:80/bricks/3parties/recorder.wav.min.js"></script>
<!--- <script src="http://localhost:80/bricks/3parties/videojs-contrib-hls.min.js"></script> --->
<script src="http://localhost:80/bricks/bricks.js"></script>
<script>
/*
if (bricks.is_mobile()){
alert('wh=' + window.innerWidth + ':' + window.innerHeight);
}
*/
var myfunc = function(params){
this.set_text(params.text);
}
bricks.RF.register('setText', myfunc);
const opts = {
"widget": {
"widgettype":"VBox",
"options":{
"width":"100%",
"height":"100%"
},
"subwidgets":[
{
"widgettype":"HBox",
"options":{
"height":"40px"
},
"subwidgets":[
{
"id":"changetext",
"widgettype":"Button",
"options":{
"dynsize":false,
"width":"80px",
"i18n":true,
"label":"Change text"
}
},
{
"id":"smaller",
"widgettype":"Button",
"options":{
"dynsize":false,
"width":"80px",
"i18n":true,
"label":"Small size"
}
},
{
"id":"larger",
"widgettype":"Button",
"options":{
"dynsize":false,
"width":"80px",
"i18n":true,
"label":"larger size"
}
}
]
},
{
"widgettype":"Filler",
"options":{},
"subwidgets":[
{
"id":"text_1",
"widgettype":"Text",
"options":{
"dynsize":true,
"text":"original text"
}
}
]
}
],
"binds":[
{
"wid":"changetext",
"event":"click",
"actiontype":"registerfunction",
"target":"text_1",
"params":{
"text":"new text"
},
"rfname":"setText"
},
{
"wid":"smaller",
"event":"click",
"actiontype":"method",
"target":"app",
"method":"textsize_smaller"
},
{
"wid":"larger",
"event":"click",
"actiontype":"method",
"target":"app",
"method":"textsize_bigger"
}
]
} };
const app = new bricks.App(opts);
app.run();
</script>
</body>
</html>
```
在上述例子中使用bricks.RF注册了一个setText函数 并在主控件的binds区域定义了当changetext按钮点击后调用注册函数“setText”来处理
2023-12-18 18:15:22 +08:00
### event
绑定事件需指定target触发target对象的一个事件
支持以下属性
dispatch_event需触发的事件名
params传递给事件的参数处理函数可以使用evemt.params获得此参数
2024-05-13 13:04:47 +08:00
```
{
"widgettype":"VBox",
"options":{},
"subwidgets":[
{
"id":"btn1",
"widgettype":"Button",
"options":{
"label":"press me"
}
},
{
"id":"txt1",
"widgettype":"Text",
"options":{
"otext":"I will dispatch a event when btn1 pressed",
"i18n":true
}
}
],
"binds":[
{
"wid":"btn1",
"event":"click",
"actiontype":"event",
"target":"txt1",
"dispatch_event":"gpc"
},
{
"wid":"txt1",
"event":"gpc",
"actiontype":"script",
"target":"self",
"script":"alert('yield');"
}
]
}
```
上述例子中在主控件的binds区域定义了btn1的按钮点击后使用event处理类型来处理btn1的click事件即转而触发“txt1”正文控件的“gpc”事件并定义了当”txt1“正文控件在gpc事件发生后使用script事件处理方法alert一个消息
2024-05-13 13:32:18 +08:00
## 定义需要确认的事件处理
有时候我们需要客户确认后在处理事件,如果用户不确认,则放弃处理事件,比如在删除数据时我们通常需要用户确认一下
例子
```
{
"id":"insert",
"widgettype":"Button",
"options":{
"width":"80px",
"i18n":true,
"label":"click me"
},
"binds":[
{
"wid":"self",
"event":"click",
"actiontype":"script",
"conform":{
"title":"conformtest",
"message":"测试事件处理前的用户确认功能,确认码?"
},
"target":"self",
"script":"alert('确认过眼神!')"
}
]
}
```
上述例子中定义了Button的click事件使用script事件处理方式来处理但是在处理前需要显示信息让用户确认是否继续如果用户放弃则不处理事件确认后正常的处理事件。
2023-12-18 18:15:22 +08:00