From 182141b6b40852cf6befd2582f95d04cdd3d0248 Mon Sep 17 00:00:00 2001 From: liuxiaohang <283700113@qq.com> Date: Mon, 9 Nov 2020 15:39:08 +0800 Subject: [PATCH] docs: uni.chooseFile --- docs/api/README.md | 5 +++ docs/api/_sidebar.md | 1 + docs/api/media/file.md | 92 +++++++++++++++++++++++++++++++++++++++++ docs/api/media/image.md | 15 +------ docs/api/media/video.md | 1 + 5 files changed, 101 insertions(+), 13 deletions(-) create mode 100644 docs/api/media/file.md diff --git a/docs/api/README.md b/docs/api/README.md index de847e166..d7169d8cc 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -114,6 +114,11 @@ function async request () { |[uni.previewImage](api/media/image?id=previewimage)|预览图片| |[uni.getImageInfo](api/media/image?id=getimageinfo)|获取图片信息| |[uni.saveImageToPhotosAlbum](api/media/image?id=saveimagetophotosalbum)|保存图片到系统相册| +##### 文件 + +|API|说明| +|:-|:-| +|[uni.chooseFile](api/media/file?id=chooseFile)|从本地选择文件| ##### 录音管理 |API|说明| diff --git a/docs/api/_sidebar.md b/docs/api/_sidebar.md index 9228d763f..46ffd4a23 100644 --- a/docs/api/_sidebar.md +++ b/docs/api/_sidebar.md @@ -37,6 +37,7 @@ * [地图组件控制](api/location/map.md) * 媒体 * [图片](api/media/image.md) + * [文件](api/media/file.md) * [录音管理](api/media/record-manager.md) * [背景音频播放管理](api/media/background-audio-manager.md) * [音频组件控制](api/media/audio-context.md) diff --git a/docs/api/media/file.md b/docs/api/media/file.md new file mode 100644 index 000000000..5081ea381 --- /dev/null +++ b/docs/api/media/file.md @@ -0,0 +1,92 @@ +### uni.chooseFile(OBJECT) +从本地选择文件。 + +**平台差异说明** + +|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序|QQ小程序| +|:-:|:-:|:-:|:-:|:-:|:-:|:-:| +|x|√`(HBuilder X2.9.8+)`|x`(可使用wx.chooseMessageFile)`|x|x|x|x| + +**OBJECT 参数说明** + +|参数名|类型|默认值|必填|说明|平台差异说明| +|:-|:-|:-|:-|:-|:-| +|count|Number|100|否|最多可以选择的图片张数|见下方说明| +|type|String|'all'|否|所选的文件的类型|见下方说明| +|extension|Array<String>||否|根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。|见下方说明| +|sourceType|Array<String>|['album','camera']|否|（仅在type为`image`或`video`时可用）`album` 从相册选图，`camera` 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项|| +|success|Function||是|成功则返回图片的本地文件路径列表 `tempFilePaths`|| +|fail|Function||否|接口调用失败的回调函数|| +|complete|Function||否|接口调用结束的回调函数（调用成功、失败都会执行）| | + +**Tips** + +- count 值在 H5 平台的表现，基于浏览器本身的规范。目前测试的结果来看，只能限制单选/多选，并不能限制数量。并且，在实际的手机浏览器很少有能够支持多选的。 +- sourceType 在H5端对应`input`的`capture`属性，设置为`['album']`无效，依然可以使用相机。 +- App端如需选择非媒体文件，可在插件市场搜索[文件选择](https://ext.dcloud.net.cn/search?q=文件选择)，其中Android端可以使用Native.js，无需原生插件，而iOS端需要原生插件。 +- extension暂只支持文件后缀名，例如`['.zip','.exe','.js']`，不支持`application/msword`等类似值 + +**注：文件的临时路径，在应用本次启动期间可以正常使用，如需持久保存，需在主动调用 [uni.saveFile](api/file/file?id=savefile)，在应用下次启动时才能访问得到。** + +**OBJECT.type 的合法值** + +|值|说明| +|:-|:-| +|all|从所有文件选择| +|video|只能选择视频文件| +|image|只能选择图片文件| + +**Tips** + +- 如果type属性可extension同时存在，例如`{type:'image',extension:['.png','.jpg']}`，则会选择`image/png,image/jpg`文件 +- 如果只配置extension属性，例如`{extension:['.doc','.xlsx','.docx']}`，则会选择`.doc,.xlsx,.docx`文件 +- 详情见[`accept`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/accept)属性 + +**success 返回参数说明** + +|参数|类型|说明| +|:-|:-|:-| +|tempFilePaths|Array<String>|图片的本地文件路径列表| +|tempFiles|Array<Object>、Array<File>|图片的本地文件列表，每一项是一个 File 对象| + +**File 对象结构如下** + +|参数|类型|说明| +|:-|:-|:-| +|path|String|本地文件路径| +|size|Number|本地文件大小，单位：B| +|name|String|包含扩展名的文件名称，仅H5支持| +|type|String|文件类型，仅H5支持| + +**示例** + +```javascript +uni.chooseFile({ + count: 6, //默认100 + extension:['.zip','.doc'], + success: function (res) { + console.log(JSON.stringify(res.tempFilePaths)); + } +}); + +// 选择图片文件 +uni.chooseFile({ + count: 10, + type: 'image', + success (res) { + // tempFilePath可以作为img标签的src属性显示图片 + const tempFilePaths = res.tempFiles + } +}) +``` + +# wx.chooseMessageFile(OBJECT) + +从微信聊天会话中选择文件。 + +**平台差异说明** + +|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序|QQ小程序| +|:-:|:-:|:-:|:-:|:-:|:-:|:-:| +|x|x|√`(基础库2.5.0+)`|x|x|x|x| + diff --git a/docs/api/media/image.md b/docs/api/media/image.md index fe800c750..aca7253fb 100644 --- a/docs/api/media/image.md +++ b/docs/api/media/image.md @@ -9,6 +9,7 @@ App端如需要更丰富的相机拍照API（如直接调用前置摄像头） |:-|:-|:-|:-|:-| |count|Number|否|最多可以选择的图片张数，默认9|见下方说明| |sizeType|Array<String>|否|original 原图，compressed 压缩图，默认二者都有|App、微信小程序、支付宝小程序、百度小程序| +|extension|Array<String>|否|根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。|H5(HBuilder X2.9.8+)| |sourceType|Array<String>|否|album 从相册选图，camera 使用相机，默认二者都有。如需直接开相机或直接选相册，请只使用一个选项|| |success|Function|是|成功则返回图片的本地文件路径列表 tempFilePaths|| |fail|Function|否|接口调用失败的回调函数|小程序、App| @@ -279,16 +280,4 @@ uni.compressImage({ console.log(res.tempFilePath) } }) -``` - - -# wx.chooseMessageFile(OBJECT) - -从微信聊天会话中选择文件。 - -**平台差异说明** - -|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序|QQ小程序| -|:-:|:-:|:-:|:-:|:-:|:-:|:-:| -|x|x|√|x|x|x|x| - +``` \ No newline at end of file diff --git a/docs/api/media/video.md b/docs/api/media/video.md index 4d837b1e5..de1a23f1e 100644 --- a/docs/api/media/video.md +++ b/docs/api/media/video.md @@ -12,6 +12,7 @@ |参数名|类型|必填|说明|平台差异说明| |:-|:-|:-|:-|:-| |sourceType|Array<String>|否|album 从相册选视频，camera 使用相机拍摄，默认为：['album', 'camera']|| +|extension|Array<String>|否|根据文件拓展名过滤，每一项都不能是空字符串。默认不过滤。|H5(HBuilder X2.9.8+)| |compressed|Boolean|否|是否压缩所选的视频源文件，默认值为 true，需要压缩。|微信小程序、百度小程序、字节跳动小程序| |maxDuration|Number|否|拍摄视频最长拍摄时间，单位秒。最长支持 60 秒。|APP平台 1.9.7+(iOS支持，Android取决于ROM的拍照组件是否实现此功能，如果没实现此功能则忽略此属性。) 微信小程序、百度小程序| |camera|String|否|'front'、'back'，默认'back'|APP、微信小程序| -- GitLab