关于 Sona.js
Sona.js 是一个沉淀了 CDC 团队在 H5 开发中常用的解决方案类库，她包括以下 7 个主要模块。
- Analytics - 统计模块
- Loader - 加载器模块
- Orientation - 横竖屏提示模块
- Scale - 页面适配模块
- Share - 微信分享模块
- Slider - 滑屏模块
- Wechat - 微信通用工具模块
Sona 的名字来源于 Leagues of legend 中一个强大的辅助型英雄 Sona，寓意着一个强大的辅助型类库。
这篇文档主要是为了开发者能快速了解 Sona.js 的一些基本功能，如果你想深入了解 Sona.js，你可以查看 Sona.js 的完整文档。
同时，我们也欢迎你在 http://git.code.oa.com/mozi/S3 协助贡献你的解决方案。
引入 Sona.js
使用 Sona.js 需要在 HTML 文档中引入 Sona.js，通常我们将 Sona.js 放在页面底部（</body> 标签之前）。
<script src="//h5app.qq.com/act/sona/0.0.1/sona.min.js"></script>Analytics 统计模块
Analytics 封装了 MTA统计，该模块需要进行统计配置后使用。
- DEMO: http://mozi.cdc.im/sona/examples/analytics.html
- 文档: http://mozi.cdc.im/sona/docs/Analytics.html
统计配置
在 <head> 标签内声明全局变量 window._SONA_.analytics 即可启用 MTA 统计。
<script>
// mta 统计配置
window._SONA_ = {
// 设置了 analytics 属性后将自动开启统计
analytics: {
name: 'a20161015sona', // 统计前缀，用于区分流量
cid: '500001169', // mta 统计 cid
sid: '500000270' // mta 统计 sid
}
};
</script>_SONA_.analytics.name 为项目名称，建议使用 a + 项目日期 + 项目名称 的形式命名，如 a20161015sona，用于区分流量。
通过设置 _SONA_.analytics.cid 和 _SONA_.analytics.sid 使用自己的 MTA 统计代码。
统计自定义事件
为了方便分析用户数据，你可以使用以下方法统计自定义事件。
// 记录事件 `buy.item1`
Sona.Analytics.send('buy.item1');微信分享统计
如果在网页内配置了 window._SONA_.analytics， Sona.Share 模块将会在用户分享后自动统计分享次数，无需再次手动统计。
Loader 加载器模块
预加载文件列表
var loader = new Sona.Loader({
files: [
{ src: '//res.wx.qq.com/open/libs/jquery/1.11.3/jquery.js' },
{ src: '//res.wx.qq.com/open/libs/weui/1.0.1/weui.css' },
{ src: '//h5app.qq.com/act/TEG/TEG_AI/media/music-bg.mp3', id: 'music' },
{ src: '//h5app.qq.com/act/common/TencentTop/1.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/2.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/3.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/4.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/5.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/6.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/7.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/8.jpg' },
{ src: '//h5app.qq.com/act/common/TencentTop/9.jpg' }
],
onProgress: function (file, target, time, percent) {
// file 为文件对象, target 为文件 dom, time 为单个文件加载时间, percent 为加载百分比
console.log('已加载:' + percent + '%');
},
onComplete: function (time) {
console.log('加载完成，耗时:' + time + 'ms');
}
});预加载单个文件
Sona.Loader.loadItem(
{src: '//h5app.qq.com/act/common/TencentTop/1.jpg'},
function (file, target, time) {
// file 为文件对象, target 为文件 dom, time 为文件加载时间
console.log('文件加载完成');
}
);Orientation 横竖屏提示模块
- DEMO: http://mozi.cdc.im/sona/examples/orientation.html
- 文档: http://mozi.cdc.im/sona/docs/orientation.html
横屏提示
var orientationHinter = new Sona.Orientation();竖屏提示
var orientationHinter = new Sona.Orientation({show: 'portrait'});其他属性
var orientationHinter = new Sona.Orientation({
// 'landscape' 为横屏显示,'portrait' 为竖屏显示, 默认为 'landscape'
show: 'landscape',
// 提示文字, 不设置时, 横屏时显示 "竖屏体验效果更佳", 竖屏时显示 "横屏体验效果更佳"
text: '翻转屏幕体验更好',
// 使用半透明背景, 默认为 false
transparent: true,
// 允许用户关闭提示, 默认为 false
canClose: true
});Scale 页面适配模块
使用 rem 适配页面
使用 rem 适配页面是通过对比设计稿尺寸和设备尺寸，计算 html 根元素的 font-size，并在全站使用 rem 单位，达到适配页面的目的。
var scale = new Sona.Scale({
// 页面实际宽度
actualWidth: 375,
// 页面实际高度
actualHeight: 603
});使用 transform 适配页面
使用 transform 适配页面是通过对比设计稿尺寸和设备尺寸，计算缩放比，对页面元素使用 transform: scale(x) 缩放进行适配。
var scale = new Sona.Scale({
// 需要缩放的页面元素, 仅在 scaleType = 'transform' 时需要设置
container: '#page',
// 缩放方式, 默认为 rem
scaleType: 'transform',
// 页面实际宽度
actualWidth: 375,
// 页面实际高度
actualHeight: 603
});适配模式
Scale 模块默认使用的适配模式是 Sona.Scale.SHOW_ALL 模式，即『保持原始宽高比缩放应用程序内容，缩放后应用程序内容的较宽方向填满播放器视口，另一个方向的两侧可能会不够宽而留有黑边』。
开发者可以根据需要自己设置适配模式，初始化时设置 scaleMode 属性：
// 不保持原始宽高比缩放应用程序内容，缩放后应用程序内容正好填满播放器视口。
Sona.Scale.EXTRACT_FIT
// 保持原始宽高比缩放应用程序内容，缩放后应用程序内容在水平和垂直方向都填满播放器视口，但只保持应用程序内容的原始高度不变，宽度可能会改变。
Sona.Scale.FIXED_HEIGHT
// 保持原始宽高比缩放应用程序内容，缩放后应用程序内容在水平和垂直方向都填满播放器视口，应用程序内容的较窄方向可能会不够宽而填充。
Sona.Scale.FIXED_NARROW
// 保持原始宽高比缩放应用程序内容，缩放后应用程序内容在水平和垂直方向都填满播放器视口，应用程序内容的较宽方向的两侧可能会超出播放器视口而被裁切
Sona.Scale.FIXED_WIDE
// 保持原始宽高比缩放应用程序内容，缩放后应用程序内容在水平和垂直方向都填满播放器视口，但只保持应用程序内容的原始宽度不变，高度可能会改变
Sona.Scale.FIXED_WIDTH
// 保持原始宽高比缩放应用程序内容，缩放后应用程序内容的较窄方向填满播放器视口，另一个方向的两侧可能会超出播放器视口而被裁切
Sona.Scale.NO_BORDER
// 不缩放应用程序内容
Sona.Scale.NO_SCALE
// 保持原始宽高比缩放应用程序内容，缩放后应用程序内容的较宽方向填满播放器视口，另一个方向的两侧可能会不够宽而留有黑边
Sona.Scale.SHOW_ALL一张图了解 Sclae 适配模式
Share 微信分享模块
注：分享模块仅在 *.qq.com 和 *.tencent.com 等白名单域名下有效。
设置微信分享文案
var share = new Sona.Share({
// 分享标题
title: 'Sona.js by Lukezhu',
// 分享描述
desc: 'Mobile solution tookit.',
// 分享缩略图, 允许使用相对路径
thumb: './images/cover.jpg',
// 分享链接, 默认是当前页面链接
link: window.location.href,
// 分享成功后回调
success: function(type, status) {
// ...
},
// 取消分享后回调
cancel: function(type, status) {
// ...
},
// 分享失败后回调
fail: function(type, status) {
// ...
}
});更新微信分享属性
如果需要更新已经实例化的分享属性，可以直接设置分享属性进行更新。
share.title = '修改后的分享标题';批量更新分享属性
如果需要更新多个属性，可以使用 setContent 方法进行批量更新。
share.setContent({
title: '更新后的分享标题',
desc: '更新后的分享描述',
thumb: '../images/cover1.jpg',
link: 'http://mozi.cdc.im/'
});Slider 滑屏模块
待更新
Wechat 微信通用工具模块
禁用调整字体大小
// 禁用调整字体大小
Sona.Wechat.disableFontResize();隐藏/显示右上角菜单
// 隐藏右上角菜单
Sona.Wechat.hideMenu();
// 显示右上角菜单
Sona.Wechat.showMenu();预览图片
// 预览图片, 支持相对路径
Sona.Wechat.imagePreview('../images/1.jpg', ['../images/1.jpg', '../images/2.jpg']);关闭当前网页
// 关闭当前网页
Sona.Wechat.closeWindow();