Gallery · Html5+參考

# [gallery]() Gallery模塊管理系統相冊，支持從相冊中選擇圖片或視頻文件、保存圖片或視頻文件到相冊等功能。通過plus.gallery獲取相冊管理對象。 ### 方法： - [pick](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.pick): 從系統相冊選擇文件（圖片或視頻） - [save](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.save): 保存文件到系統相冊中 ### 對象： - [GalleryOption](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryOption): JSON對象，從相冊中選擇文件的參數 - [GalleryFilter](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryFilter): 相冊選擇文件過濾類型 - [PopPosition](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.PopPosition): JSON對象，彈出拍照或攝像界面指示位置 ### 回調方法： - [GalleryPickSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryPickSuccessCallback): 選擇系統相冊圖片成功的回調 - [GallerySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GallerySuccessCallback): 操作系統相冊成功的回調 - [GalleryErrorCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryErrorCallback): 系統相冊操作失敗的回調 ### 權限： permissions ~~~ "Gallery": { "description": "訪問系統相冊" } ~~~ # [pick]() 從系統相冊選擇文件（圖片或視頻） ~~~ void plus.gallery.pick( successCB, errorCB, option ); ~~~ ### 說明：從系統相冊中選擇圖片或視頻文件。每次僅能選擇一個文件，選擇后將返回選擇的文件路徑。 ### 參數： - succesCB: *( [GalleryPickSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryPickSuccessCallback) ) 必選 *從系統相冊中選擇文件完成后的回調函數 - errorCB: *( [GalleryErrorCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryErrorCallback) ) 可選 *從系統相冊中選擇文件操作錯誤的回調函數 - option: *( [GalleryOption](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryOption) ) 可選 *設置選擇文件的參數 ### 返回值： void : 無 ### 平臺支持： - Android - 2.2+ (支持) - iOS - 4.3+ (支持) ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Gallery Example</title> <script type="text/javascript" > // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 擴展API加載完畢，現在可以正常調用擴展API function onPlusReady() { } // 從相冊中選擇圖片 function selectPicture() { plus.gallery.pick( function (path){ alert( "Success: " + path ); }, function ( err ) { alert( "Failed: " + err.message ); } ); } </script> </head> <body > <input type="button" value="Select picture frome Gallery" onclick="selectPicture();" ></input> </body> </html> ~~~ # [save]() 保存文件到系統相冊中 ~~~ void plus.gallery.save( path, successCB, errorCB ); ~~~ ### 說明：保存文件到系統相冊中。每次僅能保存一個文件，支持圖片類型（jpg/jpeg、png、bmp等格式）和視頻文件（3gp、mov等格式）。若保存的文件系統不支持，則通過errorCB返回錯誤信息。 ### 參數： - path : *( DOMString ) 必選 *要保存到系統相冊中的文件文件地址僅支持本地路徑，不支持網絡路徑。 - succesCB: *( [GallerySuccessCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GallerySuccessCallback) ) 必選 *保存文件到系統相冊中成功的回調函數 - errorCB: *( [GalleryErrorCallback](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryErrorCallback) ) 可選 *保存文件到系統相冊中失敗的回調函數 ### 返回值： void : 無 ### 平臺支持： - Android - 2.2+ (支持) - iOS - 4.3+ (支持) ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>Gallery Example</title> <script type="text/javascript" > // 擴展API加載完畢后調用onPlusReady回調函數 document.addEventListener( "plusready", onPlusReady, false ); var r = null; // 擴展API加載完畢，現在可以正常調用擴展API function onPlusReady() { } // 保存圖片到相冊中 function savePicture() { plus.gallery.save( "_doc/a.jpg", function () { alert( "保存圖片到相冊成功" ); } ); } </script> </head> <body > <input type="button" value="Save picture to Gallery" onclick="savePicture();" ></input> </body> </html> ~~~ # [GalleryOption]() JSON對象，從相冊中選擇文件的參數 ### 屬性： - filename: *(DOMString 類型)*選擇文件保存的路徑從系統相冊中選擇文件的保存路徑，如果路徑中包括文件后綴名稱，則表明指定文件路徑及名稱，否則僅指定文件保存目錄，文件名稱由程序自動生成。 ### 平臺支持 - Android - 2.2+ (不支持): 不支持設置文件路徑。 - iOS - 4.3+ (支持): iOS會將相冊中的文件拷貝到當前應用沙箱系統中，可通過此參數設置路徑。 - filter: *([GalleryFilter](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.GalleryFilter) 類型)*相冊中選擇文件類型過濾器可通過此參數設定相冊選擇器中可選擇的文件類型，可設置僅可選擇圖片文件或視頻文件，默認值為僅可選擇圖片文件。 - animation: *(Boolean 類型)*是否顯示系統相冊文件選擇界面的動畫是否顯示系統相冊文件選擇界面的動畫，可取值true、false，默認值為true。 ### 平臺支持 - Android - 2.2+ (不支持): 忽略此參數，無動畫效果。 - iOS - 4.3+ (支持): 支持動畫效果。 - popover: *([PopPosition](http://www.dcloud.io/docs/api/zh_cn/gallery.shtml#plus.gallery.PopPosition) 類型)*相冊選擇界面彈出指示區域對于大屏幕設備如iPad，相冊選擇界面為彈出窗口，此時可通過此參數設置彈出窗口位置。其為JSON對象，格式如{top:"10",left:10,width:200,height:200}，所有值為像素值，左上坐標相對于容器的位置，默認彈出位置為屏幕居中。 # [GalleryFilter]() 相冊選擇文件過濾類型 ### 屬性： - "image": *(DOMString 類型)*僅可選擇圖片文件 - "video": *(DOMString 類型)*僅可選擇視頻文件 - "none": *(DOMString 類型)*不過濾，可選擇圖片或視頻文件 # [PopPosition]() JSON對象，彈出拍照或攝像界面指示位置 ### 屬性： - top: *(DOMString 類型)*指示區域距離容器頂部的距離彈出拍照或攝像窗口指示區域距離容器頂部的距離，單位支持像素值（如100px）和百分比（如50%），如不寫單位則為像素值值。 - left: *(DOMString 類型)*指示區域距離容器左側的距離彈出拍照或攝像窗口指示區域距離容器左側的距離，單位支持像素值（如100px）和百分比（如50%），如不寫單位則為像素值。 - width: *(DOMString 類型)*指示區域的寬度彈出拍照或攝像窗口指示區域的寬度，單位支持像素值（如100px）和百分比（如50%），如不寫單位則為像素值。 - height: *(DOMString 類型)*指示區域的高度彈出拍照或攝像窗口指示區域的高度，單位支持像素值（如100px）和百分比（如50%），如不寫單位則為像素值。 # [GalleryPickSuccessCallback]() 選擇系統相冊圖片成功的回調 ~~~ void onSuccess( file ) { // Success code } ~~~ ### 說明：系統相冊中選擇文件成功的回調函數，在選擇文件操作成功時調用。選擇操作失敗或取消選擇不調用此方法。 ### 參數： - file: *( DOMString ) 必選 *選擇的圖片或視頻文件路徑 ### 返回值： void : 無 # [GallerySuccessCallback]() 操作系統相冊成功的回調 ~~~ void onSuccess() { // Success code } ~~~ ### 說明：系統相冊操作成功的回調函數，在保存文件到系統相冊操作成功時調用。選擇操作失敗或取消選擇不調用此方法。 ### 參數：無 ### 返回值： void : 無 # [GalleryErrorCallback]() 系統相冊操作失敗的回調 ~~~ void onError( error ) { // Error code. } ~~~ ### 說明：系統相冊操作失敗的回調函數，在選擇或保存圖片操作失敗時調用。選擇圖片時用戶取消選擇調用此方法。 ### 參數： - error: *( DOMException ) 必選 *相冊操作失敗的錯誤信息 ### 返回值： void : 無