# [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 : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS