share
Share模块管理客户端的社交分享功能,提供调用终端社交软件的分享能力。通过plus.share可获取社交分享管理对象。
方法:
- getServices: 获取分享服务
对象:
- ShareService: 分享服务对象
- ShareServerIdentity: 分享服务标识
- ShareMessage: JSON对象,分享消息对象
- GeoPosition: JSON对象,保存用户位置信息
- Authorize: 分享授权控件对象
回调方法:
- ServicesSuccessCallback: 获取分享服务成功回调
- AuthorizeSuccessCallback : 分享消息成功回调
- ShareSuccessCallback : 分享操作成功回调
- ShareErrorCallback : 分享操作失败回调
权限:
permissions
"Share": { "description": "访问分享插件" }
getServices
获取分享服务
void plus.share.getServices( successCB, errorCB );
说明:
在获取终端支持的分享通道列表,可用于提示用户进行分享服务器的选择。获取分享服务成功后通过successCB回调返回支持的所有服务列表,获取服务失败则通过errorCB回调返回。
参数:
- successCB:
(
ServicesSuccessCallback
)
必选 获取分享服务成功回调
获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。 - errorCB:
(
ShareErrorCallback
)
可选 获取分享服务失败回调
获取分享服务列表失败时的回调函数,用于返回错误信息。
返回值:
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: 分享服务标识
- description: 分享服务描述
- authenticated: 是否授权认证
- accessToken: 授权认证信息
- nativeClient: 是否存在对应的分享客户端
方法:
id
分享服务标识
说明:
ShareServerIdentity 类型 只读属性
用于表示分享服务标识,如“sinaweibo”表示新浪微博、“tencentweibo”表示腾讯微博。
description
分享服务描述
说明:
DOMString 类型 只读属性
用于描述分享服务的信息,如“新浪微博”、“腾讯微博”。
authenticated
是否授权认证
说明:
Boolean 类型 只读属性
用于标识此分享是否已经授权认证过,true表示已完成授权认证;false表示未完成授权认证。
accessToken
授权认证信息
说明:
DOMString 类型 只读属性
仅在authenticated为true时有效,标识客户认证标识信息,用于发送分享信息。
nativeClient
是否存在对应的分享客户端
说明:
Boolean 类型 只读属性
对于某些分享服务,可直接调用本地客户端程序进行授权认证,此属性即可提供此相关信息,若没有安装本地客户端则可能调用其它方式进行分享操作,如WAP方式等。
authorize
授权认证操作
void obj.authorize( successCB, errorCB );
说明:
对指定的分享服务进行授权认证操作,在授权前可通过ShareService.authenticated属性判断是否已经授权过,通常只需要对没有进行过授权认证的服务进行授权认证操作。授权认证操作成功后通过successCB回调函数通知操作完成,操作失败则通过errorCB回调返回。
参数:
- successCB:
(
AuthorizeSuccessCallback
)
必选 分享服务授权认证成功回调
分享服务授权认证操作成功时的回调函数,用于返回分享授权操作成功信息。 - errorCB:
(
ShareErrorCallback
)
可选 分享服务授权认证失败回调
分享服务授权认证操作失败时的回调函数,用于返回错误信息。
返回值:
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回调返回。若分享服务没有进行授权认证或授权认证失效则触发失败回调函数。
参数:
- msg:
(
ShareMessage
)
必选 要发送的分享消息对象
用于设置要分享的消息内容,如文字内容,图片等信息。 - successCB:
(
ShareSuccessCallback
)
必选 发送分享消息成功回调
发送分享消息操作成功时的回调函数,用于返回发送分享消息操作成功信息。 - errorCB:
(
ShareErrorCallback
)
可选 发送分享消息失败回调
发送分享消息操作失败时的回调函数,用于返回错误信息。
返回值:
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 DOMString content; attribute DOMString[] pictures; attribute GEOPosition geo; }
说明:
ShareMessage对象用于表示分享消息内容,在JS中为JSON对象,用于向系统发送分享信息操作。
属性:
- content: (DOMString
类型
)分享消息的内容
- pictures: (DOMString[]
类型
)分享消息的图片
分享消息中包含的图片路径,仅支持本地路径,暂仅支持提交一张图片,如果传入多张图片则仅提交第一张图片;
- geo: (GeoPosition
类型
)分享消息中包含的用户地理信息数据
GeoPosition
JSON对象,保存用户位置信息
interface plus.share.GeoPosition { attribute Number latitude; attribute Number longitude; }
说明:
GeoPosition对象用于表示用户分享消息时的位置信息,在JS中为JSON对象,用于标识分享操作时用户的位置信息。
属性:
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): 创建分享授权控件对象
方法:
- load: 加载分享授权页面
- setVisible: 设置分享授权控件是否可见
事件:
- onloaded: 分享控件加载完成事件
- onauthenticated: 分享授权认证成功事件
- onerror: 分享授权认证失败事件
Authorize(id,display)
创建分享授权控件对象
var obj = new plus.share.Authorize( id, display );
说明:
根据指定的id的元素创建分享控件
参数:
- id:
(
DOMString
)
必选 分享控件在窗口的对应obj节点的id值,此id值用于定位控件位置
- visible:
(
Boolean
)
可选 分享控件是否创建后立即显示,默认值为true
返回值:
Authorize : 分享控件对象load
加载分享授权页面
void obj.load( id );
说明:
创建分享授权页面后,需要调用此方法指定分享服务标识来加载授权页面数据,此标识可使用ShareService对象的id属性。
参数:
- id:
(
DOMString
)
必选 要加载的分享服务标识
返回值:
void : 无setVisible
设置分享授权控件是否可见
void obj.setVisible( visible );
说明:
创建分享授权页面后,调用此方法设置分享授权控件在页面中是否可见。
参数:
- visible:
(
Boolean
)
必选 要设置分享控件是否可见,true标识可见,false表示不可见。
返回值:
void : 无onloaded
分享控件加载完成事件
void obj.onloaded = function () { // loaded code }
说明:
EventHandler 类型
分享授权控件内容加载完成事件,通过调用load方法加载分享授权控件内容,当内容加载完成时触发。
onauthenticated
分享授权认证成功事件
void obj.onauthenticated= function ( service) { // Authenticate success code }
说明:
用户在分享授权控件上输入操作授权成功时触发,事件方法格式参考ShareSuccessCallback回调函数。
onerror
分享授权认证失败事件
void obj.onerror= function ( error ) { // Error code }
说明:
用户在分享授权控件上输入操作授权认证错误时触发,事件方法格式参考ShareErrorCallback回调函数。
ServicesSuccessCallback
获取分享服务成功回调
void ServicesSuccessCallback( services ) { // Get share services success code }
说明:
当获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。
参数:
- services:
(
ShareService
)
必选 数组,运行环境支持的分享服务列表
运行环境支持的分享服务列表数组,可通过services.length获取分享服务列表的数目。
返回值:
void : 无AuthorizeSuccessCallback
分享消息成功回调
void AuthorizeSuccessCallback( service ) { // Authorize success code }
说明:
分享操作成功回调函数,当分享操作成功时调用。
参数:
- service:
(
ShareService
)
必选 认证操作成功的分享服务对象
返回值:
void : 无ShareSuccessCallback
分享操作成功回调
void ShareSuccessCallback () { // Share success code }
说明:
分享操作成功回调函数,当分享操作成功时调用。
参数:
无
返回值:
void : 无ShareErrorCallback
分享操作失败回调
void ShareErrorCallback ( error ) { // Recognition error code }
说明:
当分享操作失败时的回调函数,用于返回分享相关操作失败的错误信息。
参数:
- error:
(
DOMException
)
必选 分享操作失败错误信息,通过error.code获取错误代码