uni-app openDocument 文件打开能力全解析uni-openDocument UTS 插件原理与实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-openDocument 是 uni-app 官方开源仓库中负责「打开文件」能力的 UTS 插件它通过uni.openDocument()接口在 AppAndroid/iOS/鸿蒙与微信小程序等平台上唤起系统或宿主应用预览/打开本地文档。本文将以仓库内 src/uni_modules/uni-openDocument 为核心结合其完整源码与官方示例页系统讲解 API 参数、错误码规范、各平台底层实现原理Android Intent/FileProvider、iOS QuickLook、鸿蒙 Want 拉起、UTS 插件机制与实战用法帮助开发者正确集成并深度理解这一能力的跨端工作方式。一、插件定位一个用 UTS 封装原生能力的最小 uni_modules 插件uni-openDocument 在仓库中的完整形态是一个标准的 uni_modules UTS 插件目录结构如下全部源码均在仓库内src/uni_modules/uni-openDocument/ ├── readme.md # 插件说明本文关联文档 ├── package.json # 插件元数据、平台声明、依赖声明 ├── changelog.md # 版本变更记录 └── utssdk/ ├── interface.uts # API 类型定义参数、回调、错误码 ├── protocol.uts # 常量API 名称 openDocument ├── unierror.uts # 统一错误对象实现UniError 子类 ├── app-android/ # Android 平台实现UTS/Kotlin │ ├── config.json # hooksClass 声明 │ └── index.uts ├── app-ios/ # iOS 平台实现UTS/Swift │ └── index.uts └── app-harmony/ # 鸿蒙平台实现UTS/ArkTS └── index.uts从 package.json 可以看到它如何被注册为 uni-app 扩展 API{ id: uni-openDocument, version: 1.0.0, engines: { HBuilderX: ^3.6.8 }, uni_modules: { dependencies: [uni-fileSystemManager], uni-ext-api: { uni: { openDocument: { name: openDocument, app: { js: false, kotlin: true, swift: true, arkts: true } } } } } }其中uni-ext-api声明了该插件向全局uni对象注入名为openDocument的扩展 API并指明 App 端分别在 KotlinAndroid、SwiftiOS、ArkTS鸿蒙三个编译目标上提供实现而js: false表示它并非纯 JS 实现dependencies声明依赖 uni-fileSystemManagerAndroid 端复制文件时会用到文件系统能力见下文源码分析。二、API 快速上手参数与回调插件的对外类型定义全部集中在 utssdk/interface.uts其中OpenDocumentOptionsinterface.uts 第 371-712 行定义了完整参数| 参数 | 类型 | 必填 | 说明 | | -- | -- | -- | -- | |filePath|string| 是 | 文件路径仅支持本地路径临时路径、静态资源路径、缓存目录路径等 | |fileType|string \| null| 否 | 文件类型扩展名如doc、pdf。微信小程序仅支持doc, xls, ppt, pdf, docx, xlsx, pptxApp 端由系统打开原则上可打开任意文件 | |success|(res: OpenDocumentSuccess) void| 否 | 调用成功回调成功时res为空对象{}| |fail|(res: OpenDocumentFail) void| 否 | 调用失败回调携带errCode/errMsg| |complete|(res: any) void| 否 | 调用结束回调成功、失败都会执行 |Uni接口中的方法声明interface.uts 第 715-788 行明确了openDocument(options?)的调用形态并标注其支持 Vue2 与 Vue3 两种工程。最简单的调用方式uni.openDocument({ filePath: /static/hello.pdf, success: () { console.log(打开文档成功) }, fail: (err) { console.log(打开文档失败, err.errCode, err.errMsg) } })OpenDocumentSuccess被定义为空对象类型interface.uts 第 4 行即打开动作本身没有业务返回值成功与否由回调与错误码体现。三、错误码规范13006011300604 的完整语义插件定义了统一错误码枚举OpenDocumentErrorCodeinterface.uts 第 8-280 行错误文案的集中映射位于 utssdk/unierror.uts| 错误码 | 枚举注释 | 源码中的 errMsg | 触发场景 | | -- | -- | -- | -- | |1300601| 路径无效 |Invalid file path| 传入路径无法被识别为有效本地文件如 iOS 端非 fileURL 的路径 | |1300602| 文件不存在 |File not exist| 本地文件校验失败文件不存在或读取失败 | |1300603| 不支持该文件类型 |Not support this filetype| 无法解析 MIME/类型或系统无应用可处理AndroidstartActivity抛异常鸿蒙端显式抛出 | |1300604| 其他未知错误 |Unkowned error| 兜底错误如 Android 端获取不到 Activity、文件复制失败 |OpenDocumentErrorImplunierror.uts 第 15-25 行继承UniError并统一设置errSubject uni-openDocument错误消息从映射表中按错误码取出未命中时为空字符串export class OpenDocumentErrorImpl extends UniError implements IOpenDocumentError { constructor(code: OpenDocumentErrorCode) { super(); this.errSubject OpenDocumentUniErrorSubject; // uni-openDocument this.errCode code; this.errMsg OpenDocumentUniErrors[code] ?? ; } }各平台实现统一通过该错误类构造fail/complete回调的入参保证跨端错误语义一致。官方示例页见下文在fail中直接读取err.errCode并以 Toast 展示即此错误码的典型消费方式。四、实战示例下载远程文档后打开仓库自带的官方示例页 src/pages/API/open-document/open-document.uvue 给出了完整可运行的范式对网络文档先用uni.downloadFile下载为本地临时文件再调用uni.openDocument对本地静态资源则直接传入路径const openDocument (item: FileItem) { if (item.url.startsWith(http)) { uni.showLoading({ title: 下载中, mask: true }) uni.downloadFile({ url: item.url, success: (res) { uni.openDocument({ filePath: res.tempFilePath, // 下载后的本地临时文件 success: () { uni.hideLoading() }, fail: (err) { uni.hideLoading() uni.showToast({ title: 错误码 err.errCode.toString(), icon: error }) } }) }, fail: (err) { /* 下载失败处理 */ } }) } else { uni.openDocument({ filePath: item.url, // 静态资源路径如 /static/test-image/logo.svg success: () { console.log(打开文档成功) }, fail: (err) { /* 错误码展示 */ } }) } }示例页覆盖了pdf/doc/docx/ppt/pptx/xls/xlsx/zip/br/mp3/mp4/svg等十余种文件类型的打开展示了 App 端“原则上可以打开任意文件”的能力边界。仓库另一示例页 src/pages/API/get-file-system-manager/filemanage.uvue 中也能看到从文件系统管理器获取路径后直接交给uni.openDocument的调用方式说明filePath与uni.getFileSystemManager()的本地路径体系天然兼容。五、各平台底层实现原理源码级解析5.1 AndroidACTION_VIEW FileProvider MimeTypeMapAndroid 实现位于 utssdk/app-android/index.uts核心流程路径归一化通过UTSAndroid.convert2AbsFullPath将相对路径转为绝对路径文件有效性校验isValidFile第 75-128 行区分三类路径——/android_asset前缀通过activity.getAssets().open(...)校验存在性若有效则把文件复制到外部缓存目录getExternalCacheDir()/uni-document/下使用依赖的uni.getFileSystemManager().copyFileSync因为 FileProvider 无法直接暴露 assets 资源content://前缀通过getContentResolver().openInputStream校验可读其余普通路径new File(path).exists()校验构造 URI第 38-47 行content://路径直接解析Android 7.0API 24Build.VERSION_CODES.N及以上使用FileProvider.getUriForFile(activity, packageName .dc.fileprovider, file)生成可共享的文件 URI以下走兼容分支构造 Intent第 48-57 行ACTION_VIEWFLAG_ACTIVITY_NEW_TASKFLAG_GRANT_READ_URI_PERMISSION若显式传了fileType则用MimeTypeMap.getSingleton().getMimeTypeFromExtension(...)解析 MIME 并调用setDataAndType否则只setData拉起与兜底activity.startActivity(intent)成功则触发success抛出Exception说明系统无应用可处理该类型触发错误码1300603拿不到UniActivity时触发1300604。此外utssdk/app-android/config.json 声明了hooksClass: uts.sdk.modules.DCloudUniOpenDocument.UniOpenDocumentHookProxy对应源码第 14-28 行的UniOpenDocumentHookProxy在应用onCreate时异步清空uni-document/缓存目录中的遗留文件避免 assets 复制产物无限累积。5.2 iOSQuickLook 原生预览控制器iOS 实现位于 utssdk/app-ios/index.uts直接使用系统框架QuickLook的QLPreviewController提供文档预览openDocument委托给单例DocumentPreviewer.shared.presentDocument(options)第 14-18 行presentDocument第 33-69 行将filePath用UTSiOS.convert2AbsFullPath归一化后构造URLtmpUrl.isFileURL false报1300601路径无效FileManager.default.fileExists为 false 报1300602文件不存在通过UTSiOS.getCurrentViewController().present(...)以无动画方式弹出QLPreviewController并实现dataSource/delegate回调第 71-87 行提供预览项UniPreviewItempreviewControllerDidDismiss中还处理了关闭后立即重新呈现的边界场景。注意 iOS 端对http(s)开头的路径不做绝对路径转换第 36-38 行说明该端的设计预期仍是传入本地文件。5.3 鸿蒙Want 拉起 uniformTypeDescriptor 类型映射鸿蒙实现位于 utssdk/app-harmony/index.uts走系统startAbility拉起文档查看应用类型解析getContentType第 19-28 行优先取fileType否则从filePath取扩展名经uniformTypeDescriptor.getUniformDataTypeByFilenameExtension与getTypeDescriptor得到首个mimeTypes[0]解析失败或传入了不支持的fileType时显式抛错码1300603路径与存在性校验第 50-62 行UTSHarmony.convert2AbsFullPath归一化后以/开头的绝对路径用fs.statSync校验存在否则抛1300602资源目录文件特殊处理第 64-81 行若文件位于getContext().resourceDir下即打包进应用的只读资源先通过fs.open/copyFile复制到临时目录TEMP_PATH/openDocumentCache再打开因为只读资源目录无法直接授权给其他应用拉起应用第 82-91 行fileUri.getUriFromPath生成 URI构造Wantaction: ohos.want.action.viewData、flags携带读写与持久化授权位、uri与type一并传入abilityContext.startAbility(want)异步封装第 94-103 行通过defineAsyncApiOpenDocumentOptions, OpenDocumentSuccess(API_OPEN_DOCUMENT, ...)注册_openDocument成功resolve({})失败以错误码ErrorWithCode携带的错误码未知错误兜底1300604reject并向下兼容导出IOpenDocumentError、各回调类型等全部类型。源码第 87 行的注释还记录了一个工程经验传入type反而可能减少可被调起的应用数量如 zip 场景说明鸿蒙端在未指定类型时的“尽力打开”策略是刻意的取舍。六、UTS 语言与 UTS 插件机制原文档核心内容6.1 uts可编译为多端原生语言的跨端语言按插件 readme.md 的定义utsuni type script是一门跨平台、高性能、强类型的现代编程语言可被编译为不同平台的编程语言| 目标平台 | 编译产物语言 | | -- | -- | | Android | Kotlin | | iOS | Swift | | 鸿蒙 OS | ArkTS | | web 平台 / 小程序 | JavaScript |uts 采用与 TypeScript 基本一致的语法规范支持绝大部分 ES6 API为了跨端进行了若干约束和平台特定增补。过去在 JS 引擎下运行支持的语法大部分在 uts 的处理下也能平滑地在 Kotlin/Swift 中使用但存在无法抹平的差异此时需要使用条件编译如本插件unierror.uts第 16-18 行仅在APP-ANDROID || APP-HARMONY下声明override errCode的做法在条件编译分支内可调用平台特有扩展语法。6.2 UTS 插件的组织方式utssdk 目录按平台分离UTS 插件是一种特定形态的 uni_modules 插件核心目的是允许 uni-app/uni-app x 开发者使用 UTS 语法调用扩展 API封装原生系统 API 或三方 SDK。实现代码位于utssdk目录并按平台分离uni-openDocument 即完全遵循这一规范| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS, Kotlin, Java | UTS 插件在 Android 平台上的具体实现源码 | |utssdk/app-ios| iOS | UTS, Swift | UTS 插件在 iOS 平台上的具体实现源码 | |utssdk/app-harmony| HarmonyOS鸿蒙 | UTS, ArkTS | UTS 插件在 HarmonyOS 平台上的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 使用 UTS 编写、可供所有平台共用的实现源码如本插件的interface.uts、unierror.uts |对照本插件的源码可以直观看到interface.uts定义纯类型与接口跨端共用protocol.uts定义 API 常量unierror.uts定义错误模型而真正的平台行为实现分别在三个app-*目录中通过export const openDocument: OpenDocument ...提供——编译器会按目标平台选择对应的实现注入uni.openDocument。七、平台支持范围与使用注意事项综合 package.json 的platforms声明与 interface.uts 中逐参数标注的uniPlatform能力注释App 端Android/iOS为插件的主要实现目标Kotlin/Swift 实现标记为y参数注释中 Android/iOS 标注unixVer: 4.71起可用鸿蒙端标注uniVer: 4.31、unixVer: 4.61、vapor 版本 5.0 起可用微信小程序宿主与 uni-app 均标记为支持hostVer: √、unixVer: 4.41但fileType仅限doc, xls, ppt, pdf, docx, xlsx, pptx七种百度、QQ、快手小程序宿主能力标记为可用但 unix 侧标记为不支持unixVer: x说明这些宿主是否可打开取决于宿主 API 能力Web、支付宝、字节、飞书、京东小程序等标记为不支持x调用不会生效应在这些平台做好条件编译降级处理。使用时的关键约束均可在上述源码与注释中印证filePath仅支持本地路径远程文档必须先经uni.downloadFile落盘如示例页做法不可直接传入 http URL类型与 MIME 的关系App 端传fileType会被映射为 MIMEAndroid 用MimeTypeMap、鸿蒙用uniformTypeDescriptor不传则由系统按文件本身判定微信端则必须在其白名单类型内Android 依赖 FileProvidercontent://与 7.0 的 FileProvider 授权是 Android 实现的核心机制工程需具备对应dc.fileprovider配置由 HBuilder 运行基座自动注入iOS 预览为应用内 QuickLook 面板打开后由用户手动关闭返回success在呈现调用成功后即触发鸿蒙资源目录文件会被复制到临时目录因此打开后如需长期保留请自行管理拷贝。八、总结uni-openDocument 是理解「UTS 插件如何封装原生能力」的一个极佳样本一份interface.uts类型契约 三份平台实现Android 的 Intent/FileProvider、iOS 的 QuickLook、鸿蒙的 Want配合统一错误码1300601~1300604把“打开本地文档”这一系统级能力在 uni-app/uni-app x 中收敛成一个跨端一致的uni.openDocument调用。开发者既可直接使用官方示例页 open-document.uvue 的下载-打开流程落地业务也可参照本插件的目录结构与实现方式编写自己的 UTS 扩展 API进一步的 API 规范细节可查阅仓库文档 docs/api/open-document.mduts 语言与 UTS 插件开发的体系化说明可参考仓库内 docs/uts 与 docs/plugin 目录下的对应文档。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 uni-app openDocument 文件打开能力全解析：uni-openDocument UTS 插件原理与实战
uni-app openDocument 文件打开能力全解析uni-openDocument UTS 插件原理与实战【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appuni-openDocument 是 uni-app 官方开源仓库中负责「打开文件」能力的 UTS 插件它通过uni.openDocument()接口在 AppAndroid/iOS/鸿蒙与微信小程序等平台上唤起系统或宿主应用预览/打开本地文档。本文将以仓库内 src/uni_modules/uni-openDocument 为核心结合其完整源码与官方示例页系统讲解 API 参数、错误码规范、各平台底层实现原理Android Intent/FileProvider、iOS QuickLook、鸿蒙 Want 拉起、UTS 插件机制与实战用法帮助开发者正确集成并深度理解这一能力的跨端工作方式。一、插件定位一个用 UTS 封装原生能力的最小 uni_modules 插件uni-openDocument 在仓库中的完整形态是一个标准的 uni_modules UTS 插件目录结构如下全部源码均在仓库内src/uni_modules/uni-openDocument/ ├── readme.md # 插件说明本文关联文档 ├── package.json # 插件元数据、平台声明、依赖声明 ├── changelog.md # 版本变更记录 └── utssdk/ ├── interface.uts # API 类型定义参数、回调、错误码 ├── protocol.uts # 常量API 名称 openDocument ├── unierror.uts # 统一错误对象实现UniError 子类 ├── app-android/ # Android 平台实现UTS/Kotlin │ ├── config.json # hooksClass 声明 │ └── index.uts ├── app-ios/ # iOS 平台实现UTS/Swift │ └── index.uts └── app-harmony/ # 鸿蒙平台实现UTS/ArkTS └── index.uts从 package.json 可以看到它如何被注册为 uni-app 扩展 API{ id: uni-openDocument, version: 1.0.0, engines: { HBuilderX: ^3.6.8 }, uni_modules: { dependencies: [uni-fileSystemManager], uni-ext-api: { uni: { openDocument: { name: openDocument, app: { js: false, kotlin: true, swift: true, arkts: true } } } } } }其中uni-ext-api声明了该插件向全局uni对象注入名为openDocument的扩展 API并指明 App 端分别在 KotlinAndroid、SwiftiOS、ArkTS鸿蒙三个编译目标上提供实现而js: false表示它并非纯 JS 实现dependencies声明依赖 uni-fileSystemManagerAndroid 端复制文件时会用到文件系统能力见下文源码分析。二、API 快速上手参数与回调插件的对外类型定义全部集中在 utssdk/interface.uts其中OpenDocumentOptionsinterface.uts 第 371-712 行定义了完整参数| 参数 | 类型 | 必填 | 说明 | | -- | -- | -- | -- | |filePath|string| 是 | 文件路径仅支持本地路径临时路径、静态资源路径、缓存目录路径等 | |fileType|string \| null| 否 | 文件类型扩展名如doc、pdf。微信小程序仅支持doc, xls, ppt, pdf, docx, xlsx, pptxApp 端由系统打开原则上可打开任意文件 | |success|(res: OpenDocumentSuccess) void| 否 | 调用成功回调成功时res为空对象{}| |fail|(res: OpenDocumentFail) void| 否 | 调用失败回调携带errCode/errMsg| |complete|(res: any) void| 否 | 调用结束回调成功、失败都会执行 |Uni接口中的方法声明interface.uts 第 715-788 行明确了openDocument(options?)的调用形态并标注其支持 Vue2 与 Vue3 两种工程。最简单的调用方式uni.openDocument({ filePath: /static/hello.pdf, success: () { console.log(打开文档成功) }, fail: (err) { console.log(打开文档失败, err.errCode, err.errMsg) } })OpenDocumentSuccess被定义为空对象类型interface.uts 第 4 行即打开动作本身没有业务返回值成功与否由回调与错误码体现。三、错误码规范13006011300604 的完整语义插件定义了统一错误码枚举OpenDocumentErrorCodeinterface.uts 第 8-280 行错误文案的集中映射位于 utssdk/unierror.uts| 错误码 | 枚举注释 | 源码中的 errMsg | 触发场景 | | -- | -- | -- | -- | |1300601| 路径无效 |Invalid file path| 传入路径无法被识别为有效本地文件如 iOS 端非 fileURL 的路径 | |1300602| 文件不存在 |File not exist| 本地文件校验失败文件不存在或读取失败 | |1300603| 不支持该文件类型 |Not support this filetype| 无法解析 MIME/类型或系统无应用可处理AndroidstartActivity抛异常鸿蒙端显式抛出 | |1300604| 其他未知错误 |Unkowned error| 兜底错误如 Android 端获取不到 Activity、文件复制失败 |OpenDocumentErrorImplunierror.uts 第 15-25 行继承UniError并统一设置errSubject uni-openDocument错误消息从映射表中按错误码取出未命中时为空字符串export class OpenDocumentErrorImpl extends UniError implements IOpenDocumentError { constructor(code: OpenDocumentErrorCode) { super(); this.errSubject OpenDocumentUniErrorSubject; // uni-openDocument this.errCode code; this.errMsg OpenDocumentUniErrors[code] ?? ; } }各平台实现统一通过该错误类构造fail/complete回调的入参保证跨端错误语义一致。官方示例页见下文在fail中直接读取err.errCode并以 Toast 展示即此错误码的典型消费方式。四、实战示例下载远程文档后打开仓库自带的官方示例页 src/pages/API/open-document/open-document.uvue 给出了完整可运行的范式对网络文档先用uni.downloadFile下载为本地临时文件再调用uni.openDocument对本地静态资源则直接传入路径const openDocument (item: FileItem) { if (item.url.startsWith(http)) { uni.showLoading({ title: 下载中, mask: true }) uni.downloadFile({ url: item.url, success: (res) { uni.openDocument({ filePath: res.tempFilePath, // 下载后的本地临时文件 success: () { uni.hideLoading() }, fail: (err) { uni.hideLoading() uni.showToast({ title: 错误码 err.errCode.toString(), icon: error }) } }) }, fail: (err) { /* 下载失败处理 */ } }) } else { uni.openDocument({ filePath: item.url, // 静态资源路径如 /static/test-image/logo.svg success: () { console.log(打开文档成功) }, fail: (err) { /* 错误码展示 */ } }) } }示例页覆盖了pdf/doc/docx/ppt/pptx/xls/xlsx/zip/br/mp3/mp4/svg等十余种文件类型的打开展示了 App 端“原则上可以打开任意文件”的能力边界。仓库另一示例页 src/pages/API/get-file-system-manager/filemanage.uvue 中也能看到从文件系统管理器获取路径后直接交给uni.openDocument的调用方式说明filePath与uni.getFileSystemManager()的本地路径体系天然兼容。五、各平台底层实现原理源码级解析5.1 AndroidACTION_VIEW FileProvider MimeTypeMapAndroid 实现位于 utssdk/app-android/index.uts核心流程路径归一化通过UTSAndroid.convert2AbsFullPath将相对路径转为绝对路径文件有效性校验isValidFile第 75-128 行区分三类路径——/android_asset前缀通过activity.getAssets().open(...)校验存在性若有效则把文件复制到外部缓存目录getExternalCacheDir()/uni-document/下使用依赖的uni.getFileSystemManager().copyFileSync因为 FileProvider 无法直接暴露 assets 资源content://前缀通过getContentResolver().openInputStream校验可读其余普通路径new File(path).exists()校验构造 URI第 38-47 行content://路径直接解析Android 7.0API 24Build.VERSION_CODES.N及以上使用FileProvider.getUriForFile(activity, packageName .dc.fileprovider, file)生成可共享的文件 URI以下走兼容分支构造 Intent第 48-57 行ACTION_VIEWFLAG_ACTIVITY_NEW_TASKFLAG_GRANT_READ_URI_PERMISSION若显式传了fileType则用MimeTypeMap.getSingleton().getMimeTypeFromExtension(...)解析 MIME 并调用setDataAndType否则只setData拉起与兜底activity.startActivity(intent)成功则触发success抛出Exception说明系统无应用可处理该类型触发错误码1300603拿不到UniActivity时触发1300604。此外utssdk/app-android/config.json 声明了hooksClass: uts.sdk.modules.DCloudUniOpenDocument.UniOpenDocumentHookProxy对应源码第 14-28 行的UniOpenDocumentHookProxy在应用onCreate时异步清空uni-document/缓存目录中的遗留文件避免 assets 复制产物无限累积。5.2 iOSQuickLook 原生预览控制器iOS 实现位于 utssdk/app-ios/index.uts直接使用系统框架QuickLook的QLPreviewController提供文档预览openDocument委托给单例DocumentPreviewer.shared.presentDocument(options)第 14-18 行presentDocument第 33-69 行将filePath用UTSiOS.convert2AbsFullPath归一化后构造URLtmpUrl.isFileURL false报1300601路径无效FileManager.default.fileExists为 false 报1300602文件不存在通过UTSiOS.getCurrentViewController().present(...)以无动画方式弹出QLPreviewController并实现dataSource/delegate回调第 71-87 行提供预览项UniPreviewItempreviewControllerDidDismiss中还处理了关闭后立即重新呈现的边界场景。注意 iOS 端对http(s)开头的路径不做绝对路径转换第 36-38 行说明该端的设计预期仍是传入本地文件。5.3 鸿蒙Want 拉起 uniformTypeDescriptor 类型映射鸿蒙实现位于 utssdk/app-harmony/index.uts走系统startAbility拉起文档查看应用类型解析getContentType第 19-28 行优先取fileType否则从filePath取扩展名经uniformTypeDescriptor.getUniformDataTypeByFilenameExtension与getTypeDescriptor得到首个mimeTypes[0]解析失败或传入了不支持的fileType时显式抛错码1300603路径与存在性校验第 50-62 行UTSHarmony.convert2AbsFullPath归一化后以/开头的绝对路径用fs.statSync校验存在否则抛1300602资源目录文件特殊处理第 64-81 行若文件位于getContext().resourceDir下即打包进应用的只读资源先通过fs.open/copyFile复制到临时目录TEMP_PATH/openDocumentCache再打开因为只读资源目录无法直接授权给其他应用拉起应用第 82-91 行fileUri.getUriFromPath生成 URI构造Wantaction: ohos.want.action.viewData、flags携带读写与持久化授权位、uri与type一并传入abilityContext.startAbility(want)异步封装第 94-103 行通过defineAsyncApiOpenDocumentOptions, OpenDocumentSuccess(API_OPEN_DOCUMENT, ...)注册_openDocument成功resolve({})失败以错误码ErrorWithCode携带的错误码未知错误兜底1300604reject并向下兼容导出IOpenDocumentError、各回调类型等全部类型。源码第 87 行的注释还记录了一个工程经验传入type反而可能减少可被调起的应用数量如 zip 场景说明鸿蒙端在未指定类型时的“尽力打开”策略是刻意的取舍。六、UTS 语言与 UTS 插件机制原文档核心内容6.1 uts可编译为多端原生语言的跨端语言按插件 readme.md 的定义utsuni type script是一门跨平台、高性能、强类型的现代编程语言可被编译为不同平台的编程语言| 目标平台 | 编译产物语言 | | -- | -- | | Android | Kotlin | | iOS | Swift | | 鸿蒙 OS | ArkTS | | web 平台 / 小程序 | JavaScript |uts 采用与 TypeScript 基本一致的语法规范支持绝大部分 ES6 API为了跨端进行了若干约束和平台特定增补。过去在 JS 引擎下运行支持的语法大部分在 uts 的处理下也能平滑地在 Kotlin/Swift 中使用但存在无法抹平的差异此时需要使用条件编译如本插件unierror.uts第 16-18 行仅在APP-ANDROID || APP-HARMONY下声明override errCode的做法在条件编译分支内可调用平台特有扩展语法。6.2 UTS 插件的组织方式utssdk 目录按平台分离UTS 插件是一种特定形态的 uni_modules 插件核心目的是允许 uni-app/uni-app x 开发者使用 UTS 语法调用扩展 API封装原生系统 API 或三方 SDK。实现代码位于utssdk目录并按平台分离uni-openDocument 即完全遵循这一规范| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS, Kotlin, Java | UTS 插件在 Android 平台上的具体实现源码 | |utssdk/app-ios| iOS | UTS, Swift | UTS 插件在 iOS 平台上的具体实现源码 | |utssdk/app-harmony| HarmonyOS鸿蒙 | UTS, ArkTS | UTS 插件在 HarmonyOS 平台上的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 使用 UTS 编写、可供所有平台共用的实现源码如本插件的interface.uts、unierror.uts |对照本插件的源码可以直观看到interface.uts定义纯类型与接口跨端共用protocol.uts定义 API 常量unierror.uts定义错误模型而真正的平台行为实现分别在三个app-*目录中通过export const openDocument: OpenDocument ...提供——编译器会按目标平台选择对应的实现注入uni.openDocument。七、平台支持范围与使用注意事项综合 package.json 的platforms声明与 interface.uts 中逐参数标注的uniPlatform能力注释App 端Android/iOS为插件的主要实现目标Kotlin/Swift 实现标记为y参数注释中 Android/iOS 标注unixVer: 4.71起可用鸿蒙端标注uniVer: 4.31、unixVer: 4.61、vapor 版本 5.0 起可用微信小程序宿主与 uni-app 均标记为支持hostVer: √、unixVer: 4.41但fileType仅限doc, xls, ppt, pdf, docx, xlsx, pptx七种百度、QQ、快手小程序宿主能力标记为可用但 unix 侧标记为不支持unixVer: x说明这些宿主是否可打开取决于宿主 API 能力Web、支付宝、字节、飞书、京东小程序等标记为不支持x调用不会生效应在这些平台做好条件编译降级处理。使用时的关键约束均可在上述源码与注释中印证filePath仅支持本地路径远程文档必须先经uni.downloadFile落盘如示例页做法不可直接传入 http URL类型与 MIME 的关系App 端传fileType会被映射为 MIMEAndroid 用MimeTypeMap、鸿蒙用uniformTypeDescriptor不传则由系统按文件本身判定微信端则必须在其白名单类型内Android 依赖 FileProvidercontent://与 7.0 的 FileProvider 授权是 Android 实现的核心机制工程需具备对应dc.fileprovider配置由 HBuilder 运行基座自动注入iOS 预览为应用内 QuickLook 面板打开后由用户手动关闭返回success在呈现调用成功后即触发鸿蒙资源目录文件会被复制到临时目录因此打开后如需长期保留请自行管理拷贝。八、总结uni-openDocument 是理解「UTS 插件如何封装原生能力」的一个极佳样本一份interface.uts类型契约 三份平台实现Android 的 Intent/FileProvider、iOS 的 QuickLook、鸿蒙的 Want配合统一错误码1300601~1300604把“打开本地文档”这一系统级能力在 uni-app/uni-app x 中收敛成一个跨端一致的uni.openDocument调用。开发者既可直接使用官方示例页 open-document.uvue 的下载-打开流程落地业务也可参照本插件的目录结构与实现方式编写自己的 UTS 扩展 API进一步的 API 规范细节可查阅仓库文档 docs/api/open-document.mduts 语言与 UTS 插件开发的体系化说明可参考仓库内 docs/uts 与 docs/plugin 目录下的对应文档。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考