MIP Shell
开发者不能直接使用 MIP Shell 的方法,但可以通过继承的方式实现满足自身业务需求的“个性化 Shell”。
这里列举几个比较常见的通过个性化 Shell 可以实现的需求,供大家参考:
对于默认的头部标题栏样式或者 DOM 结构不满意,有修改的需求。
除了头部,还有底部栏或者侧边栏需要额外渲染和绑定事件。例如下图:
开发者需要控制站点的 Shell 配置,修改/禁用/忽略某些选项。
例如开发者希望忽略 HTML 中的配置项而固定选择某些按钮,或者希望在配置之外增加某些按钮等。
继承方式
全局的 MIP 对象会暴露一个 MIP Shell 基类供大家继承。例如我们要创建一个 MIP Shell Example 组件,我们可以写如下代码:
123export default class MIPShellExample extends window.MIP.builtinComponents.MIPShell {
// Functions go here
}
类名使用驼峰命名,组件平台会自动把驼峰转化为符合 HTML 规范的短划线连接形式,如 <mip-shell-example>
。
个性化 Shell 的编写规范和普通组件相同,同样在 mip2-extensions 项目中编写,如下:
使用个性化 Shell
个性化 Shell 的使用和内置的 MIP Shell 基本类似。唯一的区别是为标签增加一个属性 mip-shell
,例子如下:
12345678910111213141516171819<mip-shell-example mip-shell>
<script type="application/json">
{
"routes": [
{
"pattern": "*",
"meta": {
"header": {
"show": true,
"title": "MIP Index",
"logo": "https://boscdn.baidu.com/assets/mip/codelab/shell/mashroom.jpg"
},
}
}
],
"exampleUserId": 1
}
</script>
</mip-shell>
可以看到这个例子中在 routes
平级增加了一个 exampleUserId
,将会在后续继承父类方法中使用到。个性化 Shell 就可以通过传入自定义数据来处理额外的逻辑。
供子类继承的方法列表
constructor
构造函数中有两个属性可以被子类修改,他们分别是:
alwaysReadConfigOnLoad, 默认值
true
因为每个页面都有全部的配置,因此在页面切换时,目标页面的配置同时存在于当前页面和目标页面两处(正常情况下两处配置应该相同)。这个属性可以控制以哪一份配置为准。如果确认每个页面的配置是严格相同的,或者为了性能考虑,则应该使用
false
,从而保证只有第一次读入配置,后续均不读取。反之如果需要每次均读取覆盖,则应该使用true
。transitionContainsHeader, 默认值
true
默认的页面切换动画会连同头部一起进行侧向滑动。如果这个值设置为false
,则头部不参与侧滑动画,转而使用 fade (渐隐渐现) 效果取代。
开发者可以在构造函数中修改这两个属性,也可以初始化自己之后将要使用的其他属性和变量。注意在初始化时,必须要调用 super
并且带上参数,如下:
123456constructor (...args) {
super(...args)
this.alwaysReadConfigOnLoad = false
this.transitionContainsHeader = false
}
showHeaderCloseButton
- 参数: 无。
- 返回值:boolean,默认
true
。
MIP Shell 的头部标题栏右侧的按钮区域会根据 MIP 页面当前所处的状态来决定是否展示关闭按钮。当处于百度搜索结果页中(即拥有 SuperFrame 环境时)会额外渲染一个关闭按钮,点击效果用以通知 SuperFrame 关闭自身,如下图所示:
MIP 页面判断当前是否处于 SuperFrame 环境的判断依据是 window.MIP.standalone
值等于 false
。
如果开发者有特殊需求,要求即便在 window.MIP.standalone === false
成立时依然 不展现 关闭按钮,可以继承这个方法并返回 false
。这个方法在 standalone
的判断 之后 生效,因此即便它返回 true
,只要 standalone
也为 true
则关闭按钮依然不展现。
1234567showHeaderCloseButton () {
if (location.href.indexOf('main') !== -1) {
return true;
} else {
return false;
}
}
handleShellCustomButton
- 参数:
buttonName
, string, 按钮配置时的name
属性。 - 返回值:无。
MIP Shell 的头部标题栏上所有的按钮(如默认的后退,关闭,更多以及用户配置的 buttonGroup
)在点击时都会调用这个方法。
虽然默认的后退(back
), 关闭(close
)和更多(more
)按钮已有其对应的处理方法(如点击更多展现浮层,点击后退路由后退等),但开发者依然可以在这里接到这些值,以添加可能存在的额外操作。
在 buttonGroup
配置时,每一个按钮均有一个 name
属性,这个 name
属性也会当做参数传入这个方法。
123456789101112handleShellCustomButton (buttonName) {
if (buttonName === 'back') {
// 默认头部已经包含 name 为 back 的按钮,并已有默认处理(路由后退)
// 如果需要,这里可以再进行一些额外的处理
console.log('click on back')
} else if (buttonName === 'about') {
// 假设 HTML 中配置了 name 为 about 的按钮,这里定义它的响应
console.log('click on about')
// 实际上跳转页面可以通过在 buttonGroup 中的 link 属性进行配置。这里仅仅是做一个示例
window.MIP.viewer.open('./about.html')
}
}
特别地,在 MIP Shell 基类逻辑中还定义了一个名为 cancel
的按钮的点击响应,作用是关闭更多按钮的浮层。因此如果开发者在 buttonGroup
中配置了名为 cancel
的按钮,可以不必自行实现关闭浮层的响应即可获得相同的效果。
processShellConfig
- 参数:
shellConfig
, Object, 经过处理的 Shell 配置对象。 - 返回值:无。
Shell 子类通过这个方法对 MIP Shell 初步处理后的配置对象进行修改,再进行后续的渲染和绑定,从而可以对 HTML 中的配置进行统一的操作。
MIP Shell 进行的所谓“初步处理”包括:
- 读取 HTML 中对应标签内的 JSON,并通过
JSON.parse()
进行转义。 - 遍历
routes
数组的每个元素,进行如下操作:- 获取
meta
值,和默认meta
进行合并并写会。HTML 中的meta
优先级更高。 - 获取
pattern
值,将字符串转化为正则表达式(采用new RegExp()
进行转化)。特别的,'*'
被转化为/.*/
以匹配任意字符 - 如果无法获取到
route.meta.header.title
的值,则从当前页面的<title>
标签获取。
- 获取
在这些操作之后,MIP Shell 将 整个 JSON 对象 当做参数传递给开发者(不单单是 routes
数组)。开发者可以在 processShellConfig
方法内对参数进行修改,不必返回。这里还分为同步和异步两种情况。
同步修改
即方法内容不涉及异步操作,直接对参数进行修改即可。示例如下:
1234processShellConfig(shellConfig) { // 强制清空 HTML 中的按钮配置 shellConfig.routes.forEach(route => route.buttonGroup = []) }
异步修改
即方法中还包含异步操作。这时通常需要先给
shellConfig
设置一个默认值(也可以以 HTML 中的配置当做默认值,则跳过此步),然后进行异步操作(例如发送请求)。在操作获取到结果之后,修改shellConfig
之后调用this.updateShellConfig()
和this.refreshShell()
分别更新缓存和页面 DOM。如下示例会使用到之前配置过的exampleUserId
:123456789101112131415161718192021222324252627282930313233343536373839404142processShellConfig (shellConfig) { // 设置默认值 shellConfig.routes.forEach(routeConfig => { routeConfig.meta.header.title = '极速服务' routeConfig.meta.header.logo = 'https://www.baidu.com/favicon.ico' }) // 获取 HTML 配置好的 exampleUserId let isId = shellConfig.exampleUserId // 使用 setTimeout 模拟异步发送请求 setTimeout(() => { // 通过 exampleUserId 获取到目标用户的标题和 LOGO,并固定按钮 shellConfig.routes[0].meta.header.title = '蓝犀牛搬家' shellConfig.routes[0].meta.header.logo = 'https://boscdn.baidu.com/assets/mip2/lanxiniu/logo.png' shellConfig.routes[0].meta.header.buttonGroup = [ { name: 'share', text: '分享' }, { name: 'indexPage', text: '首页' }, { name: 'about', text: '关于蓝犀牛' }, { name: 'cancel', text: '取消' } ] shellConfig.routes[1].meta.header.title = '红犀牛搬家' // 异步操作,需要更新 Shell 配置缓存 this.updateShellConfig(shellConfig) // 异步操作,需要更新页面上的 Shell DOM // window.MIP.viewer.page.pageId 表示当前页面的 pageId,由 MIP Shell 负责更新 this.refreshShell({pageId: window.MIP.viewer.page.pageId}) }, 1000) }
renderOtherParts
- 参数:无。
- 返回值:无。
默认的 MIP Shell 只渲染头部标题栏。如果开发者希望渲染其他部分(如底部菜单栏),可以通过继承 renderOtherParts
方法来实现。
这个方法没有参数,但可以通过获取 this.currentPageMeta
来获取当前页面的 meta
信息(即 MIP Shell 所有配置中匹配当前页面的 meta
,其中包括当前页面的标题,LOGO,按钮等所有信息)。
需要注意的是,如果需要创建 position: fixed
的 DOM 元素(如底部菜单栏),应当使用 <mip-fixed>
作为标签名,而非其他如 <div>
等 HTML 标准标签。这主要是为了解决 iOS 的 iframe 中 fixed 元素滚动抖动的 BUG。
1234567891011121314151617renderOtherParts () {
this.$footerWrapper = document.createElement('mip-fixed')
this.$footerWrapper.setAttribute('type', 'bottom')
this.$footerWrapper.classList.add('mip-shell-footer-wrapper')
this.$footer = document.createElement('div')
this.$footer.classList.add('mip-shell-footer', 'mip-border', 'mip-border-top')
this.$footer.innerHTML = this.renderFooter()
this.$footerWrapper.appendChild(this.$footer)
document.body.appendChild(this.$footerWrapper)
}
renderFooter() {
let pageMeta = this.currentPageMeta
return 'hello ${pageMeta.header.title}!'
}
建议把 this.renderFooter()
抽象成一个单独的方法,因为这个方法也会在后面 update 时被调用。
updateOtherParts
- 参数:无。
- 返回值:无。
MIP 页面首次进入时会调用 renderOtherParts()
方法进行初始渲染。而后续切换页面时,MIP Page 会将目标页面的 meta
信息设置为 this.currentPageMeta
并调用 updateOtherParts()
方法以更新自定义部件。
在 updateOtherParts()
方法中,开发者仅需要更新 HTML 即可,不需要像 renderOtherParts()
那样创建 DOM 并插入到页面中。也因此,将 renderFooter()
独立出来有利于这里继续调用。示例如下:
123updateOtherParts() {
this.$footer.innerHTML = this.renderFooter()
}
beforeSwitchPage
- 参数:
options
, Object, 路由切换时的配置项。targetPageId
, string, 目标页面的pageId
targetPageMeta
, Object, 目标页面的pageMeta
,结构和<mip-shell>
中的meta
对象相同sourcePageId
, string, 当前页面的pageId
sourcePageMeta
, Object, 当前页面的pageMeta
,结构和<mip-shell>
中的meta
对象相同newPage
, boolean, 是否需要创建 iframeisForward
, boolean, 动画是否为前进方向
- 返回值:无。
MIP 在页面切换之前,会调用此方法。如果子类需要在动画之前进行一些操作(例如加入自己的动画元素),可以继承并实现这个方法。示例如下:
1234beforeSwitchPage(options) {
// 固定动画切换方向为前进方向
options.isForward = true
}
afterSwitchPage
- 参数:
options
, Object, 路由切换时的配置项。targetPageId
, string, 目标页面的pageId
targetPageMeta
, Object, 目标页面的pageMeta
,结构和<mip-shell>
中的meta
对象相同sourcePageId
, string, 当前页面的pageId
sourcePageMeta
, Object, 当前页面的pageMeta
,结构和<mip-shell>
中的meta
对象相同newPage
, boolean, 是否需要创建 iframeisForward
, boolean, 动画是否为前进方向
- 返回值:无。
MIP 在页面切换之后,会调用此方法。如果子类需要在动画之后进行一些操作(例如要通知一些消息),可以继承并实现这个方法。示例如下:
1234567891011afterSwitchPage(options) {
// 向所有页面广播页面切换事件,并给出切换前后的 pageId
let {sourcePageId, targetPageId} = options
window.MIP.viewer.page.broadcastCustomEvent({
name: 'switchPageComplete',
data: {
targetPageId,
sourcePageId
}
})
}
个性化 Shell 实例
这里列出两个个性化 Shell 的实例(均为实际线上代码,但隐去了敏感信息和复杂的业务逻辑)
极速服务 Shell
命名为 <mip-shell-is>
,主要工作有:
- 增加额外的
isId
配置项 - 根据
isId
通过接口 异步 获取站点的标题,LOGO 和按钮配置 - 为添加的按钮增加点击响应
- 因为涉及异步获取站点
meta
信息,因此首屏请求之后不再重复获取信息
mip-shell-is.js
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960export default class MIPShellIS extends window.MIP.builtinComponents.MIPShell { constructor (...args) { super(...args) this.alwaysReadConfigOnLoad = false this.transitionContainsHeader = false } processShellConfig (shellConfig) { // 设置默认属性 shellConfig.routes.forEach(routeConfig => { routeConfig.meta.header.title = '极速服务' routeConfig.meta.header.logo = 'https://www.baidu.com/favicon.ico' routeConfig.meta.header.bouncy = false }) let isId = shellConfig.isId console.log('Simulate async request with isId:', isId) setTimeout(() => { shellConfig.routes[0].meta.header.title = '蓝犀牛搬家' shellConfig.routes[0].meta.header.logo = 'https://boscdn.baidu.com/assets/mip2/lanxiniu/logo.png' shellConfig.routes[0].meta.header.buttonGroup = [ { name: 'share', text: '分享' }, { name: 'indexPage', text: '首页' }, { name: 'about', text: '关于蓝犀牛' }, { name: 'cancel', text: '取消' } ] shellConfig.routes[1].meta.header.title = '红犀牛搬家' this.updateShellConfig(shellConfig) this.refreshShell({pageId: window.MIP.viewer.page.pageId}) }, 1000) } handleShellCustomButton (buttonName) { if (buttonName === 'share') { console.log('click on share') this.toggleDropdown(false) } else if (buttonName === 'indexPage') { console.log('click on indexPage') this.toggleDropdown(false) } else if (buttonName === 'about') { console.log('click on about') this.toggleDropdown(false) } } }
mip-shell-is.html
只列出
<body>
部分。123456789101112131415161718192021222324252627<body> <mip-shell-is mip-shell> <script type="application/json"> { "routes": [ { "pattern": "*", "meta": { "header": { "show": true } } } ], "isId": 123 } </script> </mip-shell-is> <p>This is MIP SHELL IS</p> <a class="link" href="./mip-shell-is-2.html" mip-link>Go to MIP SHELL IS 2</a> <div id="button">By viewer.open</div> <script src="../../dist/mip.js"></script> <script src="./components/mip-shell-is.js"></script> </body>
百度小说 Shell
命名为 <mip-shell-novel>
,主要工作有:
- 增加额外的
catalog
配置项用以记录小说目录 - 额外渲染底部菜单栏
- 为底部菜单栏绑定点击事件,并提供解绑函数
- 每个页面都包含目录信息,为性能考虑,只读取第一个页面的信息。
mip-shell-novel.js
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394export default class MIPShellNovel extends window.MIP.builtinComponents.MIPShell { constructor (...args) { super(...args) this.alwaysReadConfigOnLoad = false this.transitionContainsHeader = false } processShellConfig (shellConfig) { this.catalog = shellConfig.catalog } renderOtherParts () { this.$footerWrapper = document.createElement('mip-fixed') this.$footerWrapper.setAttribute('type', 'bottom') this.$footerWrapper.classList.add('mip-shell-footer-wrapper') this.$footer = document.createElement('div') this.$footer.classList.add('mip-shell-footer', 'mip-border', 'mip-border-top') this.$footer.innerHTML = this.renderFooter() this.$footerWrapper.appendChild(this.$footer) document.body.appendChild(this.$footerWrapper) } updateOtherParts () { this.$footer.innerHTML = this.renderFooter() } renderFooter () { let pageMeta = this.currentPageMeta let {buttonGroup} = pageMeta.footer let renderFooterButtonGroup = buttonGroup => buttonGroup.map(buttonConfig => ` <div class="button" mip-footer-btn data-button-name="${buttonConfig.name}">${buttonConfig.text}</div> `).join('') let footerHTML = ` <div class="upper mip-border mip-border-bottom"> <div class="switch switch-left" mip-footer-btn data-button-name="previous"><上一章</div> <div class="switch switch-right" mip-footer-btn data-button-name="next">下一章></div> </div> <div class="button-wrapper"> ${renderFooterButtonGroup(buttonGroup)} </div> ` return footerHTML } bindHeaderEvents () { super.bindHeaderEvents() let me = this let event = window.MIP.util.event // 代理底部菜单栏的点击事件 this.footEventHandler = event.delegate(this.$footerWrapper, '[mip-footer-btn]', 'click', function (e) { let buttonName = this.dataset.buttonName me.handleFooterButton(buttonName) }) if (this.$buttonMask) { this.$buttonMask.onclick = () => { this.toggleDropdown(false) this.toggleDOM(this.$footerWrapper, false, {transitionName: 'slide'}) } } } unbindHeaderEvents () { super.unbindHeaderEvents() if (this.footEventHandler) { this.footEventHandler() this.footEventHandler = undefined } } handleShellCustomButton (buttonName) { if (buttonName === 'share') { console.log('share') this.toggleDropdown(false) } else if (buttonName === 'setting') { this.toggleDOM(this.$buttonWrapper, false, {transitionName: 'slide'}) this.toggleDOM(this.$footerWrapper, true, {transitionName: 'slide'}) } } handleFooterButton (buttonName) { console.log('click on footer:', buttonName) this.toggleDOM(this.$buttonMask, false) this.toggleDOM(this.$footerWrapper, false, {transitionName: 'slide'}) } }
mip-shell-novel.html
只列出
<body>
部分。1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798<body> <h2>第1章 灵魂重生</h2> <p>“贱人,你竟敢背叛我!”</p> <p>“宋凌云,你这个畜生,我视你如手足,当你如兄弟,是我亲手把你培育成无双战神,可你竟然与那贱人勾搭成奸,还要置我于死路,我做鬼都不会放过你。” </p> <p>陆宇猛然睁开眼睛,一下子坐起,双眼之中充满了愤怒与杀气,拳头握得死紧! </p> <p>“不对,这是哪里?我明明在黑狱中灰飞烟灭,怎么可能还未死?” </p> <p>“难道说,我重生了?” </p> <p>陌生的环境让陆宇迅速清醒,过往的记忆逐一呈现在脑海里。 </p> <p>陆宇原本是神武天域的圣魂天师,开创了史无前例的武魂进化之术,将一个不起眼的辅助职业魂天师推到了巅峰极境,成为了神武天域有史以来第一个圣帝级魂天师,简称圣魂天师! </p> <p>那是至高荣誉,堪称魂天师领域的万古第一人。 </p> <p>然而就在陆宇最风光,最得意,站在人生巅峰之际,一场背叛彻底将他摧毁。 </p> <p>陆宇这一生有三大引以为傲的事情,貌美无双的娇妻,神勇无敌的兄弟,功成名就的事业,那是无数人都梦寐以求的东西,他都得到了,可他却没有猜到结局。 </p> <p>陆宇的成长并不顺利,但是开创武魂进化之术改变了他的一生,让他娶到了神武天域十大美女之一的马灵月为妻,曾羡煞无数人。 </p> <p>后来,陆宇又结识了宋凌云,两人肝胆相照,成为了好兄弟。 </p> <p>身为魂天师,陆宇致力于研究武魂进化之术,并在娇妻与兄弟身上耗费了半生精力。 </p> <p>原本,马灵月和宋凌云的武魂都只是地级三品以下,注定成就有限。 </p> <p>但是陆宇却利用自己独创的武魂进化之术,让两人的武魂等级从地级三品提升到了天级八品,一跃成为了神武天域的至强者。 </p> <mip-shell-novel mip-shell> <script type="application/json"> { "routes": [ { "pattern": "/novel-\\d", "meta": { "header": { "show": true, "title": "神武天帝", "buttonGroup": [{ "name": "share", "text": "分享" },{ "name": "setting", "text": "设置" },{ "name": "cancel", "text": "取消" }] }, "footer": { "buttonGroup": [{ "name": "catalog", "text": "目录" },{ "name": "night", "text": "夜间模式" },{ "name": "setting", "text": "设置" }] } } } ], "catalog": [ { "name": "第1章 灵魂重生", "link":"novel-1.html" }, { "name": "第2章 武魂提升", "link":"novel-2.html" }, { "name": "第3章 牛刀小试", "link":"novel-3.html" }, { "name": "第4章 笑里藏刀", "link":"novel-4.html" }, { "name": "第5章 云月儿", "link":"novel-5.html" } ] } </script> </mip-shell-novel> <script src="../../dist/mip.js"></script> <script src="./components/mip-shell-novel.js"></script> </body>