云笔记 | ArkTS驱动的现代笔记应用

运行截图:

项目概述

云笔记是一款基于 HarmonyOS ArkTS 开发的轻量级笔记管理应用，采用 MVVM（Model-View-ViewModel）架构模式，提供网格视图与列表视图两种展示方式，支持笔记的创建、浏览与排序功能。本项目旨在展示 ArkTS 语言在构建高性能、跨设备 HarmonyOS 应用方面的卓越能力，同时为开发者提供一个完整的、可复用的笔记应用开发模板。

随着移动互联网的快速发展，笔记应用已成为人们日常生活和工作中不可或缺的工具。传统笔记应用往往存在功能复杂、操作繁琐等问题，而云笔记通过简洁的界面设计和流畅的用户体验，为用户提供了一种全新的笔记管理方式。无论是学习记录、工作备忘还是生活随笔，云笔记都能满足用户的多样化需求。

本项目不仅是一个功能完整的笔记应用，更是一个学习 ArkTS 开发的优秀示例。通过深入分析项目代码，开发者可以掌握 ArkUI 组件的使用、状态管理机制、数据模型设计等核心技术，为后续开发更复杂的 HarmonyOS 应用打下坚实基础。

---

技术架构

1. 架构设计理念

云笔记采用分层架构设计，将数据模型、业务逻辑与视图展示分离，实现高内聚低耦合的代码结构：

• 数据层（Model）：负责笔记数据的定义、创建与排序操作。数据层独立于 UI 层，便于数据的持久化和复用。
• 视图层（View）：基于 ArkUI 组件构建用户界面，负责数据的展示和用户交互。视图层通过状态变量响应数据变化，实现数据驱动的视图更新。
• 状态管理层（ViewModel）：通过 @State 装饰器管理组件状态，作为视图层与数据层之间的桥梁，处理业务逻辑和状态转换。

这种分层架构的优势在于：

1. 模块化：每个层职责明确，便于单独开发和测试
2. 可维护性：代码结构清晰，修改某一层不会影响其他层
3. 可扩展性：可以方便地添加新功能或替换现有实现

2. 项目目录结构

ArkTSNote/
├── AppScope/                    # 应用全局配置
│   ├── resources/               # 全局资源文件
│   │   ├── base/
│   │   │   ├── element/         # 基础元素定义
│   │   │   │   └── string.json  # 字符串资源
│   │   │   └── media/           # 媒体资源
│   │   │       ├── background.png
│   │   │       ├── foreground.png
│   │   │       └── layered_image.json
│   │   └── dark/                # 深色主题资源
│   └── app.json5                # 应用配置文件
│
├── entry/                       # 主模块（Entry Module）
│   ├── src/main/
│   │   ├── ets/                 # ArkTS 代码目录
│   │   │   ├── entryability/    # 应用入口能力
│   │   │   │   └── EntryAbility.ets
│   │   │   ├── entrybackupability/  # 备份能力
│   │   │   │   └── EntryBackupAbility.ets
│   │   │   ├── model/           # 数据模型层
│   │   │   │   └── Note.ets     # 笔记数据定义与工具函数
│   │   │   └── pages/           # 页面组件
│   │   │       └── Index.ets    # 主页面（笔记列表）
│   │   └── resources/           # 模块资源文件
│   │       ├── base/
│   │       │   ├── element/
│   │       │   │   ├── color.json
│   │       │   │   ├── float.json
│   │       │   │   └── string.json
│   │       │   ├── media/
│   │       │   │   ├── background.png
│   │       │   │   ├── foreground.png
│   │       │   │   ├── layered_image.json
│   │       │   │   └── startIcon.png
│   │       │   └── profile/
│   │       │       ├── backup_config.json
│   │       │       └── main_pages.json
│   │       └── dark/
│   │           └── element/
│   │               └── color.json
│   ├── .gitignore
│   ├── build-profile.json5      # 模块构建配置
│   ├── hvigorfile.ts            # 模块构建脚本
│   ├── obfuscation-rules.txt    # 混淆规则
│   └── oh-package.json5         # 模块依赖配置
│
├── hvigor/                      # Hvigor 构建工具配置
│   └── hvigor-config.json5
├── .gitignore
├── build-profile.json5          # 项目构建配置
├── code-linter.json5            # 代码检查配置
├── hvigorfile.ts                # 项目构建脚本
├── local.properties             # 本地配置
├── oh-package-lock.json5        # 依赖锁定文件
└── oh-package.json5             # 项目依赖配置

3. 核心技术栈

技术领域	技术选型	说明
编程语言	ArkTS	HarmonyOS 官方声明式语言，兼容 TypeScript 语法
UI 框架	ArkUI	基于声明式范式的 UI 框架，提供丰富的组件库
状态管理	@State	组件内部状态管理装饰器，实现响应式数据绑定
构建工具	Hvigor	HarmonyOS 工程构建工具，支持多模块构建
数据存储	内存存储	本项目采用内存存储方案，便于快速开发和测试
设备类型	Phone	针对手机设备优化的界面布局和交互设计

4. ArkTS 语言特性

ArkTS 是 HarmonyOS 生态的核心编程语言，具有以下特点：

• 声明式语法：采用类似 SwiftUI 和 Flutter 的声明式 UI 写法，代码更简洁
• TypeScript 兼容：支持 TypeScript 类型系统，提供更好的代码提示和错误检查
• 组件化开发：基于组件的开发模式，便于代码复用和维护
• 响应式状态：通过装饰器实现状态与视图的自动同步
• 高性能渲染：底层基于 ArkUI 渲染引擎，提供流畅的用户体验

---

数据模型设计

1. Note 接口定义

[Note.ets](file:///d:/Code/Learn/ArkTS/21DayHarmonyOSTraining/ArkTSNote/entry/src/main/ets/model/Note.ets) 文件定义了笔记的数据结构：

export interface Note {
  id: number;
  title: string;
  content: string;
  timestamp: number;
}

字段说明：

• id: 笔记唯一标识，采用自增整数生成。ID 用于列表渲染时的 key 标识，确保列表更新时的高效 diff 算法。
• title: 笔记标题，用于快速识别笔记内容。标题是笔记的核心信息，通常显示在列表的显眼位置。
• content: 笔记正文内容，支持多行文本。内容字段存储笔记的详细信息，可以是学习笔记、会议记录、生活随笔等。
• timestamp: 创建时间戳，用于按时间排序。时间戳采用毫秒级精度，确保排序的准确性。

2. 工具函数实现

createNote 函数

let nextId = 1;

export function createNote(title: string, content: string): Note {
  return {
    id: nextId++,
    title,
    content,
    timestamp: Date.now()
  };
}

该函数负责创建新笔记对象，主要特点：

• 自动 ID 生成：使用闭包维护 nextId 变量，每次调用生成递增的 ID 值
• 时间戳记录：自动记录笔记创建时间，便于后续排序和展示
• 参数简化：只需传入标题和内容，其他字段自动生成

闭包的使用确保了 nextId 变量的私有性，避免外部代码直接修改 ID 值，保证 ID 的唯一性和连续性。

sortByTimeDesc 函数

export function sortByTimeDesc(notes: Note[]): Note[] {
  return [...notes].sort((a, b) => b.timestamp - a.timestamp);
}

该函数按时间戳降序排列笔记数组，主要特点：

• 副本创建：使用展开运算符创建数组副本，避免修改原始数据
• 降序排序：最新创建的笔记排在最前面，符合用户查看习惯
• 纯函数设计：输入相同的数组，始终返回相同的排序结果

3. 数据模型设计原则

数据模型设计遵循以下原则：

1. 简洁性：只定义必要的字段，避免冗余数据
2. 可扩展性：接口设计预留扩展空间，便于后续添加新字段
3. 类型安全：使用 TypeScript 接口定义，提供类型检查
4. 不可变性：工具函数返回新对象/数组，不修改原始数据

---

主页面实现

1. 组件状态管理

[Index.ets](file:///d:/Code/Learn/ArkTS/21DayHarmonyOSTraining/ArkTSNote/entry/src/main/ets/pages/Index.ets) 页面使用 @State 装饰器管理多个状态变量：

@State notes: Note[] = [];
@State isGrid: boolean = true;
@State showInput: boolean = false;
@State inputTitle: string = '';
@State inputContent: string = '';

状态说明：

状态变量	类型	作用	默认值
notes	Note[]	笔记列表数据，用于渲染 Grid 和 List	[]
isGrid	boolean	视图模式切换标志，true 为网格视图	true
showInput	boolean	新建笔记面板显示状态，true 显示面板	false
inputTitle	string	新建笔记标题输入值	‘’
inputContent	string	新建笔记内容输入值	‘’

状态分类：

• 数据状态：notes 存储笔记列表数据，是页面的核心数据状态
• UI 状态：isGrid 和 showInput 控制界面的显示模式
• 输入状态：inputTitle 和 inputContent 保存用户输入内容

2. 生命周期方法

aboutToAppear(): void {
  this.notes = sortByTimeDesc(this.allNotes);
}

aboutToAppear 生命周期钩子在组件即将显示时触发，主要作用：

• 数据初始化：将预置的笔记数据按时间排序后赋值给 notes 状态
• 性能优化：在组件显示前完成数据准备，避免显示时的卡顿

3. 工具方法

formatTime 方法

formatTime(timestamp: number): string {
  const date = new Date(timestamp);
  const month = date.getMonth() + 1;
  const day = date.getDate();
  const hour = date.getHours().toString().padStart(2, '0');
  const minute = date.getMinutes().toString().padStart(2, '0');
  return `${month}/${day} ${hour}:${minute}`;
}

该方法将时间戳转换为可读的日期时间字符串，格式为 MM/DD HH:mm：

• 月份处理：getMonth() 返回 0-11，需要加 1
• 补零处理：小时和分钟使用 padStart(2, '0') 确保两位数格式
• 国际化考虑：当前采用中文日期格式，可扩展支持多语言

addNote 方法

addNote(): void {
  if (this.inputTitle.length > 0) {
    const note = createNote(this.inputTitle, this.inputContent);
    this.notes = [note, ...sortByTimeDesc(this.notes)];
    this.inputTitle = '';
    this.inputContent = '';
    this.showInput = false;
  }
}

该方法创建新笔记并更新状态：

• 输入验证：检查标题是否为空，避免创建无效笔记
• 状态更新：将新笔记添加到列表顶部，并重新排序
• 状态重置：清空输入框内容并关闭面板

---

UI 组件详解

1. 顶部导航栏

顶部导航栏采用 Row 组件实现水平布局：

Row() {
  Text('我的笔记')
    .fontSize(22)
    .fontWeight(FontWeight.Bold)
    .fontColor('#333333')
  Blank()
  Text(this.isGrid ? '≡ 列表' : '⊞ 网格')
    .fontSize(13)
    .fontColor('#4A90D9')
    .onClick(() => {
      this.isGrid = !this.isGrid;
    })
  Button('+')
    .fontSize(20)
    .fontColor('#FFFFFF')
    .width(36)
    .height(36)
    .borderRadius(18)
    .backgroundColor('#4A90D9')
    .margin({ left: 12 })
    .onClick(() => {
      this.showInput = true;
    })
}

组件布局：

• 左侧显示应用标题「我的笔记」，使用加粗字体和较大字号
• 中间使用 Blank 填充空白区域，将右侧按钮推到最右边
• 右侧包含视图切换按钮和新建笔记按钮

视图切换按钮：

• 根据当前视图模式显示不同的图标和文字
• 网格模式时显示「≡ 列表」，点击切换到列表模式
• 列表模式时显示「⊞ 网格」，点击切换到网格模式

新建笔记按钮：

• 使用圆形设计，蓝色背景配合白色加号
• 点击后设置 showInput = true，显示新建笔记面板

2. Grid 网格视图

网格视图采用 Grid 组件实现两列布局：

Grid() {
  ForEach(this.notes, (note: Note) => {
    GridItem() {
      Column() {
        Text(note.title)
          .fontSize(16)
          .fontWeight(FontWeight.Bold)
          .fontColor('#333333')
          .maxLines(1)
          .textOverflow({ overflow: TextOverflow.Ellipsis })
        Text(note.content)
          .fontSize(13)
          .fontColor('#666666')
          .maxLines(3)
          .textOverflow({ overflow: TextOverflow.Ellipsis })
          .margin({ top: 6 })
        Text(this.formatTime(note.timestamp))
          .fontSize(11)
          .fontColor('#999999')
          .margin({ top: 8 })
      }
      .backgroundColor('#FFFFFF')
      .borderRadius(12)
      .padding(12)
    }
    .height(120)
  }, (note: Note) => note.id.toString())
}
.columnsTemplate('1fr 1fr')
.columnsGap(10)
.rowsGap(10)

Grid 布局配置：

属性	值	说明
columnsTemplate	‘1fr 1fr’	两列等宽布局，每列占据一半可用空间
columnsGap	10	列间距为 10vp，保证卡片之间的间距
rowsGap	10	行间距为 10vp，保证行之间的间距
GridItem.height	120	每个网格项固定高度为 120vp

笔记卡片样式：

• 白色背景配合圆角边框（12vp）
• 标题使用加粗字体（16vp），最多显示一行，超出部分用省略号表示
• 内容使用常规字体（13vp），最多显示三行，超出部分用省略号表示
• 时间戳使用灰色小号字体（11vp）显示在底部

ForEach 渲染优化：

ForEach(this.notes, (note: Note) => {
  // 渲染内容
}, (note: Note) => note.id.toString())

第三个参数是 key 生成器函数，返回 note.id.toString() 作为每个列表项的唯一标识。这有助于：

• 提高列表更新性能
• 避免不必要的组件重建
• 确保动画效果的正确性

3. List 列表视图

列表视图采用 List 组件实现垂直滚动列表：

List({ space: 8 }) {
  ForEach(this.notes, (note: Note) => {
    ListItem() {
      Row() {
        Column() {
          Row() {
            Text(note.title)
              .fontSize(16)
              .fontWeight(FontWeight.Bold)
              .fontColor('#333333')
              .layoutWeight(1)
            Text(this.formatTime(note.timestamp))
              .fontSize(11)
              .fontColor('#999999')
          }
          Text(note.content)
            .fontSize(13)
            .fontColor('#666666')
            .maxLines(2)
            .textOverflow({ overflow: TextOverflow.Ellipsis })
            .margin({ top: 6 })
        }
        .layoutWeight(1)
      }
      .backgroundColor('#FFFFFF')
      .borderRadius(10)
      .padding(14)
    }
  }, (note: Note) => note.id.toString())
}

列表视图特点：

• 列表项之间间距为 8vp
• 每个列表项采用圆角卡片样式（圆角 10vp）
• 标题与时间戳在同一行，标题使用 layoutWeight(1) 占据剩余空间
• 内容区域最多显示两行，超出部分用省略号表示

布局层次：

ListItem
  └── Row（水平布局）
      └── Column（垂直布局，layoutWeight=1）
          ├── Row（标题行）
          │   ├── Text（标题，layoutWeight=1）
          │   └── Text（时间戳）
          └── Text（内容）

4. 新建笔记面板

新建笔记面板采用 Stack 布局实现浮层效果：

if (this.showInput) {
  Column() {
    Column()
      .width('100%')
      .layoutWeight(1)
      .backgroundColor('rgba(0,0,0,0.4)')
      .onClick(() => {
        this.showInput = false;
      })

    Column() {
      Text('新建笔记')
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor('#333333')
        .margin({ bottom: 16 })

      TextInput({ placeholder: '标题', text: this.inputTitle })
        .width('100%')
        .height(44)
        .fontSize(15)
        .borderRadius(8)
        .backgroundColor('#F5F5F5')
        .onChange((value: string) => {
          this.inputTitle = value;
        })

      TextInput({ placeholder: '内容', text: this.inputContent })
        .width('100%')
        .height(100)
        .fontSize(15)
        .borderRadius(8)
        .backgroundColor('#F5F5F5')
        .margin({ top: 12 })
        .onChange((value: string) => {
          this.inputContent = value;
        })

      Row({ space: 12 }) {
        Button('取消')
          .layoutWeight(1)
          .height(44)
          .fontSize(16)
          .fontColor('#666666')
          .backgroundColor('#E0E0E0')
          .borderRadius(10)
          .onClick(() => {
            this.showInput = false;
          })
        Button('保存')
          .layoutWeight(1)
          .height(44)
          .fontSize(16)
          .fontColor('#FFFFFF')
          .backgroundColor('#4A90D9')
          .borderRadius(10)
          .onClick(() => {
            this.addNote();
          })
      }
      .width('100%')
      .margin({ top: 20 })
    }
    .width('100%')
    .padding(20)
    .backgroundColor('#FFFFFF')
    .borderRadius({ topLeft: 16, topRight: 16 })
  }
  .width('100%')
  .height('100%')
}

面板结构：

• 上层为半透明遮罩（透明度 40%），点击遮罩可关闭面板
• 下层为白色输入面板，从底部弹出，顶部有圆角（16vp）
• 面板包含标题输入框、内容输入框和操作按钮

输入框设计：

• 标题输入框高度为 44vp，适合单行输入
• 内容输入框高度为 100vp，适合多行输入
• 输入框背景色为浅灰色（#F5F5F5），边框圆角为 8vp
• onChange 回调实时更新状态变量

按钮设计：

• 取消按钮为灰色背景（#E0E0E0），文字为深灰色
• 保存按钮为蓝色背景（#4A90D9），文字为白色
• 两个按钮宽度相同，使用 layoutWeight(1) 平分可用空间

---

State 管理机制

1. @State 装饰器原理

@State 是 ArkUI 中最基础的状态管理装饰器，用于管理组件内部状态：

• 响应式更新：当 @State 装饰的变量值发生变化时，框架自动触发组件重新渲染
• 单向数据流：状态变化从父组件流向子组件，子组件不能直接修改父组件状态
• 局部作用域：@State 变量仅在当前组件及其子组件中生效

2. 状态更新流程

在云笔记应用中，状态更新遵循以下流程：

1. 用户点击新建笔记按钮 → showInput 变为 true → 触发面板显示
2. 用户输入标题/内容 → inputTitle/inputContent 更新 → 输入框同步显示
3. 用户点击保存 → 创建新笔记 → notes 数组更新 → 列表/网格重新渲染
4. 用户切换视图 → isGrid 状态切换 → 视图模式切换

3. 状态更新机制

ArkUI 的状态更新机制基于观察者模式：

• 当 @State 变量被修改时，框架自动通知所有依赖该变量的组件
• 组件收到通知后，重新执行 build() 方法，生成新的 UI 结构
• 框架对比新旧 UI 结构，只更新变化的部分

这种机制确保了：

• 高效更新：只更新变化的部分，避免全量渲染
• 数据一致性：状态变化自动反映到视图
• 简化代码：开发者只需关注状态变化，无需手动更新 UI

4. ForEach 渲染优化

使用 ForEach 渲染列表时，传入 key 生成器函数：

ForEach(this.notes, (note: Note) => {
  // 渲染内容
}, (note: Note) => note.id.toString())

key 生成器的作用：

• 唯一标识：为每个列表项提供唯一的 key 值
• 高效 diff：列表更新时，通过 key 值快速定位变化的项
• 性能优化：避免不必要的组件销毁和重建

5. 状态管理最佳实践

• 状态最小化：只声明必要的状态变量，避免冗余状态
• 状态分组：将相关状态组织在一起，便于管理
• 不可变更新：对于数组和对象，使用展开运算符创建新值
• 避免嵌套状态：尽量使用扁平的状态结构，便于维护

---

构建与运行

1. 环境要求

环境	版本要求	说明
DevEco Studio	4.0+	HarmonyOS 官方 IDE，提供完整的开发工具链
Node.js	18.20.1+	构建工具依赖，建议使用 LTS 版本
HarmonyOS SDK	API 9+	应用运行所需的 SDK，包含 ArkTS 编译器
Hvigor	3.0+	HarmonyOS 工程构建工具，已集成在 DevEco Studio 中

2. 环境配置步骤

步骤一：安装 DevEco Studio

1. 访问 HarmonyOS 开发者官网
2. 下载最新版本的 DevEco Studio
3. 运行安装程序，按照向导完成安装

步骤二：配置 SDK

1. 打开 DevEco Studio
2. 进入 Settings → Appearance & Behavior → System Settings → HarmonyOS SDK
3. 下载并安装所需的 SDK 版本（建议选择 API 9 及以上）

步骤三：配置 Node.js

1. 安装 Node.js 18.20.1 或更高版本
2. 配置环境变量，确保 node 和 npm 命令可用
3. 验证安装：运行 node --version 和 npm --version

3. 构建命令

# 进入项目目录
cd ArkTSNote

# 执行构建（生成 HAP 包）
./hvigorw assembleHap

# 构建并运行到设备
./hvigorw run

# 清理构建缓存
./hvigorw clean

# 执行代码检查
./hvigorw lint

4. 运行方式

在 DevEco Studio 中运行

1. 打开项目目录
2. 连接设备或启动模拟器：
   • 点击工具栏中的设备选择下拉框
   • 选择已连接的设备或启动新的模拟器
3. 点击「Run」按钮（快捷键 Shift+F10）
4. 应用将自动安装并启动

使用命令行运行

# 构建并运行
./hvigorw run

# 指定设备运行
./hvigorw run --device <device-id>

5. 常见问题排查

构建失败

• 检查 Node.js 版本是否符合要求
• 检查 SDK 路径是否正确配置
• 查看构建日志，定位错误原因

应用无法启动

• 检查设备是否正确连接
• 检查应用权限配置是否正确
• 查看设备日志，定位启动失败原因

---

开发最佳实践

1. 组件设计原则

• 单一职责：每个组件只负责一个功能，避免组件过于复杂
• 可复用性：提取通用逻辑为工具函数或独立组件
• 状态最小化：只声明必要的状态变量，避免状态冗余
• 接口清晰：组件接口设计简洁，便于外部调用

2. 性能优化建议

• 使用 layoutWeight：替代固定尺寸，实现响应式布局，适应不同屏幕尺寸
• 为 ForEach 提供 key：提升列表更新性能，避免不必要的组件重建
• 避免在构建函数中创建对象：每次构建都会创建新对象，影响性能
• 使用懒加载：对于大量数据，使用 List 的懒加载特性

3. 代码风格规范

• 类型注解：使用 TypeScript 类型注解，提高代码可读性和安全性
• 链式调用：组件属性采用链式调用，保持代码整洁
• 缩进一致：使用 2 或 4 个空格作为缩进，保持代码风格统一
• 注释规范：为关键代码添加注释，解释代码逻辑

4. 错误处理策略

• 输入验证：保存前检查标题是否为空，避免创建无效数据
• 状态重置：操作完成后清空相关状态，保持状态一致性
• 用户反馈：通过视觉变化或提示信息提供操作反馈
• 异常捕获：对于可能出错的操作，添加异常捕获机制

5. 代码组织建议

• 模块化：按功能模块组织代码，便于查找和维护
• 文件命名：使用清晰的文件命名，反映文件内容
• 目录结构：合理规划目录结构，区分不同类型的代码
• 代码复用：提取通用代码为工具函数或组件，避免重复代码

---

功能扩展建议

1. 数据持久化

当前版本使用内存存储，应用重启后数据会丢失。建议扩展为本地数据库存储：

// 使用 @ohos.data.preferences 存储笔记
import preferences from '@ohos.data.preferences';
import { getContext } from '@ohos.ability.featureAbility';

async function saveNotes(notes: Note[]): Promise<void> {
  const preferencesManager = preferences.getPreferencesSync(getContext(), 'notes');
  preferencesManager.putSync('notes_data', JSON.stringify(notes));
  await preferencesManager.flush();
}

async function loadNotes(): Promise<Note[]> {
  const preferencesManager = preferences.getPreferencesSync(getContext(), 'notes');
  const data = preferencesManager.getSync('notes_data', '[]');
  return JSON.parse(data);
}

实现步骤：

1. 在 aboutToAppear 中加载保存的笔记
2. 在 addNote 中保存笔记到本地
3. 添加笔记删除功能时同步保存

2. 笔记编辑功能

增加笔记详情页，支持编辑已有笔记：

// 添加编辑功能
editNote(id: number, title: string, content: string): void {
  const index = this.notes.findIndex(note => note.id === id);
  if (index !== -1) {
    this.notes[index] = {
      ...this.notes[index],
      title,
      content,
      timestamp: Date.now()
    };
    this.notes = [...this.notes];
  }
}

实现步骤：

1. 创建笔记详情页面
2. 添加笔记点击事件，跳转到详情页
3. 在详情页实现编辑和保存功能

3. 笔记删除功能

增加删除按钮和确认对话框：

// 添加删除功能
deleteNote(id: number): void {
  this.notes = this.notes.filter(note => note.id !== id);
}

实现步骤：

1. 在笔记卡片上添加删除按钮
2. 点击删除按钮时弹出确认对话框
3. 用户确认后删除笔记

4. 搜索功能

实现笔记标题和内容的模糊搜索：

// 搜索功能
@State searchKeyword: string = '';

get filteredNotes(): Note[] {
  if (!this.searchKeyword) {
    return this.notes;
  }
  const keyword = this.searchKeyword.toLowerCase();
  return this.notes.filter(note => 
    note.title.toLowerCase().includes(keyword) || 
    note.content.toLowerCase().includes(keyword)
  );
}

实现步骤：

1. 在顶部导航栏添加搜索输入框
2. 实现搜索过滤逻辑
3. 使用过滤后的列表渲染视图

5. 主题切换

支持深色/浅色主题切换：

// 主题状态
@State isDarkMode: boolean = false;

// 根据主题设置颜色
backgroundColor(this.isDarkMode ? '#1A1A1A' : '#F5F5F5')
fontColor(this.isDarkMode ? '#FFFFFF' : '#333333')

实现步骤：

1. 添加主题切换按钮
2. 实现主题状态管理
3. 根据主题状态动态设置颜色

6. 笔记分类

支持按分类管理笔记：

// 扩展笔记接口
export interface Note {
  id: number;
  title: string;
  content: string;
  timestamp: number;
  category: string; // 新增分类字段
}

// 分类列表
@State categories: string[] = ['全部', '学习', '工作', '生活'];
@State selectedCategory: string = '全部';

// 按分类过滤
get categorizedNotes(): Note[] {
  if (this.selectedCategory === '全部') {
    return this.notes;
  }
  return this.notes.filter(note => note.category === this.selectedCategory);
}

7. 分享功能

支持将笔记分享给其他应用：

// 分享功能
import { share } from '@ohos.data.share';

async function shareNote(note: Note): Promise<void> {
  const shareInfo = {
    title: note.title,
    content: note.content,
    type: 'text/plain'
  };
  await share.share(getContext(), shareInfo);
}

---

技术深度分析

1. ArkTS 与 TypeScript 的关系

ArkTS 是 HarmonyOS 推出的声明式 UI 语言，与 TypeScript 有以下关系：

• 语法兼容：ArkTS 兼容 TypeScript 语法，TypeScript 代码可以直接在 ArkTS 中运行
• 扩展特性：ArkTS 增加了声明式 UI 语法和状态管理装饰器
• 编译优化：ArkTS 编译器针对 HarmonyOS 平台进行了优化

2. ArkUI 组件模型

ArkUI 组件模型基于以下核心概念：

• 组件：UI 元素的抽象，如 Text、Button、Row、Column 等
• 属性：组件的配置项，如 fontSize、backgroundColor 等
• 事件：用户交互的响应，如 onClick、onChange 等
• 状态：组件内部的数据，通过装饰器管理

3. 响应式状态管理原理

ArkUI 的响应式状态管理基于以下机制：

• 装饰器：@State、@Prop、@Link 等装饰器标记状态变量
• 观察者模式：状态变量变化时通知所有依赖的组件
• Diff 算法：对比新旧 UI 结构，只更新变化的部分

4. 布局系统

ArkUI 提供了丰富的布局组件：

• Row：水平布局，子组件从左到右排列
• Column：垂直布局，子组件从上到下排列
• Stack：层叠布局，子组件按顺序层叠显示
• Grid：网格布局，支持多行多列排列
• List：列表布局，支持滚动和懒加载

5. 渲染性能优化

ArkUI 通过以下方式优化渲染性能：

• 虚拟列表：List 组件支持虚拟滚动，只渲染可见的列表项
• Diff 算法：对比新旧 UI 结构，只更新变化的部分
• 状态隔离：状态变化只影响相关组件，不触发全局重渲染

---

项目总结

云笔记应用展示了 ArkTS 语言在构建 HarmonyOS 应用方面的核心能力：

1. 声明式 UI：通过 ArkUI 组件实现简洁高效的界面开发，代码更简洁、易读
2. 响应式状态：@State 装饰器实现数据驱动的视图更新，状态变化自动反映到视图
3. 组件化架构：模块化设计提高代码可维护性，便于功能扩展和代码复用
4. 跨设备兼容：支持多种 HarmonyOS 设备运行，界面自动适应不同屏幕尺寸

本项目可作为 ArkTS 初学者的入门参考，也为更复杂的笔记应用开发奠定了基础。通过扩展数据持久化、编辑删除、搜索过滤等功能，可以构建功能完善的专业笔记管理应用。

---

附录

1. 快捷键参考

快捷键	功能
Shift+F10	运行应用
Ctrl+F10	应用更改
Ctrl+S	保存文件
Ctrl+D	复制行
Ctrl+X	剪切行
Ctrl+Z	撤销
Ctrl+Shift+Z	重做

2. 常用命令

# 构建 HAP 包
./hvigorw assembleHap

# 运行应用
./hvigorw run

# 清理缓存
./hvigorw clean

# 代码检查
./hvigorw lint

# 查看依赖
./hvigorw dependencies

3. 资源文件说明

文件路径	说明
resources/base/element/color.json	颜色资源定义
resources/base/element/float.json	浮点数资源定义
resources/base/element/string.json	字符串资源定义
resources/base/media/	媒体资源文件

4. 配置文件说明

文件路径	说明
app.json5	应用全局配置
module.json5	模块配置
build-profile.json5	构建配置
oh-package.json5	依赖配置

---

本文档基于 HarmonyOS ArkTS 开发实践编写，仅供学习参考。