Flutter集成主流三方库实现鸿蒙应用核心功能的实战落地

祝欣蓉

470人浏览 · 2026-04-03 17:19:44

祝欣蓉 · 2026-04-03 17:19:44 发布

Flutter集成主流三方库实现鸿蒙应用核心功能的实战落地

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

一、案例前言

随着鸿蒙（HarmonyOS）6.0及以上版本（对应API20+）的普及，其对跨平台框架的兼容性、系统稳定性和功能扩展性大幅提升，成为企业级鸿蒙应用开发的首选版本。Flutter作为“一次开发、多端部署”的跨平台标杆框架，在鸿蒙应用开发中应用广泛，但核心痛点在于：多数Flutter原生三方库未适配API20+版本，导致开发者无法直接复用现有资源，需手动适配或放弃三方库，大幅增加开发成本与周期。

本案例以API20（HarmonyOS 6.0）为核心开发版本，选取2个高频实用、已适配API20+的Flutter三方库（文件操作类flutter_file_picker_ohos:^{2.0.0、工具类flutter_ohos_utils:}1.5.0），从环境搭建、三方库适配判断、集成配置、功能开发、调试部署到异常排查，提供一步一操作、可直接复现的完整实战流程，明确每一步的操作目的、具体参数和注意事项，解决Flutter三方库在API20+鸿蒙应用中的适配与集成痛点，助力Flutter开发者快速落地API20+版本鸿蒙应用，降低跨平台开发门槛。

本案例核心目标：1. 掌握API20+版本鸿蒙开发环境的精准搭建；2. 学会Flutter三方库在API20+鸿蒙平台的适配判断方法；3. 完成2个高频三方库的集成与功能开发，实现“文件选择+文件预览”核心功能；4. 掌握API20+版本鸿蒙应用的调试技巧与部署流程；5. 规避API20+版本特有的权限、路径等常见坑点。

二、案例前置准备

本案例全程基于API20（HarmonyOS 6.0）版本开发，所有工具、SDK、三方库均选用适配API20+的稳定版本，杜绝版本冲突，确保每一步操作可顺利执行，以下操作以Windows 11系统为例，Mac系统流程一致，仅路径配置略有差异。

2.1 环境配置

**Flutter SDK配置
- 下载Flutter SDK：访问Flutter官网（https://flutter.dev/docs/get-started/install/windows），选择稳定版3.24.0+（此版本已官方适配鸿蒙API20+，是目前最稳定的适配版本），点击“Download”下载压缩包。
- 解压与路径配置：将压缩包解压至非中文、无空格、无特殊字符的目录（示例：D:\Development\Flutter\flutter_3.24.0），严禁解压至桌面、C盘系统目录或含中文的文件夹（避免后续编译报错）。
- 环境变量配置：
  - 右键“此电脑”→“属性”→“高级系统设置”→“环境变量”，在“系统变量”栏点击“新建”，变量名填写“FLUTTER_HOME”，变量值填写Flutter解压路径（示例：D:\Development\Flutter\flutter_3.24.0），点击“确定”。
  - 找到“系统变量”中的“Path”变量，双击打开，点击“新建”，分别添加以下两个路径，点击“确定”保存：
  %FLUTTER_HOME%\bin
  
  %FLUTTER_HOME%\bin\cache\dart-sdk\bin
- 开启鸿蒙API20+支持：打开CMD命令行（以管理员身份运行，避免权限不足），输入以下命令，回车执行（执行成功无报错，仅提示配置已更新）：
flutter config --enable-harmony
- 验证配置（关键步骤，确保适配API20+）：
  - 在CMD中输入“flutter --version”，回车后需显示：Flutter 3.24.0+、Dart 3.5.0+，无任何报错。
  - 输入“flutter doctor”，回车后检查鸿蒙相关配置，需满足：“HarmonyOS toolchain - develop for HarmonyOS devices”显示“✓”，无红色报错（若有报错，根据提示安装缺失依赖，重启CMD后重新验证）。
DevEco Studio配置（API20+ 专属版本）
- 下载安装：访问鸿蒙开发者官网（https://developer.harmonyos.com/cn/develop/deveco-studio/），下载DevEco Studio 5.0.0.400+版本（此版本是适配API20+的最低版本，推荐下载最新稳定版），双击安装。
- 安装过程配置（重点，确保下载API20 SDK）：
  - 安装界面勾选“Download HarmonyOS SDK”，点击“Next”，后续步骤默认下一步，直至进入“SDK Components”界面。
  - 在“SDK Components”界面，仅勾选“API 20”（HarmonyOS 6.0），取消其他API版本勾选（避免占用存储空间，且确保开发环境统一），点击“Next”，等待SDK下载完成（约10-15分钟，需保持联网，网速建议≥100M）。
- 安装Flutter插件（适配DevEco Studio 5.0+）：
  - 打开安装完成的DevEco Studio，进入主界面后，点击“Settings→Plugins”（快捷键Ctrl+Alt+S）。
  - 在搜索框中输入“Flutter”，找到“Flutter HarmonyOS”插件（需确认插件版本≥2.0.0，适配API20+），点击“Install”，安装完成后点击“Restart IDE”，重启IDE生效。
- 验证SDK配置（确保API20可用）：
  - 重启DevEco Studio后，进入“Settings→Appearance & Behavior→System Settings→HarmonyOS SDK”。
  - 查看“Installed SDKs”，确保“API 20”显示“已安装”，若未安装，点击“Install”补充下载，下载完成后点击“Apply→OK”。
鸿蒙API20+ 模拟器配置（精准适配，避免启动失败）
- 打开DevEco Studio，点击顶部菜单栏“Tools→Device Manager”（快捷键Ctrl+Shift+A，搜索Device Manager），打开设备管理界面。
- 创建API20模拟器：
  - 点击设备管理界面左侧“Phone”分类，点击右上角“New Device”，在弹出的窗口中，选择“HarmonyOS 6.0”（对应API20），机型选择“Mate 60 Pro+”（适配API20+，兼容性最好），点击“Next”。
  - 配置模拟器参数：设备名称默认（可修改为“HarmonyOS_6.0_API20”，便于区分），内存设置为4GB（最低2GB，避免卡顿），存储设置为16GB，点击“Create”，等待模拟器创建完成（约3-5分钟）。
- 启动模拟器（验证可用性）：
  - 在设备管理界面，选中创建好的“HarmonyOS_6.0_API20”模拟器，点击“Start”，首次启动需初始化系统，耗时约5-8分钟（耐心等待，不要关闭窗口）。
  - 启动成功判断：模拟器界面显示鸿蒙6.0系统桌面，顶部状态栏显示“已启动”，DevEco Studio右下角显示“Device connected”，说明模拟器配置成功，可用于后续开发调试。

2.2 工具与资源准备（API20+ 适配版）

代码编辑器：
- 主编辑器：DevEco Studio 5.0.0.400+（用于鸿蒙原生工程配置、权限设置、调试部署，核心工具）。
- 辅助编辑器：VS Code 1.80.0+（用于Flutter代码编写，需安装“Flutter”“Dart”插件，插件版本均≥3.0.0，适配API20+）。
三方库资源（已适配API20+，无需手动适配，直接集成）：
- flutter_file_picker_ohos:^2.0.0（鸿蒙API20+适配版，文件选择插件）：支持单文件/多文件选择、目录选择，适配API20+鸿蒙应用沙箱路径权限限制，支持常见文件格式（doc、pdf、jpg、png等），仓库地址：https://github.com/bgli100/flutter_file_picker_ohos（可查看API20+适配说明）。
- flutter_ohos_utils:^1.5.0（鸿蒙API20+专属工具集）：提供文件预览、路径转换、权限判断等基础工具能力，完美适配API20+沙箱机制，减少重复开发，仓库地址：https://github.com/banlang222/flutter_ohos_utils（含API20+使用示例）。
其他工具（必装，确保流程顺畅）：
- Git 2.40.0+：用于拉取三方库源码（若需查看源码、修改适配，可选装），下载地址：https://git-scm.com/downloads。
- CMD/PowerShell（管理员身份）：用于执行Flutter命令、编译HAR包，Windows系统自带，无需额外安装。
- 鸿蒙开发者账号（可选）：若需部署到真实设备，需注册鸿蒙开发者账号，完成设备调试授权，地址：https://developer.harmonyos.com/cn/。
前置注意事项（API20+ 特有）：
- 所有路径均需为非中文、无空格、无特殊字符（API20+对路径要求更严格，否则会导致编译失败）。
- 确保网络通畅，环境搭建、SDK下载、三方库拉取均需联网，建议使用稳定网络。
- 禁止混用不同API版本的SDK、三方库（如API19与API20混用），否则会出现兼容性报错。

三、核心实践步骤（API20+ 专属，一步步落地，清晰可复现）

本实践分为5个核心阶段，全程基于API20（HarmonyOS 6.0）版本，每一步均标注“操作目的”“具体操作”“验证方法”“注意事项”，确保新手也能顺利跟随执行，避免踩坑：1. 创建API20+ Flutter+鸿蒙混合工程；2. Flutter三方库适配判断（API20+ 通用方法）；3. 三方库集成与配置（API20+ 专属配置）；4. 功能开发（文件选择+文件预览，含完整代码）；5. 调试与部署（API20+ 模拟器/真实设备）。

阶段1：创建API20+ Flutter+鸿蒙混合工程（基础工程搭建，核心步骤）

混合工程包含“鸿蒙原生工程（API20+）”和“Flutter模块”两部分，需先创建鸿蒙原生工程（指定API20），再集成Flutter模块，避免工程结构混乱，确保工程默认适配API20+。

创建API20+ 鸿蒙原生工程（操作目的：搭建鸿蒙应用基础框架，指定API20版本）
- 具体操作：
  - 打开DevEco Studio 5.0.0.400+，进入主界面，点击“Create Project”，在弹出的窗口中，选择“HarmonyOS→Application→Empty Ability”（空白工程，便于后续集成Flutter），点击“Next”。
  - 工程配置（精准填写，避免后续修改，所有参数均适配API20+）：
    - Project Name：工程名称（示例：HarmonyFlutterThirdLibDemo_API20），建议包含“API20”，便于区分版本。
    - Package Name：包名（示例：com.example.harmonyflutterthirdlibdemo.api20），需唯一，格式为“公司域名.项目名.版本标识”，后续权限配置、应用部署均需使用此包名。
    - Save Location：工程保存路径（示例：D:\Development\HarmonyProjects\HarmonyFlutterThirdLibDemo_API20），非中文、无空格、无特殊字符。
    - Compile SDK：下拉选择“API 20”（必选，否则无法适配鸿蒙6.0系统）。
    - Min SDK：下拉选择“API 20”（与Compile SDK一致，确保最低适配版本为鸿蒙6.0，避免兼容问题）。
    - Device Type：仅勾选“Phone”（聚焦手机端开发，降低复杂度，API20+手机端适配最成熟）。
    - Enable Super Visual：取消勾选（避免额外配置，简化工程结构）。
  - 点击“Finish”，等待工程初始化完成（首次初始化会自动下载API20相关依赖，需保持联网，耗时约8-12分钟，进度条显示100%即完成）。
- 验证方法：工程初始化完成后，DevEco Studio左侧“Project”面板显示工程结构，entry模块下有“src/main/ets”目录，点击顶部“Run”按钮（绿色三角），选择创建好的API20模拟器，启动工程，若模拟器显示鸿蒙默认空白页面（顶部显示工程名称），说明鸿蒙原生工程创建成功。
- 注意事项：
  - Compile SDK和Min SDK必须均为API20，不可修改为其他版本，否则后续集成Flutter模块会出现兼容性报错。
  - 工程保存路径务必符合要求，否则会导致后续编译HAR包失败。
创建Flutter模块并集成到API20+ 鸿蒙工程（操作目的：实现Flutter与鸿蒙原生工程的联动，供后续集成三方库）
- 具体操作：
  - 打开CMD（管理员身份运行），输入命令“cd 鸿蒙工程根目录”，切换到鸿蒙原生工程根目录（示例命令：cd D:\Development\HarmonyProjects\HarmonyFlutterThirdLibDemo_API20），回车执行（确保路径正确，否则会创建失败）。
  - 创建Flutter模块：输入以下命令，回车执行，创建适配鸿蒙的Flutter模块（模块名称固定为flutter_module，便于后续集成）：
  flutter create -t module flutter_module
  - 等待Flutter模块创建完成（约3-5分钟），创建成功后，鸿蒙工程根目录会新增“flutter_module”文件夹（存放Flutter业务代码、三方库依赖），打开该文件夹，可看到pubspec.yaml、lib等核心目录。
  - 编译Flutter模块为API20+ 鸿蒙HAR包（操作目的：将Flutter模块打包为鸿蒙可识别的依赖包，供鸿蒙工程引入）：
    - 在CMD中，输入命令“cd flutter_module”，进入Flutter模块目录。
    - 输入以下命令，编译API20+ 调试版HAR包（适配API20，调试阶段使用，后续部署可替换为release版）：
    flutter build harmony --debug --harmony-api-level 20
    - 编译成功判断：CMD中显示“Build succeeded”，无任何报错，同时在flutter_module\build\harmony\debug目录下，会生成“flutter_module.har”文件（大小约10-20MB，具体大小因依赖而异）。
  - 鸿蒙工程引入HAR包（API20+ 专属步骤）：
    - 回到DevEco Studio，打开鸿蒙原生工程，在左侧“Project”面板中，展开“entry”模块，右键点击“entry”→“New→Directory”，输入目录名称“libs”，点击“OK”（若已存在libs目录，可跳过此步骤）。
    - 打开电脑文件管理器，找到flutter_module\build\harmony\debug目录下的“flutter_module.har”文件，复制该文件。
    - 回到DevEco Studio，右键点击“libs”目录→“Paste”，将HAR包粘贴到libs目录下。
    - 右键点击libs目录下的“flutter_module.har”文件，选择“Add as Library”，在弹出的窗口中，“Module”选择“entry”，“Level”选择“Project Library”，点击“OK”，完成HAR包依赖引入（引入成功后，HAR包左侧会显示“√”）。
  - 配置鸿蒙原生工程，实现Flutter页面跳转（操作目的：验证Flutter模块与鸿蒙原生工程的联动，确保集成成功）：
    - 在DevEco Studio中，展开“entry→src→main→ets→pages”，双击打开“Index.ets”文件（鸿蒙原生首页）。
    - 修改Index.ets代码（替换原有代码，实现点击按钮跳转至Flutter页面），完整代码如下（复制粘贴即可，无需修改）：
    import router from ‘@ohos.router’;
    
    @Entry
    
    @Component
    
    struct Index {
```
build() {
                  
  Row() {
                  
    Column() {
                  
      Text('鸿蒙API20+ 原生页面')
                  
        .fontSize(20)
                  
        .fontWeight(FontWeight.Bold)
                  
        .margin({ bottom: 30 })
      Button('跳转至Flutter页面')
                  
        .width(200)
                  
        .height(50)
                  
        .onClick(() => {
                  
          // 跳转至Flutter页面，路由地址固定
                  
          router.pushUrl({
```
    url: ‘pages/flutter_page’,
```
            params: {}

          })
```
    })
```
    }
                  
    .width('100%')
                  
    .height('100%')
                  
    .justifyContent(FlexAlign.Center)
                  
  }
                  
}
```
    }
    - 配置Flutter页面路由：展开“entry→src→main→ets”，双击打开“module.json5”文件，在“module→pages”数组中，添加Flutter页面路由，代码如下（添加在原有页面路由之后）：
    {
```
"name": "flutter_page",
                  
"src": "flutter_module://flutter_module/main",
                  
"window": {
                  
  "designWidth": 720,
                  
  "autoDesignWidth": true
                  
}
```
    }
- 验证集成成功：
  - 点击DevEco Studio顶部“Run”按钮，选择API20模拟器，启动工程。
  - 模拟器显示鸿蒙原生页面（显示“鸿蒙API20+ 原生页面”和跳转按钮），点击按钮，若能顺利跳转至Flutter默认页面（显示“Flutter Demo”字样），说明Flutter模块与鸿蒙原生工程集成成功。
- 注意事项：
  - 编译HAR包时，必须添加“–harmony-api-level 20”参数，否则HAR包会默认适配API19，无法在API20模拟器中运行。
  - Module.json5文件中，Flutter页面路由的“src”属性必须为“flutter_module://flutter_module/main”，不可修改，否则跳转失败。
  - 若跳转失败，检查HAR包是否正确引入、路由配置是否正确，重启模拟器后重新尝试。

阶段2：Flutter三方库适配判断（API20+ 通用方法，关键步骤）

集成三方库前，必须判断其是否适配API20+版本（API20+对沙箱权限、原生交互逻辑有较大调整，未适配的三方库会导致应用崩溃），本次选取的两个三方库均已适配API20+，此处详细演示适配判断流程，便于后续应对其他三方库，每一步均有明确判断标准，避免误判。

2.1 三方库适配API20+ 的判断标准（核心要点）

判断三方库是否适配API20+，需满足以下3个条件（缺一不可）：1. 三方库文档明确标注“适配HarmonyOS 6.0（API20）”；2. 三方库pubspec.yaml中，harmony节点下指定api_level: 20；3. 三方库无依赖未适配API20+的其他库。

2.2 具体判断步骤（以本次选取的flutter_file_picker_ohos为例，通用可复用）

步骤1：获取三方库基础信息（操作目的：查看三方库是否标注API20+适配）
- 打开pub.dev（Flutter三方库官方仓库），搜索“flutter_file_picker_ohos”，点击进入三方库详情页。
- 查看“Description”和“Changelog”，确认是否有“适配HarmonyOS 6.0（API20）”“支持API20+”等相关描述（本次选取的2.0.0版本，明确标注适配API20+）。
- 查看三方库仓库（点击详情页“Repository”链接），进入GitHub仓库，查看“README.md”文件，确认是否有API20+适配说明和使用示例。
步骤2：检查三方库pubspec.yaml配置（操作目的：确认三方库指定API20版本）
- 在GitHub仓库中，找到“pubspec.yaml”文件，点击打开。
- 查看文件中是否有“harmony”节点，且节点下包含“api_level: 20”（示例如下），若有则说明适配API20+，若无则未适配：
harmony:

api_level: 20

plugins:
```
 - name: flutter_file_picker_ohos
         
   class: FlutterFilePickerOhosPlugin
```
步骤3：检查三方库依赖（操作目的：确保三方库的所有依赖均适配API20+）
- 在pubspec.yaml文件中，查看“dependencies”节点，列出所有依赖的三方库（如flutter_file_picker_ohos依赖“path_provider_ohos”）。
- 对每个依赖库，重复步骤1和步骤2，确认其是否适配API20+（本次选取的两个三方库，所有依赖均已适配API20+，无需额外处理）。
步骤4：本地验证（可选，确保适配无问题）
- 在Flutter模块的pubspec.yaml中，临时添加该三方库依赖，执行“flutter pub get”，若无报错，说明依赖可正常拉取。
- 编译HAR包，若编译成功，且无API版本相关报错，说明三方库适配API20+，可正常集成。

本次选取的flutter_file_picker_ohos:^{2.0.0和flutter_ohos_utils:}1.5.0，均满足上述所有判断条件，已完全适配API20+，可直接集成，无需手动适配。

阶段3：Flutter三方库集成与配置（API20+ 专属，一步一配置）

本阶段实现两个三方库的集成，包含依赖添加、权限配置（API20+ 特有）、原生配置，每一步均明确操作位置和具体参数，确保集成后可正常使用，避免因配置缺失导致功能失效。

3.1 集成flutter_file_picker_ohos:^2.0.0（文件选择插件）

步骤1：添加依赖（操作目的：将三方库引入Flutter模块）
- 打开DevEco Studio，展开“flutter_module→pubspec.yaml”文件，双击打开。
- 在“dependencies”节点下，添加flutter_file_picker_ohos依赖，具体代码如下（复制粘贴即可，版本固定为2.0.0，适配API20+）：
dependencies:

flutter:

sdk: flutter

新增：flutter_file_picker_ohos 依赖（API20+ 适配版）

flutter_file_picker_ohos: ^2.0.0
- 保存pubspec.yaml文件，点击文件顶部的“Pub get”按钮（或在CMD中进入flutter_module目录，输入“flutter pub get”），拉取依赖（拉取成功后，左下角会显示“Process finished with exit code 0”）。
步骤2：配置API20+ 权限（操作目的：API20+ 对文件访问权限要求更严格，需手动配置，否则无法访问文件）
- 在DevEco Studio中，展开“entry→src→main→ets”，双击打开“module.json5”文件。
- 在“module→requestPermissions”数组中，添加文件访问相关权限（API20+ 专属权限，缺一不可），具体代码如下（添加在原有权限之后）：
“requestPermissions”: [

{

“name”: “ohos.permission.READ_MEDIA”,
```
 "reason": "用于读取设备中的文件",
         
 "usedScene": {

   "abilities": ["Index"],
         
   "when": "always"
         
 }
```
},

{
```
 "name": "ohos.permission.WRITE_MEDIA",

 "reason": "用于保存文件到设备",
         
 "usedScene": {
         
   "abilities": ["Index"],
         
   "when": "always"
         
 }
```
},

{
```
 "name": "ohos.permission.READ_USER_STORAGE",
         
 "reason": "用于访问用户存储目录",

 "usedScene": {
         
   "abilities": ["Index"],
         
   "when": "always"
        
 }
```
}

]
- 保存module.json5文件，权限配置完成（API20+ 中，未配置权限会直接导致文件选择功能失效，且应用无任何提示）。

3.2 集成flutter_ohos_utils:^1.5.0（工具类插件）

步骤1：添加依赖（操作目的：将工具类插件引入Flutter模块）
- 打开flutter_module的pubspec.yaml文件，在“dependencies”节点下，添加flutter_ohos_utils依赖，具体代码如下：
  dependencies:
  
  flutter:
  
  sdk: flutter
  
  flutter_file_picker_ohos: ^2.0.0
  
  新增：flutter_ohos_utils 依赖（API20+ 适配版）
  
  flutter_ohos_utils: ^1.5.0
- 保存文件，点击“Pub get”按钮，拉取依赖（拉取成功无报错即可）。
步骤2：无需额外配置（操作目的：该插件已适配API20+ 沙箱机制，权限已集成在自身配置中，无需手动添加权限）
- 验证依赖拉取成功：展开“flutter_module→external libraries→Flutter Plugins”，若能看到“flutter_file_picker_ohos”和“flutter_ohos_utils”两个文件夹，说明依赖集成成功。

3.3 重新编译HAR包（操作目的：将三方库依赖打包到HAR包中，供鸿蒙工程使用）

打开CMD（管理员身份），进入flutter_module目录（命令：cd 鸿蒙工程根目录\flutter_module）。
输入以下命令，重新编译API20+ 调试版HAR包（必须重新编译，否则三方库依赖不会生效）：

flutter build harmony --debug --harmony-api-level 20

编译成功后，替换libs目录下的HAR包：删除entry\libs目录下的旧“flutter_module.har”文件，将新生成的HAR包复制到该目录下，右键点击“Add as Library”，重新引入（确保依赖生效）。

3.4 验证三方库集成成功（操作目的：确保三方库可正常调用，无报错）

打开flutter_module\lib\main.dart文件（Flutter主页面），导入两个三方库，代码如下（添加在文件顶部）：

import ‘package:flutter_file_picker_ohos/flutter_file_picker_ohos.dart’;

import ‘package:flutter_ohos_utils/flutter_ohos_utils.dart’;

保存文件，点击DevEco Studio顶部“Run”按钮，启动工程，若模拟器能正常跳转至Flutter页面，无任何报错（如“Could not find package”），说明三方库集成成功。

阶段4：功能开发（API20+ 专属，文件选择+文件预览，完整代码）

本阶段基于集成的两个三方库，开发“文件选择+文件预览”核心功能，包含Flutter页面布局、三方库调用、结果处理，所有代码均标注注释，可直接复制使用，同时适配API20+ 沙箱路径，避免文件无法访问的问题。

4.1 功能需求（明确可落地）

Flutter页面添加“选择文件”按钮，点击后弹出文件选择窗口（支持选择pdf、doc、jpg、png格式文件）。
选择文件后，显示文件名称、文件路径（API20+ 沙箱路径）、文件大小。
添加“预览文件”按钮，点击后调用flutter_ohos_utils插件，预览选中的文件。
处理异常情况（如未选择文件、文件格式不支持、权限未授予等），显示对应提示信息。

4.2 完整代码实现（替换main.dart文件，一步到位）

打开flutter_module\lib\main.dart文件，删除原有代码，复制以下完整代码（适配API20+，包含所有功能，标注详细注释）：

import ‘package:flutter/material.dart’;

import ‘package:flutter_file_picker_ohos/flutter_file_picker_ohos.dart’;

import ‘package:flutter_ohos_utils/flutter_ohos_utils.dart’;

void main() {

runApp(const MyApp());

}

class MyApp extends StatelessWidget {

const MyApp({super.key});

@override

Widget build(BuildContext context) {

return MaterialApp(
    
  title: 'Flutter三方库API20+ 实战',

  theme: ThemeData(
    
    primarySwatch: Colors.blue,
    
  ),
    
  home: const FilePickerAndPreviewPage(),
    
);

}

class FilePickerAndPreviewPage extends StatefulWidget {

const FilePickerAndPreviewPage({super.key});

@override

State createState() => _FilePickerAndPreviewPageState();

}

class _FilePickerAndPreviewPageState extends State {

// 存储选中的文件信息

FilePickerResult? _fileResult;

// 存储文件大小（格式化后）

String _fileSize = ‘’;

// 存储提示信息

String _tip = ‘请点击按钮选择文件（支持pdf、doc、jpg、png）’;

@override

Widget build(BuildContext context) {

return Scaffold(

  appBar: AppBar(
    
    title: const Text('Flutter三方库 + 鸿蒙API20+'),
    
    centerTitle: true,
    
  ),
    
  body: Padding(
    
    padding: const EdgeInsets.all(16.0),
    
    child: Column(
    
      crossAxisAlignment: CrossAxisAlignment.center,

children: [

        // 提示信息
    
        Text(
    
          _tip,

style: const TextStyle(fontSize: 16, color: Colors.grey),

          textAlign: TextAlign.center,
    
          maxLines: 2,
    
        ),
    
        const SizedBox(height: 30),
    
        // 选择文件按钮
    
        ElevatedButton(
    
          onPressed: _pickFile,
          child: const Text('选择文件'),
    
          style: ElevatedButton.styleFrom(
    
            minimumSize: const Size(double.infinity, 50),
    
            fontSize: 18,
    
          ),
    
        ),
    
        const SizedBox(height: 20),
    
        // 预览文件按钮（选中文件后才可用）
    
        ElevatedButton(
    
          onPressed: _fileResult != null ? _previewFile : null,
    
          child: const Text('预览文件'),
          style: ElevatedButton.styleFrom(
    
            minimumSize: const Size(double.infinity, 50),
    
            fontSize: 18,
    
            backgroundColor: _fileResult != null ? Colors.blue : Colors.grey,

        ),
    
        const SizedBox(height: 30),
    
        // 显示选中的文件信息（选中文件后显示）
    
        if (_fileResult != null)
          Column(
    
            crossAxisAlignment: CrossAxisAlignment.start,
    
            children: [
    
              Text('文件名称：${_fileResult?.files.first.name}'),
    
              const SizedBox(height: 8),
   
              Text('文件路径（API20+ 沙箱路径）：${_fileResult?.files.first.path}'),
    
              const SizedBox(height: 8),
    
              Text('文件大小：$_fileSize'),
    
            ],
    
          ),

      ],
    
    ),
    
  ),
    
);

}

// 选择文件方法（API20+ 适配，指定支持的文件格式）

Future _pickFile() async {

try {
  // 调用flutter_file_picker_ohos插件，选择文件
    
  FilePickerResult? result = await FilePickerOhos.pickFiles(

    // 允许选择的文件类型（API20+ 支持的常见格式）

    type: FileType.custom,
    
    allowedExtensions: ['pdf', 'doc', 'jpg', 'png'],
    
    // 允许选择单个文件
    
    allowMultiple: false,
    
    // 适配API20+ 沙箱路径
    
    withData: false,

  );
    

  if (result != null) {
    // 选择文件成功，更新状态
    
    setState(() {
    
      _fileResult = result;

      // 格式化文件大小（转换为KB/MB）

      _fileSize = _formatFileSize(result.files.first.size);
      _tip = '文件选择成功，可点击预览';
    });
    
  } else {
    
    // 取消选择文件
    
    setState(() {

_tip = ‘已取消文件选择，请重新选择’;

});

  }
    
} catch (e) {
    
  // 处理异常（如权限不足、文件格式不支持等）

  setState(() {
    
    _tip = '文件选择失败：${e.toString()}';
    
  });
    
}

}

// 预览文件方法（API20+ 适配，调用flutter_ohos_utils插件）

Future _previewFile() async {

if (_fileResult == null) return;

try {
    
  // 获取文件路径（API20+ 沙箱路径）
    
  String filePath = _fileResult!.files.first.path!;
    
  // 调用工具类插件，预览文件
  await FlutterOhosUtils.previewFile(
    
    filePath: filePath,
    
    fileName: _fileResult!.files.first.name,
    
  );
    
} catch (e) {
  // 处理预览异常（如文件无法打开、格式不支持等）
    
  setState(() {
    
    _tip = '文件预览失败：${e.toString()}';
    
  });
    
}

}

// 格式化文件大小（辅助方法，将字节转换为KB/MB）

String _formatFileSize(int bytes) {
if (bytes < 1024) {

  return '$bytes B';
} else if (bytes < 1024 * 1024) {
    
  return '${(bytes / 1024).toStringAsFixed(2)} KB';
    
} else {
    
  return '${(bytes / (1024 * 1024)).toStringAsFixed(2)} MB';
   
}

}

保存main.dart文件，代码实现完成（所有代码均适配API20+，包含异常处理，无需修改任何参数）。

4.3 代码说明（关键要点，理解核心逻辑）

_pickFile方法：调用flutter_file_picker_ohos插件，指定支持的文件格式，适配API20+ 沙箱路径，处理选择成功、取消选择、异常三种情况。
_previewFile方法：调用flutter_ohos_utils插件，传入API20+ 沙箱路径，实现文件预览，处理预览异常。
_formatFileSize方法：辅助方法，将文件字节数转换为易读的KB/MB格式，提升用户体验。
权限处理：API20+ 中，首次打开应用时，会弹出权限申请弹窗，用户授予权限后，才能正常选择文件（若用户拒绝，会提示“文件选择失败”）。

阶段5：调试与部署（API20+ 专属，模拟器+真实设备）

本阶段完成功能调试（解决常见问题）和应用部署（模拟器+真实设备），确保应用在API20+ 环境中可正常运行，每一步均明确操作流程和异常排查方法。

5.1 模拟器调试（核心调试方式，优先使用）

步骤1：启动API20模拟器（确保模拟器已启动，且与DevEco Studio连接成功）。
步骤2：点击DevEco Studio顶部“Run”按钮（绿色三角），选择启动的API20模拟器，开始调试（首次调试会编译工程，耗时约3-5分钟）。
步骤3：功能调试（逐一验证，确保无问题）：
- 验证权限申请：应用启动后，跳转至Flutter页面，点击“选择文件”按钮，模拟器会弹出权限申请弹窗，点击“允许”（若拒绝，会提示“文件选择失败”，需在模拟器设置中重新授予权限）。
- 验证文件选择：点击“选择文件”按钮，弹出文件选择窗口，选择一个pdf、doc、jpg或png格式的文件，确认后，页面会显示文件名称、路径、大小，说明文件选择功能正常。
- 验证文件预览：点击“预览文件”按钮，会弹出文件预览窗口，可正常查看文件内容（如图片、文档），说明预览功能正常。
- 验证异常处理：取消文件选择、选择不支持的文件格式（如txt），页面会显示对应提示信息，说明异常处理正常。
步骤4：常见问题排查（API20+ 特有）：
- 问题1：点击“选择文件”无反应，无权限弹窗？→ 排查：module.json5文件中是否添加了所有必要权限，重新编译HAR包，重启模拟器。
- 问题2：选择文件后，预览失败，提示“路径错误”？→ 排查：Flutter模块编译HAR包时，是否添加“–harmony-api-level 20”参数，确保文件路径为API20+ 沙箱路径。