Skip to content

Commit c11f912

Browse files
zhurczhurc
committed
/example下增加：范例编写原则说明.md
1 parent d71472e commit c11f912

File tree

2 files changed

+283
-0
lines changed

2 files changed

+283
-0
lines changed

‎examples/config.png‎

93.5 KB
Loading

‎examples/范例编写原则说明.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
2+
## 范例编写原则说明
3+
4+
1. [目录结构](#example-1)
5+
2. [完整步骤](#example-2)
6+
3. [范例创建](#example-3)
7+
* [脚本引用](#example-3-1)
8+
* [服务地址](#example-3-2)
9+
* [统一样式](#example-3-3)
10+
4. [缩略图规范](#example-4)
11+
5. [配置文件](#example-5)
12+
6. [离线开发](#example-6)
13+
* [克隆代码](#example-6-1)
14+
* [开发](#example-6-2)
15+
7. [注意事项](#example-7)
16+
17+
18+
<h3 id="example-1">目录结构</h3>
19+
20+
范例目录结构：
21+
```
22+
/example
23+
├─css 公共css目录
24+
├─fonts 公共字体目录
25+
├─img 公共图片目录
26+
├─js 公共js目录
27+
├─section 公共模板目录(包括范例站点的公共头部和主体框架等)
28+
├─data 范例中使用的公共数据
29+
│
30+
├─leaflet leaflet范例目录
31+
│ ├─img 缩略图目录
32+
│ └─config.js 配置文件
33+
├─mapboxgl mapboxgl范例目录
34+
│ ├─img 缩略图目录
35+
│ └─config.js 配置文件
36+
├─openlay openlay范例目录
37+
│ ├─img 缩略图目录
38+
│ └─config.js 配置文件
39+
├─classic classic范例目录
40+
│ ├─img 缩略图目录
41+
│ └─config.js 配置文件
42+
└─3dwebgl 3dwebgl范例目录
43+
├─img 缩略图目录
44+
└─config.js 配置文件
45+
46+
47+
```
48+
49+
<h3 id="example-2">完整步骤</h3>
50+
51+
1. 在对应的客户端根目录下创建范例(具体规范请参考：[范例创建](#example-3))
52+
2. 截取范例缩略图(具体规范请参考：[缩略图规范](#example-4))，并存放到对应的客户端目录下img目录
53+
3. 修改对应的客户端根目录下的`config.js`文件(具体参数请参考：[配置文件](#example-5))
54+
55+
<h3 id="example-3">范例创建</h3>
56+
57+
示例如下：
58+
59+
```html
60+
<!DOCTYPE html>
61+
<html>
62+
<head>
63+
<meta charset="utf-8"/>
64+
<title>quick start</title>
65+
<script type="text/javascript" include="bootstrap-css" src="../js/include-web.js"></script>
66+
<style>
67+
html, body {
68+
width: 100%; height: 100%; margin: 0; padding: 0;
69+
}
70+
#map {
71+
width: 100%; height: 100%;
72+
}
73+
</style>
74+
</head>
75+
<body>
76+
<div id="map"></div>
77+
<script type="text/javascript" src="../../dist/include-leaflet.js"></script>
78+
<script>
79+
//your code
80+
</script>
81+
</body>
82+
</html>
83+
```
84+
为满足多元化使用需求，请将示例中的服务地址修改如下：
85+
```javascript
86+
87+
var host = window.isLocal
88+
? document.location.protocol + "//" + document.location.host
89+
: "http://[public iServer domain/ip]:8090";
90+
var mapUrl=host+"/iserver/services/map-world/rest/maps/World";
91+
//other code
92+
//...
93+
```
94+
95+
<h4 id="example-3-1">脚本引用</h4>
96+
97+
以leaflet为例
98+
99+
引入脚本主要有两个：
100+
101+
`/example/js/include-web.js`: 引入web相关库（如：jquery，bootstrap），所有库都使用公共CDN地址
102+
103+
`/dist/include-xxx.js`: 引入gis相关库（如：leaflet，iclient9-leaflet，d3,echarts），除iclient9的库之外，所有库都建议使用公共CDN地址
104+
105+
106+
* web相关库: 如果需要jquery，bootstrap等web相关库，引入`/example/js`公共目录下的`include-web.js`，引入格式如下：
107+
108+
```html
109+
<script type='text/javascript' include='XXX,XXX' src='../js/include-web.js'></script>
110+
```
111+
* `include`属性: 引入需要使用的库。多个库用","号隔开。没有默认引入的库
112+
* 没有`exclude`属性
113+
* include中参数的具体值参考`include-web.js`
114+
115+
* gis相关库：script标签引入`dist`目录下的`include-leaflet.js`脚本，格式如下：
116+
117+
```html
118+
<script type='text/javascript' include='XXX,XXX' exclude='XXXX,XXXX' src='../../dist/include-leaflet.js'></script>
119+
```
120+
* `include`属性: 需要使用的库(如leaflet相关插件,d3,mapv等)，多个库用","号隔开。默认引入的库不用再次填加。
121+
默认引入的库：客户端（leflet/openlayers/mapboxgl/iclient8c）相关库以及其对应的iclient9相关库。如在本例(leaflet)中，默认引入的是：
122+
`leaflet.js`,`leaflet.css` ,`iclient9-leaflet`，`iclient9-leaflet-css`
123+
* `exclude`属性: 排除默认引入的库，多个库用","号隔开。
124+
* `include`和`exclude`中参数的具体值参考`include-xxx.js`
125+
126+
* 新增库：如果`include-web.js`或者`include-xxx.js`中没有需要的库，则参照以下方法引入三方库：
127+
128+
* 找到`include-web.js`或者`include-xxx.js`中的load方法
129+
* 在load方法末尾添加如下代码:
130+
131+
```javascript
132+
if (inArray(includes, 'xxxx')) {//'xxxx'为引入include-XXX.js的script标签中include属性的值
133+
inputCSS(" libs CDN url");
134+
inputScript("libs CDN url");
135+
}
136+
```
137+
* 建议使用CDN地址。 推荐的公共CDN：[BootCDN](http://www.bootcdn.cn) ([http://www.bootcdn.cn](http://www.bootcdn.cn))
138+
139+
<h4 id="example-3-2">服务地址</h4>
140+
141+
公共iServer服务地址: [http://support.supermap.com.cn:8090](http://support.supermap.com.cn:8090)
142+
143+
可指定其他公网可访问的iServer地址
144+
145+
146+
<h4 id="example-3-3">统一样式</h4>
147+
148+
* 底图建议全屏
149+
* 页面样式优先使用bootstrap，建议不要使用原生的HTML样式
150+
* 等待加载界面
151+
* 引入`include-web.js`脚本的script标签include属性中添加loader
152+
* 显示loader: ```showLoader()```
153+
* 移除loader: ```removeLoader()```
154+
* ...等待补充
155+
156+
157+
158+
159+
<h3 id="example-4">缩略图规范</h3>
160+
161+
* 建议大小：260*208（1:0.8），PNG8格式压缩
162+
* 有动态效果的界面缩略图建议也使用gif格式动图
163+
* 存放目录：对应客户端下的img目录（如`/example/leaflet/img`）
164+
165+
166+
<h3 id="example-5">配置文件</h3>
167+
168+
每个客户端范例目录(如：`/example/leaflet`)下都有一个`config.js`文件，文件在站点初始化时读取。
169+
170+
`config.js`中范例相关的配置项为`exampleConfig`，参数如下：
171+
172+
左边为侧边栏菜单，右边为示例列表
173+
174+
![config](./config.png)
175+
176+
177+
<h3 id="example-6">离线开发</h3>
178+
179+
<div style="color:red">离线开发需要内部权限，非授权用户请直接忽略。</div>
180+
181+
为了使站点和示例在离线状态(如iServer中)能够正常使用，需要增加并修改另一个项目
182+
183+
<h4 id="example-6-1">克隆代码</h4>
184+
185+
离线开发项目地址：[https://gitee.com/isupermap/iclient9-web](https://gitee.com/isupermap/iclient9-web)
186+
187+
* clone代码到本地
188+
* 更改项目目录名为web
189+
* 将项目移动到你的iClient9项目的根目录下,与example同级
190+
191+
<h4 id="example-6-2">开发</h4>
192+
193+
**【脚本的使用跟在线的脚本一样，区别在于三方库全部为本地托管（`/web/libs`)】**
194+
195+
离线开发涉及修改的相关的目录为：`/example`目录，`/web/build`目录，`/web/libs`目录
196+
197+
* `/web`: 站点目录
198+
199+
* `/web/build`：离线引用脚本目录
200+
201+
* `/web/libs`：离线三方库存放目录
202+
203+
* `/example`：范例目录
204+
205+
206+
#### /web
207+
208+
脚本的使用跟在线的脚本一样，只不过路径不同，在具体范例中通过script标签引入`/web/build/`下的脚本
209+
210+
相关的脚本为 `/web/build/include-xxx.js`和 `/web/build/include-web.js`,
211+
212+
* `/web/build/include-web.js`: 引入web相关库（如：jquery，bootstrap）(使用相对路径)，相关库的存放目录为`/web/libs`
213+
214+
* `/web/build/include-xxx.js`: 引入gis相关库（如：iclient9-leaflet，leaflet）(使用相对路径)，相关库的存放目录为`/web/libs`
215+
216+
217+
* 新增库：如果`include-web.js`或者`include-xxx.js`中没有需要的库，则参照以下方法引入三方库：
218+
* 下载三方库到本地
219+
* 将三方库按文件夹移动到`/web/libs`目录
220+
* 在三方库中的js文件中加上三方自己的版权标识(如果原先没有的话)，版权标识包括但不限于版权所有者，开源协议，软件版本等
221+
* 找到`include-web.js`或者`include-xxx.js`中的load方法
222+
* 在load方法末尾添加如下代码，注意路径必须是：`../../web/libs`
223+
224+
```javascript
225+
if (inArray(includes, "xxx")) {//"xxx"为引入include-XXX.js的script标签中include属性的值
226+
inputCSS("../../web/libs/name.css");//name为插件的名称
227+
inputScript("../../web/libs/name.min.js");//name为插件的名称,使用压缩后的脚本
228+
}
229+
```
230+
231+
#### /example
232+
233+
离线环境下范例除了修改引入的脚本（引入/web/build目录下的脚本）外，还需要修改范例服务地址。
234+
```html
235+
<!DOCTYPE html>
236+
<html>
237+
<head>
238+
<meta charset="utf-8"/>
239+
<title>quick start</title>
240+
<script type="text/javascript" include="bootstrap-css" src="../../web/build/include-web.js"></script>
241+
<style>
242+
html, body {
243+
width: 100%; height: 100%; margin: 0; padding: 0;
244+
}
245+
#map {
246+
width: 100%; height: 100%;
247+
}
248+
</style>
249+
</head>
250+
<body>
251+
<div id="map"></div>
252+
<script type="text/javascript" src="../../web/build/include-leaflet.js"></script>
253+
<script>
254+
//your code
255+
</script>
256+
</body>
257+
</html>
258+
```
259+
260+
261+
离线环境中，范例与服务【一般】在同一域下。保证范例在离线时使用的是本地的服务，所以需要修改范例中使用的地址（如地图服务，数据服务等地址）为：`http://localhost:port/xxx`。
262+
263+
而为保证范例同时在离线和在线状态都能正常使用，建议修改示例中的服务地址如下：
264+
265+
```javascript
266+
267+
var host = window.isLocal
268+
? document.location.protocol + "//" + document.location.host
269+
: "http://[public iServer domain/ip]:8090";
270+
var mapUrl=host+"/iserver/services/map-world/rest/maps/World";
271+
//other code
272+
//...
273+
```
274+
275+
<h3 id="example-7">注意事项</h3>
276+
277+
暂无
278+
279+
280+
281+
282+
283+

0 commit comments

Comments
 (0)