MIP个性化组件提交规范

MIP个性化组件一般用来实现前后端数据传输或特殊的交互效果，由广大开发者贡献。出于性能、可维护性等方面的考虑，开发者在新增组件或升级组件时，请遵守以下规范。

规范中的必须（MUST），禁止（MUST NOT），应该（SHOULD），不应该（SHOULD NOT），建议（MAY），不建议（MAY NOT）关键词使用遵循TFC2119规范。

新增组件

速度&展现相关

1.1 不应该使用 jQuery（SHOULD NOT）

MIP是主要用在移动端，应该使用原生JS或Zepto。jQuery代码过于庞大冗余。如有特殊依赖，需在注释中说明。

define(function (require) {
    // 推荐
    var $ = require('zepto'); 
    // 特殊情况：使用jQuery的xx特性，Zepto不支持
    var $ = require('jquery'); 
});

1.2 不应该使用外链JS （SHOULD NOT）

为了更好的页面性能，不建议以外链的方式引入JS。开发者本站维护的脚本必须封装为组件或AMD方式引入。广告，第三方统计等JS，请在代码注释中说明用途及服务提供商。未来会上线第三方JS引入机制，新机制上线后不允许引用更多外链JS。

1.3. 组件生命应该使用 firstInviewCallback（SHOULD）

为了首屏元素优先展示，加速页面显示速度。组件声明周期应该统一使用 firstInviewCallback。如有特殊情况需要使用其它声明周期，请在代码注释中说明。

// 推荐：组件进入首屏时加载
customElement.prototype.firstInviewCallback = function () {
    var ele = this.element;
};

// build说明: 导航组件，在首屏展示，需要尽快加载
customElement.prototype.build = function () {
    var ele = this.element;
};

1.4 不应该提交重复功能组件 (SHOULD NOT)

应该使用官方组件，官方组件会测试各个常见浏览器兼容性。
第三方提供的通用服务（广告，统计，评论等其他网站也会用到的功能），不应该自己封装。请到GitHub提交issue，MIP项目组会联系通用服务提供方开发组件。

1.5 异步请求使用建议（MAY）

异步请求建议使用核心代码提供的 fetch 和 fetchJsonp，文档：https://www.mipengine.org/doc/3-widget/6-help/1-introduce.html

1.6 建议将非固定属性写入配置（MAY）

数字如果经常变化，可以作为配置写在组件属性中，在组件内部读取属性并使用。避免未来属性变化还需要升级组件。

// html： 在DOM中配置 data-target 变量
<mip-aa data-target="#id1"></mip-aa>

// 组件JS：获取 data-target 变量用于后续逻辑
customElement.prototype.firstInviewCallback = function () {
    var _element = this.element;
    this.target = _element.getAttribute('data-target');
}

1.7 CSS样式，style标签建议和HTML，JavaScript分离（MAY）

为了分离JS，HTML和CSS，增强代码的可维护性，请不要在页面内使用内联style；建议在head中含有mip-custom属性的style标签内自定义样式。

1.8 不建议在循环中绑定事件（MAY NOT）

为了更好的页面性能，不建议循环绑定事件，建议使用官方方法将事件代理到element，文档：https://www.mipengine.org/doc/3-widget/6-help/1-introduce.html

// 不推荐
var list = document.querySelectorAll('.unorder li');
for(var i=0; i<list.length; i++) {
    list[i].addEventListener('click', clickHandler);
}

// 推荐
var util = require('util');
var delegate = util.event.delegate(document, 
        document.querySelectorAll('.unorder li'),
        'click',
        clickHandler);

1.9 不应该使用 document.write和document.writeln（SHOULD NOT）

不应该使用严重影响页面性能的操作。

1.10 建议使用框架接口调用localStorage、sessionStorage （MAY）

使用方式：https://www.mipengine.org/doc/3-widget/6-help/6-storage.html

1.11 MIP 组件操作应该遵循分离原则 (SHOULD)

当前组件 JS 脚本只为当前组件容器服务，不应该处理组件以外的 dom 和交互。

customElement.prototype.firstInviewCallback = function () {
        // 不应该这样使用, 全局选择
        var lists = document.querySelectorAll('li');

        // 推荐, 组件内选择
        var ele = this.element;
        var lists = ele.querySelectorAll('li');
}

代码维护相关

2.1 完整填写readme.md（MUST）

必须详细填写readme.md文件，说明组件用法、所需属性、注意事项等信息。方便其它开发者直接使用。

// 默认生成，不可直接提交
mip-xxx-xxx 组件说明

// 内容太少，未说明清楚
mip-xxx-xxx

// 优秀的组件说明
mip-carousel 用来支持 MIP 中图片展示，支持多图轮播。

2.2 命名符合规范（MUST）

组件命名规则：mip-站点域名-功能，尽量简洁。 如mip-mipengine-search。

2.3 package.json 描述不全（SHOULD）

在package.json中的description字段中应该添加详细描述：组件功能，当前版本号，组件维护者联系方式。

MIP业务相关

3.1 新增组件应该使用MIP组件平台提交（SHOULD）

新增个性化组件，请确认符合 FECS 规范后，在组件平台提交（使用文档）或在 GitHub/mip-extensions-platform 提交PR. GitHub/mip-extensions仓库仅提交通用的组件。

3.2 前后端通信，服务器地址必须支持HTTPS（MUST）

由于MIP页会在百度搜索结果页的HTTPS环境打开。组件与服务器的数据请求，必须支持https://。但<mip-img> 的src不强制要求HTTPS，在组件代码中有转换逻辑。

3.3 MIP页面使用JS跳转，跳转操作必须使用window.top.location.href=”“（MUST）

由于MIP页会在百度搜索结果页以iframe内嵌形式打开，跳转链接需要使用window.top.location.href来修改iframe外层URL。

升级组件

4.1 旧组件不符合以上规则处理办法（MUST）

已上线组件可以继续使用，但升级组件必须按照上述规则执行，升级组件代码时必须确认修改后代码符合上述规则。

4.2 组件升级改版本号（MAY）

组件升级，为了表明便于维护区分，建议修改package.json中的组件version版本号。