Share · Html5+參考

# [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 : 無