# [share]() Share模块管理客户端的社交分享功能,提供调用终端社交软件的分享能力。通过plus.share可获取社交分享管理对象。 ### 方法: - [getServices](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.getServices): 获取分享服务 ### 对象: - [ShareService](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService): 分享服务对象 - [ShareServerIdentity](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareServerIdentity): 分享服务标识 - [ShareMessage](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareMessage): JSON对象,分享消息对象 - [GeoPosition](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.GeoPosition): JSON对象,用户位置信息 - [ShareMessageExtra](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareMessageExtra): JSON对象,保存分享消息扩展信息 - [Authorize](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize): 分享授权控件对象 ### 回调方法: - [ServicesSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ServicesSuccessCallback): 获取分享服务成功回调 - [AuthorizeSuccessCallback ](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.AuthorizeSuccessCallback%20): 分享消息成功回调 - [ShareSuccessCallback ](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareSuccessCallback%20): 分享操作成功回调 - [ShareErrorCallback ](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareErrorCallback%20): 分享操作失败回调 ### 权限: permissions ~~~ "Share": { "description": "访问分享插件" } ~~~ # [getServices]() 获取分享服务 ~~~ void plus.share.getServices( successCB, errorCB ); ~~~ ### 说明: 在获取终端支持的分享通道列表,可用于提示用户进行分享服务器的选择。获取分享服务成功后通过successCB回调返回支持的所有服务列表,获取服务失败则通过errorCB回调返回。 ### 参数: - successCB: *( [ServicesSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ServicesSuccessCallback) ) 必选 *获取分享服务成功回调 获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。 - errorCB: *( [ShareErrorCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.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](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.id): 分享服务标识 - [description](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.description): 分享服务描述 - [authenticated](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.authenticated): 是否授权认证 - [accessToken](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.accessToken): 授权认证信息 - [nativeClient](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.nativeClient): 是否存在对应的分享客户端 ### 方法: - [authorize](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.authorize): 授权认证操作 - [forbid](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.forbid): 取消授权认证 - [send](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService.send): 发送分享 # [id]() 分享服务标识 ### 说明: [ShareServerIdentity](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.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](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.AuthorizeSuccessCallback) ) 必选 *分享服务授权认证成功回调 分享服务授权认证操作成功时的回调函数,用于返回分享授权操作成功信息。 - errorCB: *( [ShareErrorCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.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](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareMessage) ) 必选 *要发送的分享消息对象 用于设置要分享的消息内容,如文字内容,图片等信息。 - successCB: *( [ShareSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareSuccessCallback) ) 必选 *发送分享消息成功回调 发送分享消息操作成功时的回调函数,用于返回发送分享消息操作成功信息。 - errorCB: *( [ShareErrorCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.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]() 分享服务标识 ### 常量: - "sinaweibo": *(DOMString 类型)*新浪微博 - "tencentweibo": *(DOMString 类型)*腾讯微博 - "weixin": *(DOMString 类型)*微信 # [ShareMessage]() JSON对象,分享消息对象 ~~~ interface plus.share.ShareMessage { attribute String content; attribute String[] pictures; attribute String href; attribute String title; attribute JSON extra; attribute GEOPosition geo; } ~~~ ### 说明: ShareMessage对象用于表示分享消息内容,在JS中为JSON对象,用于向系统发送分享信息操作。 ### 属性: - content: *(String 类型)*分享消息的文字内容 - pictures: *(String[] 类型)*分享消息的图片 分享消息中包含的图片路径,仅支持本地路径。 若分享平台仅支持提交一张图片,传入多张图片则仅提交第一张图片。 如果不能同时支持其它内容信息,优先级顺序为:pictures>content。 - thumbs: *(String[] 类型)*分享消息的缩略图 分享消息中包含的缩略图路径,仅支持本地路径。 若分享平台仅支持提交一张图片,传入多张图片则仅提交第一张图片。 如果分享平台的信息不支持缩略图,则忽略其属性值。 - href: *(String 类型)*分享独立的链接 分享独立链接地址,仅支持网络地址(以http://或https://开头)。 如果不能同时支持其它内容信息,优先级顺序为:href>pictures>content。 - title: *(String 类型)*分享消息的标题 目前仅微信分享独立链接消息时支持。 - geo: *([GeoPosition](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.GeoPosition) 类型)*分享消息中包含的用户地理信息数据 - extra: *([ShareMessageExtra](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareMessageExtra) 类型)*分享消息扩展参数 # [GeoPosition]() JSON对象,用户位置信息 ~~~ interface plus.share.GeoPosition { attribute Number latitude; attribute Number longitude; } ~~~ ### 说明: GeoPosition对象用于表示用户分享消息时的位置信息。用于标识分享操作时用户的位置信息。 ### 属性: - latitude: *(Number 类型)*用户位置的纬度坐标信息 - longitude: *(Number 类型)*用户位置的经度坐标信息 # [ShareMessageExtra]() JSON对象,保存分享消息扩展信息 ~~~ interface plus.share.ShareMessageExtra { attribute String scene; } ~~~ ### 说明: ShareMessageExtra对象用于保存各分享平台扩展的参数,用于自定义分享功能。 ### 属性: - scene: *(String 类型)*微信分享场景,仅微信分享平台有效 可取值: "WXSceneSession"分享到微信的“我的好友”; "WXSceneTimeline"分享到微信的“朋友圈”中; "WXSceneFavorite"分享到微信的“我的收藏”中。 默认值为"WXSceneSession"。 # [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)](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize.Authorize(id,display)): 创建分享授权控件对象 ### 方法: - [load](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize.load): 加载分享授权页面 - [setVisible](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize.setVisible): 设置分享授权控件是否可见 ### 事件: - [onloaded](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize.onloaded): 分享控件加载完成事件 - [onauthenticated](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize.onauthenticated): 分享授权认证成功事件 - [onerror](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.Authorize.onerror): 分享授权认证失败事件 # [Authorize(id,display)]() 创建分享授权控件对象 ~~~ var obj = new plus.share.Authorize( id, display ); ~~~ ### 说明: 根据指定的id的元素创建分享控件 ### 参数: - id: *( DOMString ) 必选 *分享控件在窗口的对应obj节点的id值,此id值用于定位控件位置 - visible: *( Boolean ) 可选 *分享控件是否创建后立即显示,默认值为true ### 返回值: [Authorize](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.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](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.EventHandler) 类型 分享授权控件内容加载完成事件,通过调用load方法加载分享授权控件内容,当内容加载完成时触发。 # [onauthenticated]() 分享授权认证成功事件 ~~~ void obj.onauthenticated= function ( service) { // Authenticate success code } ~~~ ### 说明: [ShareSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareSuccessCallback) 类型 用户在分享授权控件上输入操作授权成功时触发,事件方法格式参考ShareSuccessCallback回调函数。 # [onerror]() 分享授权认证失败事件 ~~~ void obj.onerror= function ( error ) { // Error code } ~~~ ### 说明: [ShareErrorCallback](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareErrorCallback) 类型 用户在分享授权控件上输入操作授权认证错误时触发,事件方法格式参考ShareErrorCallback回调函数。 # [ServicesSuccessCallback]() 获取分享服务成功回调 ~~~ void ServicesSuccessCallback( services ) { // Get share services success code } ~~~ ### 说明: 当获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。 ### 参数: - services: *( [ShareService](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService) ) 必选 *数组,运行环境支持的分享服务列表 运行环境支持的分享服务列表数组,可通过services.length获取分享服务列表的数目。 ### 返回值: void : 无 # [AuthorizeSuccessCallback ]() 分享消息成功回调 ~~~ void AuthorizeSuccessCallback( service ) {   // Authorize success code } ~~~ ### 说明: 分享操作成功回调函数,当分享操作成功时调用。 ### 参数: - service: *( [ShareService](http://www.dcloud.io/docs/api/zh_cn/share.shtml#plus.share.ShareService) ) 必选 *认证操作成功的分享服务对象 ### 返回值: void : 无 # [ShareSuccessCallback ]() 分享操作成功回调 ~~~ void ShareSuccessCallback () { // Share success code } ~~~ ### 说明: 分享操作成功回调函数,当分享操作成功时调用。 ### 参数: 无 ### 返回值: void : 无 # [ShareErrorCallback ]() 分享操作失败回调 ~~~ void ShareErrorCallback ( error ) { // Recognition error code } ~~~ ### 说明:   当分享操作失败时的回调函数,用于返回分享相关操作失败的错误信息。 ### 参数: - error: *( DOMException ) 必选 *分享操作失败错误信息,通过error.code获取错误代码 ### 返回值: void : 无