# doodlelib

**Repository Path**: kingwild/doodlelib

## Basic Information

- **Project Name**: doodlelib
- **Description**: Harmony OS 涂鸦
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-08
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DoodleLib - HarmonyOS 涂鸦库

[![HarmonyOS](https://img.shields.io/badge/HarmonyOS-6.0.1-blue)](https://www.harmonyos.com/)
[![ArkTS](https://img.shields.io/badge/ArkTS-Latest-orange)](https://developer.harmonyos.com/cn/develop/arkts/)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](LICENSE)

一个基于 HarmonyOS 平台的简易涂鸦库，采用 MVVM(V2) 架构设计，提供图片涂鸦编辑功能。

## ✨ 特性

- 🎨 **多种绘图工具**: 支持箭头、圆形、折线箭头、马赛克、文本等
- 🏗️ **MVVM(V2) 架构**: 采用现代化的 MVVM 架构，代码结构清晰
- 🎯 **响应式状态管理**: 使用 @ObservedV2 + @Trace 实现高效的状态管理
- 🎭 **现代化 UI**: 毛玻璃效果、渐变背景、卡片式布局
- 📱 **HarmonyOS 原生**: 完全基于 HarmonyOS 原生 API 开发
- 🔧 **高度可配置**: 支持单模式、自定义颜色、默认工具等配置
- 🚀 **高性能**: Canvas 优化、按需渲染、内存优化

## 📋 目录

- [快速开始](#快速开始)
- [使用指南](#使用指南)
- [API 文档](#api-文档)
- [架构设计](#架构设计)
- [开发指南](#开发指南)
- [常见问题](#常见问题)
- [更新日志](#更新日志)
- [贡献指南](#贡献指南)
- [许可证](#许可证)

## 🚀 快速开始

### 环境要求

- DevEco Studio 5.0+
- HarmonyOS SDK 6.0.1+ (API Level 21+)
- Node.js 14+

### 安装

1. 在你的 HarmonyOS 项目中添加依赖：

```json5
// oh-package.json5
{
  "dependencies": {
    "@akingyin/doodlelib": "^1.0.0"
  }
}
```

2. 或直接引入本地 HAR 包：

```typescript
import { DoodlePageV2, DOODLE_ROUTE_NAME_V2 } from '@akingyin/doodlelib';
```

### 基础使用

```typescript
import { NavPathStack } from '@kit.ArkUI';
import { DOODLE_ROUTE_NAME_V2, DoodleParam, DoodleResultEvent, RESULT_OK } from '@akingyin/doodlelib';

@Entry
@Component
struct IndexPage {
  @Provide('pageStack') pageStack: NavPathStack = new NavPathStack();

  build() {
    Navigation(this.pageStack) {
      Button('打开涂鸦')
        .onClick(() => {
          // 创建涂鸦参数
          const param = new DoodleParam();
          param.imagePath = '/data/app/el2/100/base/com.example.app/haps/entry/files/image.jpg';
          param.originalPath = param.imagePath;
          
          // 导航到涂鸦页面
          this.pageStack.pushPathByName(DOODLE_ROUTE_NAME_V2, param, (result) => {
            if (result) {
              const event = result as DoodleResultEvent;
              if (event.result === RESULT_OK) {
                console.info('涂鸦保存成功:', event.path);
                // 处理涂鸦结果
              }
            }
          });
        });
    }
  }
}
```

## 📖 使用指南

### DoodleParam 参数配置

```typescript
const param = new DoodleParam();

// 必需参数
param.imagePath = '...';        // 涂鸦图片路径（应用沙箱路径）
param.originalPath = '...';     // 原始图片路径

// 可选参数
param.drawShapeSingleMode = true;              // 单模式：只使用一种绘图工具
param.defaultShape = 'Arrow';                  // 默认绘图形状
param.strokeColor = '#FF0000';                 // 默认画笔颜色
param.strokeWidth = 3;                         // 默认画笔宽度
```

### 绘图工具类型

```typescript
import { DrawingShapeEnum } from '@akingyin/doodlelib';

// 可用的绘图形状
DrawingShapeEnum.Arrow          // 箭头
DrawingShapeEnum.Circle         // 圆形
DrawingShapeEnum.PolylineArrow  // 折线箭头
DrawingShapeEnum.Mosaic         // 马赛克
DrawingShapeEnum.Text           // 文本
DrawingShapeEnum.None           // 无（选择模式）
```

### 接收结果

```typescript
this.pageStack.pushPathByName(DOODLE_ROUTE_NAME_V2, param, (result) => {
  if (result) {
    const event = result as DoodleResultEvent;
    
    switch (event.result) {
      case RESULT_OK:
        // 涂鸦保存成功
        console.info('保存路径:', event.path);
        break;
      case RESULT_CANCEL:
        // 用户取消
        console.info('用户取消涂鸦');
        break;
      default:
        // 其他情况
        break;
    }
  }
});
```

### 设置页面

涂鸦库提供了设置页面，可以配置自动退出等选项：

```typescript
import { SETTINGS_ROUTE_NAME } from '@akingyin/doodlelib';

// 导航到设置页面
this.pageStack.pushPathByName(SETTINGS_ROUTE_NAME, null);
```

## 📚 API 文档

### 导出模块

```typescript
// 页面路由
export { DOODLE_PAGE_PATH, DOODLE_ROUTE_NAME } from './src/main/ets/pages/DoodlePage';
export { DOODLE_PAGE_PATH_V2, DOODLE_ROUTE_NAME_V2 } from './src/main/ets/pages/DoodlePageV2';
export { SETTINGS_ROUTE_NAME } from './src/main/ets/pages/SettingsPage';

// 核心类型
export { DoodleParam, DrawingShape, DrawingShapeKey, DrawingShapeEnum } from './src/main/ets/core/BaseDoodleShape';
export { DoodleResultEvent, RESULT_OK, RESULT_CANCEL } from './src/main/ets/core/DoodleResultEvent';

// 工具函数
export { add } from './src/main/ets/utils/Calc';
```

### DoodleParam

涂鸦参数配置类。

**属性**:

| 属性名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `imagePath` | string | ✅ | - | 涂鸦图片路径（应用沙箱路径） |
| `originalPath` | string | ✅ | - | 原始图片路径 |
| `drawShapeSingleMode` | boolean | ❌ | false | 是否启用单模式 |
| `defaultShape` | DrawingShapeKey | ❌ | 'None' | 默认绘图形状 |
| `strokeColor` | string | ❌ | '#FF0000' | 默认画笔颜色 |
| `strokeWidth` | number | ❌ | 2 | 默认画笔宽度 |

### DoodleResultEvent

涂鸦结果事件。

**属性**:

| 属性名 | 类型 | 说明 |
|--------|------|------|
| `path` | string | 涂鸦后的图片路径 |
| `result` | number | 结果代码 (RESULT_OK 或 RESULT_CANCEL) |

### 常量

```typescript
// 结果代码
export const RESULT_OK = 0;      // 成功
export const RESULT_CANCEL = 1;  // 取消
```

## 🏗️ 架构设计

### MVVM(V2) 架构

```
┌─────────────────────────────────────────┐
│              View Layer                  │
│  - DoodlePageV2 (主页面)                 │
│  - TopToolbarV2 (顶部工具栏)             │
│  - BottomToolbarV2 (底部工具栏)          │
│  - DoodleView (涂鸦画布)                 │
└─────────────────────────────────────────┘
                    ↕
┌─────────────────────────────────────────┐
│           ViewModel Layer                │
│  - DoodleViewModel (@ObservedV2)         │
│    - 状态管理                             │
│    - 业务逻辑                             │
│    - 数据转换                             │
└─────────────────────────────────────────┘
                    ↕
┌─────────────────────────────────────────┐
│            Model Layer                   │
│  - DoodleModel (数据模型)                │
│  - DrawingShape (绘图形状)               │
│  - DoodleParam (参数配置)                │
└─────────────────────────────────────────┘
```

### 核心设计

1. **响应式状态管理**: 使用 `@ObservedV2` 和 `@Trace` 实现高效的状态追踪
2. **单向数据流**: 用户操作 → ViewModel → Model → UI 更新
3. **组件化设计**: 高度组件化，职责清晰
4. **策略模式**: 绘图工具采用策略模式，易于扩展

详细设计文档请参考 [DESIGN.md](docs/DESIGN.md)。

## 🛠️ 开发指南

### 项目结构

```
doodlelib/
├── AppScope/                    # 应用级配置
│   └── app.json5                # 应用配置
├── doodle/                      # 涂鸦库模块 (HAR)
│   ├── src/main/
│   │   ├── ets/
│   │   │   ├── pages/           # 页面
│   │   │   │   ├── DoodlePageV2.ets    # 主页面 V2
│   │   │   │   ├── DoodlePage.ets      # 主页面 V1 (已废弃)
│   │   │   │   └── SettingsPage.ets    # 设置页面
│   │   │   ├── components/      # 组件
│   │   │   │   ├── TopToolbarV2.ets    # 顶部工具栏
│   │   │   │   ├── BottomToolbarV2.ets # 底部工具栏
│   │   │   │   └── DoodleView.ets      # 涂鸦画布
│   │   │   ├── viewmodel/       # ViewModel
│   │   │   │   └── DoodleViewModel.ets
│   │   │   ├── model/           # Model
│   │   │   │   └── DoodleModel.ets
│   │   │   ├── core/            # 核心逻辑
│   │   │   │   ├── BaseDoodleShape.ets  # 基础形状
│   │   │   │   ├── Pen.ets              # 画笔基类
│   │   │   │   ├── LineArrow.ets        # 箭头
│   │   │   │   ├── Circle.ets           # 圆形
│   │   │   │   ├── Mosaic.ets           # 马赛克
│   │   │   │   └── TextDrawing.ets      # 文本
│   │   │   └── utils/           # 工具函数
│   │   │       └── Calc.ets
│   │   └── resources/           # 资源文件
│   ├── Index.ets                # 导出入口
│   └── oh-package.json5         # 包配置
├── entry/                       # 主应用模块
├── build-profile.json5          # 构建配置
└── hvigorfile.ts                # 构建脚本
```

### 本地开发

1. 克隆项目：
```bash
git clone https://github.com/akingyin/doodlelib.git
cd doodlelib
```

2. 打开项目：
```bash
# 使用 DevEco Studio 打开项目
```

3. 运行示例：
```bash
# 选择 entry 模块运行
```

### 添加新的绘图工具

1. 在 `core/` 目录下创建新的绘图工具类：

```typescript
// core/Rectangle.ts
import { Pen } from './Pen';

export class Rectangle extends Pen {
  // 实现绘制逻辑
  draw(context: CanvasRenderingContext2D): void {
    // ...
  }
}
```

2. 在 `BaseDoodleShape.ets` 中注册新工具：

```typescript
export type DrawingShapeKey = "Arrow" | "Circle" | "Rectangle" | ...;

export const DrawingShapeEnum: Record<DrawingShapeKey, DrawingShape> = {
  ...
  "Rectangle": { name: "矩形", code: "Rectangle" },
  ...
};
```

3. 在 `DoodleViewModel` 中添加处理逻辑。

## ❓ 常见问题

### Q: 图片路径应该使用什么格式？

A: 必须使用应用沙箱内的绝对路径，例如：
```typescript
param.imagePath = '/data/app/el2/100/base/com.example.app/haps/entry/files/image.jpg';
```

如果从相册选择图片，需要先将媒体库 URI 转换为沙箱路径。

### Q: 如何处理从相册选择的图片？

A: 需要先将媒体库 URI 转换为应用沙箱路径：

```typescript
import { fileUri } from '@kit.CoreFileKit';

// 转换 URI 为沙箱路径
const realPath = fileUri.getUriFromPath(mediaUri);
// 或使用文件描述符
const file = fs.openSync(mediaUri, fs.OpenMode.READ_ONLY);
```

### Q: 为什么使用 MVVM(V2) 而不是 MVVM(V1)？

A: MVVM(V2) 提供了更好的性能和开发体验：
- 更高效的状态追踪机制
- 更少的模板代码
- 更好的类型推断
- 更符合现代 ArkTS 开发规范

### Q: 如何自定义 UI 样式？

A: 可以通过修改以下文件自定义样式：
- `TopToolbarV2.ets`: 顶部工具栏样式
- `BottomToolbarV2.ets`: 底部工具栏样式
- `resources/`: 资源文件（颜色、字体等）

### Q: 支持哪些设备？

A: 目前支持：
- 📱 手机设备
- 📱 平板设备（计划中）
- 📱 折叠屏设备（计划中）

## 📝 更新日志

### v1.0.0 (2026-06-26)

**新功能**:
- ✨ 初始版本发布
- ✨ 支持箭头、圆形、折线箭头、马赛克、文本绘图工具
- ✨ MVVM(V2) 架构
- ✨ 现代化 UI 设计
- ✨ 设置页面

**优化**:
- 🚀 Canvas 渲染优化
- 🚀 状态管理优化
- 🚀 内存优化

**修复**:
- 🐛 修复 LocalStorage.getShared() 废弃 API
- 🐛 修复导航参数传递问题

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 代码规范

- 遵循 ArkTS 编码规范
- 使用 `@ObservedV2` 和 `@Trace` 进行状态管理
- 添加必要的注释和文档
- 编写单元测试

## 📄 许可证

本项目采用 Apache 2.0 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [HarmonyOS](https://www.harmonyos.com/) - 华为鸿蒙操作系统
- [ArkUI](https://developer.harmonyos.com/cn/develop/arkui/) - HarmonyOS UI 框架
- [DevEco Studio](https://developer.harmonyos.com/cn/develop/deveco-studio/) - HarmonyOS 开发工具

## 📮 联系方式

- 作者: akingyin
- 邮箱: akingyin@163.com
- 项目地址: [https://github.com/akingyin/doodlelib](https://github.com/akingyin/doodlelib)

---

**⭐ 如果这个项目对你有帮助，请给一个 Star！**