轻应用组件

跳转到: 导航, 搜索

目录

轻应用组件是什么?

轻应用组件是轻应用提供给开发者的,应用内可以直接调用的小组件。

轻应用是区分 Web 版(PC 版)和 H5 版(移动版)的。

由于 Web 版和 H5 版的应用视觉设计差异较大,组件的功能也大不一样。因此,针对 Web 版和 H5 版,轻应用提供了不同的 JS 来支持,请开发者务必使用正确的 JS 文件。

(接入方的应用内,如何区分 Web 版和 H5 版请阅读轻应用开发指南 Web 版和 H5 版的区分部分)

Web 版轻应用组件调用

Web 版轻应用组件指的是轻应用 PC 版为接入方应用提供的、调用框架功能的 Javascript 功能包。

主要功能包括:设置 iframe 高度、获取父页面信息、改变父页面滚动条位置、唤起登录浮层等

引入 JS 文件

<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/frame/appclient.js" charset="utf-8"></script>

引入了这个 JS 到需要自适应高度的页面,你的应用就能自动适应高度了。


友情提示:为了对页面性能产生最小的影响,建议此文件放在 </body> 之前


API方法

触发行为

App.trigger('<cmd>', ['<param>', ['<function>]]);

  • • <cmd> 必选参数,指定行为的名称
  • • <param> 可选参数,指定调用行为的参数
  • • <function> 可选参数,指定行为的异步回调函数


<cmd> 列表如下


setPageHeight 设置iframe自身的高度

设置页面高度为 500px

App.trigger('setPageHeight', 500);

scrollTo 改变父页面滚动条位置

设置父页面滚动到顶部位置200px的地方

App.trigger('scrollTo', 200); 

设置父页面滚动到iframe的顶部位置

App.trigger('scrollTo', 'page');


parentInfo 获取父页面信息

App.trigger('parentInfo', function(parentWin) {
	console.log(parentWin);
	// parentWin.iframe.width 获得iframe宽度
	// parentWin.iframe.height 获得iframe高度
	// parentWin.iframe.left 获得iframe距离父页面左端的距离
	// parentWin.iframe.top 获得iframe距离父页面顶端的距离
	// parentWin.page.height 父页面高度
	// parentWin.page.width 父页面宽度
	// parentWin.page.scrollTop 父页面的滚动条scrollTop
	// parentWin.page.scrollLeft 父页面的滚动条scrollLeft
	// parentWin.page.url 父页面url
	// parentWin.win.width 父页面窗口宽度
	// parentWin.win.height 父页面窗口高度
});


login 唤起登录浮层

应用支持未登录状态下访问,必要的时候唤起登录浮层来登录微博。

App.trigger('login', {
	// 请注意,redirect_uri 是登录成功后回调的 URL,必须传的是 *.weibo.com 下的 URL,不支持第三方的地址
	'redirect_uri' : encodeURIComponent('http://apps.weibo.com/1852339337/8s1i6v74?key=g-16504')
});


setShareDefaultText 设置分享功能的默认文案

App.trigger('setShareDefaultText', "默认文案 http://weib.com");


sendMessage 唤起私信浮层或者IM

// 第二个参数为必选,提供 UID、昵称,用半角逗号分隔
App.trigger('sendMessage', "1406758883,Bencalie");


deliverAddress:default 【共享地址簿组件 PC 版】获得当前登录用户的默认收货地址

/* 回调函数的形参是 addr
 * 如果没有默认收货地址,返回 null
 * 如果有收货地址,返回一个 JSON,形如
 *	{
 *		'name' : '张三',
 *		'mobile' : '13901234567',
 *		'address' : '北京海淀中关村大街40号'
 *	}
 */
App.trigger('deliverAddress:default', function(addr){
	var result = (addr == null) ? "亲,你没有设置默认收货地址" : addr.name + " " + addr.mobile + " " + addr.address;
	document.getElementById('address').innerHTML = result;
});


deliverAddress:change 【共享地址簿组件 PC 版】选择别的收货地址、或管理收货地址(增删改查)

/* 回调函数的形参是 addr
 * 如果用户选择了一个收货地址,返回一个 JSON,形如
 *	{
 *		'name' : '张三',
 *		'mobile' : '13901234567',
 *		'address' : '北京海淀中关村大街40号'
 *	}
 */
App.trigger('deliverAddress:change', function(addr){
	var result = (addr == null) ? "亲,你没有设置默认收货地址" : addr.name + " " + addr.mobile + " " + addr.address;
	document.getElementById('address').innerHTML = result;
});


setTitle 设置父页面标题栏(此API暂未开放)

App.trigger('setTitle', "Home-My Application Name");


事件监听 (on/off)

App.on('<event>;', '<function>'); App.off('<event>', '<function>');

  • • <event>为必选参数,指定要监听的事件称
  • • <function>为可选参数,指定事件的异步回调函数

<event> 列表如下


scroll 外层滚动页面的事件

绑定 scroll 事件

App.on('scroll', function(scrollPos){
	console.log(scrollPos);
	// scrollPos.top 纵向滚动条距顶部距离
	// scrollPos.left 横向滚动条距左边框距离
})

解绑 scroll 事件

App.off('scroll', <function>)


resize 外层改变页面大小的事件

绑定 resize 事件

App.on('resize', function(parentWin) {
	console.log(parentWin);
	// parentWin.page.width 父页面宽度
	// parentWin.page.height 父页面高度
	// parentWin.win.width 父页面窗口宽度
	// parentWin.win.height 父页面窗口高度
});

解绑 resize 事件

App.off('resize', <function>)


常见问题

我的应用为什么没有高度自适应?

  • • 检查是否引入了微博提供的 JS 文件
  • • 检查引入 JS 文件的 URL 是否正确?


H5 版轻应用组件调用

H5 版轻应用组件指的是轻应用移动版(内嵌在微博客户端中)为接入方应用提供的、唤起微博原生功能的 JavaScript 功能包。

让轻应用能实现诸如获取当前网络状态、获取定位信息、唤起客户端二维码扫描、查看大图等功能,同时也提供了一些组件供接入方调用,如共享地址簿组件。

使用条件

微博 Android 与 iPhone 官方客户端 4.3.0 以上版本的内置浏览器。

引入 JS 文件

使用 H5 版 JS API,需要首先引入一个 JS 文件。

<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/pageapp/mobile/jsapi.js" charset="utf-8"></script>


该 JS 文件会使用全局命名空间 WeiboJSBridge,提供了两个 JS 方法:

  • • WeiboJSBridge.invoke() 用途:调用 Bridge 的 Action 或组件
  • • WeiboJSBridge.on() 用途:监听 Bridge 的事件


下面,一一进行说明:

WeiboJSBridge.invoke()

通过 `window.WeiboJSBridge` 的 `invoke` 方法来调用 bridge 的 action。

例如:

WeiboJSBridge.invoke("getNetworkType", {"param" : "value"}, function (params, success, code) {
	if (success) {
		document.write('网络状态是' + params.network_type);
	} else {
		if (code == WeiboJSBridge.STATUS_CODE.NO_RESULT) {
			// do something.
		}
	}
});

第一个参数为要调用的 action,第二个为 参数列表,第三个为回调函数。

Action 列表

openImage 查看大图

- 参数列表:

  • `url`: 当前选中的图片src;
  • `urls`: 当前页面中的所有图片src,用于支持横滑查看

- 返回值:无

- 错误码:

  • `MISSING_PARAMS`: `url` 与 `urls` 至少需要传递一个


getNetworkType 获取网络状态

- 参数列表:无

- 返回值:`{"network_type": "wwan"}`,`wwan` 代表 2G 或 3G, `wifi` 代表 WIFI, `fail` 代表无网络


scanQRCode 扫描二维码

- 参数列表:无

- 返回值:`{"result": "http://weibo.com"}`

- 错误码:

  • `USER_CANCELLED`: 用户取消了扫描
  • `SERVICE_FORBIDDEN`: 设备没有摄像头或用户不允许使用摄像头


pickImage 获取照片

- 参数列表:

  • `source`: `camera` 为拍照,其他为从相册选择

- 返回值:`{"base64": "9sa1..."}`

- 错误码:

  • `USER_CANCELLED`: 用户取消了选图
  • `SERVICE_FORBIDDEN`: 设备没有摄像头或用户不允许选图


getLocation 定位

- 参数列表:无

- 返回值:`{"lat": 100, "long": 100}`

- 错误码:

  • `SERVICE_FORBIDDEN`: 定位服务不可用
  • `NO_RESULT`: 获取位置失败


queryPreloadCache 获取预加载内容

- 使用条件:

  • 仅 weibo.com、weibo.cn 及其子域名可以调用

- 参数列表:

  • `cid`: 内容的id,必需

- 返回值:`{"result": "{'key': 'value'}"}`,result为内容预加载接口返回值

- 错误码:

  • `MISSING_PARAMS`: 未传递 `cid` 参数
  • `NO_RESULT`: 指定缓存不存在
  • `INTERNAL_ERROR`: 缓存读取失败
  • `ILLEGAL_ACCESS`: 调用域名无权限访问


deletePreloadCache 删除预加载缓存

- 使用条件:

  • 仅 weibo.com、weibo.cn 及其子域名可以调用

- 参数列表:

  • `cid`: 内容的id,必需

- 返回值:无

- 错误码:

  • `MISSING_PARAMS`: 未传递 `cid` 参数
  • `INTERNAL_ERROR`: 文件删除失败(不包括缓存不存在)
  • `ILLEGAL_ACCESS`: 调用域名无权限访问


setBrowserTitle 设置顶导标题

- 参数列表:

  • `title`: 新标题,必需

- 返回值:无

- 备注:通过此方法设置的标题优先级最高

- 错误码:

  • `MISSING_PARAMS`: 未传递 `title` 参数


login 唤起登录功能

- 参数列表:

  • `redirect_uri`: 登录后回调的地址,必需。并且该 URL 必须是 http://apps.weibo.com 开头,不接受任何其他域名的 URL

- 返回值:无

WeiboJSBridge.invoke("login", {
	"redirect_uri" : encodeURIComponent("http://apps.weibo.com/test/1406758883/2I8KtA/demo/game/yangtuo")
}, function (params, success, code) {});

setIframeSize 设置 iframe 高度

此方法用于解决部分 Android 机器下页面动态添加了内容,但滚动条拉不到底的问题。


- 参数列表:

  • `title`: 新标题,必需

- 返回值:无

- 备注:通过此方法设置的标题优先级最高

WeiboJSBridge.invoke("setIframeSize", {
	'height' : 500		// 开发者需要自行计算动态添加内容后的页面高度,并当参数传递
});


组件的使用在下文说明


Status Code 列表

状态码会在 action 的回调中提供

OK: 				操作成功
MISSING_PARAMS: 	缺少必须的参数
ILLEGAL_ACCESS: 	非法调用
INTERNAL_ERROR: 	客户端内部处理错误
ACTION_NOT_FOUND: 	客户端未实现此 action
NO_RESULT: 			客户端没有获取到结果
USER_CANCELLED: 	用户取消了操作
SERVICE_FORBIDDEN: 	相关服务未启用或被禁止 (如定位服务,相册权限)


网页通过比对回调的code值和以上值进行处理

if (code == WeiboJSBridge.STATUS_CODE.NO_RESULT) {
	// 客户端没有获取到结果
}


WeiboJSBridge.on()

有时 native 会给网页发送一些事件通知,网页可以选择性接收。


WeiboJSBridge.on('networkTypeChanged', function(params){
	document.write('网络状态已变为:' + params.network_type);
});

Event 列表

networkTypeChanged 网络状态改变

- 使用条件:

  • 目前仅iPhone支持

- 返回结果:

  • `network_type`: 改变后的状态,`wwan` 或 `wifi` 或 `fail`


orientationChange屏幕旋转事件

- 使用条件:无

- 返回结果:

  • `orientation`: 屏幕方向的状态,即 window.orientation 的取值

共享地址簿组件

共享地址簿组件用于接入方获得当前微博用户在微博的收货地址。目前处于内部体验阶段,不向所有接入方开放。

组件有两种形态:

PC 版:

address_web.png

H5 版:

address.png


第一步、使用共享地址簿组件,需要申请,请将 appkey 发送给 wanglei25@staff.weibo.com 申请该组件的使用权限。

第二步、代码开发。共享地址簿组件提供了两个 Action 供调用:


PC 版调用方法:(也可以点击这里

1、获取默认收货地址

App.trigger('deliverAddress:default', function(addr){ /* 回调函数 */ });


2、选择其他的收货地址(可以增加、删除、修改地址)

App.trigger('deliverAddress:change', function(addr){ /* 回调函数 */ });


完整 Web 版调用范例:

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" />
	<title>共享地址簿组件 Web 版</title>
</head>
<body>
	<div id="address">收货地址读取中……</div>
	<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/frame/appclient.js" charset="utf-8"></script>
	<script>
		function $(o){
			return document.getElementById(o);
		}
		// 显示地址组件返回的地址
		function showAddress(addr){
			var address = $("address");
			if(addr == null){
				address.innerHTML = "没有默认收货地址";
			} else {
				address.innerHTML = addr.name + " " + addr.mobile + " " + addr.address;
			}
		}
		// 获取当前登录用户的默认收货地址
		App.trigger('deliverAddress:default', showAddress);

		// 给地址区域绑定点击事件,点击该区域,唤起地址组件选择界面
		$('address').onclick = function(){
			App.trigger('deliverAddress:change',  showAddress);
		};
	</script>
</body>
</html>


H5 版调用方法:


1、获取默认收货地址

WeiboJSBridge.invoke("deliverAddress:default", {}, function(addr){ /* 回调函数 */ });


2、选择其他的收货地址(可以增加、删除、修改地址)

WeiboJSBridge.invoke("deliverAddress:change", {}, function(addr){ /* 回调函数 */ });


完整 H5 版调用范例:

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" />
	<title>共享地址簿组件 H5 版</title>
</head>
<body>
	<div id="address">收货地址读取中……</div>
	<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/pageapp/mobile/jsapi.js" charset="utf-8"></script>
	<script>
		function $(o){
			return document.getElementById(o);
		}
		// 显示地址组件返回的地址
		function showAddress(addr){
			var address = $("address");
			if(addr == null){
				address.innerHTML = "没有默认收货地址";
			} else {
				address.innerHTML = addr.name + " " + addr.mobile + " " + addr.address;
			}
		}
		// 获取当前登录用户的默认收货地址
		WeiboJSBridge.invoke("deliverAddress:default", {}, showAddress);

		// 给地址区域绑定点击事件,点击该区域,唤起地址组件选择界面
		$('address').onclick = function(){
			WeiboJSBridge.invoke("deliverAddress:change", {}, showAddress);
		};
	</script>
</body>
</html>

轻应用 H5 底导

轻应用在微博客户端内现在都是在对象正文页的内置浏览器展示(底部有转评赞按钮),它是有一定缺陷的,如:

  • 不支持内页分享。比如你的应用内有一个对象,点击对象内的链接,iframe 内部跳转到一个非对象的 URL,这时候你点转发,仍然分享的是刚开始进来的对象的信息。
  • 不支持定制分享文案。点转发唤起的发布器,文案是固定的,你无法修改。
  • 可定制性差

目前,轻应用提供了一款 H5 底导组件,该组件用 HTML+JavaScript 实现,和现在的对象正文页底导 UI 几乎雷同,但能够支持内页分享,并且文案可以随心所欲的定制。目前处于内部体验阶段,不向所有接入方开放。

h5nav.jpg

接入方式:


第一步、使用轻应用 H5 底导,需要申请,请将 appkey 发送给 wanglei25@staff.weibo.com 申请该组件的使用权限。

第二步、在需要支持内页分享的页面内,引入轻应用组件移动版的 JS。

<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/pageapp/mobile/jsapi.js" charset="utf-8"></script>

这时候,你就能直接看到组件了。

第三步、修改默认分享文案。

WeiboJSBridge.invoke('bottomNavigation:info', {
	"title" : "我的分享文案,爱怎么写就怎么写,哈哈"
}, function(){});

完整范例:

<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8" />
	<title>轻应用 H5 底导</title>
</head>
<body>
	<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/pageapp/mobile/jsapi.js" charset="utf-8"></script>
	<script>
		WeiboJSBridge.invoke('bottomNavigation:info', {
			"title" : "我的分享文案,爱怎么写就怎么写,哈哈"
		}, function(){});
	</script>
</body>
</html>

轻应用 H5 组件Demo

请使用微博客户端扫描下方二维码查看演示Demo:


8aafa3b9jw1eq42k689zxj20430433ym.jpg


Demo中涉及到的接口详情详见以下文档:


微博支付应用接入指南:http://open.weibo.com/wiki/微博支付应用接入指南


微博API接口文档:http://open.weibo.com/wiki/%E5%BE%AE%E5%8D%9AAPI

更新日志

  • • 2014.08.22 轻应用移动端增加 H5 底导、唤起登录功能
  • • 2014.08.08 轻应用 PC 端增加唤起收货地址组件功能,简化了 H5 版组件的调用
  • • 2014.08.05 轻应用 PC 端增加唤起私信浮层或 IM 功能
  • • 2014.06.18 合并 Web 版 Javascript 包文档到轻应用组件
文档更新时间: 2016-04-15