更新记录

1.0.0（2026-11-12）

• 首次发布：iOS / Android 仿微信选图页（相册切换、多选序号、大图预览、原图、视频试看、原生图片编辑）
• 参数：count、mediaType、maxImageCount、maxVideoCount、mixSelect、maxDuration、minDuration、maxVideoSize、showOriginal、defaultOriginal、editable、videoPlayable、columns、themeColor、confirmText、cancelText、compressQuality、compressMaxSide、haptic
• 鸿蒙调用系统选择器 PhotoViewPicker

平台兼容性

uni-app x(5.31)

其他

tlink-photo-picker 仿微信图片 / 视频选择器

uni-app x 原生选图插件。原生层读取系统相册，界面是插件自带的 uvue 页面，交互对齐微信。

目录

• 功能
• 平台支持
• 安装
• 快速开始
• chooseMedia 参数
• success 返回值
• fail 错误码
• 常用场景示例
• 各平台差异
• 权限与隐私
• 底层原生 API
• 常见问题

功能

iOS / Android：

• 相册列表：顶部胶囊切换相册，第一项为「最近项目」，空相册不显示
• 多选：带序号；跨相册保留已选；可限制总数、图片数、视频数，可禁止图片视频混选
• 视频：显示时长角标，可限制最短、最长时长和最大文件大小，支持预览中试看
• 大图预览：左右翻页（可在整个相册里连续翻），双击放大，双指缩放，单击显隐上下栏；底部已选缩略图条，点击跳转
• 原图开关：可隐藏，可设默认勾选
• 图片编辑（原生页面）：涂鸦、表情、文字、裁剪旋转、马赛克；编辑后自动勾选，缩略图换成编辑结果
• 可选压缩：未勾原图时按质量和长边压缩，GIF 跳过
• 主题色、按钮文字、网格列数可配置；宽屏（≥ 600px）自动 6 列
• iOS「部分照片」授权：顶部提示条和「管理」入口；Android 13 分媒体权限、14「部分照片」
• 缩略图按滚动位置流式生成，万张图库不卡；HEIC 自动转 JPEG，GIF / PNG / JPEG 原样导出

平台支持

安装

1. 在插件市场导入插件。HBuilderX 会提示把选图页合并进 pages.json，选「合并」。
2. 没有合并时，手动在 pages.json 的 pages 数组里加（不能放首位）：

{
    "path": "uni_modules/tlink-photo-picker/pages/picker/picker",
    "style": {
        "navigationBarTitleText": "选择图片",
        "navigationStyle": "custom",
        "navigationBarTextStyle": "white",
        "disableSwipeBack": true
    }
}

3. 视频试看用到 video 组件：在 manifest.json 的「App 模块配置」里勾选 Video（或在源码视图 app-android / app-ios 的 distribute.modules 中加 "uni-video": {}）。
4. 插件含原生代码，必须重新制作自定义基座后运行，标准基座不可用。付费插件试用也只能在自定义基座上进行。

快速开始

import {
    chooseMedia,
    TLChooseMediaResult,
    TLChooseMediaFail
} from '@/uni_modules/tlink-photo-picker/common/index.uts'

chooseMedia({
    count: 9,
    success: (res : TLChooseMediaResult) => {
        for (let i = 0; i < res.tempFiles.length; i++) {
            const f = res.tempFiles[i]
            console.log(f.type, f.path, f.width, f.height, f.size)
        }
    },
    fail: (err : TLChooseMediaFail) => {
        if (err.errCode != 1) {
            uni.showToast({ title: err.errMsg, icon: 'none' })
        }
    }
})

chooseMedia 参数

chooseMedia(options : TLChooseMediaOptions) : void，所有参数都可省略。

选择范围

视频限制

原图与压缩

不开压缩时插件不处理图片：勾不勾原图都返回原尺寸文件，你可以根据 original 自行压缩。

编辑

界面

回调

success 返回值

TLChooseMediaResult

TLMediaFile

文件格式：GIF / JPEG / PNG 原样导出，HEIC / HEIF 等其他图片格式转为原尺寸 JPEG；编辑过的图片为 JPEG；视频为原文件拷贝。

fail 错误码

TLChooseMediaFail：{ errCode : number, errMsg : string }，errMsg 以 chooseMedia:fail 开头。

常用场景示例

聊天发图（同微信）

chooseMedia({
    count: 9,
    maxDuration: 300,
    maxVideoSize: 1024 * 1024 * 1024,
    confirmText: '发送',
    compressQuality: 80,
    compressMaxSide: 1600,
    success: (res) => {
        for (let i = 0; i < res.tempFiles.length; i++) {
            const f = res.tempFiles[i]
            if (f.type == 'video' && f.path.length == 0) {
                uni.showToast({ title: '视频超过 1GB，无法发送', icon: 'none' })
                continue
            }
            // 上传 f.path
        }
    }
})

朋友圈：图片最多 9 张、视频只能 1 个、不能混选

chooseMedia({
    count: 9,
    maxVideoCount: 1,
    mixSelect: false,
    maxDuration: 30,
    minDuration: 3
})

换头像：单张图片，不要原图和视频

chooseMedia({
    count: 1,
    mediaType: 'image',
    showOriginal: false,
    compressQuality: 85,
    compressMaxSide: 800,
    success: (res) => {
        const path = res.tempFiles[0].path
    }
})

只选视频、不允许编辑和试看、自定义主题

chooseMedia({
    mediaType: 'video',
    count: 3,
    videoPlayable: false,
    editable: false,
    themeColor: '#2B7CFF',
    confirmText: '下一步',
    cancelText: '关闭'
})

各平台差异

权限与隐私

iOS

• 插件的 utssdk/app-ios/info.plist 已带 NSPhotoLibraryUsageDescription，默认文案为「需要访问你的相册，以便选择照片和视频」，需要修改时直接改该文件。
• 同一文件设置了 PHPhotoLibraryPreventAutomaticLimitedAccessAlert = true，关闭系统在「部分照片」授权下的自动提示（对整个 App 生效），由选图页顶部的「管理」入口替代。
• 首次打开选图页才申请权限。

Android

• 插件声明的权限：READ_EXTERNAL_STORAGE（Android 12 及以下）、READ_MEDIA_IMAGES、READ_MEDIA_VIDEO（13+）、READ_MEDIA_VISUAL_USER_SELECTED（14+ 部分照片）。
• 首次打开选图页才申请。国内应用市场上架时，需在隐私政策中说明相册用途，并按市场要求在申请前展示用途说明。
• 用户拒绝后，选图页显示「去设置」按钮，并弹框引导到系统设置。

鸿蒙

• 使用系统 PhotoViewPicker，不需要声明任何权限。

数据

• 插件不联网、不采集任何数据。
• 选中的文件拷贝到本应用缓存目录：iOS / Android 由插件定期清理旧的导出文件和缩略图缓存，鸿蒙每次选择前清理一天前的文件。需要长期保存时请自行拷贝到 uni.env.USER_DATA_PATH。

底层原生 API

自己画界面时可以直接用原生层。引入：import { ... } from '@/uni_modules/tlink-photo-picker'。跨桥的列表都是 JSON 字符串，自行 JSON.parse。所有回调都在主线程触发。鸿蒙上只有 photoPickSystem 可用，其余为空实现。

常见问题

调用后没反应 / errCode 3：选图页没注册到 pages.json，按安装第 2 步添加。

报「模块不存在」或原生方法找不到：没有重新打自定义基座，或 iOS 覆盖安装没更新原生库。卸载旧 App 后重新打基座安装。

视频点播放没反应：manifest 没勾选 Video 模块，勾选后重新打基座。

直接 uni.navigateTo 打开选图页拿不到结果：必须通过 chooseMedia 打开，结果走回调。

iOS 只显示部分照片：用户授权的是「部分照片」，点顶部「管理」增减；或引导用户到设置改为「完全访问」。

选图页颜色：固定深色风格（同微信），不跟随系统暗黑模式；主题色可用 themeColor 修改。

多语言：界面文字为中文，按钮文字可通过 confirmText / cancelText 修改，其余暂不支持。