ylui-app v2.1.9
窗体API
窗体API指窗体在运行过程中可以使用的API，得益于YLUI精巧的设计，跨域的窗体也能实现一些强大的功能。
对于同域的窗体，可以使用
parent.window来获取父窗体（YLUI主体）的所有全局对象，自然也就可以为所欲为。但是我们依然推荐开发者使用YLUI的窗体API模式，来获取更安全、更低耦合的开发体验。
开始
首先要使用 窗体API ，我们需要在窗体页面引入js文件：/res/yl.app.js，你可以将这个文件放置在其他位置，只要能正确加载到即可。
没错，对于最基本的使用，只需要加载yl.app.js文件，你甚至不需要写其他代码。
功能
成功接入窗体API 后，窗体将获得以下特性
- 支持在YLUI的地址栏中前进后退
- 支持F5刷新窗体而不是整个页面
- 直接获取同域的，其他子窗体的window对象
- 检测窗体是否运行于YLUI框架下，如果是，触发回调
- 窗体通信（高级）
YLApp.id
每个窗体被打开，YLUI都会为它分配一个id。子窗口通过YLApp.id可以获取。
如果获取后为空，可能是当前APP不是运行在YLUI下，或尚未初始化。
YLApp.data
data是这个窗体在被创造时赋予的数据，常被用于窗体通信。
例如，通过这个窗体a新建一个窗体b，可以为b的data赋值
parent:a的id来标记创建者。
YLApp.open(url)
url string 打开新窗体的url地址
立即在YLUI中打开一个新窗口。此处参数只有一个url，简单而常用的一个API。
可以替代传统的a标签打开新窗口。
YLApp.onEvent(cb)
cb function 回调函数
接受到YLUI事件时触发，cb为事件处理函数（高级）。
YLUI主体会广播一些公共事件，它们分别为
- dataChanged 存档数据已被用户变更（监听此事件，上传用户的最新存档数据至你的数据库）
- open 某窗体被打开
- close 某窗体被关闭
- desktopMouseMove 桌面鼠标移动
- desktopMouseDown 桌面鼠标按下
- desktopMouseUp 桌面鼠标抬起
- desktopClick 桌面鼠标点击
- resize 主窗体尺寸改变
未来会加入更多公共事件
###YLApp.getWinObject(id)
id string 目标窗体id
return window object
获取指定窗体的window对象，仅在同域有效。
YLApp.onEvent(cb)
cb function 回调函数
接受到YLUI事件时触发，cb为事件处理函数（高级）。
YLApp.emit(event,data,target)
event string 事件名
data mixed 数据
target string|array|true 广播对象
发送一个事件。其中。如果target是string类型，表示发送给对应id的窗口；如果target是数组，表示发送给数组中所有id对应的窗体；如果target为true，表示发送给所有窗体。
特别的，YLUI主体的id为0。
YLApp.eval(method,data, cb)
method string 方法名
data mixed 数据
cb function 回调函数
主动向YLUI发布指令或请求数据，完成后触发回调，请求结果会传递到回调函数的第一个参数上。
YLUI提供了很多方法可供窗体使用，它们统一使用YLApp.eval的形式。
参数为id的方法，如果id为空，则默认是当前窗体的id
| method | data | return | 描述 |
|---|---|---|---|
| getID | int | 返回YLUI的一个id流水号 | |
| getVersion | string | 返回YLUI的当前版本 | |
| historyBack | string id | 指定id窗体后退 | |
| historyBackAvailable | string id | bool | 指定id窗体是否可以后退 |
| historyForward | string id | 指定id窗体前进 | |
| historyForwardAvailable | string id | bool | 指定id窗体是否可以前进 |
| refresh | string id | 刷新指定id窗体 | |
| setWinData | object data | 设置当前窗体的数据 | |
| getWinData | object | 获取当前窗体的数据 | |
| setWallpaper | string urlImg | 设置壁纸为urlImg图片 | |
| setThemeColor | string color | 设置主题色 | |
| getConfigs | object | 获取配置 | |
| getRuntime | object | 获取运行时数据 | |
| open | object|array data | string | 打开窗体，返回窗体id。具体调用方式参看7.1全局API YL.open，其中，data为array对应了YL.open两个参数的用法 |
| close | string id | 关闭指定id的窗体，如果未指定id，关闭本窗体 | |
| minimize | string id | 最小化指定id的窗体 | |
| maximize | string id | 最大化指定id的窗体 | |
| hide | string id | 隐藏指定id的窗体 | |
| show | string id | 显示指定id的窗体 | |
| restore | string id | 还原指定id的窗体 | |
| msg | array data | 推送消息。data0为标题，data1为正文 | |
| simpleMsg | string data | 发送简单的文本提示信息 | |
| setAppBadge | array|string|int data | bool | 设置APP的角标值；如果data为数组，data0为角标值，data1为APP id；如果data为数字或字符串，设置窗口所属APP的角标为data；返回操作是否成功 |
| getAppVersion | string id | string | 返回指定id窗体或当前窗体所属APP的版本号 |
| uninstall | string|array data | 卸载应用。data为string卸载指定id的应用，data为array卸载多个应用 | |
| import | object data | 【需要受信任APP权限】导入数据，重载YLUI | |
| export | object | 【需要受信任APP权限】导出YLUI存档数据 | |
| eval | string data | 【需要受信任APP权限】在YLUI主体执行eval | |
| setup | object data | 安装。见下文 |
setup
setup是比较复杂而强大的指令，可以为YLUI动态添加APP和快捷方式。利用它你可以很快打造出一个YLUI应用商店。
data 的数据结构如下。其中，每一项不是必须存在的（比如只想添加图标不想添加磁贴，则可以省去tiles属性）。
{
apps:{...},
shortcuts:[...],
sidebar:[...],
tiles:[...],
menu:{...},
}apps 需要传入多个新增/修改app的数据结构，形如
{my_app1_id:{my app1 data ...},my_app2_id:{my app2 data ...}}。APP的数据格式可以参阅
6.3应用程序池。shortcuts 需要新增的多个桌面图标数据，形如
[{data1 ...},'my_app2_id']，相当于调用了YL.addShortcut函数。sidebar 需要新增的多个侧边栏按钮的数据，形如
[{data1 ...},'my_app2_id']，相当于调用了YL.addSidebarBtn函数。tiles 需要新增的多个磁贴的数据，形如
[{data1 ...},'my_app2_id']，相当于调用了YL.addTile函数。menu 需要新增的多个菜单项的数据，形如
{item1_id:{item1_data ...},item2_id:{item2_data ...}}。注意菜单项的id不能与其他项重复。菜单项的数据格式可以参阅
6.6开始菜单。
5 years ago