Flutter for OpenHarmony：基于 SharedPreferences 的本地化笔记应用架构与实现

摘要

本文详细阐述如何将一个标准的 Flutter 笔记应用（支持创建、编辑、删除、搜索与本地持久化）完整迁移并优化至OpenHarmony 4.0+平台。通过深度集成shared_preferences与 OpenHarmony 的应用沙箱存储机制，结合intl实现符合中文用户习惯的时间格式化，构建出一个轻量、安全、离线可用的原子化服务原型。

全文包含完整的代码结构、pubspec.yaml配置、OpenHarmony 权限声明、数据存储路径适配及真机部署验证，适用于希望在 OpenHarmony 生态中快速落地 Flutter 轻应用的开发者。

关键词：Flutter for OpenHarmony、本地笔记应用、SharedPreferences、原子化服务、离线数据持久化

1. 为什么选择笔记应用作为 OpenHarmony 入门项目？

笔记应用具备以下特性，使其成为 OpenHarmony + Flutter 融合的理想载体：

• 无网络依赖：完全离线运行，规避 OpenHarmony 网络权限复杂性；
• 轻量级数据：适合shared_preferences存储，无需 SQLite；
• 高频交互：涵盖列表、表单、搜索等典型 UI 模式；
• 可扩展为元服务：未来可封装为“快捷笔记卡片”，嵌入桌面或服务中心。

更重要的是，它能清晰展示Flutter 应用在 OpenHarmony 上的生命周期、存储隔离与权限模型。

2. 项目配置：适配 OpenHarmony 的 pubspec.yaml

2.1 依赖精简与目标对齐

# pubspec.yamlname:sfcdescription:"A simple note-taking application built with Flutter for OpenHarmony."environment:sdk:">=3.6.2 <4.0.0"dependencies:flutter:sdk:fluttercupertino_icons:^1.0.8shared_preferences:^2.2.2# 用于本地 JSON 存储intl:^0.19.0# 日期格式化（如 "2026-01-28 14:30"）flutter:uses-material-design:true# 注意：OpenHarmony 不支持 assets/images/ 等资源目录自动加载# 如需图片，应使用 ohos_resource 或通过 native 传递

✅关键点：移除所有非必要插件（如flutter_avif），确保在 OpenHarmony NDK 环境下编译通过。

3. OpenHarmony 权限与存储适配

3.1 权限声明（module.json5）

虽然shared_preferences使用应用私有目录，但仍需声明基础存储权限：

// entry/src/main/module.json5{"module":{"requestPermissions":[{"name":"ohos.permission.READ_USER_STORAGE","reason":"$string:storage_reason","usedScene":{"when":"$string:storage_when","scene":["access storage"]}},{"name":"ohos.permission.WRITE_USER_STORAGE"}]}}

💡 实际上，shared_preferences在 OpenHarmony 中默认写入/data/storage/el2/base/<bundle_name>/，属于应用私有空间，无需动态申请权限。但为兼容未来扩展（如导出到公共目录），建议提前声明。

3.2 数据存储路径确认

在 OpenHarmony 设备上，可通过hdc shell验证数据是否写入：

hdc shellcd/data/storage/el2/base/com.example.sfc/catdefault_flutter_shared_preferences.xml

你将看到类似：

<map><stringname="flutter.notes">{"notes":[{...}]}</string></map>

4. 核心代码实现（适配 OpenHarmony）

所有代码位于lib/main.dart，共 495 行，结构清晰。

4.1 笔记数据模型（Note）

classNote{finalStringid;finalStringtitle;finalStringcontent;finalDateTimecreatedAt;finalDateTimeupdatedAt;Note({requiredthis.id,requiredthis.title,requiredthis.content,requiredthis.createdAt,requiredthis.updatedAt,});Map<String,dynamic>toMap()=>{'id':id,'title':title,'content':content,'createdAt':createdAt.toIso8601String(),'updatedAt':updatedAt.toIso8601String(),};factoryNote.fromMap(Map<String,dynamic>map)=>Note(id:map['id'],title:map['title'],content:map['content'],createdAt:DateTime.parse(map['createdAt']),updatedAt:DateTime.parse(map['updatedAt']),);}

4.2 主应用入口（NoteApp）

voidmain()async{WidgetsFlutterBinding.ensureInitialized();// OpenHarmony 下无需额外初始化 shared_preferencesrunApp(constNoteApp());}classNoteAppextendsStatelessWidget{constNoteApp({super.key});@overrideWidgetbuild(BuildContextcontext){returnMaterialApp(title:'我的笔记',theme:ThemeData(useMaterial3:true),home:NoteListPage(),debugShowCheckedModeBanner:false,);}}

4.3 笔记列表页（核心：_loadNotes & _saveNotes）

class_NoteListPageStateextendsState<NoteListPage>{List<Note>_notes=[];List<Note>_filteredNotes=[];bool _isLoading=true;@overridevoidinitState(){super.initState();_loadNotes();}Future<void>_loadNotes()async{setState(()=>_isLoading=true);try{finalprefs=awaitSharedPreferences.getInstance();finaljsonString=prefs.getString('notes');if(jsonString!=null){finaljsonList=jsonDecode(jsonString)asList;_notes=jsonList.map((e)=>Note.fromMap(e)).toList();}else{_notes=[];}_filteredNotes=_notes;}catch(e){// OpenHarmony 日志可通过 hdc hilog 查看print('Load notes error:$e');ScaffoldMessenger.of(context).showSnackBar(SnackBar(content:Text('加载笔记失败')),);}finally{setState((){_isLoading=false;});}}Future<void>_saveNotes()async{try{finalprefs=awaitSharedPreferences.getInstance();finaljsonList=_notes.map((note)=>note.toMap()).toList();awaitprefs.setString('notes',jsonEncode({'notes':jsonList}));}catch(e){ScaffoldMessenger.of(context).showSnackBar(SnackBar(content:Text('保存失败')),);}}}

✅OpenHarmony 适配要点：

• SharedPreferences.getInstance()在 OpenHarmony 上由 Flutter 引擎自动映射到系统 KV 存储；
• 异常处理必须完善，因 OpenHarmony 沙箱限制更严格。

4.4 搜索功能（NoteSearchDelegate）

classNoteSearchDelegateextendsSearchDelegate<String>{finalList<Note>notes;NoteSearchDelegate(this.notes);@overrideList<Widget>?buildActions(BuildContextcontext){return[IconButton(icon:Icon(Icons.clear),onPressed:()=>query='',),];}@overrideWidget?buildLeading(BuildContextcontext){returnIconButton(icon:Icon(Icons.arrow_back),onPressed:()=>close(context,''),);}@overrideWidgetbuildResults(BuildContextcontext)=>_buildSearchResults();@overrideWidgetbuildSuggestions(BuildContextcontext)=>_buildSearchResults();Widget_buildSearchResults(){finalfiltered=notes.where((note){finaltext='${note.title}${note.content}'.toLowerCase();returntext.contains(query.toLowerCase());}).toList();returnListView.builder(itemCount:filtered.length,itemBuilder:(context,index){finalnote=filtered[index];returnListTile(title:Text(note.title),subtitle:Text(note.content.substring(0,min(note.content.length,50))),onTap:(){close(context,note.id);// 返回选中笔记 ID},);},);}}

5. 测试与部署

5.1 单元测试（widget_test.dart）

testWidgets('Note app smoke test on OpenHarmony',(tester)async{awaittester.pumpWidget(constNoteApp());expect(find.text('我的笔记'),findsOneWidget);expect(find.text('还没有笔记'),findsOneWidget);// 测试添加笔记流程awaittester.tap(find.byType(FloatingActionButton));awaittester.pumpAndSettle();expect(find.text('新建笔记'),findsOneWidget);});

5.2 构建与安装

# 编译 OpenHarmony HAP 包flutter build ohos --release# 安装到设备hdcinstall./build/ohos/outputs/hap/release/sfc-release-standard-ark-signed.hap

⚠️ 注意：需配置 DevEco Studio 与 Flutter OpenHarmony 插件。

6. 性能与安全考量

7. 未来演进方向

1. 封装为元服务卡片：将“快速新建笔记”功能提取为 2x2 服务卡片；
2. 分布式同步：利用 DSoftBus 实现手机写笔记 → 智慧屏查看；
3. 语音输入：调用 OpenHarmony 语音识别能力，提升输入效率；
4. 暗色模式适配：监听系统主题，自动切换 UI 主题。

结语

本文成功将一个标准 Flutter 笔记应用完整部署于 OpenHarmony 平台，验证了Flutter 在 OpenHarmony 上构建轻量级、离线优先应用的可行性。通过合理使用shared_preferences与intl，配合 OpenHarmony 的权限与存储模型，开发者可快速交付具备生产级质量的原子化服务。

该应用虽小，却涵盖了状态管理、数据持久化、UI 交互、错误处理、国际化等核心开发要素，是学习Flutter for OpenHarmony的理想起点。

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