115 |
116 |
117 |
118 | `;
119 | }
120 |
121 | // Good
122 | function greeting(name) {
123 | return 'Hello, \n'
124 | + `${name.firstName} ${name.lastName}`;
125 | }
126 |
127 | // Bad
128 | function greeting(name) {
129 | return `Hello,
130 | ${name.firstName} ${name.lastName}`;
131 | }
132 | ```
133 |
134 |
135 | #### 2.2.2 空格
136 |
137 |
138 | ##### [强制] 使用 `generator` 时，`*` 前面不允许有空格，`*` 后面必须有一个空格。
139 |
140 | 示例：
141 |
142 | ```javascript
143 | // good
144 | function* caller() {
145 | yield 'a';
146 | yield* callee();
147 | yield 'd';
148 | }
149 |
150 | // bad
151 | function * caller() {
152 | yield 'a';
153 | yield *callee();
154 | yield 'd';
155 | }
156 | ```
157 |
158 |
159 | #### 2.2.3 语句
160 |
161 |
162 | ##### [强制] 类声明结束不允许添加分号。
163 |
164 | 解释：
165 |
166 | 与函数声明保持一致。
167 |
168 |
169 | ##### [强制] 类成员定义中，方法定义后不允许添加分号，成员属性定义后必须添加分号。
170 |
171 | 解释：
172 |
173 | 成员属性是当前 **Stage 0** 的标准，如果使用的话，则定义后加上分号。
174 |
175 | 示例：
176 |
177 | ```javascript
178 | // good
179 | class Foo {
180 | foo = 3;
181 |
182 | bar() {
183 |
184 | }
185 | }
186 |
187 | // bad
188 | class Foo {
189 | foo = 3
190 |
191 | bar() {
192 |
193 | }
194 | }
195 | ```
196 |
197 | ##### [强制] `export` 语句后，不允许出现表示空语句的分号。
198 |
199 | 解释：
200 |
201 | `export` 关键字不影响后续语句类型。
202 |
203 | 示例：
204 |
205 | ```javascript
206 | // good
207 | export function foo() {
208 | }
209 |
210 | export default function bar() {
211 | }
212 |
213 |
214 | // bad
215 | export function foo() {
216 | };
217 |
218 | export default function bar() {
219 | };
220 | ```
221 |
222 |
223 | ##### [强制] 属性装饰器后，可以不加分号的场景，不允许加分号。
224 |
225 | 解释：
226 |
227 | 只有一种场景是必须加分号的：当属性 `key` 是 `computed property key` 时，其装饰器必须加分号，否则修饰 `key` 的 `[]` 会做为之前表达式的 `property accessor`。
228 |
229 | 上面描述的场景，装饰器后需要加分号。其余场景下的属性装饰器后不允许加分号。
230 |
231 | 示例：
232 |
233 | ```javascript
234 | // good
235 | class Foo {
236 | @log('INFO')
237 | bar() {
238 |
239 | }
240 |
241 | @log('INFO');
242 | ['bar' + 2]() {
243 |
244 | }
245 | }
246 |
247 | // bad
248 | class Foo {
249 | @log('INFO');
250 | bar() {
251 |
252 | }
253 |
254 | @log('INFO')
255 | ['bar' + 2]() {
256 |
257 | }
258 | }
259 | ```
260 |
261 |
262 | ##### [强制] 箭头函数的参数只有一个，并且不包含解构时，参数部分的括号必须省略。
263 |
264 | 示例：
265 |
266 | ```javascript
267 | // good
268 | list.map(item => item * 2);
269 |
270 | // good
271 | let fetchName = async id => {
272 | let user = await request(`users/${id}`);
273 | return user.fullName;
274 | };
275 |
276 | // bad
277 | list.map((item) => item * 2);
278 |
279 | // bad
280 | let fetchName = async (id) => {
281 | let user = await request(`users/${id}`);
282 | return user.fullName;
283 | };
284 | ```
285 |
286 | ##### [建议] 箭头函数的函数体只有一个单行表达式语句，且作为返回值时，省略 `{}` 和 `return`。
287 |
288 | 如果单个表达式过长，可以使用 `()` 进行包裹。
289 |
290 | 示例：
291 |
292 | ```javascript
293 | // good
294 | list.map(item => item * 2);
295 |
296 | let foo = () => (
297 | condition
298 | ? returnValueA()
299 | : returnValueB()
300 | );
301 |
302 | // bad
303 | list.map(item => {
304 | return item * 2;
305 | });
306 | ```
307 |
308 | ##### [建议] 箭头函数的函数体只有一个 `Object Literal`，且作为返回值时，使用 `()` 包裹。
309 |
310 | 示例：
311 |
312 | ```javascript
313 | // good
314 | list.map(item => ({name: item[0], email: item[1]}));
315 | ```
316 |
317 | ##### [强制] 解构多个变量时，如果超过行长度限制，每个解构的变量必须单独一行。
318 |
319 | 解释：
320 |
321 | 太多的变量解构会让一行的代码非常长，极有可能超过单行长度控制，使代码可读性下降。
322 |
323 | 示例：
324 |
325 | ```javascript
326 | // good
327 | let {
328 | name: personName,
329 | email: personEmail,
330 | sex: personSex,
331 | age: personAge
332 | } = person;
333 |
334 | // bad
335 | let {name: personName, email: personEmail,
336 | sex: personSex, age: personAge
337 | } = person;
338 | ```
339 |
340 |
341 |
342 |
343 |
344 |
345 | ## 3 语言特性
346 |
347 |
348 |
349 |
350 |
351 | ### 3.1 变量
352 |
353 |
354 | #### [强制] 使用 `let` 和 `const` 定义变量，不使用 `var`。
355 |
356 | 解释：
357 |
358 | 使用 `let` 和 `const` 定义时，变量作用域范围更明确。
359 |
360 | 示例：
361 |
362 | ```javascript
363 | // good
364 | for (let i = 0; i < 10; i++) {
365 |
366 | }
367 |
368 | // bad
369 | for (var i = 0; i < 10; i++) {
370 |
371 | }
372 | ```
373 |
374 |
375 |
376 | ### 3.2 解构
377 |
378 |
379 | #### [强制] 不要使用3层及以上的解构。
380 |
381 | 解释：
382 |
383 | 过多层次的解构会让代码变得难以阅读。
384 |
385 | 示例：
386 |
387 | ```javascript
388 | // bad
389 | let {documentElement: {firstElementChild: {nextSibling}}} = window;
390 | ```
391 |
392 | #### [建议] 使用解构减少中间变量。
393 |
394 | 解释：
395 |
396 | 常见场景如变量值交换，可能产生中间变量。这种场景推荐使用解构。
397 |
398 | 示例：
399 |
400 | ```javascript
401 | // good
402 | [x, y] = [y, x];
403 |
404 | // bad
405 | let temp = x;
406 | x = y;
407 | y = temp;
408 | ```
409 |
410 | #### [强制] 仅定义一个变量时不允许使用解构。
411 |
412 | 解释：
413 |
414 | 在这种场景下，使用解构将降低代码可读性。
415 |
416 | 示例：
417 |
418 | ```javascript
419 | // good
420 | let len = myString.length;
421 |
422 | // bad
423 | let {length: len} = myString;
424 | ```
425 |
426 | #### [强制] 如果不节省编写时产生的中间变量，解构表达式 `=` 号右边不允许是 `ObjectLiteral` 和 `ArrayLiteral`。
427 |
428 | 解释：
429 |
430 | 在这种场景下，使用解构将降低代码可读性，通常也并无收益。
431 |
432 | 示例：
433 |
434 | ```javascript
435 | // good
436 | let {first: firstName, last: lastName} = person;
437 | let one = 1;
438 | let two = 2;
439 |
440 | // bad
441 | let [one, two] = [1, 2];
442 | ```
443 |
444 | #### [强制] 使用剩余运算符时，剩余运算符之前的所有元素必需具名。
445 |
446 | 解释：
447 |
448 | 剩余运算符之前的元素省略名称可能带来较大的程序阅读障碍。如果仅仅为了取数组后几项，请使用 `slice` 方法。
449 |
450 | 示例：
451 |
452 | ```javascript
453 | // good
454 | let [one, two, ...anyOther] = myArray;
455 | let other = myArray.slice(3);
456 |
457 | // bad
458 | let [,,, ...other] = myArray;
459 | ```
460 |
461 |
462 |
463 | ### 3.3 模板字符串
464 |
465 |
466 |
467 | #### [强制] 字符串内变量替换时，不要使用 `2` 次及以上的函数调用。
468 |
469 | 解释：
470 |
471 | 在变量替换符内有太多的函数调用等复杂语法会导致可读性下降。
472 |
473 | 示例：
474 |
475 | ```javascript
476 | // good
477 | let fullName = getFullName(getFirstName(), getLastName());
478 | let s = `Hello ${fullName}`;
479 |
480 | // bad
481 | let s = `Hello ${getFullName(getFirstName(), getLastName())}`;
482 | ```
483 |
484 |
485 |
486 | ### 3.4 函数
487 |
488 |
489 | #### [建议] 使用变量默认语法代替基于条件判断的默认值声明。
490 |
491 | 解释：
492 |
493 | 添加默认值有助于引擎的优化，在未来 `strong mode` 下也会有更好的效果。
494 |
495 | 示例：
496 |
497 | ```javascript
498 | // good
499 | function foo(text = 'hello') {
500 | }
501 |
502 | // bad
503 | function foo(text) {
504 | text = text || 'hello';
505 | }
506 | ```
507 |
508 |
509 | #### [强制] 不要使用 `arguments` 对象，应使用 `...args` 代替。
510 |
511 | 解释：
512 |
513 | 在未来 `strong mode` 下 `arguments` 将被禁用。
514 |
515 | 示例：
516 |
517 | ```javascript
518 | // good
519 | function foo(...args) {
520 | console.log(args.join(''));
521 | }
522 |
523 | // bad
524 | function foo() {
525 | console.log([].join.call(arguments));
526 | }
527 | ```
528 |
529 |
530 |
531 |
532 | ### 3.5 箭头函数
533 |
534 |
535 |
536 | #### [强制] 一个函数被设计为需要 `call` 和 `apply` 的时候，不能是箭头函数。
537 |
538 | 解释：
539 |
540 | 箭头函数会强制绑定当前环境下的 `this`。
541 |
542 |
543 |
544 | ### 3.6 对象
545 |
546 |
547 | #### [建议] 定义对象时，如果所有键均指向同名变量，则所有键都使用缩写；如果有一个键无法指向同名变量，则所有键都不使用缩写。
548 |
549 | 解释：
550 |
551 | 目的在于保持所有键值对声明的一致性。
552 |
553 | ```javascript
554 | // good
555 | let foo = {x, y, z};
556 |
557 | let foo2 = {
558 | x: 1,
559 | y: 2,
560 | z: z
561 | };
562 |
563 |
564 | // bad
565 | let foo = {
566 | x: x,
567 | y: y,
568 | z: z
569 | };
570 |
571 | let foo2 = {
572 | x: 1,
573 | y: 2,
574 | z
575 | };
576 | ```
577 |
578 | #### [强制] 定义方法时使用 `MethodDefinition` 语法，不使用 `PropertyName: FunctionExpression` 语法。
579 |
580 | 解释：
581 |
582 | `MethodDefinition` 语法更清晰简洁。
583 |
584 | 示例：
585 |
586 | ```javascript
587 | // good
588 | let foo = {
589 | bar(x, y) {
590 | return x + y;
591 | }
592 | };
593 |
594 | // bad
595 | let foo = {
596 | bar: function (x, y) {
597 | return x + y;
598 | }
599 | };
600 | ```
601 |
602 | #### [建议] 使用 `Object.keys` 或 `Object.entries` 进行对象遍历。
603 |
604 | 解释：
605 |
606 | 不建议使用 `for .. in` 进行对象的遍历，以避免遗漏 `hasOwnProperty` 产生的错误。
607 |
608 | 示例：
609 |
610 | ```javascript
611 | // good
612 | for (let key of Object.keys(foo)) {
613 | let value = foo[key];
614 | }
615 |
616 | // good
617 | for (let [key, value] of Object.entries(foo)) {
618 | // ...
619 | }
620 | ```
621 |
622 | #### [建议] 定义对象的方法不应使用箭头函数。
623 |
624 | 解释：
625 |
626 | 箭头函数将 `this` 绑定到当前环境，在 `obj.method()` 调用时容易导致不期待的 `this`。除非明确需要绑定 `this`，否则不应使用箭头函数。
627 |
628 | 示例：
629 |
630 | ```javascript
631 | // good
632 | let foo = {
633 | bar(x, y) {
634 | return x + y;
635 | }
636 | };
637 |
638 | // bad
639 | let foo = {
640 | bar: (x, y) => x + y
641 | };
642 | ```
643 |
644 |
645 | #### [建议] 尽量使用计算属性键在一个完整的字面量中完整地定义一个对象，避免对象定义后直接增加对象属性。
646 |
647 | 解释：
648 |
649 | 在一个完整的字面量中声明所有的键值，而不需要将代码分散开来，有助于提升代码可读性。
650 |
651 | 示例：
652 |
653 | ```javascript
654 | // good
655 | const MY_KEY = 'bar';
656 | let foo = {
657 | [MY_KEY + 'Hash']: 123
658 | };
659 |
660 | // bad
661 | const MY_KEY = 'bar';
662 | let foo = {};
663 | foo[MY_KEY + 'Hash'] = 123;
664 | ```
665 |
666 |
667 |
668 |
669 |
670 | ### 3.7 类
671 |
672 |
673 |
674 | #### [强制] 使用 `class` 关键字定义一个类。
675 |
676 | 解释：
677 |
678 | 直接使用 `class` 定义类更清晰。不要再使用 `function` 和 `prototype` 形式的定义。
679 |
680 | ```javascript
681 | // good
682 | class TextNode {
683 | constructor(value, engine) {
684 | this.value = value;
685 | this.engine = engine;
686 | }
687 |
688 | clone() {
689 | return this;
690 | }
691 | }
692 |
693 | // bad
694 | function TextNode(value, engine) {
695 | this.value = value;
696 | this.engine = engine;
697 | }
698 |
699 | TextNode.prototype.clone = function () {
700 | return this;
701 | };
702 | ```
703 |
704 | #### [强制] 使用 `super` 访问父类成员，而非父类的 `prototype`。
705 |
706 | 解释：
707 |
708 | 使用 `super` 和 `super.foo` 可以快速访问父类成员，而不必硬编码父类模块而导致修改和维护的不便，同时更节省代码。
709 |
710 | ```javascript
711 | // good
712 | class TextNode extends Node {
713 | constructor(value, engine) {
714 | super(value);
715 | this.engine = engine;
716 | }
717 |
718 | setNodeValue(value) {
719 | super.setNodeValue(value);
720 | this.textContent = value;
721 | }
722 | }
723 |
724 | // bad
725 | class TextNode extends Node {
726 | constructor(value, engine) {
727 | Node.apply(this, arguments);
728 | this.engine = engine;
729 | }
730 |
731 | setNodeValue(value) {
732 | Node.prototype.setNodeValue.call(this, value);
733 | this.textContent = value;
734 | }
735 | }
736 | ```
737 |
738 |
739 |
740 | ### 3.8 模块
741 |
742 |
743 |
744 | #### [强制] `export` 与内容定义放在一起。
745 |
746 | 解释：
747 |
748 | 何处声明要导出的东西，就在何处使用 `export` 关键字，不在声明后再统一导出。
749 |
750 | 示例：
751 |
752 | ```javascript
753 | // good
754 | export function foo() {
755 | }
756 |
757 | export const bar = 3;
758 |
759 |
760 | // bad
761 | function foo() {
762 | }
763 |
764 | const bar = 3;
765 |
766 | export {foo};
767 | export {bar};
768 | ```
769 |
770 | #### [建议] 相互之间无关联的内容使用命名导出。
771 |
772 | 解释：
773 |
774 | 举个例子，工具对象中的各个方法，相互之间并没有强关联，通常外部会选择几个使用，则应该使用命名导出。
775 |
776 | 简而言之，当一个模块只扮演命名空间的作用时，使用命名导出。
777 |
778 |
779 |
780 | #### [强制] 所有 `import` 语句写在模块开始处。
781 |
782 | 示例：
783 |
784 | ```javascript
785 | // good
786 | import {bar} from './bar';
787 |
788 | function foo() {
789 | bar.work();
790 | }
791 |
792 | // bad
793 | function foo() {
794 | import {bar} from './bar';
795 | bar.work();
796 | }
797 | ```
798 |
799 |
800 |
801 |
802 | ### 3.9 集合
803 |
804 |
805 | #### [建议] 对数组进行连接操作时，使用数组展开语法。
806 |
807 | 解释：
808 |
809 | 用数组展开代替 `concat` 方法，数组展开对 `Iterable` 有更好的兼容性。
810 |
811 | 示例：
812 |
813 | ```javascript
814 | // good
815 | let foo = [...foo, newValue];
816 | let bar = [...bar, ...newValues];
817 |
818 | // bad
819 | let foo = foo.concat(newValue);
820 | let bar = bar.concat(newValues);
821 | ```
822 |
823 | #### [建议] 不要使用数组展开进行数组的复制操作。
824 |
825 | 解释：
826 |
827 | 使用数组展开语法进行复制，代码可读性较差。推荐使用 `Array.from` 方法进行复制操作。
828 |
829 | 示例：
830 |
831 | ```javascript
832 | // good
833 | let otherArr = Array.from(arr);
834 |
835 | // bad
836 | let otherArr = [...arr];
837 | ```
838 |
839 | #### [建议] 尽可能使用 `for .. of` 进行遍历。
840 |
841 | 解释：
842 |
843 | 使用 `for .. of` 可以更好地接受任何的 `Iterable` 对象，如 `Map#values` 生成的迭代器，使得方法的通用性更强。
844 |
845 | 以下情况除外：
846 |
847 | 1. 遍历确实成为了性能瓶颈，需要使用原生 `for` 循环提升性能。
848 | 2. 需要遍历过程中的索引。
849 |
850 |
851 | #### [强制] 当键值有可能不是字符串时，必须使用 `Map`；当元素有可能不是字符串时，必须使用 `Set`。
852 |
853 | 解释：
854 |
855 | 使用普通 Object，对非字符串类型的 `key`，需要自己实现序列化。并且运行过程中的对象变化难以通知 Object。
856 |
857 |
858 | #### [建议] 需要一个不可重复的集合时，应使用 `Set`。
859 |
860 | 解释：
861 |
862 | 不要使用 `{foo: true}` 这样的普通 `Object`。
863 |
864 | 示例：
865 |
866 | ```javascript
867 | // good
868 | let members = new Set(['one', 'two', 'three']);
869 |
870 | // bad
871 | let members = {
872 | one: true,
873 | two: true,
874 | three: true
875 | };
876 | ```
877 |
878 |
879 | #### [建议] 当需要遍历功能时，使用 `Map` 和 `Set`。
880 |
881 | 解释：
882 |
883 | `Map` 和 `Set` 是可遍历对象，能够方便地使用 `for...of` 遍历。不要使用使用普通 Object。
884 |
885 | 示例：
886 |
887 | ```javascript
888 | // good
889 | let membersAge = new Map([
890 | ['one', 10],
891 | ['two', 20],
892 | ['three', 30]
893 | ]);
894 | for (let [key, value] of map) {
895 | }
896 |
897 | // bad
898 | let membersAge = {
899 | one: 10,
900 | two: 20,
901 | three: 30
902 | };
903 | for (let key in membersAge) {
904 | if (membersAge.hasOwnProperty(key)) {
905 | let value = membersAge[key];
906 | }
907 | }
908 | ```
909 |
910 | #### [建议] 程序运行过程中有添加或移除元素的操作时，使用 `Map` 和 `Set`。
911 |
912 | 解释：
913 |
914 | 使用 `Map` 和 `Set`，程序的可理解性更好；普通 Object 的语义更倾向于表达固定的结构。
915 |
916 | 示例：
917 |
918 | ```javascript
919 | // good
920 | let membersAge = new Map();
921 | membersAge.set('one', 10);
922 | membersAge.set('two', 20);
923 | membersAge.set('three', 30);
924 | membersAge.delete('one');
925 |
926 | // bad
927 | let membersAge = {};
928 | membersAge.one = 10;
929 | membersAge.two = 20;
930 | membersAge.three = 30;
931 | delete membersAge['one'];
932 | ```
933 |
934 |
935 |
936 |
937 | ### 3.10 异步
938 |
939 |
940 | #### [强制] 回调函数的嵌套不得超过3层。
941 |
942 | 解释：
943 |
944 | 深层次的回调函数的嵌套会让代码变得难以阅读。
945 |
946 | 示例：
947 |
948 | ```javascript
949 | // bad
950 | getUser(userId, function (user) {
951 | validateUser(user, function (isValid) {
952 | if (isValid) {
953 | saveReport(report, user, function () {
954 | notice('Saved!');
955 | });
956 | }
957 | });
958 | });
959 | ```
960 |
961 | #### [建议] 使用 `Promise` 代替 `callback`。
962 |
963 | 解释：
964 |
965 | 相比 `callback`，使用 `Promise` 能够使复杂异步过程的代码更清晰。
966 |
967 | 示例：
968 |
969 | ```javascript
970 | // good
971 | let user;
972 | getUser(userId)
973 | .then(function (userObj) {
974 | user = userObj;
975 | return validateUser(user);
976 | })
977 | .then(function (isValid) {
978 | if (isValid) {
979 | return saveReport(report, user);
980 | }
981 |
982 | return Promise.reject('Invalid!');
983 | })
984 | .then(
985 | function () {
986 | notice('Saved!');
987 | },
988 | function (message) {
989 | notice(message);
990 | }
991 | );
992 | ```
993 |
994 |
995 | #### [强制] 使用标准的 `Promise` API。
996 |
997 | 解释：
998 |
999 | 1. 不允许使用非标准的 `Promise` API，如 `jQuery` 的 `Deferred`、`Q.js` 的 `defer` 等。
1000 | 2. 不允许使用非标准的 `Promise` 扩展 API，如 `bluebird` 的 `Promise.any` 等。
1001 |
1002 | 使用标准的 `Promise` API，当运行环境都支持时，可以把 Promise Lib 直接去掉。
1003 |
1004 |
1005 | #### [强制] 不允许直接扩展 `Promise` 对象的 `prototype`。
1006 |
1007 | 解释：
1008 |
1009 | 理由和 **不允许修改和扩展任何原生对象和宿主对象的原型** 是一样的。如果想要使用更方便，可以用 utility 函数的形式。
1010 |
1011 |
1012 | #### [强制] 不得为了编写的方便，将可以并行的IO过程串行化。
1013 |
1014 | 解释：
1015 |
1016 | 并行 IO 消耗时间约等于 IO 时间最大的那个过程，串行的话消耗时间将是所有过程的时间之和。
1017 |
1018 | 示例：
1019 |
1020 | ```javascript
1021 | requestData().then(function (data) {
1022 | renderTags(data.tags);
1023 | renderArticles(data.articles);
1024 | });
1025 |
1026 | // good
1027 | async function requestData() {
1028 | const [tags, articles] = await Promise.all([
1029 | requestTags(),
1030 | requestArticles()
1031 | ]);
1032 | return {tags, articles};
1033 | }
1034 |
1035 | // bad
1036 | async function requestData() {
1037 | let tags = await requestTags();
1038 | let articles = await requestArticles();
1039 |
1040 | return Promise.resolve({tags, articles});
1041 | }
1042 | ```
1043 |
1044 | #### [建议] 使用 `async/await` 代替 `generator` + `co`。
1045 |
1046 | 解释：
1047 |
1048 | 使用语言自身的能力可以使代码更清晰，也无需引入 `co` 库。
1049 |
1050 | 示例：
1051 |
1052 | ```javascript
1053 | addReport(report, userId).then(
1054 | function () {
1055 | notice('Saved!');
1056 | },
1057 | function (message) {
1058 | notice(message);
1059 | }
1060 | );
1061 |
1062 | // good
1063 | async function addReport(report, userId) {
1064 | let user = await getUser(userId);
1065 | let isValid = await validateUser(user);
1066 |
1067 | if (isValid) {
1068 | let savePromise = saveReport(report, user);
1069 | return savePromise();
1070 | }
1071 |
1072 | return Promise.reject('Invalid');
1073 | }
1074 |
1075 | // bad
1076 | function addReport(report, userId) {
1077 | return co(function* () {
1078 | let user = yield getUser(userId);
1079 | let isValid = yield validateUser(user);
1080 |
1081 | if (isValid) {
1082 | let savePromise = saveReport(report, user);
1083 | return savePromise();
1084 | }
1085 |
1086 | return Promise.reject('Invalid');
1087 | });
1088 | }
1089 | ```
1090 |
1091 |
1092 |
1093 |
1094 |
1095 |
1096 |
1097 |
1098 |
1099 | ## 4 环境
1100 |
1101 |
1102 |
1103 |
1104 |
1105 |
1106 | ### 4.1 运行环境
1107 |
1108 |
1109 | #### [建议] 持续跟进与关注运行环境对语言特性的支持程度。
1110 |
1111 | 解释：
1112 |
1113 | [查看环境对语言特性的支持程度](https://kangax.github.io/compat-table/es6/)
1114 |
1115 | ES 标准的制定还在不断进行中，各种环境对语言特性的支持也日新月异。了解项目中用到了哪些 ESNext 的特性，了解项目的运行环境，并持续跟进这些特性在运行环境中的支持程度是很有必要的。这意味着：
1116 |
1117 | 1. 如果有任何一个运行环境（比如 chrome）支持了项目里用到的所有特性，你可以在开发时抛弃预编译。
1118 | 2. 如果所有环境都支持了某一特性（比如 Promise），你可以抛弃相关的 shim，或无需在预编译时进行转换。
1119 | 3. 如果所有环境都支持了项目里用到的所有特性，你可以完全抛弃预编译。
1120 |
1121 | 无论如何，在选择预编译工具时，你都需要清晰的知道你现阶段将在项目里使用哪些语言特性，然后了解预编译工具对语言特性的支持程度，做出选择。
1122 |
1123 |
1124 | #### [强制] 在运行环境中没有 `Promise` 时，将 `Promise` 的实现 `shim` 到 `global` 中。
1125 |
1126 | 解释：
1127 |
1128 | 当前运行环境下没有 `Promise` 时，可以引入 `shim` 的扩展。如果自己实现，需要实现在 `global` 下，并且与标准 API 保持一致。
1129 |
1130 | 这样，未来运行环境支持时，可以随时把 `Promise` 扩展直接扔掉，而应用代码无需任何修改。
1131 |
1132 |
1133 |
1134 |
1135 |
1136 | ### 4.2 预编译
1137 |
1138 |
1139 | #### [建议] 使用 `babel` 做为预编译工具时，建议使用 `5.x` 版本。
1140 |
1141 | 解释：
1142 |
1143 | 由于 `babel` 最新的 `6` 暂时还不稳定，建议暂时使用 `5.x`。不同的产品，对于浏览器支持的情况不同，使用 `babel` 的时候，需要设置的参数也有一些区别。下面在示例中给出一些建议的参数。
1144 |
1145 | 示例：
1146 |
1147 | ```shell
1148 | ＃ 建议的参数
1149 | --loose all --modules amd --blacklist strict
1150 |
1151 | ＃ 如果需要使用 es7.classProperties、es7.decorators 等一些特性，需要额外的 --stage 0 参数
1152 | --loose all --modules amd --blacklist strict --stage 0
1153 | ```
1154 |
1155 |
1156 | #### [建议] 使用 `babel` 做为预编译工具时，通过 `external-helpers` 减少生成文件的大小。
1157 |
1158 | 解释：
1159 |
1160 | 当 `babel` 在转换代码的过程中发现需要一些特性时，会在该文件头部生成对应的 `helper` 代码。默认情况下，对于每一个经由 `babel` 处理的文件，均会在文件头部生成对应需要的辅助函数，多份文件辅助函数存在重复，占用了不必要的代码体积。
1161 |
1162 | 因此推荐打开`externalHelpers: true`选项，使 `babel` 在转换后内容中不写入 `helper` 相关的代码，而是使用一个外部的 `.js`统一提供所有的 `helper`。对于[external-helpers](https://github.com/babel/babel.github.io/blob/5.0.0/docs/usage/external-helpers.md)的使用，可以有两种方式：
1163 |
1164 | 1. 默认方式：需要通过 `
2858 | ```
2859 |
2860 |
2861 | ##### [建议] 获取元素的直接子元素时使用 `children`。避免使用`childNodes`，除非预期是需要包含文本、注释和属性类型的节点。
2862 |
2863 |
2864 |
2865 |
2866 | #### 4.2.2 样式获取
2867 |
2868 |
2869 | ##### [建议] 获取元素实际样式信息时，应使用 `getComputedStyle` 或 `currentStyle`。
2870 |
2871 | 解释：
2872 |
2873 | 通过 style 只能获得内联定义或通过 JavaScript 直接设置的样式。通过 CSS class 设置的元素样式无法直接通过 style 获取。
2874 |
2875 |
2876 |
2877 |
2878 | #### 4.2.3 样式设置
2879 |
2880 |
2881 | ##### [建议] 尽可能通过为元素添加预定义的 className 来改变元素样式，避免直接操作 style 设置。
2882 |
2883 | ##### [强制] 通过 style 对象设置元素样式时，对于带单位非 0 值的属性，不允许省略单位。
2884 |
2885 | 解释：
2886 |
2887 | 除了 IE，标准浏览器会忽略不规范的属性值，导致兼容性问题。
2888 |
2889 |
2890 |
2891 |
2892 | #### 4.2.4 DOM 操作
2893 |
2894 |
2895 | ##### [建议] 操作 `DOM` 时，尽量减少页面 `reflow`。
2896 |
2897 | 解释：
2898 |
2899 | 页面 reflow 是非常耗时的行为，非常容易导致性能瓶颈。下面一些场景会触发浏览器的reflow：
2900 |
2901 | - DOM元素的添加、修改（内容）、删除。
2902 | - 应用新的样式或者修改任何影响元素布局的属性。
2903 | - Resize浏览器窗口、滚动页面。
2904 | - 读取元素的某些属性（offsetLeft、offsetTop、offsetHeight、offsetWidth、scrollTop/Left/Width/Height、clientTop/Left/Width/Height、getComputedStyle()、currentStyle(in IE)) 。
2905 |
2906 |
2907 | ##### [建议] 尽量减少 `DOM` 操作。
2908 |
2909 | 解释：
2910 |
2911 | DOM 操作也是非常耗时的一种操作，减少 DOM 操作有助于提高性能。举一个简单的例子，构建一个列表。我们可以用两种方式：
2912 |
2913 | 1. 在循环体中 createElement 并 append 到父元素中。
2914 | 2. 在循环体中拼接 HTML 字符串，循环结束后写父元素的 innerHTML。
2915 |
2916 | 第一种方法看起来比较标准，但是每次循环都会对 DOM 进行操作，性能极低。在这里推荐使用第二种方法。
2917 |
2918 |
2919 |
2920 |
2921 | #### 4.2.5 DOM 事件
2922 |
2923 |
2924 | ##### [建议] 优先使用 `addEventListener / attachEvent` 绑定事件，避免直接在 HTML 属性中或 DOM 的 `expando` 属性绑定事件处理。
2925 |
2926 | 解释：
2927 |
2928 | expando 属性绑定事件容易导致互相覆盖。
2929 |
2930 |
2931 | ##### [建议] 使用 `addEventListener` 时第三个参数使用 `false`。
2932 |
2933 | 解释：
2934 |
2935 | 标准浏览器中的 addEventListener 可以通过第三个参数指定两种时间触发模型：冒泡和捕获。而 IE 的 attachEvent 仅支持冒泡的事件触发。所以为了保持一致性，通常 addEventListener 的第三个参数都为 false。
2936 |
2937 |
2938 | ##### [建议] 在没有事件自动管理的框架支持下，应持有监听器函数的引用，在适当时候（元素释放、页面卸载等）移除添加的监听器。
2939 |
2940 |
2941 |
2942 |
--------------------------------------------------------------------------------
~\`\`）生成属性值或变量，其中包含的字符串两侧的引号*尽量*（SHOULD）使用单引号（`'`）。
373 |
374 | ***
375 |
376 | ## 注释
377 |
378 | 单行注释*尽量*（SHOULD）使用 `//` 方式。
379 |
380 | ```less
381 | // Hide everything
382 | * {
383 | display: none;
384 | }
385 | ```
386 |
--------------------------------------------------------------------------------
/e-json.md:
--------------------------------------------------------------------------------
1 | # E-JSON数据传输标准
2 |
3 |
4 | ## 简介
5 |
6 | E-JSON的设计目标是使业务系统向浏览器端传递的JSON数据保持一致，容易被理解和处理，并兼顾传输的数据量。E-JSON依托于http协议（rfc2616）与JSON数据交换格式（rfc4627）。
7 |
8 | ### 编撰
9 |
10 | erik, 欧阳先伟
11 |
12 |
13 | ### 评审
14 |
15 | 曹特磊，蓝晓斌，李铮，林攀辉，童遥，王志寿，严俊羿
16 |
17 |
18 | ### 要求
19 |
20 | 在本文档中，使用的关键字会以中文+括号包含的关键字英文表示：必须(MUST)。关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"被定义在rfc2119中。
21 |
22 |
23 |
24 |
25 |
26 | ## JSON数据类型
27 |
28 | JSON（JavaScript Object Notation）是一种轻量级，基于文本，语言无关的数据交换格式。其包括了基本数据类型4种和复合数据类型2种，共6种数据类型。在下面章节中，JSON数据类型的表示法为JSON+空格+数据类型，如：JSON Array。
29 |
30 | 传输的数据，包括对象属性以及数组成员， *必须(MUST)* 是6种JSON数据类型之一。 *杜绝(MUST NOT)* 使用function、Date等js对象类型。
31 |
32 |
33 | ### 基本数据类型
34 |
35 | - Number可以表示整数和浮点数。
36 | - Boolean可以表示真假，值为true或false。
37 | - String表示一个字符串。
38 | - Null通常用于表示空对象。
39 |
40 | "true"和true，这两个数据代表的是不同的数据类型。非字符串类型数据输出时一定 *不要(MUST NOT)* 为两端加上双引号，否则可能产生不希望的后果（如if中判断"false"的结果是true）。其他容易产生错误的例子如：0和"0"等。
41 |
42 |
43 |
44 |
45 | ### 复合数据类型
46 |
47 | Object是无序的集合，以键值对的方式保持数据。一个Object中包含零到多个name/value的数据，数据间以逗号(,)分隔。name为String类型，value可以是任意类型的数据。
48 |
49 | Object的最后一个元素之后一定 *不要(MUST NOT)* 加上分隔符的逗号，否则可能导致解析出错。
50 |
51 | Array(数组)为多个值的有序集合，数组元素间以逗号(,)分隔。
52 |
53 |
54 |
55 |
56 | ## http响应头
57 |
58 |
59 | ### status
60 |
61 | http响应的status *必须(MUST)* 为200。通常JSON数据被用于通过XMLHttpRequest对象访问，通过javascript进行处理。返回错误的状态码可能导致错误不被响应，数据不被处理。
62 |
63 |
64 |
65 |
66 | ### Content-Type
67 |
68 | Content-Type字段定义了响应体的类型。一般情况下，浏览器会根据该类型对内容进行正确的处理。对于传输JSON数据的响应，Content-Type *推荐(RECOMMENDED)* 设置为"text/javascript"或"text/plain"。 *避免(MUST NOT)* 将Context-Type设置为text/html，否则可能导致安全问题。
69 |
70 | Content-Type中可以指定字符集。通常 *需要(SHOULD)* 明确指定一个字符集。如果是通过XMLHTTPRequest请求的数据，并且字符编码为UTF-8时，可以不指定字符集。
71 |
72 |
73 | #### Context-Type示例
74 |
75 | text/javascript;charset=UTF-8
76 |
77 |
78 |
79 |
80 |
81 |
82 | ## 数据字段
83 |
84 | 返回的数据包含在http响应体中。数据 *必须(MUST)* 是一个JSON Object。该Object可能包含3个字段：status，statusInfo，data。
85 |
86 |
87 | ### status
88 |
89 | status字段 *必须(MUST)* 是一个不小于0的JSON Number整数，表示请求的状态。这个字段 *可以(SHOULD)* 被省略，省略时和为0时表示同一含义。
90 |
91 | 0：表示server端理解了请求，成功处理并返回。
92 |
93 | 非0：表示发生错误。 *可以(SHOULD)* 根据错误类型扩展错误码。
94 |
95 |
96 | #### 一个成功请求的status字段
97 |
98 | ```json
99 | {
100 | "status": 0,
101 | "data": "hello world!"
102 | }
103 | ```
104 |
105 |
106 |
107 |
108 | ### statusInfo
109 |
110 | statusInfo字段 *通常(SHOULD)* 是一个JSON String或JSON Object，表示除了请求状态外server端想要对status做出的说明，使client端能够获取更多信息进行后续处理。这个字段是 *可选的(OPTIONAL)* 。下面的两个例子中，statusInfo字段的信息都可以用于client端程序的后续处理，但是粒度和处理方式会有不同。
111 |
112 |
113 | #### client端参数错误的statusInfo
114 |
115 | 简单说明的statusInfo：
116 |
117 | ```json
118 | {
119 | "status": 1,
120 | "statusInfo": "参数错误"
121 | }
122 | ```
123 |
124 | 具有更多信息的statusInfo：
125 |
126 | ```json
127 | {
128 | "status": 1,
129 | "statusInfo": {
130 | "text": "参数错误",
131 | "parameters": {
132 | "email": "电子邮件格式不正确"
133 | }
134 | }
135 | }
136 | ```
137 |
138 |
139 |
140 |
141 | ### data
142 |
143 | data字段可以是除JSON Null之外的任意JSON类型，表示请求返回的数据主体。这个字段是 *可选的(OPTIONAL)* 。数据主体data包含了在请求成功时有意义的数据。
144 |
145 |
146 | #### 一个查询姓名请求的返回数据
147 |
148 | ```json
149 | {
150 | "status": 0,
151 | "data": "Lily"
152 | }
153 | ```
154 |
155 |
156 |
157 |
158 |
159 |
160 | ## 数据场景
161 |
162 | 本章为常见数据场景定义了通用的标准数据格式，用于数据传输和使用。额外地，本章为部分可能大数据量传输的数据场景定义了变通数据格式。变通数据格式可在数据解析阶段转换成标准数据格式。
163 |
164 | 变通数据格式 *必须(MUST)* 是一个JSON Object，其中 *必须(MUST)* 包含e-type属性和data属性。e-type属性标识数据类型，便于对数据进行解析；data属性包含变通后的数据。变通数据 *可以(MAY)* 包含其他的属性，标识数据的其他扩展信息。
165 |
166 | 变通数据格式的e-type属性定义了table值。e-type属性可以使用者扩展其他属性值，扩展的属性值 *必须(MUST)* 以“项目缩写-名称”命名，如“fc-list”，自主解析。
167 |
168 |
169 | ### 日期类型
170 |
171 | 日期类型不属于JSON数据类型。对于日期类型，我们 *必须(MUST)* 使用JSON String来表示。为了让日期能够更容易的被显示和被解析，对于日期我们 *应当(SHOULD)* 使用更适合internet的格式，遵循rfc3339。
172 |
173 |
174 | #### 数据场景：日期
175 |
176 | ```json
177 | {
178 | "status": 0,
179 | "data": "2010-10-10"
180 | }
181 | ```
182 |
183 |
184 |
185 |
186 | ### 记录
187 |
188 | 记录代表二维表中的一行，通常用于表示某个具体事务抽象的属性。标准记录数据 *必须(MUST)* 为一个JSON Object，记录的主键命名 *必须(MUST)* 为“id”。单条记录数据不包含变通数据格式。
189 |
190 |
191 | #### 数据场景：记录
192 |
193 | ```json
194 | {
195 | "id": 250,
196 | "name": "erik",
197 | "sex": 1,
198 | "age": 18
199 | }
200 | ```
201 |
202 |
203 |
204 |
205 | ### 二维表
206 |
207 | 二维表类型表识为table，是关系模型的主要数据结构。二维表结构具有变通数据格式。标准二维表数据 *必须(MUST)* 以一维JSON Array形式表示，JSON Array中每一项是一个JSON Object，代表一条记录。JSON Object的每个成员代表一个字段。每条记录的主键命名 *必须(MUST)* 为"id"。
208 |
209 | 在标准二维表中，字段名在每条记录中都被传输，会造成额外的数据量传输。这个问题会随着记录数的增大会更加突出。为了减少传输数据量，变通格式使用二维JSON Array传输数据，扩展fields属性用于字段说明。fields字段为JSON Array。
210 |
211 |
212 | #### 数据场景：标准二维表
213 |
214 | ```json
215 | [
216 | {
217 | "id": 250,
218 | "name": "erik",
219 | "sex": 1,
220 | "age": 18
221 | },
222 | {
223 | "id": 251,
224 | "name": "欧阳先伟",
225 | "sex": 1,
226 | "age": 28
227 | }
228 | ]
229 | ```
230 |
231 |
232 | #### 数据场景：变通二维表
233 |
234 | ```json
235 | {
236 | "e-type": "table",
237 | "fields": ["id", "name", "sex", "age"],
238 | "data": [
239 | [250, "erik", 1, 18],
240 | [251, "欧阳先伟", 1, 28]
241 | ]
242 | }
243 | ```
244 |
245 |
246 |
247 |
248 | ### 数据页
249 |
250 | 数据页是列表数据常用的数据方式，可能通过查询或翻页获得数据。数据页是二维表数据的包装，包含列表数据本身更多的信息。
251 |
252 | 数据页 *必须(MUST)* 是一个JSON Object，其中 *必须(MUST)* 包含的属性为data。data是一个二维表。数据页可以包括一些 *可选(OPTIONAL)* 的属性，表示当前数据页的信息。下表列举了数据页的可选属性。
253 |
254 |
255 | ### 数据页可选属性
256 |
257 |
258 | + {Number} page - 当前页码，计数 *必须(MUST)* 为不小于0的整数，从0开始。
259 | + {Number} pageSize - 每页显示条数， *必须(MUST)* 大于0。
260 | + {Number} total - 列表总记录数， *必须(MUST)* 为不小于0的整数。表示当前条件下所有记录的数目，非本页的记录数。
261 | + {String} orderBy - 列表排序规则。多个排序规则之间以逗号分割（,）；正序或倒序以asc或desc表示，与字段名之间以一个空格间隔。例："id desc,name asc"
262 | + {String} keyword - 列表所属的搜索关键字。
263 | + {Object} condition - 列表所属的搜索条件集合。属性中可以包含或不包含keyword字段，如果不包含， *建议(RECOMMMANDED)* 在解析的时候附加搜索关键字keyword条件。
264 |
265 |
266 | #### 数据场景：数据页
267 |
268 | ```json
269 | {
270 | "page": 0,
271 | "pageSize": 30,
272 | "keyword": "",
273 | "data": [
274 | {
275 | "id": 250,
276 | "name": "erik",
277 | "sex": 1,
278 | "age": 18
279 | },
280 | {
281 | "id": 251,
282 | "name": "欧阳先伟",
283 | "sex": 1,
284 | "age": 28
285 | }
286 | ]
287 | }
288 | ```
289 |
290 |
291 |
292 | ### 键/值对象
293 |
294 | 对于在一个JSON Object中表示键/值：
295 |
296 | + 键的属性名 *必须(MUST)* 为name， *杜绝(MUST NOT)* 使用key或k
297 | + 值的属性名 *必须(MUST)* 为value， *杜绝(MUST NOT)* 使用v。
298 |
299 |
300 | #### 数据场景：键/值对象
301 |
302 | ```json
303 | {
304 | "name": "BMW",
305 | "value": 1
306 | }
307 | ```
308 |
309 |
310 |
311 | ### 键/值有序集合
312 |
313 | 键/值有序集合表示对事务或逻辑类型的抽象与分类。常见的应用场景有单选复选框集合，下拉菜单等。
314 |
315 | 标准的键/值有序集合是一个JSON Array，集合中的每一项是一个JSON Object。项 *必须(MUST)* 包含name和value属性。 *可以(MAY)* 通过其他的属性修饰每一项的特殊信息，如selected。
316 |
317 |
318 | #### 数据场景：键/值有序集合
319 |
320 | ```json
321 | [
322 | {
323 | "name": "BMW",
324 | "value": 1
325 | },
326 | {
327 | "name": "Benz",
328 | "value": 2,
329 | "selected": true
330 | }
331 | ]
332 | ```
333 |
334 |
335 |
336 |
337 | ### 树
338 |
339 | 树形数据用于表示层叠的数据结构。树型数据 *必须(MUST)* 是一个JSON Object，代表树型数据的根节点。下面是标准定义的可选节点列表，不在列表中的属性 *可以(SHOULD)* 自行扩展。
340 |
341 |
342 | ### 树型数据结构的可选节点属性
343 |
344 |
345 | + {Number|String} id - 节点的唯一标识。
346 | + {String} text - 名称或用于显示的字符串。
347 | + {Array} children - 子节点列表。
348 |
349 |
350 | #### 数据场景：树型数据
351 |
352 | ```json
353 | {
354 | "id": 1,
355 | "text": "中国",
356 | "children": [
357 | {
358 | "id": 10,
359 | "text": "北京",
360 | "children": [
361 | {
362 | "id": 100,
363 | "text": "东城区"
364 | },
365 | {
366 | "id": 101,
367 | "text": "西城区"
368 | },
369 | {
370 | "id": 102,
371 | "text": "海淀区"
372 | }
373 | ......
374 | ]
375 | },
376 | {
377 | "id": 31,
378 | "text": "海南",
379 | "children": [
380 | {
381 | "id": 600,
382 | "text": "海口"
383 | },
384 | {
385 | "id": 601,
386 | "text": "三亚"
387 | },
388 | {
389 | "id": 602,
390 | "text": "五指山"
391 | }
392 | ......
393 | ]
394 | }
395 | ......
396 | ]
397 | }
398 | ```
399 |
400 |
401 | ## 引用
402 |
403 | + [RFC 2119] "Key words for use in RFCs to Indicate Requirement Levels"
404 | + [RFC 4627] "The application/json Media Type for JavaScript Object Notation (JSON)"
405 | + [RFC 2616] "Hypertext Transfer Protocol"
406 | + [RFC 3339] "Date and Time on the Internet: Timestamps"
407 |
408 |
--------------------------------------------------------------------------------
/module.md:
--------------------------------------------------------------------------------
1 | # 模块和加载器规范
2 |
3 | ## 简介
4 |
5 | 该文档主要的设计目标是定义前端代码的模块规范，便于开发资源的共享和复用。该文档
6 | 在 [amdjs](https://github.com/amdjs/amdjs-api/wiki) 规范的基础上，进行了更细粒度的规范化。
7 |
8 | ### 编撰
9 |
10 | 李玉北、erik、黄后锦、王杨、张立理、赵雷、陈新乐、顾轶灵、林志峰、刘恺华。
11 |
12 | 本文档由`商业运营体系前端技术组`审校发布。
13 |
14 | ### 要求
15 |
16 | 在本文档中，使用的关键字会以中文+括号包含的关键字英文表示： 必须(MUST) 。关键字"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL"被定义在rfc2119中。
17 |
18 | ## 模块定义
19 |
20 | 模块定义 *必须(MUST)* 采用如下的方式：
21 |
22 | ```javascript
23 | define( factory );
24 | ```
25 |
26 | 推荐采用`define(factory)`的方式进行`模块定义`。使用匿名`moduleId`，从而保证开发中模块与路径相关联，有利于模块的管理与整体迁移。
27 |
28 | SHOULD NOT使用如下的方式：
29 |
30 | ```javascript
31 | define( moduleId, deps, factory );
32 | ```
33 |
34 | ### moduleId
35 |
36 | `moduleId`的格式应该符合 [amdjs](https://github.com/amdjs/amdjs-api/wiki/AMD) 中的约束条件。
37 |
38 | 1. `moduleId`的类型应该是`string`，并且是由`/`分割的一些`term`来组成。例如：`this/is/a/moduleId`。
39 | 2. `term`应该符合`[a-zA-Z0-9_]+`这个规则。
40 | 3. `moduleId`不应该有`.js`后缀。
41 | 4. `moduleId`应该跟文件的路径保持一致。
42 |
43 | `moduleId`在实际使用（如`require`）的时候，又可以分为如下几种类型：
44 |
45 | 1. `relative moduleId`：是以`./`或者`../`开头的`moduleId`。例如：`./foo`, `../../bar`。
46 | 2. `top-level moduleId`：除上面两种之外的`moduleId`。例如`foo`，`bar/a`，`bar/b`。
47 |
48 | 在模块定义的时候，`define`的第一个参数如果是`moduleId`， *必须(MUST)* 是`top-level moduleId`， *不允许(MUST NOT)* 是`relative moduleId`。
49 |
50 | ### factory
51 |
52 | #### AMD风格与CommonJS风格
53 |
54 | 模块的`factory`有两种风格，`AMD推荐的风格`和`CommonJS的风格`。`AMD推荐的风格`通过返回一个对象做为模块对象，`CommonJS的风格`通过对`module.exports`或`exports的属性`赋值来达到暴露模块对象的目的。
55 |
56 | *建议(SHOULD)* 使用`AMD推荐的风格`，其更符合Web应用的习惯，对模块的数据类型也便于管理。
57 |
58 |
59 | ```javascript
60 | // AMD推荐的风格
61 | define( function( require ) {
62 | return {
63 | method: function () {
64 | var foo = require("./foo/bar");
65 | // blabla...
66 | }
67 | };
68 | });
69 |
70 | // CommonJS的风格
71 | define( function( require, exports, module ) {
72 | module.exports = {
73 | method: function () {
74 | var foo = require("./foo/bar");
75 | // blabla...
76 | }
77 | };
78 | });
79 | ```
80 |
81 | #### 参数
82 |
83 | 模块的`factory`默认有三个参数，分别是`require`, `exports`, `module`。
84 |
85 | ```javascript
86 | define( function( require, exports, module ) {
87 | // blabla...
88 | });
89 | ```
90 |
91 | 使用`AMD推荐风格`时，`exports`和`module`参数可以省略。
92 |
93 | ```javascript
94 | define( function( require ) {
95 | // blabla...
96 | });
97 | ```
98 |
99 | 开发者 *不允许(MUST NOT)* 修改`require`, `exports`, `module`参数的形参名称。下面就是错误的用法：
100 |
101 | ```javascript
102 | define( function( req, exp, mod ) {
103 | // blablabla...
104 | });
105 | ```
106 |
107 | #### 类型
108 |
109 | `factory`可以是任何类型，一般来说常见的就是三种类型`function`, `string`, `object`。当`factory`不是`function`时，将直接做为模块对象。
110 |
111 | ```javascript
112 | // src/foo.js
113 | define( "hello world. I'm {name}" );
114 |
115 | // src/bar.js
116 | define( {"name": "fe"} );
117 | ```
118 |
119 | 上面这两种写法等价于：
120 |
121 | ```javascript
122 | // src/foo.js
123 | define( function(require) {
124 | return "hello world. I'm {name}";
125 | });
126 |
127 | // src/bar.js
128 | define( function(require) {
129 | return {"name": "fe"};
130 | } );
131 | ```
132 |
133 | #### require
134 |
135 | `require`这个函数的参数是`moduleId`，通过调用`require`我们就可以引入其他的模块。`require`有两种形式：
136 |
137 | ```javascript
138 | require( {string} moduleId );
139 | require( {Array} moduleIdList, {Function} callback );
140 | ```
141 |
142 | `require`存在`local require`和`global require`的区别。
143 |
144 | 在`factory`内部的`require`是`local require`，如果`require`参数中的`moduleId`的类型是`relative moduleId`，那么相对的是当前`模块id`。
145 |
146 | 在全局作用域下面调用的`require`是`global require`，`global require`不支持`relative moduleId`。
147 |
148 | ```javascript
149 | // src/foo.js
150 | define( function( require ) {
151 | var bar = require("./bar"); // local require
152 | });
153 |
154 | // src/main.js
155 | // global require
156 | require( ['foo', 'bar'], function ( foo, bar ) {
157 | // blablalbla...
158 | });
159 | ```
160 |
161 | #### exports
162 |
163 | `exports`是使用`CommonJS风格`定义模块时，用来公开当前模块对外提供的API的。另外也可以忽略`exports`参数，直接在`factory`里面返回自己想公开的API。例如下面三种写法功能是一样的：
164 |
165 | ```javascript
166 | define( function( require, exports, module ) {
167 | exports.name = "foo";
168 | });
169 |
170 | define( function( require, exports, module ) {
171 | return { "name" : "foo" };
172 | });
173 |
174 | define( function( require, exports, module ) {
175 | module.exports.name = "foo";
176 | });
177 | ```
178 |
179 | `module`是当前模块的一些信息，一般不会用到。其中`module.exports === exports`。
180 |
181 | ### dependencies
182 |
183 | 模块和模块的依赖关系需要通过`require`函数调用来保证。
184 |
185 | ```javascript
186 | // src/js/ui/Button.js
187 | define( function( require, exports, module ) {
188 | require("css!../../css/ui/Button.css");
189 | require("tpl!../../tpl/ui/Button.tpl.html");
190 |
191 | var Control = require("ui/Control");
192 |
193 | /**
194 | * @constructor
195 | * @extends {Control}
196 | */
197 | function Button() {
198 | Control.call(this);
199 |
200 | var foo = require("./foo");
201 | foo.bar();
202 | }
203 | baidu.inherits(Button, Control);
204 |
205 | ...
206 |
207 | // exports = Button;
208 | // return Button;
209 | });
210 | ```
211 |
212 | 具体实现的时候是通过正则表达式分析`factory`的函数体来识别出来的。因此为了保证识别的正确率，请尽量
213 | 避免在函数体内定义`require`变量或者`require`属性。例如不要这么做：
214 |
215 | ```javascript
216 | var require = function(){};
217 | var a = {require:function(){}};
218 | a.require("./foo");
219 | require("./bar");
220 | ```
221 |
222 |
223 | ## 模块加载器配置
224 |
225 | `AMD Loader`应该支持如下的配置，更新配置的时候，写法如下：
226 |
227 | ```html
228 |
229 |
234 | ```
235 |
236 | ### baseUrl
237 |
238 | 类型应该是`string`。在`ID-to-path`的阶段，会以`baseUrl`作为根目录来计算。如果没有配置的话，就默认以当前页面所在的目录为`baseUrl`。
239 | 如果`baseUrl`的值是`relative`，那么相对的是当前页面，而不是`AMD Loader`所在的位置。
240 |
241 | ### paths
242 |
243 | 类型应该是`Object.
83 |
84 |
85 |
86 |
87 | );
88 | }
89 | }
90 | ```
91 |
92 | ## 组件声明
93 |
94 | - [强制]使用ES Class声明组件，禁止使用`React.createClass`。
95 |
96 | [React v15.5.0](https://facebook.github.io/react/blog/2017/04/07/react-v15.5.0.html)已经弃用了`React.createClass`函数。
97 |
98 | ```javascript
99 | // Bad
100 | let Message = React.createClass({
101 | render() {
102 | return {this.state.message};
103 | }
104 | });
105 |
106 | // Good
107 | class Message extends PureComponent {
108 | render() {
109 | return {this.state.message};
110 | }
111 | }
112 | ```
113 |
114 | - [强制]不使用`state`的组件声明为函数组件。
115 |
116 | 函数组件在React中有着特殊的地位，在将来也有可能得到更多的内部优化。
117 |
118 | ```javascript
119 | // Bad
120 | class NextNumber {
121 | render() {
122 | return {this.props.value + 1}
123 | }
124 | }
125 |
126 | // Good
127 | let NextNumber = ({value}) => {value + 1};
128 | ```
129 |
130 | - [强制]所有组件均需声明`propTypes`。
131 |
132 | `propsTypes`在提升组件健壮性的同时，也是一种类似组件的文档的存在，有助于代码的阅读和理解。
133 |
134 | - [强制]对于所有非`isRequired`的属性，在`defaultProps`中声明对应的值。
135 |
136 | 声明初始值有助于对组件初始状态的理解，也可以减少`propTypes`对类型进行校验产生的开销。
137 |
138 | 对于初始没有值的属性，应当声明初始值为`null`而非`undefined`。
139 |
140 | - [强制]如无必要，使用静态属性语法声明`propsTypes`、`contextTypes`、`defaultProps`和`state`。
141 |
142 | 仅当初始`state`需要从`props`计算得到的时候，才将`state`的声明放在构造函数中，其它情况下均使用静态属性声明进行。
143 |
144 | - [强制]依照规定顺序编排组件中的方法和属性。
145 |
146 | 按照以下顺序编排组件中的方法和属性：
147 |
148 | 1. `static displayName`
149 | 2. `static propTypes`
150 | 3. `static contextTypes`
151 | 4. `state defaultProps`
152 | 5. `static state`
153 | 6. 其它静态的属性
154 | 7. 用于事件处理并且以属性的方式（`onClick = e => {...}`）声明的方法
155 | 8. 其它实例属性
156 | 9. `constructor`
157 | 10. `getChildContext`
158 | 11. `componentWillMount`
159 | 12. `componentDidMount`
160 | 13. `shouldComponentUpdate`
161 | 14. `componentWillUpdate`
162 | 15. `componentDidUpdate`
163 | 16. `componentWillUnmount`
164 | 17. 事件处理方法
165 | 18. 其它方法
166 | 19. `render`
167 |
168 | 其中`shouldComponentUpdate`和`render`是一个组件最容易被阅读的函数，因此放在最下方有助于快速定位。
169 |
170 | - [建议]无需显式引入React对象。
171 |
172 | 使用JSX隐式地依赖当前环境下有`React`这一对象，但在源码上并没有显式使用，这种情况下添加`import React from 'react';`会造成一个没有使用的变量存在。
173 |
174 | 使用[babel-plugin-react-require](https://www.npmjs.com/package/babel-plugin-react-require)插件可以很好地解决这一问题，因此无需显式地编写`import React from 'react';`这一语句。
175 |
176 | - [建议]使用箭头函数声明函数组件。
177 |
178 | 箭头函数具备更简洁的语法（无需`function`关键字），且可以在仅有一个语句时省去`return`造成的额外缩进。
179 |
180 | - [建议]高阶组件返回新的组件类型时，添加`displayName`属性。
181 |
182 | 同时在`displayName`上声明高阶组件的存在。
183 |
184 | ```javascript
185 | // Good
186 | let asPureComponent = Component => {
187 | let componentName = Component.displayName || Component.name || 'UnknownComponent';
188 | return class extends PureComponent {
189 | static displayName = `asPure(${componentName})`
190 |
191 | render() {
192 | return
284 | Hello World
285 |
;
286 | }
287 | }
288 |
289 | // Good
290 | class Message {
291 | render() {
292 | return (
293 |
294 | Hello World
295 |
296 | );
297 | }
298 | }
299 | ```
300 |
301 | 对于直接`return`的函数组件，可以直接使用括号而省去大括号和`return`关键字：
302 |
303 | ```javascript
304 | let Message = () => (
305 |
306 | Hello World
307 |
308 | );
309 | ```
310 |
311 | - [强制]对于多属性需要换行，从第一个属性开始，每个属性一行。
312 |
313 | ```javascript
314 | // 没有子节点
315 | -
413 | {
414 | items.map(item => (
415 |
-
416 |
417 | 420 |{item.title}
418 | {item.subtitle} 419 |{item.content} 421 | 424 |
425 | ))
426 | }
427 |
{title}
434 | {subtitle} 435 |
448 |
452 | );
453 |
454 | let List = ({items}) => (
455 | -
456 | {items.map(Item)}
457 |
-
82 |
- first 83 |
- second 84 |
Hello StyleGuide!
188 | 189 | 190 |Hello StyleGuide!
191 | ``` 192 | 193 | #### [强制] 对于无需自闭合的标签，不允许自闭合。 194 | 195 | 解释： 196 | 197 | 常见无需自闭合标签有 `input`、`br`、`img`、`hr` 等。 198 | 199 | 200 | 示例： 201 | 202 | ```html 203 | 204 | 205 | 206 | 207 | 208 | ``` 209 | 210 | #### [强制] 对 `HTML5` 中规定允许省略的闭合标签，不允许省略闭合标签。 211 | 212 | 解释： 213 | 214 | 对代码体积要求非常严苛的场景，可以例外。比如：第三方页面使用的投放系统。 215 | 216 | 217 | 示例： 218 | 219 | ```html 220 | 221 |-
222 |
- first 223 |
- second 224 |
-
228 |
- first 229 |
- second 230 |
Esprima serves as an important building block for some JavaScript language tools.
269 | 270 | 271 |Esprima serves as an important building block for some JavaScript language tools.
272 | ```
273 |
274 |
275 | #### [建议] 在 CSS 可以实现相同需求的情况下不得使用表格进行布局。
276 |
277 | 解释：
278 |
279 | 在兼容性允许的情况下应尽量保持语义正确性。对网格对齐和拉伸性有严格要求的场景允许例外，如多列复杂表单。
280 |
281 |
282 | #### [建议] 标签的使用应尽量简洁，减少不必要的标签。
283 |
284 | 示例：
285 |
286 | ```html
287 |
288 | 
289 |
290 |
291 |
292 |
293 |
294 | ```
295 |
296 |
297 |
298 | ### 2.4 属性
299 |
300 |
301 | #### [强制] 属性名必须使用小写字母。
302 |
303 | 示例：
304 |
305 | ```html
306 |
307 |
778 |
784 | {/if}
785 |
786 |
787 | {if $display == true}
788 | -
779 | {foreach $item_list as $item}
780 |
- {$item.name}
- 781 | {/foreach} 782 |
789 |
795 | {/if}
796 | ```
797 |
798 | #### [建议] 模板代码应以保证 HTML 单个标签语法的正确性为基本原则。
799 |
800 | 示例：
801 |
802 | ```html
803 |
804 | -
790 | {foreach $item_list as $item}
791 |
- {$item.name}
- 792 | {/foreach} 793 |
| { $item.name } | 821 | {/foreach} 822 |
| { $item.name } | 831 | {if $item@iteration is div by 5} 832 |