README.md 9.12 KB
Newer Older
template admin's avatar
template admin committed
1 2
# ng-template-generator

liujiangnan's avatar
liujiangnan committed
3 4 5 6 7 8 9
angularjs技术框架下的H5互动模板框架脚手架,基于NG-ZORRO实现快速开发基于绘玩云的H5互动课件。

# 使用简介

## 生成项目

* 登录绘玩云课件开发平台:http://staging-teach.ireadabc.com/ 
liujiangnan's avatar
liujiangnan committed
10
* 点击“登录账号,查看我的课件”
liujiangnan's avatar
liujiangnan committed
11
* 输入测试的用户名/密码:developers/12345678
liujiangnan's avatar
liujiangnan committed
12
* 在右上角“个人中心”的下拉菜单里,点击“我的模板” 菜单,然后点击“新建模板”, 填写必要的信息,在“技术选型”一项上选择“Angular”
liujiangnan's avatar
liujiangnan committed
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
* 点击“确定”后,列表页就会出现一个新生成的模板项目
* 在项目的卡片下找到“开发”按钮,则会弹出相对应的git地址

## 获取并启动项目

```
// xxx 是上面项目对应的Git地址
git clone xxx
cd 项目名称/
npm install
npm start

//启动成功后打开浏览器,输入:http://localhost:4200 则可以看到这个项目的初始化效果了

```

## 项目结构

|-- bin
liujiangnan's avatar
liujiangnan committed
32

liujiangnan's avatar
liujiangnan committed
33
|-- dist
liujiangnan's avatar
liujiangnan committed
34

liujiangnan's avatar
liujiangnan committed
35
|-- e2e
liujiangnan's avatar
liujiangnan committed
36

liujiangnan's avatar
liujiangnan committed
37
|-- node_modules
liujiangnan's avatar
liujiangnan committed
38

liujiangnan's avatar
liujiangnan committed
39
|-- publish
liujiangnan's avatar
liujiangnan committed
40

liujiangnan's avatar
liujiangnan committed
41
|-- src
liujiangnan's avatar
liujiangnan committed
42

liujiangnan's avatar
liujiangnan committed
43
| |-- app
liujiangnan's avatar
liujiangnan committed
44

liujiangnan's avatar
liujiangnan committed
45
| | |-- common
liujiangnan's avatar
liujiangnan committed
46

liujiangnan's avatar
liujiangnan committed
47
| | |-- form
liujiangnan's avatar
liujiangnan committed
48

liujiangnan's avatar
liujiangnan committed
49
| | |-- pipes
liujiangnan's avatar
liujiangnan committed
50

liujiangnan's avatar
liujiangnan committed
51
| | |-- play
liujiangnan's avatar
liujiangnan committed
52

liujiangnan's avatar
liujiangnan committed
53
| | |-- services
liujiangnan's avatar
liujiangnan committed
54

liujiangnan's avatar
liujiangnan committed
55
| | |-- style
liujiangnan's avatar
liujiangnan committed
56

liujiangnan's avatar
liujiangnan committed
57
| | |-- app.component.html
liujiangnan's avatar
liujiangnan committed
58

liujiangnan's avatar
liujiangnan committed
59
| | |-- app.component.scss
liujiangnan's avatar
liujiangnan committed
60

liujiangnan's avatar
liujiangnan committed
61
| | |-- app.component.ts
liujiangnan's avatar
liujiangnan committed
62

liujiangnan's avatar
liujiangnan committed
63
| | |-- app.module.ts
liujiangnan's avatar
liujiangnan committed
64

liujiangnan's avatar
liujiangnan committed
65
| |-- assets
liujiangnan's avatar
liujiangnan committed
66

liujiangnan's avatar
liujiangnan committed
67
| |-- environments
liujiangnan's avatar
liujiangnan committed
68

liujiangnan's avatar
liujiangnan committed
69
| |-- services
liujiangnan's avatar
liujiangnan committed
70

liujiangnan's avatar
liujiangnan committed
71
| |-- index.html
liujiangnan's avatar
liujiangnan committed
72

liujiangnan's avatar
liujiangnan committed
73
| |-- main.ts
liujiangnan's avatar
liujiangnan committed
74

liujiangnan's avatar
liujiangnan committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
| |--.......



* 其中 play 文件夹是H5模板展示页面,form文件夹是模板的配置页面
* common文件夹是以往做过的模板积累的一些比较常用的 AngularJs 的组件
* assets文件夹存放模板样式的静态资源,例如小图标、背景图片、字体、样式等等
* 其他文件夹开发者可以不做任何更改

## 开始开发

本脚手架的页面类UI框架是基于  [NG-ZORRO](https://ng.ant.design/docs/introduce/zh "With a Title") 框架实现的,在配置页面(form文件夹),一些表单输入,上传图片等组件也可以使用 NG-ZORRO 现成的组件

### 开发配置页面(form/)

配置页面主要作用是为了呈现多样化模板,提高H5模板的高复用性、灵活性提供的一个配置工具,根据H5模板的设计规划或特性,会规定某些元素是可以配置的,比如背景图片、音频、选项、标题等等等等。(课件制作者) 通过配置页面,就可以灵活的更换这些,从而形成多种多样的课件。


配置页面的开发要求很简单,我们不关心布局、样式、交互等所有实现细节与效果,只需调用两个内置的全局接口即可:

* setData 接口,用于将配置的数据存储到云端。

  此方法是一个异步的方法,接收三个必要参数

  obj: 一个json对象

  callback: 回调函数

  t_name: 模板名称

  一般使用例子如下:

  ```
  // ts语法,不能直接使用js的window对象自定义方法
  (<any> window).courseware.setData(obj, callback, t_name);
  ```

* getData 接口,用于当点击修改的时候将配置的数据从云端获取下来。

  此方法是一个异步的方法,接收两个必要参数 

  > callback: 回调函数, 回调函数里会得到云端保存的数据

  > t_name: 模板名称

  一般使用例子如下:

  ```
  // ts语法,不能直接使用js的window对象自定义方法
  const getData = (<any> window).courseware.getData;
  getData((data) => {
    //data 就是云端获取的数据,也就是setData方法存到云端的那个obj
    //模板开发者需要根据数据,依次填写到表单的相应位置,方便用户二次修改编辑
  });
  ```

### 开发展示页面(play/)

展示页面主要是呈现模板,通过H5技术,实现多样化的交互与展示方式。


展示页面更简单,开发者可以运用各种技术,实现Web端可以实现的任何效果,包括2D、3D、动画、游戏等各种场景,把表单配置的数据获取到,用于渲染相对应的页面即可:
 
* getData 接口,用于当点击修改的时候将配置的数据从云端获取下来。

  此方法是一个异步的方法,接收两个必要参数 

  > callback: 回调函数, 回调函数里会得到云端保存的数据

  > t_name: 模板名称

  一般使用例子如下:

  ```
  // ts语法,不能直接使用js的window对象自定义方法
  const getData = (<any> window).courseware.getData;
  getData((data) => {
    //data 就是云端获取的数据,也就是setData方法存到云端的那个obj
    //模板开发者需要根据数据来渲染或控制展示页面的呈现,达到模板的互动目的 
  });
  ```

liujiangnan's avatar
liujiangnan committed
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
  ### 互动课件

  通过H5的交互方式,我们可以很轻松的制作在线的互动课件,使老师端与学生端实现联动,使在线课堂更具有交互性。

  * onEvent 定义事件:用于自定义同步事件,配合多端互动使用,与sendEvent方法配合使用,用于监听多端发送的同步事件

  参数

  > evtName : 自定义事件的名称

  > callback : 回调函数,回调函数里会得到传过来的数据

  使用例子:

  ```
  const cw = (<any> window).courseware;
  //订阅一个事件
  cw.onEvent('testEvent', (data,next) => {
    console.log(data); 
    //处理事件的同步逻辑

    //在逻辑处理完之后一定要执行next方法,用于解锁事件队列
    next();
  }); 
  ```

  * sendEvent 发送事件:用于自定义同步事件,配合多端互动使用,与onEvent方法配合使用,用于对端发送同步事件

  参数

  > evtName : 自定义事件的名称

  > data : 传递的参数 

  使用例子:

  ```
  const cw = (<any> window).courseware;
  //发送事件
  //这样,所有端(教师、学生) 都会触发 testEvent 方法
  cw.sendEvent('testEvent', 'Hello world'); 

  ```

  * storeAspect 存储切面数据: 课件的切面状态数据;互动课件需要每一个开发者设计切面状态,用于学生进入已经进行的课件,恢复课件同步。例如老师讲图片轮播到第四页,这个时候学生进入教师,要恢复到第四页,才能跟老师同步上课。

  参数

  > data : 保存的数据,一个JSON对象

  使用例子:

  ```
  const cw = (<any> window).courseware; 
  //存储切面数据,用于学生进入教室,同步课堂信息等
  cw.storeAspect({page: 5}); 
  ```

  * getAspect 获取切面数据: 课件的切面状态数据;互动课件需要每一个开发者设计切面状态,用于学生进入已经进行的课件,恢复课件同步。例如老师讲图片轮播到第四页,这个时候学生进入教师,要恢复到第四页,才能跟老师同步上课。

  参数

  > callback : 获取切面数据的回调函数

  使用例子:

  ```
  const cw = (<any> window).courseware; 
  //存储切面数据,用于学生进入教室,同步课堂信息等
  cw.getAspect(function(aspect){
    //恢复切面状态的逻辑
  }); 
  ```

  * 补充项

  1)  有时候我们在实现模板效果的时候,需要当前用户数据,比如,老师会显示某个按钮,而学生不显示,我们可以用如下方式获取教室信息

  ```
  //获取教室信息,值得注意的是获取这个信息一定要再 getData方法之后,或者确保页面完成之后
  let airClassInfo = window["air"].airClassInfo;
  ```

  2)  互动课件的 getData 方法的回调函数里多返回了一个切面参数,类似如下:

  ```
  const getData = (<any> window).courseware.getData;
  getData((data, aspect) => {
    //data 就是云端获取的数据,也就是setData方法存到云端的那个obj
    //aspect 切面参数,用于恢复页面的状态
    //模板开发者需要根据数据来渲染或控制展示页面的呈现,达到模板的互动目的 
  });
  ```


liujiangnan's avatar
liujiangnan committed
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270

  ### 补充方法

  在模板的编辑或展示过程中,还会经常遇到如下两个场景,特提供针对性的解决办法

  1)  表单录入往往需要上传图片、音视频等多媒体文件,所以脚手架内置如下方法,用于获取一个上传到云端的接口方法

  ```
  const uploadUrl = (<any> window).courseware.uploadUrl;
  const uploadData = (<any> window).courseware.uploadData;

  //例如用于NG-ZORRO的上传组件则如下写法:
  <nz-upload class="p-image-uploader" [nzDisabled]="disableUpload"
    [nzShowUploadList]="false"
    nzAccept = "image/*"
    [nzAction]="uploadUrl"    <!-- 注意这里 -->
    [nzData]="uploadData"     <!-- 注意这里 -->
    (nzChange)="handleChange($event)">
  </nz-upload>
liujiangnan's avatar
liujiangnan committed
271

liujiangnan's avatar
liujiangnan committed
272
  ```
liujiangnan's avatar
liujiangnan committed
273

liujiangnan's avatar
liujiangnan committed
274
  2)  在展示页面加载完成的时候,需要调用一下下面的方法,用于释放切换课件的遮罩层
liujiangnan's avatar
liujiangnan committed
275

liujiangnan's avatar
liujiangnan committed
276 277 278 279
  ```
  //此方法为固定写法,
  //其中t_name为模板名称,obj是云端存储的配置数据
  window["air"].hideAirClassLoading(t_name,obj);
liujiangnan's avatar
liujiangnan committed
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
  ```


  ## 打包发布

  模板开发完成之后,要推送到云平台上使用则需要进行打包发布操作

  ```
  npm run publish
  ```
  在项目根目录下执行上述命令,则在 ./publish 目录下生产一个 .zip的压缩包,此时打开云平台
  http://staging-teach.ireadabc.com/ 
  点击“模板管理” 菜单,找到对应的模板卡片,点击“发布”按钮,在弹出的对话框中选中压缩包,然后点击“确定”,上传完成后,则发布就成功了