# set-wallpaper

**Repository Path**: zestbox/set-wallpaper

## Basic Information

- **Project Name**: set-wallpaper
- **Description**: 鸿蒙开发Arkts 实现简单的壁纸手势的demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-29
- **Last Updated**: 2025-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎨 鸿蒙壁纸设置应用

一个基于 HarmonyOS ArkTS 开发的交互式壁纸设置应用，支持静态图片和动图壁纸选择、手势控制和实时预览。

## 📱 应用信息

- **应用名称**: 壁纸设置器
- **Bundle ID**: com.zestbox.wallpaper
- **版本**: 1.0.0 (1000000)
- **开发框架**: HarmonyOS ArkTS
- **最低API版本**: API 12

## ✨ 功能特性

### 🖼️ 静态壁纸管理
- **默认壁纸**: 内置 `test1.png` 作为默认静态背景
- **相册选择**: 支持从系统相册选择自定义静态图片
- **格式支持**: 支持常见静态图片格式 (PNG, JPG, JPEG 等)
- **自动重置**: 选择新图片时自动重置所有变换参数

### 🎬 动图壁纸功能 (新增)
- **动图选择**: 支持从相册选择动态照片 (Live Photo)
- **自动播放**: 动图加载后自动开始播放
- **循环播放**: 支持无限循环播放动图
- **播放控制**: 支持播放/暂停切换
- **静音控制**: 支持音频开关
- **手势控制**: 支持拖拽和缩放调整动图位置和大小

### 🎮 手势控制
- **单指拖拽**: 移动壁纸位置，支持任意方向
- **双指缩放**: 以手指中心为基准进行缩放
- **缩放范围**: 0.5x - 3.0x 倍数限制
- **流畅交互**: 无跳跃，连续性操作体验

### 🔧 编辑模式
- **模式切换**: 编辑/完成模式一键切换
- **实时调试**: 显示当前缩放比例和偏移量
- **操作提示**: 内置使用说明指导
- **重置功能**: 一键恢复默认状态

### 🎯 显示优化
- **比例保持**: 自动保持图片原始宽高比
- **完整显示**: 确保图片内容不被裁切
- **自适应**: 支持各种屏幕尺寸和图片比例

## 🏗️ 技术架构

### 核心组件结构
```
Stack (容器)
├── Column (背景层) - backgroundImage 显示
├── Column (手势+UI层) - 透明覆盖层
│   ├── 调试信息显示
│   ├── 功能按钮组
│   └── 手势识别区域
└── Button (编辑切换) - 固定定位
```

### 状态管理
```typescript
// 编辑状态
@State isEditMode: boolean = false

// 图片变换参数
@State imageScale: number = 1.0
@State imageOffsetX: number = 0
@State imageOffsetY: number = 0

// 手势状态缓存
@State lastPanOffsetX: number = 0
@State lastPanOffsetY: number = 0
@State lastScale: number = 1.0

// 图片资源
@State selectedImageUri: string = ''
```

### 关键技术实现

#### 1. 图片显示策略
```typescript
.backgroundImage(this.selectedImageUri ? this.selectedImageUri : $r('app.media.test1'))
.backgroundImageSize({
  width: `${100 * this.imageScale}%`,
  height: 'auto'  // 关键：保持比例
})
.backgroundImagePosition({
  x: this.imageOffsetX,
  y: this.imageOffsetY
})
```

**设计原理**:
- `width` 控制缩放大小
- `height: 'auto'` 自动计算高度，保持原始宽高比
- 避免使用 `scale` 属性，防止缩放中心点错误

#### 2. 手势处理算法

**拖拽手势**:
```typescript
.onActionStart() => {
  // 保存当前偏移作为拖拽起点
  this.lastPanOffsetX = this.imageOffsetX
  this.lastPanOffsetY = this.imageOffsetY
}
.onActionUpdate() => {
  // 基于起点计算新位置
  this.imageOffsetX = this.lastPanOffsetX + event.offsetX
  this.imageOffsetY = this.lastPanOffsetY + event.offsetY
}
```

**缩放手势**:
```typescript
.onActionUpdate() => {
  const newScale = this.lastScale * event.scale
  // 计算以手指中心为基准的偏移调整
  const scaleDiff = newScale - this.imageScale
  this.imageOffsetX = this.imageOffsetX - (centerX - this.imageOffsetX) * (scaleDiff / this.imageScale)
  this.imageOffsetY = this.imageOffsetY - (centerY - this.imageOffsetY) * (scaleDiff / this.imageScale)
}
```

#### 3. 图片选择机制
```typescript
async selectImageFromGallery() {
  const photoSelectOptions = new picker.PhotoSelectOptions()
  photoSelectOptions.MIMEType = picker.PhotoViewMIMETypes.IMAGE_TYPE
  photoSelectOptions.maxSelectNumber = 1
  
  const photoPicker = new picker.PhotoViewPicker()
  const result = await photoPicker.select(photoSelectOptions)
  // 选择成功后重置所有变换参数
}
```

## 🚀 使用方法

### 静态壁纸操作
1. **启动应用** - 显示默认壁纸
2. **进入编辑** - 点击右下角"编辑"按钮
3. **选择图片** - 点击"选择图片"从相册选择
4. **调整位置** - 单指拖拽移动图片
5. **调整大小** - 双指捏合缩放图片
6. **重置状态** - 点击"重置"恢复默认
7. **完成编辑** - 点击"完成"退出编辑模式

### 动图壁纸操作 (新增)
1. **进入动图模式** - 在主页编辑模式下点击"动图壁纸"按钮
2. **选择动图** - 点击"选择动图"从相册选择动态照片
3. **自动播放** - 动图加载后会自动开始循环播放
4. **播放控制** - 使用"播放/暂停"按钮控制播放状态
5. **音频控制** - 使用"静音/取消静音"按钮控制音频
6. **调整动图** - 单指拖拽移动，双指缩放调整大小
7. **重置位置** - 点击"重置位置"恢复默认状态
8. **返回主页** - 点击"返回主页"回到静态壁纸页面

### 高级技巧
- **精确定位**: 利用调试信息查看具体数值
- **比例控制**: 缩放时注意保持合适的显示比例
- **中心缩放**: 将手指放在希望保持不动的位置进行缩放
- **动图优化**: 动图会自动循环播放，适合作为动态壁纸使用

## 📁 项目结构

```
set_wallpaper/
├── AppScope/                    # 应用全局配置
│   ├── app.json5               # 应用基本信息
│   └── resources/              # 全局资源
├── entry/                      # 主模块
│   ├── src/main/
│   │   ├── ets/pages/
│   │   │   ├── Index.ets       # 主页面 (静态壁纸)
│   │   │   └── MovingWallpaper.ets # 动图壁纸页面 (新增)
│   │   └── resources/
│   │       ├── base/
│   │       │   ├── media/
│   │       │   │   └── test1.png   # 默认壁纸
│   │       │   ├── element/
│   │       │   │   └── string.json # 字符串资源
│   │       │   └── profile/
│   │       │       └── main_pages.json # 页面路由配置
│   │       └── module.json5    # 模块配置 (包含权限)
│   ├── build-profile.json5     # 构建配置
│   └── oh-package.json5        # 模块依赖
├── oh-package.json5            # 项目依赖
└── README.md                   # 项目说明
```

## 🔧 开发环境

### 必需工具
- **DevEco Studio**: 5.0.3.900 或更高版本
- **HarmonyOS SDK**: API 12 或更高版本
- **Node.js**: 18.x 或更高版本

### 权限说明
- **READ_MEDIA权限**: 访问媒体库选择图片和动图 (动图功能必需)
- **系统级访问**: 使用 `@kit.CoreFileKit` 和 `@kit.MediaLibraryKit`
- **自动授权**: 应用首次运行时会请求相关权限

## 🎨 UI设计

### 视觉层次
1. **背景层** - 壁纸显示 (最底层)
2. **交互层** - 手势捕获 (透明中间层)  
3. **控制层** - 按钮和信息 (最顶层)

### 颜色方案
- **编辑按钮**: 橙色(编辑) / 绿色(完成)
- **功能按钮**: 红色(选择) / 蓝色(重置)
- **信息显示**: 黑色半透明背景 + 白色文字

### 响应式设计
- **自适应布局**: 支持不同屏幕尺寸
- **比例保持**: 图片在任何设备上都保持正确比例
- **触控优化**: 手势识别区域覆盖全屏

## 📄 许可证

本项目仅供学习和研究使用。

## 👥 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

---

**开发者**: ZestBox Team  
**最后更新**: 2025年7月
**技术支持**: [HarmonyOS 官方文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkui-declarative-comp)