wap2App 入门讲解,100%速成,全面为你讲解。
一、wap2App 是什么
wap2App 是一个将现有 M 站(也称手机 wap 站,区别于 pc 的 Web 站)快速发布成 App 的增强方案,通过 DCloud 的 wap2App 框架,进行简单的配置和必要的编程,即可完成 M 站的体验强化,达到原生应用的功能体验,进而再发布为原生安装包或流应用。
产品特点
- 提供了原生渲染能力,让界面渲染速度和动画效果,达到原生体验(优化后的体验有多好,可以滚动到文档底部看 “案例体验” 章节)
- 提供丰富的系统原生能力(定位、分享、支付、推送等),达到原生功能
- 通过 JSON 配置页面规则和强化规则,工作量低,学习成本低
- M 站仅需稍作修改,改造成本低
- 强化部分和之前的 M 站解耦合,M 站后续升级业务逻辑,生成的 App 自动含有更新后的业务逻辑
生成文件目录结构如下:
- sitemap.json:wap2App 核心配置文件,wap2App 的大部分工作在该文件中完成
- app.js:为弥补 sitemap.json 的格式限制,提供的基于 JavaScript 的可编程增强方案
- manifest.json:工程参数配置,比如 icon、splash 图等(打开该文件后有帮助链接)
- client_index.html:内置静态页面,若首页有选项卡,需在该文件中配置
- %APPID%.append.css:本示例中 APPID 为 “W2Am.example.com” ,故默认创建了一个 W2Am.example.com.append.css 文件;该 CSS 文件负责提前修饰首页的样式,比如隐藏 M 站首页的原生下载引导等 DOM 元素。
以上文件的名称以及位置,不可修改或调整。二、sitemap.json 配置文件
1. global
webviewParameter 设置标题栏
属性包含如下:
- titleNView:原生导航栏样式配置
- statusbar:系统状态栏样式配置
- subNViews:NView 模板配置
- pullToRefresh:下拉刷新配置
- appendCss:向服务端页面插入的 CSS 代码
- appendJs:向服务端页面插入的 JavaScript 代码
- tabBar:选项卡切换效果优化,目前仅支持首页底部选项卡
easyConfig 为提升用户体验而提供的简化设置,比如后退处理
{
"global": {
//global 为全局配置,与 pages 数组中 webview 对象呈继承关系
"webviewParameter": {
"titleNView": {
"autoBackButton": true,
"backgroundColor": "#D74B28",// 导航栏背景色
"titleColor": "#f7f7f7",// 标题颜色
"titleSize": "17px",// 字体大小
"splitLine": {// 标题栏的底部分割线,默认不显示底部分割线
"color": "#D74B28", // 分割线颜色
"height": "1px"
}
},
"appendCss": ".download,.mui-bar-tab,header{display:none!important;} .mui-bar-nav~.mui-content,.info,.dcontent{padding-top: 0!important;} .sdcontent{top:0!important;}"
},
"easyConfig": {
"quit": {// 参考文档 【http://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/12750】 quit
"toast": {
"showFeedback": false // 默认为 true
}
}
}
}
}
2.pages 每个页面的单独设置
page 节点包含四个属性
- webviewId:当前页面所属 webview 的 id,类型为 String,方便后续增强编程实现,比如在 app.js 中可使用 plus.webview.getWebviewById () 方法获取当前的 webview 对象
- matchUrls:页面 URL 匹配规则,满足 matchUrls 匹配规则的页面,将使用当前页面配置规则打开,比如 webview 的 id 固定为本页配置的"webviewId"属性
- webviewParameter webview 相关设置,比如原生导航条
- easyConfig:为提升用户体验而提供的简化实现,比如 back 按键时,优先关闭弹出层
matchUrls 配置
matchUrls:页面链接匹配规则集合,类型为 Array,满足数组中任一项匹配条件,即可使用当前页面配置,故值域为 [matchurl1,matchurl2...]
选择匹配类型
- href:页面完整 url,类型为 String,可选,与 window.location.href 进行比较
- hostname 域名信息,类型为 String,可选,与 window.location.hostname 进行比较
- pathname 路径信息,类型为 String,可选,与 window.location.pathname 进行比较
- search 查询字符串,类型为 String,可选,与 window.location.search 进行比较
- hash 锚点信息,类型为 String,可选,与 window.location.hash 进行比较
例子
http://ask.dcloud.net.cn/article/12731?canshu=123#maodian1
href="http://ask.dcloud.net.cn/article/12731"
hostname="ask.dcloud.net.cn"
pathname="/article/12731"
search="?canshu=123"
hash="#maodian1"
选择匹配值表达式
- 默认为精确匹配,即字符串完全相等才匹配,如"/article/12731.html"
- 正则匹配:以"REGEX:"为前缀,可简写为"R:",后跟正则字符串,如"REGEX:/\/article\/\d+.html$/ "
- 通配符匹配:以"WILDCARD:"为前缀,可简写为"W:",后跟通配符,如 “WILDCARD:/article/*.html”
精确匹配模式
"pathname":"/login"
http://www.example.com/login // 匹配成功
http://www.example.com/login/ // 匹配失败,pathname 为 '/login/',最后多了一个 '/'
正则匹配模式
- ` /\/detail\/\d+.html$/ // 正则表达值字面量,/pattern/ 模式
new RegExp ("\/detail\/\d+\.html$") // 调用 RegExp 对象的构造函数
sitemap.json 是一个 JSON 格式的文件,不支持原生 JS
- REGEX:"或"R:"开头的字符串
- 通配符匹配模式 W:,"pathname": "W:/item/[0+]"
多条匹配规则同时设置的关系
{
"hostname":"m.example.com" // 匹配 hostname
"pathname":"/" // 匹配 pathname
}
三、其他配置
1). 系统状态栏
系统状态栏位于手机屏幕顶端
属性包含如下:
- style:状态栏前景色(文字颜色)
- dark:深色前景色样式(即状态栏前景文字为黑色)
- light:浅色前景色样式(即状态栏前景文字为白色)
- background:状态栏背景色,默认应该和原生导航条背景色一致;
- 在 wap2App 项目中,除首页外,其它页面默认均启用了原生导航条;因此,首页需要配置 background,其它页面,均无需配置。
background 首页未启用原生导航条
{
"webviewId": "__W2A__m.example.com",// 首页
"matchUrls": [
//url 配置规则
],
"webviewParameter": {
"titleNView": false,// 首页默认不使用原生导航
"statusbar": {
// 状态条背景色,
// 首页不使用原生导航条,颜色值建议和 global->webviewParameter->titleNView->backgroundColor 颜色值保持一致
"background": "#f7f7f7"
}
}
}
2).配置导航栏
1.配置导航栏的样式
- "backgroundColor": "#f7f7f7",// 导航栏背景色
- "titleColor": "#000000",// 标题颜色
- "titleSize": "17px"// 标题字体大小
- "titleText": '我的项目',// 导航栏标题
2.单独设置某个页面导航栏样式
在 pages 下设置 webviewParameter,titleNView 重写即可
"pages": [
{
"webviewid":"detail",// 详情页
"matchurls": [
{
"pathname": "R:\\/detail\\/\\d+"
}
],
"webviewParameter": {
"titleNView":{
"titleText":"新闻详情" // 单独设置新闻详情页的标题内容
}
}
}
]
3.导航条的启用 / 禁用
"titleNView": false
不使用原生导航条
2.完整的 titleNView 配置参数
{
"webviewId": "page1",
"matchUrls": [
//page1 url 匹配规则
],
"webviewParameter": {
"titleNView": {
"titleText": "原生标题栏",
"buttons": [
{
"float": "right",
"fontSize": "27px",
"fontSrc": "__wap2app.ttf",//wap2App 内置字体文件
"text": "\ue602",
"onclick": "JavaScript:plus.webview.getWebviewById ('page1').evalJS ('myshare ();')"
}
]
}
}
}
onclick 注意事项
总结一点,需要指定页面,调用函数,需要对应页面里面有这个函数
- 仅支持字符串类型,且以 JavaScript:为前缀
- 必须先获得对应的 webview,然后以 evalJS 的方式执行;evalJS 是 Webview 的标准 API,具体 API 参考 http://HTML5plus.org/doc/zh_cn/webview.html#plus.webview.WebviewObject,在里面搜 evalJS。
evalJS 的意思就是让某个 Webview 运行其内部的某个 JS 函数。
示例中,myshare () 这个函数写在 id 为 page1 的页面内,故需通过 plus.webview.getWebviewById ('page1') 获得目标 webview 对象,并且命令这个 Webview 运行 myshare 这个函数; - 目标页面的函数必须是全局函数(通过 Windows 可访问的的函数);示例中调用的 myshare 方法,需要写在原生标题栏所属的 webview 页面中;
- 真机运行时,首页 webview 的 id 为"HBuilder",若为首页原生标题增加按钮,则建议使用 plus.webview.getLaunchWebview ().evalJS ('myshare ()');
- 注意在 onclick 后面的 JS 里,不能写 plus.webview.currentWebview ()。因为 sitemap 不运行在任何 Webview 下,在 sitemap 里写的 JS 其实是和 app.js 一起运行在一个独立的、不可见的本地 Webview 中。所以若需要操作当前 titleNView 所在的 Webview,也必须指定明确的 WebviewID。
- 内置字体
向右箭头:\ue600 向左箭头(返回箭头):\ue601 分享图标:\ue602 收藏图标:\ue604 主页图标:\ue605 关闭图标:\ue650
通过 JS 动态调整 titleNView
`plus.webview.currentWebview ().setStyle ({titleNView: {titleText: 'new text'}});
首页启用原生导航条配置示例:
{
"webviewId": "__W2A__m.example.com",// 首页
"matchUrls": [
//url 配置规则
],
"webviewParameter": {
"titleNView": {// 首页启用原生导航条
"backgroundColor": "#FF00FF",// 导航栏背景色
"titleColor": "#00ffff",// 标题颜色为白色
"titleText": "wap2App 首页"
},
// 若首页启用了原生导航条,则建议将首页的 statusbar 配置为 false(或直接删除 statusbar 节点),这样状态条可以和原生导航条背景色保持一致;
"statusbar": false
}
}
3).subNViews 原生渲染区域,加快速度
而 Webview 则仍在慢慢经历:联网下载页面代码、构建 Dom、渲染 Dom 等过程。因此 subNView 是加快 Web 页面渲染的一大利器。如下为一个使用 subNView 增强后的商品详情页示例:
( 手册 )[http://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/12759]
在页面加载动画时,subNView 可以直接渲染出来,而后 wap 页面才慢慢渲染完毕。
"pages": [{
"webviewId": "__W2A__deli.kong-qi.com", // 首页
"matchUrls": [{
"href": "http://deli.kong-qi.com/mobile"
}, {
"href": "http://deli.kong-qi.com/mobile/"
}],
"webviewParameter": { // 参考文档【http://ask.dcloud.net.cn/docs/#//ask.dcloud.net.cn/article/12749】
"tabBar": { // 选项卡配置,仅首页支持
"height": "51px", // 选项卡高度,默认为 50px
"list": [{
"url": "http://deli.kong-qi.com/mobile"
},
{
"url": "http://deli.kong-qi.com/mobile/news.html"
},
{
"url": "http://deli.kong-qi.com/mobile/product.html"
},
{
"url": "http://deli.kong-qi.com/mobile/product.html"
},
{
"url": ""
}
]
},
"titleNView": false
}
},
{ // 复用前页数据 - 列表页
"webviewId": "nviewsList",
"matchUrls": [{
"href": "http://deli.kong-qi.com/mobile/product.html"
}],
"webviewParameter": {
"appendJs": "JS/list.js"
},
"easyConfig": {
"open": {
"waiting": false
}
}
},
{
"webviewId": "about", // 首页
"matchUrls": [{
"href": "W:http://deli.kong-qi.com/mobile/product/show/id/*"
}],
"webviewParameter": {
"subNViews": "detail.nview"
}
}
]
detail.nview 参考
<template>
<nviews cachemaxage="86400">
<nview id="detail_img" style="height:180px;">
<canvas style="width:100%; height:180px; top:0;">
<img src={data.cover} style="width:100%; height:200%;"/>
</canvas>
<richtext style="width:90%; position:absolute; left:5%; bottom:15px; height:40px;">
<font id="detail_title" style="color: #fff;font-size: 16px;">{data.title}</font>
</richtext>
</nview>
<nview style={{backgroundColor:'#ffffff',height:data.rem * 7.6,width:'100%'}}>
<imageslider images={data.imgs}></imageslider>
</nview>
</nviews>
</template>
<script>
module.exports = {
init: function (url) {
var self = this;
//wap2app.getFromCache// 取得缓存数据
wap2app.getFromCache ('detail_cache2', function (cacheData) {
console.log (JSON.stringify (cacheData));
if (cacheData){
self.setData (cacheData);// 设置页面的数据
}
});
wap2app.getFromWebService ({
url: 'http://hello.wap2app.dcloud.io/brand/detail',
data: {},
type: 'get'
}, function (data) {
self.data.imgs = data;
//TODO 如果服务端返回数据格式和模板需要的格式不同,则需要做一下转换
self.setData (self.data);
})
},
methods: {
// 方法
}
};
</script>
4).easyConfig
sitemap 中的 webviewParameter 配置其实是 HTML5Plus 规范中的 Webview 的参数设置。
back
用户按下 back 按键或点击顶部标题栏的返回箭头时,将触发 wap2App 的后退逻辑。
,back 按钮是关闭当前 Webview 并显示上一个 Webview。
目前 back 节点下有 before 和 history 这 2 个配置。
before
若页面有弹出层时,此时用户按下 back 按键,其实不应该把这个 Webview 关闭。
理想的效果是按下 back 时关闭弹出的浮层,当浮层关闭后再按 back 键,才是关闭 Webview。
wap2App 会智能处理弹出层的关闭,当用户点击 back 按键时,先探测当前页面是否存在弹出层,若存在则关闭弹出层,否则关闭当前页面。
- 全屏弹出层(比如 modal 组件),通常会提供按钮关闭弹出层,比如取消按钮或关闭图标
- 非全屏弹出层,通常也会有取消按钮,另外大多还会有半透明遮罩层,用户点击遮罩层,也可以关闭弹出层;
"easyConfig":{ "back":{ "before":[ { "popupSelector":".popup", // 弹出层选择器 "closeSelector":".mask", // 取消按钮选择器或遮罩层选择器 "eventType":"click" // 事件类型,默认为 "click" } ] } }
history
open
animation
wap2App 在打开新窗口时,新窗口默认使用从右向左的移动动画
"easyConfig":{
"open":{
"animation":{// 窗口切换动画配置
"type":"slide-in-right",// 窗口动画类型
"duration":300// 窗口动画执行时间
}
}
}
- "none": 无动画效果,立即显示页面,无任何动画效果,此效果忽略动画时间参数。
- "slide-in-right": 页面从屏幕右侧外向内横向滑动显示
- "slide-in-left": 页面从屏幕左侧向右横向滑动显示
- "slide-in-top": 页面从屏幕上侧向下竖向滑动显示
- "slide-in-bottom": 页面从屏幕下侧向上竖向滑动显示
- "fade-in": 页面从完全透明到不透明逐渐显示
- "zoom-out": 页面在屏幕中间从小到大逐渐放大显示
- "zoom-fade-out": 页面在屏幕中间从小到大逐渐放大并且从透明到不透明逐渐显示
- "pop-in": 页面从屏幕右侧滑入显示,同时上一个页面带阴影效果从屏幕左侧滑出隐藏
waiting
wap2App 在打开新窗口时,默认会显示 waiting 等待框,新 webview 的 titleUpdate 事件触发后,自动关闭 waiting 等待框
quit
用户在应用首页按下 back 按键,会触发 wap2App 的退出逻辑,应用退出的相关配置在 global->easyConfig->quit 节点下配置。
5).M 站改造
为什么要改造
我们在很多的时候,使用了原生代替,所以需要替代。
替换部分参考:
- 标题栏
- 头部导航
- 底部导航
替换 2 种方式
- 服务端判断使用场景
- wap2App 动态修改
服务器端修改
原理判断使用的浏览器类型 navigator.userAgent,例如 PHP
<?PHP
$agent = $_SERVER ['HTTP_USER_AGENT'];
if (strpos ($agent,"HTML5Plus") === false){// 仅在非 5+ 引擎环境下才显示导航栏
?>
<header class="mui-bar mui-bar-nav">
<a class="mui-action-back mui-icon mui-icon-left-nav mui-pull-left"></a>
<h1 class="mui-title">Web 导航栏</h1>
</header>
<?PHP
}
?>
wap2App 动态修改
1.动态增加样式 appendCss
"webviewParameter": {
"appendCss":"#header{display:none}" // 插入 CSS 代码
},
"appendCss":"page1.append.css" // 需插入的 CSS 文件路径
2.如果要自动运行调用
插入的 CSS 文件放在项目根目录下,然后遵循%webviewId%.append.css 这样的命名格式
3.动态 appendJs
跟 CSS 一样
4.下拉刷新 pullToRefresh
基于 div 方式的下拉刷新是不流畅,wap2App 框架提供了原生的下拉刷新
"webviewId":"page1",
"matchUrls": [
//url 匹配规则
],
"webviewParameter": {
"pullToRefresh":{
"support":true // 启用下拉刷新
}
},
"easyConfig":{}
}
5.tabBar
原生 App 切换选项卡时,选项卡区域不变,仅内容区 view 变化;但 M 站选项卡切换时,会将整个页面重新加载,经常出现白屏现象
优化思路
通过 2 个文件嵌套形式
实现方法
- 创建本地选项卡(client_index.html 中实现)
- 配置选项卡页面规则(sitemap.json 中实现)
创建本地选项卡
把上面的 JS 文件注释去掉
link rel="stylesheet" type="text/CSS" href="__wap2apptabbar.css" />
<script src="__wap2apptabbar.js" type="text/JavaScript" charset="utf-8"></script>
<script>
new TabBar ({
list: [{
url: "http://m.exampple.com/",
text: "首页",
iconPath: 'home.png',
selectedIconPath: 'home-selected.png'
}, {
url: "http://m.exampple.com/list.html",
text: "示例",
iconPath: 'tab1.png', // 本地图标
selectedIconPath: 'tab1-selected.png'
}, {
url: "http://m.exampple.com/about",
text: "关于",
iconPath: 'http://m.exampple.com/imgs/about.png',// 网络图标
selectedIconPath: 'http://m.exampple.com/imgs/about-selected.png'
}]
});
</script>
选项卡文字颜色配置
- 可以在 client_index.html 中通过 CSS 自定义选项卡文字颜色
<style type="text/CSS"> /*自定义选项卡文字颜色示例*/ .tab-item { color: black;// 选项卡文字默认为黑色 } .tab-item.active { color: blue;// 选项卡文字高亮时为蓝色 } </style>
Tips:自定义的 CSS 代码需要放在__wap2App_tabbar.css 的引用之后
6.配置选项卡页面规则
{
"webviewId": "__W2A__m.example.com",
"matchUrls": [
//URL 匹配规则
],
"webviewParameter": {
"tabBar": {// 选项卡配置,仅首页支持
"height": "50px",// 选项卡高度,默认为 50px
"list": [
{
"url": "http://m.exampple.com/" //tab1 页面地址
}, {
"url": "http://m.exampple.com/list.html" //tab2 页面地址
}, {
"url": "http://m.exampple.com/about.html" //tab3 页面地址
}
]
}
}
}
四、app.js
App () 函数接受一个 object 类型的 appConfig 参数,用来设定 wap2App 应用的生命周期函数
appConfig 参数说明:
- options Object 配置全局参数
- onLaunch Function 生命周期函数,监听 wap2App 应用初始化;当 wap2App 初始化完成时触发,全局只触发一次。
- onShow Function 生命周期函数,监听 wap2App 应用显示;当 wap2App 从后台进入前台显示时触发。
- onHide Function 生命周期函数,监听 wap2App 应用隐藏;当 wap2App 从前台进入后台显示时触发。
前台、后台定义: 当用户按了设备 Home 键,wap2App 应用并没有直接销毁,而是进入了后台;当再次打开 wap2App 应用时,又会从后台进入前台。App ({ options: { debug: false }, /** * 当 wap2App 初始化完成时,会触发 onLaunch */ onLaunch: function () { console.log ('launch'); }, /** * 当 wap2App 启动,或从后台进入前台显示,会触发 onShow */ onShow: function () { console.log ('show'); }, /** * 当 wap2App 从前台进入后台,会触发 onHide */ onHide: function () { console.log ('hide'); } });
Page () 函数用来注册一个页面。
Page (id,pageConfig);
id 是字符串类型,表示 webview 的 id,对应 sitemap.json 中配置的"webviewId"属性值。
- onShow Function 生命周期函数,监听 webview 显示;当对应 webview 窗口显示时触发。
- onHide Function 生命周期函数,监听 webview 关闭;当对应 webview 窗口关闭时触发。
Page ('page1', { /** * 当页面显示时触发 */ onShow: function (options) { console.log ('page1 show'); }, /** * 当页面关闭时触发 */ onClose: function () { console.log ('page1 hide'); } });
版权提示
1.除了标识原创之外,其他可能来源于网友的分享,仅供学习使用2.如您发现侵犯了您的权利,请联系我们删除
3.转载必须带本文链接,否则你将侵权
4.关于会员或其发布的相关内容均由会员自行提供,会员依法应对其提供的任何信息承担全部责任,本站不对此承担任何法律责任