share

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

方法：

对象：

回调方法：

权限：

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>

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 );
	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( successCB, errorCB );

说明：

对指定的分享服务进行授权认证操作，在授权前可通过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){
		alert( "获取分享服务列表失败："+e.message );
	} );
}, false );
function shareAction(){
	var s = shares[0];
	if ( !s.authenticated ) {
		s.authorize( functioin(){
			alert( "认证完成！" );
		}, function(e){
			outLine( "未进行认证" );
		} )
	}
}
	</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>
	</body>
</html>

ShareServerIdentity

分享服务标识

常量：

ShareMessage

JSON对象，分享消息对象


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

说明：

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对象用于保存各分享平台扩展的参数，用于自定义分享功能。

属性：

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( service ) {
	　　// Authorize success code
}

说明：

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

参数：

返回值：

void : 无

ShareSuccessCallback

分享操作成功回调


void ShareSuccessCallback () {
	// Share success code
}

说明：

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

参数：

无

返回值：

void : 无

ShareErrorCallback

分享操作失败回调


void ShareErrorCallback ( error ) {
	// Recognition error code
}

说明：

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

参数：

返回值：

void : 无