MIP个性化组件一般用来实现前后端数据传输或特殊的交互效果,由广大开发者贡献。出于性能、可维护性等方面的考虑,开发者在新增组件或升级组件时,请遵守以下规范。
规范中的必须(MUST),禁止(MUST NOT),应该(SHOULD),不应该(SHOULD NOT),建议(MAY),不建议(MAY NOT)关键词使用遵循TFC2119规范。
MIP是主要用在移动端,应该使用原生JS或Zepto。jQuery代码过于庞大冗余。如有特殊依赖,需在注释中说明。
define(function (require) {
// 推荐
var $ = require('zepto');
// 特殊情况:使用jQuery的xx特性,Zepto不支持
var $ = require('jquery');
});
为了更好的页面性能,不建议以外链的方式引入JS。开发者本站维护的脚本必须封装为组件或AMD方式引入。广告,第三方统计等JS,请在代码注释中说明用途及服务提供商。未来会上线第三方JS引入机制,新机制上线后不允许引用更多外链JS。
为了首屏元素优先展示,加速页面显示速度。组件声明周期应该统一使用 firstInviewCallback。如有特殊情况需要使用其它声明周期,请在代码注释中说明。
// 推荐:组件进入首屏时加载
customElement.prototype.firstInviewCallback = function () {
var ele = this.element;
};
// build说明: 导航组件,在首屏展示,需要尽快加载
customElement.prototype.build = function () {
var ele = this.element;
};
应该使用官方组件,官方组件会测试各个常见浏览器兼容性。
第三方提供的通用服务(广告,统计,评论等其他网站也会用到的功能),不应该自己封装。请到GitHub提交issue,MIP项目组会联系通用服务提供方开发组件。
异步请求建议使用核心代码提供的 fetch 和 fetchJsonp,文档:https://www.mipengine.org/doc/3-widget/6-help/1-introduce.html
数字如果经常变化,可以作为配置写在组件属性中,在组件内部读取属性并使用。避免未来属性变化还需要升级组件。
// html: 在DOM中配置 data-target 变量
"#id1">
// 组件JS:获取 data-target 变量用于后续逻辑
customElement.prototype.firstInviewCallback = function () {
var _element = this.element;
this.target = _element.getAttribute('data-target');
}
为了分离JS,HTML和CSS,增强代码的可维护性,请不要在页面内使用内联style;建议在head中含有mip-custom属性的style标签内自定义样式。
为了更好的页面性能,不建议循环绑定事件,建议使用官方方法将事件代理到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);
document.write
和document.writeln
(SHOULD NOT)不应该使用严重影响页面性能的操作。
localStorage
、sessionStorage
(MAY)使用方式:https://www.mipengine.org/doc/3-widget/6-help/6-storage.html
当前组件 JS 脚本只为当前组件容器服务,不应该处理组件以外的 dom 和交互。
customElement.prototype.firstInviewCallback = function () {
// 不应该这样使用, 全局选择
var lists = document.querySelectorAll('li');
// 推荐, 组件内选择
var ele = this.element;
var lists = ele.querySelectorAll('li');
}
代码维护相关
必须详细填写readme.md文件,说明组件用法、所需属性、注意事项等信息。方便其它开发者直接使用。
// 默认生成,不可直接提交
mip-xxx-xxx 组件说明
// 内容太少,未说明清楚
mip-xxx-xxx
// 优秀的组件说明
mip-carousel 用来支持 MIP 中图片展示,支持多图轮播。
组件命名规则:mip-站点域名-功能,尽量简洁。 如mip-mipengine-search
。
package.json
描述不全(SHOULD)在package.json中的description字段中应该添加详细描述:组件功能,当前版本号,组件维护者联系方式。
新增个性化组件,请确认符合 FECS 规范后,在组件平台提交(使用文档)或在 GitHub/mip-extensions-platform 提交PR. GitHub/mip-extensions仓库仅提交通用的组件。
由于MIP页会在百度搜索结果页的HTTPS环境打开。组件与服务器的数据请求,必须支持https://
。但
的src不强制要求HTTPS,在组件代码中有转换逻辑。
由于MIP页会在百度搜索结果页以iframe内嵌形式打开,跳转链接需要使用window.top.location.href
来修改iframe外层URL。
已上线组件可以继续使用,但升级组件必须按照上述规则执行,升级组件代码时必须确认修改后代码符合上述规则。
组件升级,为了表明便于维护区分,建议修改package.json
中的组件version版本号。