更新记录

1.2.9（2026-09-02）

• 修复 recent-photo.ets：RecentPhotoInfo 等从 @ohos.file.RecentPhotoComponent 导入，避免 @kit.MediaLibraryKit 未再导出导致 ArkTS 编译失败。

1.2.8（2026-09-02）

• 修复已知问题。

1.2.7（2026-09-01）

• 修复已知问题。

平台兼容性

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-save 另支持鸿蒙 SaveButton API 20+ 属性（官方文档）：

setIcon / setText 需在工程 harmony-configs 声明受限权限 ohos.permission.CUSTOMIZE_SAVE_BUTTON（需应用市场上架审批），否则自定义不生效、仍显示默认样式。

嵌入式组件

相册 + 图片选择

<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 :options="pickerOptions" @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,
    UmiImagePickerOptions,
    UmiSelectMode,
    UmiReminderMode,
    UmiPickerColorMode,
    UmiItemDisplayRatio
} from "@/uni_modules/umi-secure-controls"

const pickerOptions : UmiImagePickerOptions = {
    MIMEType: 'image',
    maxSelectNumber: 9,
    isPhotoTakingSupported: true,
    isSearchSupported: true,
    selectMode: UmiSelectMode.MULTI_SELECT,
    checkBoxColor: '#FF007AFF',
    maxSelectedReminderMode: UmiReminderMode.TOAST,
    uiComponentColorMode: UmiPickerColorMode.AUTO,
    singleLineConfig: {
        itemDisplayRatio: UmiItemDisplayRatio.SQUARE_RATIO,
        itemBorderRadius: 8,
        itemGap: 4
    },
    completeButtonText: 'done'
}

umiImagePickerSelect(pickerOptions).then((res) => {
    const uris = res.photoUris
})

UmiImagePickerOptions 对应鸿蒙 PhotoPickerComponent / PickerOptions（与嵌入式 umi-photo-picker 字段一致）。枚举与官方一致：UmiSelectMode、UmiReminderMode、UmiPickerColorMode、UmiItemDisplayRatio，单行模式使用 singleLineConfig（UmiSingleLineConfig）。另含 completeButtonText（弹窗顶栏确认文案：done | send | add）。

文件选择支持 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，重新运行后才会进包。