API Reference

Plugins

Native.js


share

Share模块管理客户端的社交分享功能,提供调用终端社交软件的分享能力。通过plus.share可获取社交分享管理对象。

方法:

对象:

回调方法:

模块:

permissions


{
// ...
"permissions":{
	// ...
	"Share": {
		"description": "分享"
	}
}
}
			

getServices

获取分享服务


void plus.share.getServices(successCB, errorCB);
				

说明:

获取终端支持的分享通道列表,可用于提示用户进行分享服务器的选择。获取分享服务成功后通过successCB回调返回支持的所有服务列表,获取服务失败则通过errorCB回调返回。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Share Example</title>
	<script type="text/javascript">
var shares=null;
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.share.getServices(function(s){
		shares = s;
	}, function(e){
		alert("获取分享服务列表失败:"+e.message);
	});
}, false );
	</script>
	</head>
	<body>
	</body>
</html>
				

sendWithSystem

使用系统组件发送分享


void plus.share.sendWithSystem(msg, successCB, errorCB);
				

说明:

调用系统分享组件分享消息,通过msg参数设置分享内容。 发送成功后通过successCB回调函数通知操作完成,发送失败则通过errorCB回调返回。

参数:

返回值:

void : 无

平台支持:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Share Example</title>
	<script type="text/javascript">
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
}, false);
// 通过系统组件分享 
function shareSystem(){
	plus.share.sendWithSystem({content:'分享内容',href:'http://www.dcloud.io/'}, function(){
		console.log('分享成功');
	}, function(e){
		console.log('分享失败:'+JSON.stringify(e));
	});
}
	</script>
	</head>
	<body>
		使用系统组件发送分享<br/>
		<button onclick="shareSystem()">发送分享</button>
	</body>
</html>
				

ShareService

分享服务对象


interface plus.share.ShareService {
	// Attributes
	attribute DOMString id;
	attribute DOMString description;
	attribute Boolean authenticated;
	attribute DOMString accessToken;
	attribute Boolean nativeClient;
	
	// Methods
	function void authorize(successCallback, errorCallback, options);
	function void forbid();
	function void send(message);
}
				

说明:

ShareService对象用于表示分享服务,在JS中为对象,用于向系统请求分享操作。

属性:

方法:

id

分享服务标识

说明:

ShareServerIdentity 类型 只读属性

用于表示分享服务标识: "sinaweibo" - 表示新浪微博; "tencentweibo" - 表示腾讯微博; "weixin" - 表示微信; "qq" - 表示腾讯QQ。

description

分享服务描述

说明:

DOMString 类型 只读属性

用于描述分享服务的信息: 如“新浪微博”、“腾讯微博”、“微信”、“QQ”。

authenticated

是否授权认证

说明:

Boolean 类型 只读属性

用于标识此分享是否已经授权认证过,true表示已完成授权认证;false表示未完成授权认证。

accessToken

授权认证信息

说明:

DOMString 类型 只读属性

仅在authenticated为true时有效,标识客户认证标识信息,用于发送分享信息。

nativeClient

是否存在对应的分享客户端

说明:

Boolean 类型 只读属性

对于某些分享服务,可直接调用本地客户端程序进行授权认证,此属性即可提供此相关信息,若没有安装本地客户端则可能调用其它方式进行分享操作,如WAP方式等。

authorize

授权认证操作


						
void obj.authorize(successCallback, errorCallback, options);
						
						

说明:

对指定的分享服务进行授权认证操作,在授权前可通过ShareService.authenticated属性判断是否已经授权过,通常只需要对没有进行过授权认证的服务进行授权认证操作。 授权认证操作成功后通过successCB回调函数通知操作完成,操作失败则通过errorCB回调返回。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Share Example</title>
	<script type="text/javascript">
var shares=null;
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.share.getServices(function(s){
		shares = s;
	}, function(e){
		console.log("获取分享服务列表失败:"+e.message);
	} );
}, false);
function shareAction(){
	var s = shares[0];
	if(!s.authenticated){
		s.authorize(functioin(){
			console.log("认证完成!");
		}, function(e){
			console.log("未进行认证");
		} )
	}
}
	</script>
	</head>
	<body>
	</body>
</html>
						

forbid

取消授权认证


void obj.forbid();
						

说明:

对指定的分享服务取消授权认证操作,取消授权认证后,再次分享时需重新进行授权操作。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Share Example</title>
	<script type="text/javascript">
var shares=null;
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.share.getServices(function(s){
		shares = s;
	}, function(e){
		alert("获取分享服务列表失败:"+e.message);
	} );
}, false);
// 取消所有分享服务的
function cancelAuthorize(){
	for(var i in shares){
		var s = shares[i];
		if(s.authenticated){
			s.forbid();
		}
	}
}
	</script>
	</head>
	<body>
	</body>
</html>
						

send

发送分享


void obj.send(msg, successCB, errorCB);
						

说明:

发送分享消息,分享消息的内容通过msg设置。 发送成功后通过successCB回调函数通知操作完成,发送失败则通过errorCB回调返回。若分享服务没有进行授权认证或授权认证失效则触发失败回调函数。

参数:

返回值:

void : 无

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>Share Example</title>
	<script type="text/javascript">
var shares=null;
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.share.getServices(function(s){
		shares = s;
	}, function(e){
		alert("获取分享服务列表失败:"+e.message);
	});
}, false);
/**
 * 分享操作
 * @param {plus.share.ShareService} s
 */
function shareAction(s){
	if(!s){
		return;
	}
	if(s.authenticated){
		shareMessage(s);
	}else{
		s.authorize(shareMessage, function(e){
			alert("未进行认证");
		});
	}
}
/**
 * 发送分享消息
 * @param {plus.share.ShareService} s
 */
function shareMessage(s){
	s.send({content:"Hello"}, function(){
		alert("分享成功!");
	},function(e){
		alert("分享失败:"+e.message);
	});
}
	</script>
	</head>
	<body>
		发送分享<br/>
		<button onclick="shareAction(shares[0])">发送分享</button>
	</body>
</html>
						

ShareServerIdentity

分享服务标识

常量:

ShareMessage

JSON对象,分享消息对象


interface plus.share.ShareMessage {
	attribute String type;
	attribute String content;
	attribute String[] thumbs;
	attribute String[] pictures;
	attribute String media;
	attribute String href;
	attribute String title;
	attribute JSON extra;
	attribute GEOPosition geo;
	attribute ShareMessageExtra extra;
	attribute ShareMiniProgram miniProgram;
	attribute String interface;
}
				

说明:

ShareMessage对象用于表示分享消息内容,在JS中为JSON对象,用于向系统发送分享信息操作。

属性:

GeoPosition

JSON对象,用户位置信息


interface plus.share.GeoPosition {
	attribute Number latitude;
	attribute Number longitude;
}
				

说明:

GeoPosition对象用于表示用户分享消息时的位置信息。用于标识分享操作时用户的位置信息。

属性:

ShareMessageExtra

JSON对象,保存分享消息扩展信息


interface plus.share.ShareMessageExtra {
	attribute String scene;
}
				

说明:

ShareMessageExtra对象用于保存各分享平台扩展的参数,用于自定义分享功能。

属性:

ShareMiniProgram

JSON对象,保存微信小程序信息


interface plus.share.ShareMiniProgram {
	attribute String id;
	attribute String path;
	attribute Nnumber type;
	attribute webUrl;
}
				

说明:

用于配置分享小程序的参数,如小程序标识、页面路径等。 注意:分享的小程序需要在微信开放平台关联的开发者账号下,否则会分享失败。

属性:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
var sweixin=null;
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.oauth.getServices(function(services){
		auths = services;
		sweixin=shares['weixin'];
	}, function(e){
		alert("获取分享服务列表失败:"+e.message+" - "+e.code);
	});
}, false );
// 发送分享
function doShare(srv, msg){
	outLine(JSON.stringify(msg));
	srv.send(msg, function(){
		outLine('分享到"'+srv.description+'"成功!');
	}, function(e){
		outLine('分享到"'+srv.description+'"失败: '+JSON.stringify(e));
	});
}
// 分享小程序
function shareMiniProgram(){
    if(!sweixin){
		plus.nativeUI.alert('当前环境不支持微信分享操作!');
    }
	var msg={type:'miniProgram',title:'分享小程序标题',thumbs:['_www/mp.png']};
	msg.content = '分享小程序描述内容。';
	msg.miniProgram={id:'g_XXXXXXX',	// 小程序的原始标识
    webUrl:'http://www.dcloud.io/'};
	// 发送分享
	if(sweixin.authenticated){
		doShare(sweixin, msg);
	}else{
		sweixin.authorize(function(){
			doShare(sweixin, msg);
		}, function(e){
			console.log('认证授权失败:'+JSON.stringify(e));
		});
	}
}
	</script>
	</head>
	<body>
		<button onclick="shareMiniProgram()">分享小程序</button>
	</body>
</html>
				

AuthOptions

JSON对象,分享授权认证参数选项


interface plus.share.AuthOptions {
	attribute String appid;
	attribute String appkey;
	attribute String appsecret;
	attribute String redirect_uri;
}
				

说明:

此对象支持的属性值由分享服务的授权认证模块定义。

属性:

示例:


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8"/>
	<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
	<title>OAuth Example</title>
	<script type="text/javascript">
var auths=null;
// 监听plusready事件  
document.addEventListener("plusready", function(){
	// 扩展API加载完毕,现在可以正常调用扩展API
	plus.oauth.getServices(function(services){
		auths = services;
	}, function(e){
		alert("获取分享服务列表失败:"+e.message+" - "+e.code);
	});
}, false );
// 登录操作
function authLogin(){
	var s = auths[0];
	if(!s.authResult){
		s.login(function(e){
			alert("登录认证成功!");
		}, function(e){
			alert("登录认证失败!");
		}, {appid:"wx0411fa6a39d61297"  // 微信应用的appid
			,scope:"snsapi_userinfo"}   // 授权获取用户信息
		);
	}
}
	</script>
	</head>
	<body>
		请求授权登录认证操作(配置参数)
		<button onclick="authLogin()">Login</button>
	</body>
</html>
				

Authorize

分享授权控件对象


interface plus.share.Authorize{
	// Methods
	function void load(id);
	function void setVisible(visible);

	// Events
	function void onloaded();
	function void onauthenticated();
	function void onerror();
}
				

说明:

Authorize对象表示分享控件对象,用于在窗口中显示分享控件,使用此对象可自定义分享授权界面。

构造:

方法:

事件:

Authorize(id,display)

创建分享授权控件对象


var obj = new plus.share.Authorize(id, display);
						

说明:

根据指定的id的元素创建分享控件。

参数:

返回值:

Authorize : 分享控件对象

load

加载分享授权页面


void obj.load(id);
						

说明:

创建分享授权页面后,需要调用此方法指定分享服务标识来加载授权页面数据,此标识可使用ShareService对象的id属性。

参数:

返回值:

void : 无

setVisible

设置分享授权控件是否可见


void obj.setVisible(visible);
						

说明:

创建分享授权页面后,调用此方法设置分享授权控件在页面中是否可见。

参数:

返回值:

void : 无

onloaded

分享控件加载完成事件


void obj.onloaded = function(){
	// loaded code 
}
						

说明:

EventHandler 类型

分享授权控件内容加载完成事件,通过调用load方法加载分享授权控件内容,当内容加载完成时触发。

onauthenticated

分享授权认证成功事件


void obj.onauthenticated = function(service){
	// Authenticate success code 
}
						

说明:

ShareSuccessCallback 类型

用户在分享授权控件上输入操作授权成功时触发,事件方法格式参考ShareSuccessCallback回调函数。

onerror

分享授权认证失败事件


void obj.onerror = function(error) {
	// Error code 
}
						

说明:

ShareErrorCallback 类型

用户在分享授权控件上输入操作授权认证错误时触发,事件方法格式参考ShareErrorCallback回调函数。

ServicesSuccessCallback

获取分享服务成功回调


void ServicesSuccessCallback(services){
	// Get share services success code
}
				

说明:

当获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。

参数:

返回值:

void : 无

AuthorizeSuccessCallback

分享授权认证成功回调


void AuthorizeSuccessCallback(services){
	  // Authorize success code
}
				

说明:

分享服务授权认证操作成功时调用。

参数:

返回值:

void : 无

ShareSuccessCallback

分享操作成功回调


void ShareSuccessCallback(){
	// Share success code
}
				

说明:

分享操作成功回调函数,当分享操作成功时调用。

参数:

返回值:

void : 无

ShareErrorCallback

分享操作失败回调


void ShareErrorCallback(error){
	// Error 
	var code = error.code; 			// 错误编码
	var message = error.message;	// 错误描述信息
}
				

说明:

当分享操作失败时的回调函数,用于返回分享相关操作失败的错误信息。

参数:

返回值:

void : 无