更新记录

1.2.1（2026-06-02） 下载此版本

修复电脑端小程序预览失败的bug

1.2.0（2026-05-29） 下载此版本

优化mode=list readonly是的文件预览功能。

1.1.9（2026-05-13） 下载此版本

优化文件上传。

平台兼容性

uni-app(4.33)

jx-file-picker

基于 uni-file-picker 组件的增强版本，支持文件大小限制、标题控制、多文件类型预览等功能。

功能特点

• 保留官方所有原有功能
• 支持文件大小限制（size 属性）
• 支持控制标题显示（showTitle 属性）
• 支持自定义标题后缀（title 属性）
• 文件大小单位为 MB
• 支持多文件类型预览（H5、App、小程序、Web）
  • 图片：jpg、png、gif、bmp、webp、svg
  • PDF 文件
  • 视频：mp4、mov、avi、wmv、flv、mkv、webm
  • 音频：mp3、wav、ogg、aac、flac
  • 文本：txt、json、xml、html、css、js、md、csv

属性说明

只读模式说明（mode=list + readonly）

当设置 mode="list" + readonly="true" 时，组件进入只读预览模式：

隐藏的内容

• 标题区域（文件大小限制提示）
• 文件计数（如 "0/9"）
• "选择文件" 按钮
• 删除按钮

保留的内容

• 文件列表展示
• 所有可预览文件都可点击预览（文件名显示为蓝色）

文件预览支持

在 mode="list" + readonly="true" 模式下，以下文件类型可以点击预览：

预览行为说明

• 可预览的文件：文件名显示为蓝色，可点击预览
• 不可预览的文件：文件名显示为灰色，不可点击
• H5/Web：图片使用 uni.previewImage，其他文件在新标签页打开
• App：调用系统应用打开（阅读器、播放器等）
• 小程序：先下载文件，再使用 uni.openDocument 打开

使用示例

<!-- 只读模式：展示文件列表，所有可预览文件都可点击 -->
<jx-file-picker
  mode="list"
  :readonly="true"
  :value="fileList"
  file-mediatype="all">
</jx-file-picker>

文件预览功能详解

本组件支持多种文件类型的直接预览功能：

图片预览

• 支持格式：jpg, jpeg, png, gif, bmp, webp, svg
• H5/Web：调用 uni.previewImage 实现图片轮播预览
• App：调用 uni.previewImage
• 小程序：调用 uni.previewImage

PDF 预览

• H5/Web：在新窗口中打开 PDF 文件
• App (iOS/Android)：调用系统 PDF 阅读器或第三方应用打开
• 小程序：自动下载后使用 uni.openDocument API 打开 PDF

视频/音频预览

• H5/Web：在新窗口中打开文件
• App：调用系统播放器
• 小程序：下载后使用 uni.openDocument 打开

文本文件预览

• 支持格式：txt, json, xml, html, css, js, md, csv
• H5/Web：在新窗口中打开
• App：调用系统文本编辑器
• 小程序：下载后使用 uni.openDocument 打开

使用方法

<!-- 选择所有文件类型，可预览图片、PDF、视频等 -->
<jx-file-picker
  mode="list"
  file-mediatype="all"
  :size="10">
</jx-file-picker>

<!-- readonly 模式下仅展示文件，可预览文件可点击 -->
<jx-file-picker
  mode="list"
  :readonly="true"
  v-model="fileList"
  file-mediatype="all">
</jx-file-picker>

数据格式支持

组件支持以下文件数据格式：

// 格式1：HTTP URL
{
  name: 'xxx.pdf',
  url: 'https://example.com/xxx.pdf'
}

// 格式2：云存储地址（自动转换）
{
  name: 'xxx.pdf',
  fileID: 'cloud://xxx',
  url: ''
}
// 组件会自动将 cloud:// 转换为可访问的 HTTP URL

// 格式3：本地路径（仅 App 支持）
{
  name: 'xxx.pdf',
  path: '/static/xxx.pdf'
}

注意事项

• 小程序环境：需要在 manifest.json 中配置下载域名白名单
• 云存储文件：组件会自动将 cloud:// 地址转换为 HTTP URL，转换失败时会在预览时重试
• Blob URL：blob: 开头的本地临时地址在小程序中无法预览，建议重新上传
• 权限配置：确保 uniCloud 已正确配置，且云存储文件可访问

使用方法

基础用法

<!-- 限制文件大小为 1MB -->
<jx-file-picker
  :size="1"
  file-mediatype="all">
</jx-file-picker>

使用标题后缀

<!-- 显示提示："文件必须小于 0.5MB，高度 100 宽度 100" -->
<jx-file-picker
  :size="0.5"
  title="高度100宽度100"
  file-mediatype="all">
</jx-file-picker>

隐藏标题

<!-- 不显示任何标题 -->
<jx-file-picker
  :size="2"
  :showTitle="false"
  file-mediatype="all">
</jx-file-picker>

控制上传 loading

<!-- 显示上传 loading（默认行为） -->
<jx-file-picker
  :size="2"
  :showUploadLoading="true"
  file-mediatype="all">
</jx-file-picker>

<!-- 隐藏上传 loading -->
<jx-file-picker
  :size="2"
  :showUploadLoading="false"
  file-mediatype="all">
</jx-file-picker>

完整示例

<jx-file-picker
  :limit="2"
  :size="0.1"
  :showTitle="false"
  :showUploadLoading="true"
  title="高度100宽度100"
  :image-styles="{ width: '80px', height: '80px' }"
  :dir="pages_list.updir">
</jx-file-picker>

注意事项

• 当 size 值小于 1024 时，单位为 MB
• 当 size 值大于等于 1024 时，单位为字节
• 当 size 为 0 时，表示不限制文件大小
• 当 showTitle 为 false 时，整个标题区域将不显示
• 当 showUploadLoading 为 false 时，不显示上传状态 loading
• title 内容会作为后缀追加到基础提示文字后
• 在 mode="list" + readonly="true" 模式下，所有可预览文件都可点击预览