Skip to content

Commit e1bc34e

Browse files
liqian7liqian7
committed
common 下 api 参数优化 review by songym
1 parent 8723a27 commit e1bc34e

28 files changed

+144
-141
lines changed

‎src/common/commontypes/BaseTypes.js

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
*/
55

66
/**
7+
* @function SuperMap.inherit
78
* @description 除了 C 和 P 两个必要参数外，可以传递任意数量的对象，这些对象都将继承C。
89
* @memberOf SuperMap
910
* @param {Object} C - 继承的类。
@@ -26,6 +27,7 @@ SuperMap.inherit = function (C, P) {
2627

2728

2829
/**
30+
* @function SuperMap.mixin
2931
* @description 实现多重继承。
3032
* @memberOf SuperMap
3133
* @param {Class|Object} ...mixins - 继承的类。
@@ -78,6 +80,7 @@ SuperMap.mixin = function (...mixins) {
7880
export var StringExt = SuperMap.String = {
7981

8082
/**
83+
* @function SuperMap.String.startsWith
8184
* @description 判断目标字符串是否以指定的子字符串开头。
8285
* @param {string} str - 目标字符串。
8386
* @param {string} sub - 查找的子字符串。
@@ -88,6 +91,7 @@ export var StringExt = SuperMap.String = {
8891
},
8992

9093
/**
94+
* @function SuperMap.String.contains
9195
* @description 判断目标字符串是否包含指定的子字符串。
9296
* @param {string} str - 目标字符串。
9397
* @param {string} sub - 查找的子字符串。
@@ -98,6 +102,7 @@ export var StringExt = SuperMap.String = {
98102
},
99103

100104
/**
105+
* @function SuperMap.String.trim
101106
* @description 删除一个字符串的开头和结尾处的所有空白字符。
102107
* @param {string} str - （可能）存在空白字符填塞的字符串。
103108
* @returns {string} 删除开头和结尾处空白字符后的字符串。
@@ -107,8 +112,9 @@ export var StringExt = SuperMap.String = {
107112
},
108113

109114
/**
115+
* @function SuperMap.String.camelize
110116
* @description 骆驼式("-")连字符的字符串处理。
111-
* 例如: "chicken-head" becomes "chickenHead",
117+
* 例如："chicken-head" becomes "chickenHead",
112118
* "-chicken-head" becomes "ChickenHead"。
113119
* @param {string} str - 要处理的字符串，原始内容不应被修改。
114120
* @returns {string}
@@ -124,9 +130,10 @@ export var StringExt = SuperMap.String = {
124130
},
125131

126132
/**
133+
* @function SuperMap.String.format
127134
* @description 提供带 ${token} 标记的字符串, 返回 context 对象属性中指定标记的属性值。
128135
* @example
129-
* 示例:
136+
* 示例：
130137
* (code)
131138
* 1、template = "${value,getValue}";
132139
* context = {value: {getValue:function(){return Math.max.apply(null,argument);}}};
@@ -204,18 +211,21 @@ export var StringExt = SuperMap.String = {
204211
},
205212

206213
/**
207-
* @description 寻找带 token 的字符串。
214+
* @member {RegExp} [SuperMap.String.tokenRegEx]
215+
* @description 寻找带 token 的字符串，默认为 tokenRegEx=/\$\{([\w.]+?)\}/g。
208216
* @example
209217
* Examples: ${a}, ${a.b.c}, ${a-b}, ${5}
210218
*/
211219
tokenRegEx: /\$\{([\w.]+?)\}/g,
212220

213221
/**
214-
* @description Used to test strings as numbers.
222+
* @member {RegExp} [SuperMap.String.numberRegEx]
223+
* @description 判断一个字符串是否只包含一个数值，默认为 numberRegEx=/^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/。
215224
*/
216225
numberRegEx: /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/,
217226

218227
/**
228+
* @function SuperMap.String.isNumeric
219229
* @description 判断一个字符串是否只包含一个数值。
220230
* @example
221231
* (code)
@@ -231,6 +241,7 @@ export var StringExt = SuperMap.String = {
231241
},
232242

233243
/**
244+
* @function SuperMap.String.numericIf
234245
* @description 把一个看似数值型的字符串转化为一个数值。
235246
* @returns {(number|string)} 如果能转换为数值则返回数值，否则返回字符串本身。
236247
*/
@@ -249,20 +260,21 @@ export var StringExt = SuperMap.String = {
249260
export var NumberExt = SuperMap.Number = {
250261

251262
/**
252-
* @description 格式化数字时默认的小数点分隔符。
253-
* @constant
254-
* @default "."
263+
* @member {string} [SuperMap.Number.decimalSeparator='.']
264+
* @description 格式化数字时默认的小数点分隔符。
265+
* @constant
255266
*/
256267
decimalSeparator: ".",
257268

258269
/**
259-
* @description 格式化数字时默认的千位分隔符。
260-
* @constant
261-
* @default ","
270+
* @member {string} [SuperMap.Number.thousandsSeparator=',']
271+
* @description 格式化数字时默认的千位分隔符。
272+
* @constant
262273
*/
263274
thousandsSeparator: ",",
264275

265276
/**
277+
* @function SuperMap.Number.limitSigDigs
266278
* @description 限制浮点数的有效数字位数。
267279
* @param {number} num - 浮点数。
268280
* @param {integer} sig - 有效位数。
@@ -277,6 +289,7 @@ export var NumberExt = SuperMap.Number = {
277289
},
278290

279291
/**
292+
* @function SuperMap.Number.format
280293
* @description 数字格式化输出。
281294
* @param {number} num - 数字。
282295
* @param {integer} [dec=0] - 数字的小数部分四舍五入到指定的位数。设置为 null 值时小数部分不变。
@@ -344,6 +357,7 @@ if (!Number.prototype.limitSigDigs) {
344357
*/
345358
export var FunctionExt = SuperMap.Function = {
346359
/**
360+
* @function SuperMap.Function.bind
347361
* @description 绑定函数到对象。方便创建 this 的作用域。
348362
* @param {function} func - 输入函数。
349363
* @param {Object} object - 对象绑定到输入函数（作为输入函数的 this 对象）。
@@ -363,6 +377,7 @@ export var FunctionExt = SuperMap.Function = {
363377
},
364378

365379
/**
380+
* @function SuperMap.Function.bindAsEventListener
366381
* @description 绑定函数到对象，在调用该函数时配置并使用事件对象作为第一个参数。
367382
* @param {function} func - 用于监听事件的函数。
368383
* @param {Object} object - this 对象的引用。
@@ -375,6 +390,7 @@ export var FunctionExt = SuperMap.Function = {
375390
},
376391

377392
/**
393+
* @function SuperMap.Function.False
378394
* @description 该函数仅仅返回 false。该函数主要是避免在 IE8 以下浏览中 DOM 事件句柄的匿名函数问题。
379395
* @example
380396
* document.onclick = SuperMap.Function.False;
@@ -385,6 +401,7 @@ export var FunctionExt = SuperMap.Function = {
385401
},
386402

387403
/**
404+
* @function SuperMap.Function.True
388405
* @description 该函数仅仅返回 true。该函数主要是避免在 IE8 以下浏览中 DOM 事件句柄的匿名函数问题。
389406
* @example
390407
* document.onclick = SuperMap.Function.True;
@@ -395,6 +412,7 @@ export var FunctionExt = SuperMap.Function = {
395412
},
396413

397414
/**
415+
* @function SuperMap.Function.Void
398416
* @description 可重用函数，仅仅返回 "undefined"。
399417
* @returns {undefined}
400418
*/
@@ -412,12 +430,12 @@ export var FunctionExt = SuperMap.Function = {
412430
export var ArrayExt = SuperMap.Array = {
413431

414432
/**
415-
* @description 过滤数组，提供了 ECMA-262 标准中 Array.prototype.filter 函数的扩展。
416-
* @see {@link http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter}
433+
* @function SuperMap.Array.filter
434+
* @description 过滤数组，提供了 ECMA-262 标准中 Array.prototype.filter 函数的扩展。详见：{@link http://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/filter}
417435
* @param {Array} array - 要过滤的数组。
418-
* @param {function} callback - 数组中的每一个元素调用该函数。
419-
* 如果函数的返回值为 true，该元素将包含在返回的数组中。该函数有三个参数: 数组中的元素，元素的索引，数组自身。
420-
* 如果设置了可选参数 caller，在调用 callback 时，使用可选参数 caller 设置为 callback 的参数。
436+
* @param {function} callback - 数组中的每一个元素调用该函数。</br>
437+
* 如果函数的返回值为 true，该元素将包含在返回的数组中。该函数有三个参数: 数组中的元素，元素的索引，数组自身。</br>
438+
* 如果设置了可选参数 caller，在调用 callback 时，使用可选参数 caller 设置为 callback 的参数。</br>
421439
* @param {Object} [caller] - 在调用 callback 时，使用参数 caller 设置为 callback 的参数。
422440
* @returns {Array} callback 函数返回 true 时的元素将作为返回数组中的元素。
423441
*/

‎src/common/commontypes/Bounds.js

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -306,7 +306,7 @@ export class Bounds {
306306
* @description 在当前 bounds 上扩展 bounds，支持 point，lanlat 和 bounds。扩展后的 bounds 的范围是两者的结合。
307307
* @example
308308
* var bounds1 = new SuperMap.Bounds(-50,-50,40,40);
309-
* //bounds改变
309+
* //bounds 改变
310310
* bounds.extend(new SuperMap.LonLat(50,60));
311311
* @param {(SuperMap.Geometry.Point|SuperMap.LonLat|SuperMap.Bounds)} object - 可以是 point、lonlat 和 bounds。
312312
*/
@@ -420,7 +420,7 @@ export class Bounds {
420420
* @param {float} x - 传入的 x 坐标值。
421421
* @param {float} y - 传入的 y 坐标值。
422422
* @param {boolean} [inclusive=true] - 是否包含边界。
423-
* @returns {boolean} 传入的 x,y 坐标在当前范围内。
423+
* @returns {boolean} 传入的 x，y 坐标是否在当前范围内。
424424
*/
425425
contains(x, y, inclusive) {
426426
//set default
@@ -558,7 +558,7 @@ export class Bounds {
558558

559559
/**
560560
* @function SuperMap.Bounds.prototype.determineQuadrant
561-
* @description 判断传入坐标在 bounds 范围内的象限。以 bounds 中心点为坐标原点。
561+
* @description 判断传入坐标是否在 bounds 范围内的象限。以 bounds 中心点为坐标原点。
562562
* @example
563563
* var bounds = new SuperMap.Bounds(-180,-90,100,80);
564564
* //str = "tr";
@@ -671,7 +671,7 @@ export class Bounds {
671671
* @description 通过字符串参数创建新的 bounds 的构造函数。
672672
* @example
673673
* var bounds = SuperMap.Bounds.fromString("-180,-90,100,80");
674-
* @param {string} str - 边界字符串，用逗号隔开 (e.g. <i>"5,42,10,45"</i>)。
674+
* @param {string} str - 边界字符串，用逗号隔开（e.g. <i>"5,42,10,45"</i>）。
675675
* @param {boolean} [reverseAxisOrder=false] - 是否反转轴顺序。
676676
* 如果设为true，则倒转顺序（bottom,left,top,right），否则按正常轴顺序（left,bottom,right,top）。
677677
* @returns {SuperMap.Bounds} 返回给定的字符串创建的新的边界对象。
@@ -686,7 +686,7 @@ export class Bounds {
686686
* @description 通过边界框数组创建 Bounds。
687687
* @example
688688
* var bounds = SuperMap.Bounds.fromArray([-180,-90,100,80]);
689-
* @param {Array.<float>} bbox - 边界值数组。(e.g. <i>[5,42,10,45]</i>)。
689+
* @param {Array.<float>} bbox - 边界值数组。（e.g. <i>[5,42,10,45]</i>）。
690690
* @param {boolean} [reverseAxisOrder=false] - 是否是反转轴顺序。如果设为true，则倒转顺序（bottom,left,top,right），否则按正常轴顺序（left,bottom,right,top）。
691691
* @returns {SuperMap.Bounds} 返回根据传入的数组创建的新的边界对象。
692692
*/

‎src/common/commontypes/Credential.js

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22

33
/**
44
* @class SuperMap.Credential
5-
* @classdesc SuperMap 的安全证书类，其中包括 token 等安全验证信息。
6-
* 需要使用用户名和密码在："http://localhost:8090/iserver/services/security/tokens" 下申请 value。
7-
* 获得形如："2OMwGmcNlrP2ixqv1Mk4BuQMybOGfLOrljruX6VcYMDQKc58Sl9nMHsqQaqeBx44jRvKSjkmpZKK1L596y7skQ.." 的 value。
8-
* 目前支持的功能包括：地图服务、专题图、量算、查询、公交换乘、空间分析、网络分析，不支持轮询功能。
5+
* @classdesc SuperMap 的安全证书类，其中包括 token 等安全验证信息。</br>
6+
* 需要使用用户名和密码在："http://localhost:8090/iserver/services/security/tokens" 下申请 value。</br>
7+
* 获得形如："2OMwGmcNlrP2ixqv1Mk4BuQMybOGfLOrljruX6VcYMDQKc58Sl9nMHsqQaqeBx44jRvKSjkmpZKK1L596y7skQ.." 的 value。</br>
8+
* 目前支持的功能包括：地图服务、专题图、量算、查询、公交换乘、空间分析、网络分析，不支持轮询功能。</br>
99
* @param {string} value - 访问受安全限制的服务时用于通过安全认证的验证信息。
1010
* @param {string} [name='token'] - 验证信息前缀，name=value 部分的 name 部分。
1111
* @example

‎src/common/commontypes/Date.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ export var DateExt = SuperMap.Date = {
2121
return function (date) {
2222
return date.toISOString();
2323
};
24-
} else {// //部分浏览器没有，就得自己组合，组合后的字符串规则不变
24+
} else {// 部分浏览器没有，就得自己组合，组合后的字符串规则不变
2525
function pad(num, len) {
2626
var str = num + "";
2727
while (str.length < len) {

‎src/common/commontypes/Events.js

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import {Util} from './Util';
88
* @class SuperMap.Events
99
* @classdesc 事件类。
1010
* @param {Object} object - 当前事件对象被添加到的 JS 对象。
11-
* @param {HTMLElement} element - 响应浏览器事件的 dom 元素。
11+
* @param {HTMLElement} element - 响应浏览器事件的 DOM 元素。
1212
* @param {Array.<string>} eventTypes - 自定义应用事件的数组。
1313
* @param {boolean} [fallThrough=false] - 是否允许事件处理之后向上传递（冒泡），为 false 的时候阻止事件冒泡。
1414
* @param {Object} options - 事件对象选项。
@@ -54,7 +54,7 @@ export class Events {
5454

5555
/**
5656
* @member {HTMLElement} SuperMap.Events.prototype.element
57-
* @description 接受浏览器事件的DOM节点。
57+
* @description 接受浏览器事件的 DOM 节点。
5858
*/
5959
this.element = null;
6060

@@ -71,16 +71,16 @@ export class Events {
7171
this.eventHandler = null;
7272

7373
/**
74-
* @member {boolean} SuperMap.Events.prototype.fallThrough
75-
* @description 是否允许事件处理之后向上传递（冒泡），为false的时候阻止事件冒泡。
74+
* @member {boolean} [SuperMap.Events.prototype.fallThrough=false]
75+
* @description 是否允许事件处理之后向上传递（冒泡），为 false 的时候阻止事件冒泡。
7676
*/
7777
this.fallThrough = fallThrough;
7878

7979
/**
8080
* @member {boolean} [SuperMap.Events.prototype.includeXY=false]
8181
* @description 判断是否让 xy 属性自动创建到浏览器上的鼠标事件，一般设置为 false，如果设置为 true，鼠标事件将会在事件传递过程中自动产生 xy 属性。
82-
* 可根据事件对象的 'evt.object' 属性在相关的事件句柄上调用 getMousePosition 函数。这个选项习惯默认为false的原因在于，当创建一个
83-
* 事件对象，其主要目的是管理。在一个div的相对定位的鼠标事件，将其设为 true 也是有意义的。这个选项也可以用来控制是否抵消缓存。如果
82+
* 可根据事件对象的 'evt.object' 属性在相关的事件句柄上调用 getMousePosition 函数。这个选项习惯默认为 false 的原因在于，当创建一个
83+
* 事件对象，其主要目的是管理。在一个 div 的相对定位的鼠标事件，将其设为 true 也是有意义的。这个选项也可以用来控制是否抵消缓存。如果
8484
* 设为 false 不抵消，如果设为 true，用 this.clearMouseCache() 清除缓存偏移（边界元素偏移，元素在页面的位置偏移）。
8585
* @example
8686
* function named(evt) {
@@ -93,7 +93,7 @@ export class Events {
9393
* @member {Object} SuperMap.Events.prototype.extensions
9494
* @description 事件扩展。Keys 代表事件类型，values 代表事件对象。
9595
* @example
96-
* 以扩展"foostart" 和 "fooend" 事件为例。展示替换css属性为foo的元素的click事件。
96+
* 以扩展 "foostart" 和 "fooend" 事件为例。展示替换 css 属性为 foo 的元素的 click 事件。
9797
*
9898
* SuperMap.Events.foostart = SuperMap.Class({
9999
* initialize: function(target) {
@@ -195,8 +195,8 @@ export class Events {
195195

196196
/**
197197
* @function SuperMap.Events.prototype.attachToElement
198-
* @description 给dom元素绑定浏览器事件。
199-
* @param {HTMLDOMElement} element - 绑定浏览器事件的dom元素。
198+
* @description 给 DOM 元素绑定浏览器事件。
199+
* @param {HTMLDOMElement} element - 绑定浏览器事件的 DOM 元素。
200200
*/
201201
attachToElement(element) {
202202
if (this.element) {
@@ -233,10 +233,10 @@ export class Events {
233233
* @function SuperMap.Events.prototype.on
234234
* @description 在一个相同的范围内注册监听器的方法，此方法调用 register 函数。
235235
* @example
236-
* // 注册一个"loadstart"监听事件
236+
* // 注册一个 "loadstart" 监听事件
237237
* events.on({"loadstart": loadStartListener});
238238
*
239-
* // 同样注册一个"loadstart"监听事件
239+
* // 同样注册一个 "loadstart" 监听事件
240240
* events.register("loadstart", undefined, loadStartListener);
241241
*
242242
* // 同时为对象注册多个监听事件
@@ -246,7 +246,7 @@ export class Events {
246246
* scope: object
247247
* });
248248
*
249-
* // 同时为对象注册多个监听事件，多次调用register方法
249+
* // 同时为对象注册多个监听事件，多次调用 register 方法
250250
* events.register("loadstart", object, loadStartListener);
251251
* events.register("loadend", object, loadEndListener);
252252
*
@@ -315,10 +315,10 @@ export class Events {
315315
* @function SuperMap.Events.prototype.un
316316
* @description 在一个相同的范围内取消注册监听器的方法，此方法调用 unregister 函数。
317317
* @example
318-
* // 移除"loadstart" 事件监听
318+
* // 移除 "loadstart" 事件监听
319319
* events.un({"loadstart": loadStartListener});
320320
*
321-
* // 使用unregister方法移除"loadstart" 事件监听
321+
* // 使用 "unregister" 方法移除 "loadstart" 事件监听
322322
* events.unregister("loadstart", undefined, loadStartListener);
323323
*
324324
* // 取消对象多个事件监听
@@ -381,7 +381,7 @@ export class Events {
381381
* @description 触发一个特定的注册事件。
382382
* @param {string} type - 触发事件类型。
383383
* @param {Event} evt - 事件对象。
384-
* @returns {boolean} 返回监听对象，如果返回是false，则停止监听。
384+
* @returns {boolean} 返回监听对象，如果返回是 false，则停止监听。
385385
*/
386386
triggerEvent(type, evt) {
387387
var listeners = this.listeners[type];

‎src/common/commontypes/LonLat.js

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -109,10 +109,8 @@ export class LonLat {
109109
/**
110110
* @function SuperMap.LonLat.prototype.wrapDateLine
111111
* @description 通过传入的范围对象对坐标对象转换到该范围内。
112-
* 如果经度小于给定范围最小精度，则在原经度基础上加上范围宽度，
113-
* 直到精度在范围内为止，如果经度大于给定范围则在原经度基础上减去范围宽度。
114-
* 换句话说就是将不在经度范围内的坐标转换到范围以内。
115-
* （只会转换 lon，不会转换 lat，主要用于转移到日界线以内）
112+
* 如果经度小于给定范围最小精度，则在原经度基础上加上范围宽度，直到精度在范围内为止，如果经度大于给定范围则在原经度基础上减去范围宽度。
113+
* 即指将不在经度范围内的坐标转换到范围以内（只会转换 lon，不会转换 lat，主要用于转移到日界线以内）。
116114
* @example
117115
* var lonLat1 = new SuperMap.LonLat(420,50);
118116
* var lonLat2 = lonLat1.wrapDateLine(
@@ -156,12 +154,12 @@ export class LonLat {
156154

157155
/**
158156
* @function SuperMap.LonLat.fromString
159-
* @description 通过字符串生成一个 <SuperMap.LonLat> 对象
157+
* @description 通过字符串生成一个 {@link SuperMap.LonLat} 对象。
160158
* @example
161159
* var str = "100,50";
162160
* var lonLat = SuperMap.LonLat.fromString(str);
163161
* @param {string} str - 字符串的格式：Lon+","+Lat。如："100,50"。
164-
* @returns {SuperMap.LonLat} 返回一个 <SuperMap.LonLat> 对象。
162+
* @returns {SuperMap.LonLat} 返回一个 {@link SuperMap.LonLat} 对象。
165163
*/
166164
static fromString(str) {
167165
var pair = str.split(",");

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy