都可以,使用setInterval
最简单了,推荐。
Posts made by 陈旭
本文介绍Jigsaw的API文档编写方法、规则、约定。
目录
文档写在哪?
Jigsaw的所有API相关的文档全部编写对应的代码中,以文档注释的方式编写,例如
/**
* 总体说明
*/
export interface IAjaxComponentData {
/**
* 属性说明
*/
busy: boolean;
/**
* 方法说明
* @param {string} url 参数说明
* @returns {Observable<any>} 函数返回值说明
*/
fromAjax(url?: string): Observable<any>;
}
在构建版本的时候,文档构建工具会自动提取出这些文档,并组织和合并成合适的结构,方便ued网站使用。
如何编写?
如前文例子所示,根据文档所在位置的不同,主要分为如下几个类型:
- 总体说明部分
- 属性说明部分
- 方法说明部分
- 参数说明部分
- 函数返回值说明部分
虽然文档类型众多,但是文档编写所采用的格式都是一样的,全部采用markdown格式书写文档。除此之外,你还需要了解一下文档tag、文档中的变量以及文档中的链接小节。
文档自动发现
由于Jigsaw的API非常多,并且其中相当一部分API有继承、接口实现关系,Jigsaw的文档工具支持帮助API自动发现已有文档,在无更具体的api时,文档工具会往上追溯取最近一个有血缘关系的api的文档。这样可以大大减少文档在api之间多次拷贝,时长日久演进过程中,出现漏更新,进而导致误导应用使用的后果。虽然手工创建链接可以避免文档拷贝,但是手工维护这些链接工作量也不小,况且不停的链接跳转会导致文档阅读体验下降。
文档自动发现可以覆盖除了“总体说明”部分的其他所有文档。这是有意为之的,我们认为,一个类之所以被创建出来,肯定是有它独特的作用的(即使是为了语义),因此每个类的总体说明必然不同,因此,文档工具故意避开总体说明部分自动发现。
文档自动发现的一些约定(坑)
- 尽可能在接口、基类上编写详细的文档,且接口的优先级高于类。道理很简单,越靠近根部的文档会覆盖越多的子类,反过来说,子类需要独立编写的文档就越少。
- 子类实现接口方法、或者覆盖父类的方法时,请务必保持参数名字一致,这样才可以在子类中自动发现父类上的文档。这可能是最大的一个坑了。这是由于文档工具实现机制决定的,文档工具追溯类的血缘关系靠的不是编译器给出的信息,而是靠静态语法分析,因此它难以重根本上了解父子类中两个方法是否有血缘。
文档tag
这里介绍文档工具能够支持的JS文档标记。
所有可以被支持的JS文档标记以及用法介绍在这里可以找到。其中@link
和@example
这2个不建议使用,而是建议采用markdown风格的链接和代码块来书写。
常用的罗列如下
@param
用于定义一个方法的参数,语法为@param {type} var descriptions
;@returns
用于定义一个方法的返回值,语法为@returns {type} descriptions
;特别注意,最后有个s!webstorm自动生成的JS标记有时候没有加上s。
文档中的变量
为了尽可能自动化生成更多的文档以解脱人的时间投入,文档工具支持一些变量。文档变量的使用语法为:
$var = value
其中var
是变量名,value
是该变量的值,是一个字符串。如果同一个变量有多个值,则配置多行,文档工具会自动将其合并为一个数组:
$var = value1
$var = value2
$var = value3
扩展:之所以使用
$
作为特殊字符而不用@
是因为JS文档解析工具的约束导致的。@
开头的自定义标记无法生成文档。
已经支持的所有变量如下:
$demo
将一个demo与当前文档关联起来- 它的值是demo的url,例如
$demo = data-encapsulation/array-ajax
; - 允许出现在总体部分、属性部分、方法部分;
- 支持多值;
- 它的值是demo的url,例如
$since
用于标记当前api可用的起始版本- 它的值是一个版本号,例如
$since = v1.1.4
; - 允许出现在总体部分、属性部分、方法部分;
- 它的值是一个版本号,例如
$deprecatedFrom
用于标记当前api被废弃的起始版本- 它的值是一个版本号,例如
$deprecatedFrom = v1.1.4
; - 允许出现在总体部分、属性部分、方法部分;
- 常常与
$replacement
变量结伴使用;
- 它的值是一个版本号,例如
$replacement
用于指明被废弃的api的替代方案。- 它的值是一段代码,例如
$replacement = touchValueByRow()
; - 允许出现在总体部分、属性部分、方法部分;
- 必须与
$deprecatedFrom
结伴使用,如果所在区域的文档中未出现$deprecatedFrom
,则此变量无效;
- 它的值是一段代码,例如
文档中的链接
同样的,为了减少人编写文档的投入和链接的有效性,文档工具能够自动识别文档中可识别的类型,并自动给加上超链,详见这个issue。
例如以下这段文档:
/**
* Jigsaw的数据总体分成两大分支:
* - `ArrayCollection` 这个分支只关注数组类型的集合;
* - `GeneralCollection` 这个分支只关注通用的key-value结构(即JSON对象)的集合;
* ...
*/
文档工具可以将文档中的行内代码块 `ArrayCollection` 和 `GeneralCollection` 加上链接,注意只有行内代码块才会被自动转换。
因此,在编写文档的时候,尽量的给已知类型设置为行内代码块。
使用文档工具
执行如下命令
# 我们需要依赖[compodoc](https://github.com/compodoc/compodoc)来生成基础数据
npm install -g @compodoc/compodoc@1.0.9
git clone https://github.com/rdkmaster/jigsaw.git
cd jigsaw
sh build/scripts/doc-generator/generate.sh /path/to/output/doc
执行成功之后,就会在 /path/to/output/doc
目录下生成所需的文档了
原文链接 https://github.com/rdkmaster/jigsaw/wiki/Jigsaw-API-Documentation-Specification
新特性 / New Features
- 重磅功能:增强
j-box
布局功能,支持用户在界面上拖拽调整布局尺寸,详见这里 - 重磅功能:增加
j-editable-box
组件,纯数据驱动的布局方式,更加灵活,轻松实现所见即所得的布局效果,详见这里 - 新组件:增加
j-notification
组件,更加灵活&友好的消息提示功能,详见这里 - https://github.com/rdkmaster/jigsaw/issues/481 PageableTableData支持post请求
破坏性修改 / Breaking Changes
- 无 / none
优化 / Modified
- https://github.com/rdkmaster/jigsaw/issues/349 增加图例和饼图间距的配置,解决描述文字模糊的问题
- https://github.com/rdkmaster/jigsaw/issues/467 table的滚动条加个最小长度
- 简化
PopupService.setPosition()
的参数列表,提升易用性
修复 / Fixes
- https://github.com/rdkmaster/jigsaw/issues/434 Combo在tag变化时计算下拉的位置,没有判断有没有下拉
- https://github.com/rdkmaster/jigsaw/issues/439 j-tile自动去除selectedItems里无效的条目
- https://github.com/rdkmaster/jigsaw/issues/354 【ie 11】table有时会出现渲染不出来的情况,鼠标hover上去,才渲染出来
- https://github.com/rdkmaster/jigsaw/issues/405 【ie 11】button/disabled 鼠标点击CheckBox后,四周边框黑线出现,但是box没有打上勾
- https://github.com/rdkmaster/jigsaw/issues/461 tree销毁时会把页面所有的ztree都销毁
- https://github.com/rdkmaster/jigsaw/issues/458 paginaton的page、goto支持国际化
- slider的值校验功能在组件初始化之前执行异常导致
value
的初始值在特定情况下未生效 - 修复
PopupService.show()
自动根据路由变化关闭所有对话框功能异常
国内外有很多在线演示代码站点,但是功能都太简单,稍微复杂些的app就运行不了。
再此之前,市面上能够完美运行angular1.x angular2+的在线站点,就只有plnkr.co这一个,但杯具的是它被墙了。
现在好了,有了j-lunker,大家以后分享代码及其运行效果就有多一个去处了。http://rdk.zte.com.cn/j-lunker 首页还很简陋,希望有时间的同学能够帮我完善它。
用J-lunker来做啥
J-lunker可以在线运行任意前端代码,并且可以在代码被编辑之后,J-lunker会立即重新运行他们。它可以让你很方便的将代码及其结果和行为分享给他人。
J-lunker和embed.plnkr.co在功能、用法上都非常相似,就连名字也很相似不是吗?
为啥需要J-lunker
你可能已经知道了,embed.plnkr.co的功能和J-lunker几乎是一样的了,那为啥还需要J-lunker呢?这里是一些原因:
- 避免被GFW干扰:这是我创造J-lunker的最主要原因,GFW在我们使用plunker来分享和运行代码的过程中,制造了太多的麻烦了,Jigsaw的demo代码的读者们常常抱怨这一点。
- 更快的速度:我在国内部署了一个J-lunker的服务器,这样就可以让多数Jigsaw的demo代码读者享受到更快的代码打开和运行速度了,相信他们会很开心的。
- 只将代码及其运行效果共享给授信的人,而非所有人:J-lunker极其轻量,因此它可以非常容易的部署到任何范围可控且安全的环境中去,因此你就不需要担心你将代码发给plunker上去运行之后,被不信任的人(包括plunker在内)偷走了。
如果上述任何一个理由也适合你,那么J-lunker就是一个更好的选择。
代码持久化在哪
J-lunker本身不永久保存被运行的代码,代码由J-lunker的用户自行保存,J-lunker只是提供在线运行他们的功能。如果你和Jigsaw、angular.io、angular.cn那样,也有大量需要在线演示的代码的话,那J-lunker对你来说是很适合的工具。自行持久化代码的好处是你可以很容易通过CI或者其他脚本来更新或者生成这些代码。
如何使用
J-lunker的用法和embed.plnkr.co极其相似。拷贝下面的代码,保存到一个文件中去,假设命名为embed.html
,使用任意的浏览器打开它,你应该可以立即看到J-lunker运行后的效果了。
<html>
<head>
<meta charset="UTF-8">
</head>
<body>
<form id="mainForm" method="post" target="_self"
action="http://rdk.zte.com.cn/rdk/service/app/j-lunker/server/eval">
<input type="hidden" name="option[show]" value="index.html,preview" />
<input type="hidden" name="entries[asset/styles.css][content]" value="
h1 {
font-size: 30px;
transition: .5s;
}
h1:hover {
color: red;
}
a {
cursor: pointer;
transition: .3s;
}
a:hover {
color: blue;
}
" />
<input type="hidden" name="entries[script/script.js][content]" value="
function gotoProject() {
window.open('https://github.com/rdkmaster/j-lunker');
}
">
<input type="hidden" name="entries[index.html][content]" value="
<!DOCTYPE html>
<html>
<head>
<title>J-lunker basic template</title>
<link rel="stylesheet" type="text/css" href="asset/styles.css">
<script type="text/javascript" src="script/script.js"></script>
</head>
<body>
<h1>Hello J-lunker!</h1>
<p>
This is the basic template.
<a onclick="gotoProject()">Click here to star us.</a>
</p>
</body>
</html>
">
<input type="hidden" name="title" value="J-lunker basic template." />
</form>
<script>document.getElementById("mainForm").submit();</script>
</body>
</html>
这个embed.html
文件没有任何依赖,可以将它保存到你的web服务器下的任意目录,这样你就可以通过对应的链接来将他分享给任何人了,或者也可以将代码插入在你的文档、文章中去。使用CI或者脚本来创建这样的文件是很简单的事情。
注意到这个文件的核心部分是一个表单(form),以及一些隐藏了的inputs。这些inputs的name
属性值定义了一个J-lunker可识别的属性,value
定义了该属性的值。J-lunker目前可以支持的属性有:
option[show]
:关键字option
表明这里定义的是一个选项,show
是这个选项的名字,它的值是index.html,preview
,这个选项告诉J-lunker在页面准备继续之后,就打开index.html
这个文件,以及打开运行效果预览区。entries[asset/styles.css][content]
:entries
用于定义一个文件,asset/styles.css
是文件名和路径。此属性的值就是文件的内容。注意需要对文件内容做uri编码。title
:此属性用于定义运行结果的页面的标题。
这里给出Jigsaw的生产环境中的live demo的代码作为例子:http://rdk.zte.com.cn/j-lunker。
我们的CI环境每天自动检查两遍http://rdk.zte.com.cn/j-lunker这个站点以确保它是可用的。
如何部署
如果你只需要运行你的代码,你是无需部署J-lunker服务器的,请先阅读这个小节,然后再决定是否继续按照这个小节的说明部署你自己的J-lunker服务器。
这个小节说明了如何部署一台独立的J-lunker服务器,由此,你就可以使用你自己部署的J-lunker服务器来运行你的代码了,被运行的代码不需要发送到公网上,因此被运行的代码的安全性就可以得到保障。
详细步骤如下:
- 克隆或者下载这个仓库的代码,并且解压缩到一个任意目录,最好不要解压到有空格或者中文的目录中。
- J-lunker的服务端需要jre1.8以上,如果你的运行环境上没有,则请安装或者设置JAVA_HOME指向jre1.8。如果你的环境无法安装或者不方便设置环境变量,你也可以将jre1.8拷贝到
proc/bin/jre
目录下。 - 如果你想将J-lunker部署在Windows上,或者只想试一试,那么双击
start.bat
就可以启动J-lunker的服务端和web服务器了。接下来你可以按照这个小节的方法来测试你自己的J-lunker服务器了。别忘了将例子中的http://rdk.zte.com.cn
改为http://localhost:8080
。
如果你想将J-lunker部署在其他操作系统上,则还要继续:
- 配置你的web服务器,这里用nginx作为例子。首先你需要在nginx.conf中的server节点下添加一个反向代理配置:
location /rdk/service {
proxy_pass http://localhost:5812;
}
这个配置项告诉nginx将所有包含/rdk/service
关键字的URL转发给J-lunker的服务器,别忘了需要重启一下nginx。
你可以对比这个文件,它也许可以帮助你解决这方面的配置问题。
- 将
www
目录设置为你的web服务器的根目录,如果你的web服务器已经有一个根了,则可以将下面这几行插入到nginx.conf中的server节点下
location /j-lunker {
root /dir/to/j-lunker/www/;
index index.html index.htm;
}
你可以对比这个文件,它也许可以帮助你解决这方面的配置问题。
- 将web服务器的监听端口改为任何你喜欢的,默认是
8080
。 - 到
proc/bin
目录下,执行sh run.sh
命令,它将启动J-lunker的服务端,再次提醒,J-lunker的服务端需要jre1.8以上。 - 至此大功告成,接下来你可以按照这个小节的方法来测试你自己的J-lunker服务器了。别忘了将例子中的
http://rdk.zte.com.cn
改为http://localhost:8080
。 - 如果你碰到了任何困难,欢迎给我提issue。
共创共建
我非常欢迎你给我推送PR。
J-lunker的默认首页现在非常简陋,而且我不会有太多的时间花在它上面,我很希望有人能够帮我完善它,具体请参考这个issue。
另一个可选的方案是Jigsaw的PopupService
,功能非常强大,可以解决所有弹出场景
源码在这里 https://github.com/rdkmaster/jigsaw/blob/master/src/jigsaw/service/popup.service.ts
它的依赖很少,如果你不想整体使用Jigsaw,也可以拷贝他的源码,到你的工程里使用