cdc-sona

v1.0.2

Published

2 years ago

Mobile solution tookit.

Downloads

0High
0Medium
0Low

ontheroad1992

s3 mobile tookit

关于 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统计，该模块需要进行统计配置后使用。

统计配置

在 <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 加载器模块

DEMO: http://mozi.cdc.im/sona/examples/loader.html
文档: http://mozi.cdc.im/sona/docs/Loader.html

预加载文件列表

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 横竖屏提示模块

横屏提示

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 页面适配模块

文档: http://mozi.cdc.im/sona/docs/Scale.html

使用 rem 适配页面

使用 rem 适配页面是通过对比设计稿尺寸和设备尺寸，计算 html 根元素的 font-size，并在全站使用 rem 单位，达到适配页面的目的。

DEMO: http://mozi.cdc.im/sona/examples/scale_rem.html

var scale = new Sona.Scale({
    // 页面实际宽度
    actualWidth: 375,
    // 页面实际高度
    actualHeight: 603
});

使用 transform 适配页面

使用 transform 适配页面是通过对比设计稿尺寸和设备尺寸，计算缩放比，对页面元素使用 transform: scale(x) 缩放进行适配。

DEMO: http://mozi.cdc.im/sona/examples/scale_transform.html

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 微信分享模块

DEMO: http://mozi.cdc.im/sona/examples/share.html
文档: http://mozi.cdc.im/sona/docs/Share.html

注：分享模块仅在 *.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 滑屏模块

DEMO: http://mozi.cdc.im/sona/examples/slider.html
文档: http://mozi.cdc.im/sona/docs/Slider.html

待更新

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();