# share

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

## 方法：

- getServices: 获取分享服务
- sendWithSystem: 使用系统组件发送分享

## 对象：

- AuthOptions: JSON对象，分享授权认证参数选项
- Authorize: 分享授权控件对象
- GeoPosition: JSON对象，用户位置信息
- ShareService: 分享服务对象
- ShareServerIdentity: 分享服务标识
- ShareMessage: JSON对象，分享消息对象
- ShareMessageExtra: JSON对象，保存分享消息扩展信息
- WeixinMiniProgramOptions: JSON对象，微信小程序信息

## 回调方法：

- ServicesSuccessCallback: 获取分享服务成功回调
- AuthorizeSuccessCallback: 分享授权认证成功回调
- ShareSuccessCallback: 分享操作成功回调
- ShareErrorCallback: 分享操作失败回调

## 权限：

permissions

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

# AuthOptions

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

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

## 说明：

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

## 属性：

- appid: (String 类型 )分享服务平台申请的appid

  动态设置分享服务授权认证时需要使用的appid，仅需要此参数的分享服务（如“微信”、“QQ”）支持。 如果未设置则使用运行环境中内置的appid值（如在HBuilder中可在manifest.json的“SDK配置”项中进行设置）。

- appkey: (String 类型 )分享服务平台申请的appkey

  动态设置分享服务授权认证时需要使用的appkey，仅需要此参数的分享服务（如“新浪微博”）支持。 如果未设置则使用运行环境中内置的appkey值（如在HBuilder中可在manifest.json的“SDK配置”项中进行设置）。

- appsecret: (String 类型 )分享服务平台申请的appsecret

  动态设置分享服务中需要使用的appsecret，仅需要此参数的分享服务（如“微信”、“新浪微博”）支持。 如果未设置则使用运行环境中内置的appsecret值（如在HBuilder中可在manifest.json的“SDK配置”项中进行设置）；当开放平台申请的appsecret值涉及到安全问题时，可在应用运行时从服务器获取，然后通过此api动态设置。

- redirect_url: (String 类型 )分享服务平台申请的redirect_url

  动态设置分享服务中需要使用的redirect_url，仅需要此参数的登录授权服务（如“新浪微博登录”）支持。 如果未设置则使用运行环境中内置的redirect_url值（如在HBuilder中可在manifest.json的SDK配置项中进行设置）。

# 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: 分享授权认证失败事件

# GeoPosition

JSON对象，用户位置信息

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

## 说明：

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

## 属性：

- latitude: (Number 类型 )用户位置的纬度坐标信息
- longitude: (Number 类型 )用户位置的经度坐标信息

# 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);
    	function void launchMiniProgram(options);
    }

## 说明：

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

## 属性：

- id: 分享服务标识
- description: 分享服务描述
- authenticated: 是否授权认证
- accessToken: 授权认证信息
- nativeClient: 是否存在对应的分享客户端

## 方法：

- authorize: 授权认证操作
- forbid: 取消授权认证
- send: 发送分享
- launchMiniProgram: 调用微信小程序

# ShareServerIdentity

分享服务标识

## 常量：

- "sinaweibo": (DOMString 类型 )新浪微博
- "tencentweibo": (DOMString 类型 )腾讯微博
- "weixin": (DOMString 类型 )微信

# 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 WeixinMiniProgramOptions miniProgram;
    	attribute String interface;
    }

## 说明：

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

## 属性：

- type: (String 类型 )分享消息的类型

  微信分享平台，可取值： "web"-分享网页类型，title（必填）、content（必填）、thumbs（必填）、href（网页url，必填）属性值有效； "text"-分享文字类型，content（必填）属性值有效； "image"-分享图片类型，pictures（必填）属性值有效； "music"-分享音乐类型，title（必填）、content（必填）、thumbs（必填）、media（音乐url，必填）属性值有效； "video"-分享视频类型，title（必填）、content（必填）、thumbs（必填）、media（视频url，必填）属性值有效； "miniProgram"-分享小程序类型（仅支持分享到好友），title（必填）、content（必填）、thumbs（图片小于128K，宽高比为5:4，必填）、miniProgram（小程序参数，必填）属性值有效； 没有设置type时，如果href值有效则默认值为"web"，如果pictures有效则默认值为"image"，否则默认值为"text"。 新浪微博分享平台，可取值： "web"-分享网页类型，content、href（网页url，必填），分享链接添加到内容之后； "text"-分享文字类型，content（必填）属性有效，可在内容中直接插入链接地址； "image"-分享图片类型，content（可选）、thumbs（可选）、pictures（必填）属性有效； "video"-分享视频类型，content（可选）、thumbs（可选）、media（本地视频文件，必填）属性有效； 没有设置type时，如果存在thumbs则默认值为"image"，如果存在href则默认值为"web"，否则默认为"text"。 QQ分享平台，可取值： "text"-分享文字类型，href（iOS可选，Android必填）、title（必填，最长30个字符）、content（可选，最长40个字符）、pictures或thumbs（可选，优先pictures，iOS不支持）属性有效； "image"-分享图片类型，pictures或thumbs（必填，优先pictures）属性有效； "music"-分享音乐类型，title（必填，最长30个字符）、content（可选，最长40个字符）、href（必填）、media（音乐url，必填）、pictures或thumbs（可选，优先pictures）属性值有效； 没有设置type时，默认值"text"。

- content: (String 类型 )分享消息的文字内容
- pictures: (Array[ String ] 类型 )分享消息的图片

  分享消息中包含的图片路径，仅支持本地路径。 若分享平台仅支持提交一张图片，传入多张图片则仅提交第一张图片。 如果未指定type类型，优先级顺序为：pictures>content（即设置了pictures则认为分享图片类型）。

- thumbs: (Array[ Stromg ] 类型 )分享消息的缩略图

  分享消息中包含的缩略图路径，支持本地路径及网络路径。 若分享平台仅支持提交一张图片，传入多张图片则仅提交第一张图片。 如果分享平台的信息不支持缩略图，若没有设置消息的图片（pictures）则使用缩略图，否则忽略其属性值。 注意：图片有大小限制，推荐图片小于20Kb。

- media: (Strubg 类型 )分享的多媒体资源

  分享的多媒体资源地址，当type值为"music"、"video"时有效。 注意： 微信分享平台支持音乐、视频类型，仅支持网络地址（以http://或https://开头）； QQ分享平台支持音乐类型，仅支持网络路径（以http://或https://开头）； 新浪微博分享平台支持视频类型，仅支持本地文件路径。

- href: (String 类型 )分享独立的链接

  分享资源地址，仅支持网络地址（以http://或https://开头）。 如果未指定type类型，优先级顺序为：href>pictures>content（即设置了href则认为分享网页类型）。

- title: (String 类型 )分享消息的标题

  仅微信分享网页、音频、视频、小程序类型时支持。

- geo: (GeoPosition 类型 )分享消息中包含的用户地理信息数据
- extra: (ShareMessageExtra 类型 )分享消息扩展参数
- miniProgram: (WeixinMiniProgramOptions 类型 )分享微信小程序参数

  仅微信分享小程序类型时支持。

- interface: (String 类型 )分享消息的模式

  可取值： "auto" - 自动选择，如果已经安装微博客户端则采用编辑界面进行分享，否则采用无界面分享； "slient" - 静默分享，采用无界面模式进行分享； "editable" - 进入编辑界面，用户确认分享内容后发送，如果当前未安装微博客户端则触发错误回调。 默认值为"auto"。 （仅新浪微博分享时生效）

# ShareMessageExtra

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

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

## 说明：

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

## 属性：

- scene: (String 类型 )微信分享场景，仅微信分享平台有效

  可取值： "WXSceneSession"分享到微信的“我的好友”； "WXSceneTimeline"分享到微信的“朋友圈”中； "WXSceneFavorite"分享到微信的“我的收藏”中。 默认值为"WXSceneSession"。

# WeixinMiniProgramOptions

JSON对象，微信小程序信息

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

## 说明：

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

## 属性：

- id: (String 类型 )微信小程序ID

  注意：是微信小程序的原始ID（"g_"开头的字符串）。

- path: (String 类型 )微信小程序打开的页面路径
- type: (Number 类型 )微信小程序版本类型

  可取值： 0-正式版； 1-测试版； 2-体验版。 默认值为0。

- webUrl: (String 类型 )兼容低版本的网页链接

# ServicesSuccessCallback

获取分享服务成功回调

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

## 说明：

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

## 参数：

- services: ( Array[ ShareService ] ) 必选 数组，运行环境支持的分享服务列表
  运行环境支持的分享服务列表数组，可通过services.length获取分享服务列表的数目。

## 返回值：

void : 无

# AuthorizeSuccessCallback

分享授权认证成功回调

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

## 说明：

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

## 参数：

- service: ( ShareService ) 必选 授权认证操作的分享服务对象

## 返回值：

void : 无

# ShareSuccessCallback

分享操作成功回调

    void ShareSuccessCallback(){
    	// Share success code
    }

## 说明：

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

## 参数：

无

## 返回值：

void : 无

# ShareErrorCallback

分享操作失败回调

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

## 说明：

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

## 参数：

- error: ( DOMException ) 必选 分享操作失败错误信息
  可通过error.code（Number类型）获取错误编码； 可通过error.message（String类型）获取错误描述信息。

## 返回值：

void : 无