更新记录

1.1.0（2026-08-30）

• 修复已知问题。

1.0.0（2026-08-29）

• 安全控件：umi-save（保存图片到图库）、umi-paste（读取剪贴板）、umi-location（获取定位）
• 嵌入式组件：umi-photo-picker（图片/视频选择）、umi-album-picker（相册列表）、umi-recent-photo（最近一张图）、umi-card-recognition（卡证识别）、umi-doc-scanner（文档扫描）
• 拉起式 Picker：umi-image-picker（系统相册）、umi-file-picker（文件选择/保存）、umi-audio-picker（音频选择/保存）、umi-camera（系统相机）、umi-contact-picker（联系人）、umi-scan（扫码）、umi-cast（投播）
• 支持摇树按需打包，未使用组件不进入产物，打包体积更小

平台兼容性

uni-app x(4.83)

其他

umi-secure-controls

鸿蒙安全控件 / 嵌入式选择与视觉控件，仅支持 App 鸿蒙端（HBuilderX 4.61+）。

摇树（按需打包）

package.json 已开启 uni_modules.treeShaking.app.harmony = true。

• 模板里用到的 umi-* 组件（easycom）才会进入产物
• 各组件通过相对路径引用自己的原生实现，互不拖带
• 业务侧请按需 import API / 类型，例如只 import { umiScanStart }，不要一次性导入未使用的符号

// 推荐：按需
import { umiScanStart, UmiScanError } from "@/uni_modules/umi-secure-controls"

// 不推荐：无意义的整包导入习惯（命名空间式）会削弱摇树效果

安全按钮

<umi-save class="btn" text="saveToGallery" buttonType="capsule" @click="onSave"></umi-save>
<umi-paste class="btn" text="paste" buttonType="capsule" @click=""></umi-paste>
<umi-location class="btn" text="currentLocation" buttonType="capsule" @click="onLocation"></umi-location>

通用属性：icon、text、buttonType（capsule | circle | normal），创建后不可动态修改。建议按钮尺寸不小于约 220×40，且不要被其他组件遮挡。

嵌入式组件

相册 + 图片选择

<umi-album-picker :options="albumOptions" @albumClick="onAlbumClick"></umi-album-picker>
<umi-photo-picker ref="photoPicker" :options="pickerOptions" @select=""></umi-photo-picker>

UmiPickerOptions 对应鸿蒙 PickerOptions + BaseSelectOptions（含 MIMEType、选择上限、拍照/搜索/编辑/原图、预选、推荐、勾选框颜色、单行模式等）。

umi-photo-picker 方法：setAlbumUri、setData、setMaxSelected、setPhotoBrowserItem、setPhotoBrowserUIElementVisibility、exitPhotoBrowser。

相册点击后调用 setAlbumUri(uri) 刷新宫格。selectOnItemClick 默认 true，对应 onItemClicked 的返回值。

最近图片

<umi-recent-photo :options="{ period: 86400, MIMEType: 'imageVideo', photoSource: 'all' }"
    @recentPhotoClick="onRecent"></umi-recent-photo>

grantOnClick 默认 true，点击后授予该 URI 读权限。

卡证识别

属性对应鸿蒙 CardRecognition：supportType、cardSide、cardRecognitionConfig（defaultShootingMode、isPhotoSelectionSupported、setCardMargins、银行卡弹窗、身份证人像/质量检测）。

<umi-card-recognition supportType="id" cardSide="default"
    defaultShootingMode="manual" :isPhotoSelectionSupported="true"
    @result="onCardResult"></umi-card-recognition>

supportType：auto | id | bank | passport | driverLicense | vehicleLicense
cardSide：default | front | back

文档扫描

属性对应鸿蒙 DocumentScannerConfig：maxShotCount、supportType、isGallerySupported、editTabs、defaultFilterId、defaultShootingMode、isShareable、saveOptions、originalUris。

<umi-doc-scanner :maxShotCount="3" :supportType="['doc','sheet']"
    :saveOptions="['jpg','pdf']" @result="onScanResult"></umi-doc-scanner>

拉起式 Picker

系统半模态选择器，也可当组件点击拉起。同时导出同名 API，可直接 import 调用。

<umi-image-picker MIMEType="image" :maxSelectNumber="9" @success="onImage" @fail="onFail">
    <text>选择图片</text>
</umi-image-picker>
<umi-file-picker :maxSelectNumber="5" selectMode="file" @success="onFiles"></umi-file-picker>
<umi-camera cameraPosition="back" :mediaTypes="['photo','video']" @success="onCamera"></umi-camera>
<umi-scan :scanTypes="['qr']" :enableAlbum="true" @success="onScan"></umi-scan>
<umi-cast pickerStyle="panel" sessionType="video" @stateChange="onCast"></umi-cast>

import { umiImagePickerSelect, umiFilePickerSelect } from "@/uni_modules/umi-secure-controls"

umiImagePickerSelect({
    MIMEType: 'image',
    maxSelectNumber: 9,
    isEditSupported: true,
    isOriginalSupported: true
}).then((res) => {
    const uris = res.photoUris
})

文件选择支持 selectMode（file | folder | mixed）、fileSuffixFilters、authMode、mergeMode 等 DocumentSelectOptions 字段；保存走 mode="save" 或 umiFilePickerSave。

相机支持 cameraPosition、mediaTypes、saveUri、videoDuration。扫码支持 scanTypes、enableMultiMode、enableAlbum。

扫码失败时 @fail / umiScanStart 的 reject 返回 UmiScanError：{ code, message }，code 为鸿蒙 BusinessError.code。用户取消时 message 通常为 The user canceled the barcode scanning.，可按 code 或文案自行分支。

权限说明

鸿蒙权限需在工程 harmony-configs 中声明（不会随插件自动写入）。请直接参考本仓库示例项目的配置，按业务裁剪后放到你自己的工程：

组件与权限对照

* 示例工程当前未声明相机权限；若你方业务强依赖相机且审核要求声明，再在示例配置基础上追加。

示例工程已配置的定位权限

module.json5 中关键片段（完整内容见示例文件）：

"requestPermissions": [
  { "name": "ohos.permission.INTERNET" },
  {
    "name": "ohos.permission.APPROXIMATELY_LOCATION",
    "reason": "$string:permission_approximately_location_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.LOCATION",
    "reason": "$string:permission_location_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

对应中文用途文案（resources/zh_CN/element/string.json）：

• permission_approximately_location_reason：用于在用户点击定位按钮后获取大致位置
• permission_location_reason：用于在用户点击定位按钮后获取精确位置

注意： 精确位置与模糊位置必须成对声明；仅改 unpackage 下产物无效，需写在项目根目录 harmony-configs，重新运行后才会进包。