# qazll-app-android

**Repository Path**: qazll/qazll-app-android

## Basic Information

- **Project Name**: qazll-app-android
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Qazll App - 简单计数器

一个简单的 Android 计数器应用，使用 Java 语言开发。

## 项目概述

这是一个基础的 Android 应用示例，展示了 Android 开发的基本结构和最佳实践。应用功能包括：
- 显示当前计数
- 点击"增加"按钮增加计数
- 点击"重置"按钮将计数归零
- 支持浅色/深色主题

## 环境要求

- **Android Studio**: Otter 2 Feature Drop | 2025.2.2 或更高版本
- **JDK**: 17
- **Android SDK**: compileSdk 35, minSdk 24, targetSdk 35
- **Gradle**: 8.14
- **Android Gradle Plugin (AGP)**: 8.11.1

## 项目结构

```
qazll-app/
├── .gradle/                    # Gradle 缓存目录（自动生成，无需版本控制）
├── app/                        # 应用模块
│   ├── build/                  # 构建输出目录（自动生成，无需版本控制）
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com/qazll/app/
│   │       │       └── MainActivity.java    # 主活动
│   │       ├── res/
│   │       │   ├── drawable/
│   │       │   │   └── ic_launcher_foreground.xml  # 应用图标前景
│   │       │   ├── layout/
│   │       │   │   └── activity_main.xml   # 主界面布局
│   │       │   ├── mipmap-anydpi-v26/
│   │       │   │   ├── ic_launcher.xml     # 自适应图标（方形）
│   │       │   │   └── ic_launcher_round.xml  # 自适应图标（圆形）
│   │       │   ├── values/
│   │       │   │   ├── colors.xml          # 颜色定义
│   │       │   │   ├── strings.xml         # 字符串资源
│   │       │   │   └── themes.xml          # 浅色主题
│   │       │   └── values-night/
│   │       │       └── themes.xml          # 深色主题
│   │       └── AndroidManifest.xml         # 应用清单文件
│   ├── build.gradle.kts                    # 模块级 Gradle 配置
│   └── proguard-rules.pro                  # ProGuard 混淆规则
├── build/                      # 项目级构建输出（自动生成，无需版本控制）
├── gradle/
│   ├── wrapper/
│   │   └── gradle-wrapper.properties       # Gradle Wrapper 配置
│   └── libs.versions.toml                  # 版本目录（Version Catalog）
├── build.gradle.kts           # 项目级 Gradle 配置
├── gradle.properties          # Gradle 属性配置
├── gradlew.bat                # Windows Gradle Wrapper 脚本
├── settings.gradle.kts        # Gradle 设置文件
└── README.md                  # 项目说明文档（本文件）
```

## 文件详解

### 根目录文件

#### 1. [settings.gradle.kts](file:///C:/development/data/qazll/qazll-app/settings.gradle.kts)
Gradle 项目设置文件，定义项目名称和包含的模块。

- `pluginManagement`: 配置 Gradle 插件的仓库（Google、Maven Central、Gradle Plugin Portal）
- `dependencyResolutionManagement`: 配置依赖解析的仓库
- `rootProject.name`: 项目名称，显示在 Android Studio 中
- `include(":app")`: 包含 app 模块

#### 2. [build.gradle.kts](file:///C:/development/data/qazll/qazll-app/build.gradle.kts)
项目级 Gradle 构建脚本，配置所有模块共享的构建配置。

- `plugins`: 定义可用的 Gradle 插件（Android Application 插件）
- 注意：`apply false` 表示插件不在根项目中应用，只在子模块中选择性应用

#### 3. [gradle.properties](file:///C:/development/data/qazll/qazll-app/gradle.properties)
Gradle 全局属性配置文件。

- `org.gradle.jvmargs`: 设置 Gradle 守护进程的 JVM 参数（堆内存 2GB，UTF-8 编码）
- `android.useAndroidX`: 启用 AndroidX 库（替代旧的 Support Library）
- `android.nonTransitiveRClass`: 启用非传递性 R 类（优化构建性能）

#### 4. [gradlew.bat](file:///C:/development/data/qazll/qazll-app/gradlew.bat)
Windows 平台的 Gradle Wrapper 脚本。

- Gradle Wrapper 允许在没有全局安装 Gradle 的情况下运行 Gradle
- 首次运行时会自动下载配置的 Gradle 版本
- 使用方法：在项目根目录运行 `gradlew.bat <task>`，例如 `gradlew.bat assembleDebug`

### gradle 目录

#### 5. [gradle/libs.versions.toml](file:///C:/development/data/qazll/qazll-app/gradle/libs.versions.toml)
版本目录（Version Catalog）文件，集中管理所有依赖的版本。

**结构说明：**

- `[versions]`: 定义所有依赖的版本号
  - `agp`: Android Gradle Plugin 版本 (8.11.1)
  - `core`: AndroidX Core 库版本
  - `junit`: JUnit 测试框架版本
  - `appcompat`: AppCompat 库版本
  - `material`: Material Design 组件版本
  - 等等...

- `[libraries]`: 定义库依赖的完整坐标
  - 使用 `group`、`name`、`version.ref` 组合
  - `version.ref` 引用 `[versions]` 中定义的版本号

- `[plugins]`: 定义 Gradle 插件
  - `android-application`: Android 应用插件

**使用方式：**
- 在 build.gradle.kts 中通过 `libs.xxx` 引用
- 例如：`implementation(libs.androidx.core)`

**优点：**
- 版本集中管理，修改一处生效
- 避免在多个 build.gradle.kts 文件中重复定义版本
- 支持类型安全的依赖引用

#### 6. [gradle/wrapper/gradle-wrapper.properties](file:///C:/development/data/qazll/qazll-app/gradle/wrapper/gradle-wrapper.properties)
Gradle Wrapper 的配置文件。

- `distributionUrl`: Gradle 发行版的下载地址
- 当前配置：`gradle-8.14-bin.zip`
- `distributionBase/Path`: 下载的 Gradle 存储位置
- `zipStoreBase/Path`: 下载的 zip 文件存储位置

### app 模块文件

#### 7. [app/build.gradle.kts](file:///C:/development/data/qazll/qazll-app/app/build.gradle.kts)
app 模块的 Gradle 构建脚本，定义该模块的构建配置。

**plugins 块：**
- `com.android.application`: Android 应用插件，使该模块成为 Android 应用

**android 块：**
- `namespace`: 应用的包名 (com.qazll.app)
- `compileSdk`: 编译时使用的 Android SDK 版本 (35)

**defaultConfig 块：**
- `applicationId`: 应用的唯一标识符 (com.qazll.app)
- `minSdk`: 最低支持的 Android 版本 (24，即 Android 7.0)
- `targetSdk`: 目标 Android 版本 (35)
- `versionCode`: 内部版本号 (1)
- `versionName`: 显示给用户的版本名 ("1.0")
- `testInstrumentationRunner`: 仪器化测试的运行器

**buildTypes 块：**
- `release`: 发布版本配置
  - `isMinifyEnabled = false`: 禁用代码混淆
  - `proguardFiles`: 指定混淆规则文件

**compileOptions 块：**
- 设置 Java 源代码和目标兼容性为 Java 17

**dependencies 块：**
- `implementation`: 编译期和运行期都需要的依赖
  - `androidx.core`: AndroidX 核心库
  - `androidx.appcompat`: 向后兼容库
  - `google.material`: Material Design 组件
  - `androidx.activity`: Activity 扩展库
  - `androidx.constraintlayout`: 约束布局
  - `androidx.lifecycle-runtime`: 生命周期管理
- `testImplementation`: 仅单元测试需要的依赖 (JUnit)
- `androidTestImplementation`: 仪器化测试需要的依赖

#### 8. [app/proguard-rules.pro](file:///C:/development/data/qazll/qazll-app/app/proguard-rules.pro)
ProGuard 混淆规则文件。

- 当 `minifyEnabled = true` 时使用
- 用于定义哪些类/方法不应该被混淆
- 当前为空，因为应用较简单且禁用了混淆

### AndroidManifest 和源代码

#### 9. [app/src/main/AndroidManifest.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/AndroidManifest.xml)
Android 应用清单文件，描述应用的基本信息。

**根元素 `<manifest>`:**
- 定义 XML 命名空间

**`<application>` 元素:**
- `android:allowBackup`: 允许应用数据备份
- `android:icon`: 应用图标 (@mipmap/ic_launcher)
- `android:label`: 应用名称 (@string/app_name)
- `android:roundIcon`: 圆形应用图标
- `android:supportsRtl`: 支持从右到左布局
- `android:theme`: 应用主题 (@style/Theme.QazllApp)

**`<activity>` 元素:**
- `android:name`: Activity 类名 (.MainActivity)
- `android:exported`: 允许其他应用启动此 Activity
- `<intent-filter>`: 意图过滤器
  - `android.intent.action.MAIN`: 作为应用的入口点
  - `android.intent.category.LAUNCHER`: 在应用启动器中显示

#### 10. [app/src/main/java/com/qazll/app/MainActivity.java](file:///C:/development/data/qazll/qazll-app/app/src/main/java/com/qazll/app/MainActivity.java)
主活动类，应用的入口界面。

**类结构:**
- 继承自 `AppCompatActivity`（带 ActionBar 的 Activity）
- 私有字段 `count`: 存储当前计数值

**onCreate 方法:**
- Activity 创建时调用
- `setContentView(R.layout.activity_main)`: 加载布局文件
- `findViewById`: 通过 ID 查找视图控件
  - `countTextView`: 显示计数的文本视图
  - `incrementButton`: 增加计数的按钮
  - `resetButton`: 重置计数的按钮

**点击监听器:**
- 使用匿名内部类实现 `View.OnClickListener`
- 增加按钮：`count++`，更新文本显示
- 重置按钮：`count = 0`，更新文本显示
- 使用 `getString(R.string.count_format, count)` 格式化字符串

### 资源文件 (res 目录)

#### 11. [app/src/main/res/layout/activity_main.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/layout/activity_main.xml)
主界面的布局文件，使用 ConstraintLayout。

**ConstraintLayout:**
- Android 官方推荐的布局管理器
- 通过约束关系定位子视图
- 扁平的视图层级，性能更好

**视图控件:**

1. **titleTextView (TextView)**
   - 显示标题 "简单计数器"
   - 文字大小 24sp，加粗
   - 约束：水平居中，顶部对齐父视图

2. **countTextView (TextView)**
   - 显示当前计数
   - 文字大小 48sp
   - 约束：水平居中，在标题下方

3. **incrementButton (Button)**
   - "增加"按钮
   - 约束：水平居中，在计数下方

4. **resetButton (Button)**
   - "重置"按钮
   - 约束：水平居中，在增加按钮下方

**约束语法:**
- `app:layout_constraintTop_toTopOf`: 顶部对齐
- `app:layout_constraintBottom_toTopOf`: 底部对齐到某视图顶部
- `app:layout_constraintStart_toStartOf`: 起始边对齐
- `app:layout_constraintEnd_toEndOf`: 结束边对齐
- `android:layout_marginBottom`: 底部外边距

#### 12. [app/src/main/res/values/strings.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/values/strings.xml)
字符串资源文件，集中管理所有文本内容。

**定义的字符串:**
- `app_name`: 应用名称 ("Qazll App")
- `app_title`: 界面标题 ("简单计数器")
- `increment`: 按钮文本 ("增加")
- `reset`: 按钮文本 ("重置")
- `count_format`: 计数格式化字符串 ("计数: %d")
- `count_format_zero`: 初始计数显示 ("计数: 0")

**使用方式:**
- 在 XML 中：`@string/xxx`
- 在 Java 中：`getString(R.string.xxx)`

**优点:**
- 便于国际化（多语言支持）
- 便于统一修改
- 避免硬编码字符串

#### 13. [app/src/main/res/values/colors.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/values/colors.xml)
颜色资源文件，集中管理所有颜色值。

**定义的颜色:**
- `purple_200`: 浅紫色 (#FFBB86FC)
- `purple_500`: 紫色 (#FF6200EE)
- `purple_700`: 深紫色 (#FF3700B3)
- `teal_200`: 浅青色 (#FF03DAC5)
- `teal_700`: 深青色 (#FF018786)
- `black`: 黑色 (#FF000000)
- `white`: 白色 (#FFFFFFFF)

**颜色格式:**
- `#AARRGGBB`：Alpha + Red + Green + Blue
- 每个分量 2 位十六进制数 (00-FF)

**使用方式:**
- 在 XML 中：`@color/xxx`

#### 14. [app/src/main/res/values/themes.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/values/themes.xml)
浅色主题定义文件。

**主题基础:**
- 继承自 `Theme.MaterialComponents.DayNight.DarkActionBar`
- DayNight 主题：自动根据系统设置切换浅色/深色模式
- DarkActionBar：带深色 ActionBar

**主题属性:**
- `colorPrimary`: 主要颜色（紫色 #6200EE）
- `colorPrimaryVariant`: 主要颜色变体（深紫色）
- `colorOnPrimary`: 在主要颜色上的文字颜色（白色）
- `colorSecondary`: 次要颜色（青色）
- `colorSecondaryVariant`: 次要颜色变体
- `colorOnSecondary`: 在次要颜色上的文字颜色（黑色）

**Material Design 颜色系统:**
- Primary：品牌主色
- Secondary：强调色
- On Primary：在主色背景上的内容颜色

#### 15. [app/src/main/res/values-night/themes.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/values-night/themes.xml)
深色主题定义文件。

**与浅色主题的区别:**
- `colorPrimary`: 使用浅紫色 (#BB86FC) - 在深色背景上更易读
- `colorPrimaryVariant`: 使用紫色 (#6200EE)
- `colorOnPrimary`: 使用黑色 - 在浅色主色上更清晰
- 其他属性类似

**values-night 目录:**
- Android 系统自动识别
- 当设备设置为深色模式时自动加载此目录的资源
- 资源名称必须与 values 目录对应

### 应用图标文件

#### 16. [app/src/main/res/drawable/ic_launcher_foreground.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/drawable/ic_launcher_foreground.xml)
应用图标的前景图层（矢量图形）。

**矢量图形:**
- 使用 `<vector>` 元素定义
- 可以无损缩放，适配各种分辨率
- 相比位图资源，文件更小

**绘制内容:**
- 紫色背景矩形 (108x108dp)
- 两个白色三角形，形成一个"上箭头"和"下箭头"的组合图案

**路径绘制:**
- `android:pathData`: 使用 SVG 路径语法
- `M x,y`: 移动到指定点
- `L x,y`: 画直线到指定点
- `Z`: 闭合路径

#### 17. [app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml)
自适应图标定义（方形）。

**自适应图标 (Adaptive Icons):**
- Android 8.0 (API 26) 引入
- 由背景层和前景层组成
- 系统可以根据设备样式裁剪成不同形状（方形、圆形、圆角方形等）

**结构:**
- `<background>`: 背景层（紫色）
- `<foreground>`: 前景层（箭头图案）

**mipmap-anydpi-v26:**
- `anydpi`: 表示可以适配任何密度
- `v26`: 仅在 API 26+ 设备上使用

#### 18. [app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml](file:///C:/development/data/qazll/qazll-app/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml)
自适应图标定义（圆形）。

- 内容与 `ic_launcher.xml` 完全相同
- 用于需要圆形图标的设备/启动器
- Android 系统会根据需要选择使用方形或圆形图标

### 自动生成的目录

**`.gradle/` 目录:**
- Gradle 构建系统的缓存目录
- 存储已下载的依赖、构建缓存等
- 可以安全删除，下次构建时会自动重新生成
- 不应加入版本控制（.gitignore 中应包含）

**`build/` 目录:**
- 构建输出目录
- 包含编译生成的 APK、中间文件等
- 执行 Clean 操作时会被删除
- 不应加入版本控制

**`app/build/` 目录:**
- app 模块的构建输出
- `outputs/apk/`: 生成的 APK 文件
- `intermediates/`: 构建过程中的中间文件

## 如何使用

### 打开项目

1. 启动 Android Studio
2. 选择 `File` → `Open...`
3. 选择项目根目录 `qazll-app`
4. 等待 Gradle 同步完成（首次需要下载依赖）

### 运行应用

1. 连接 Android 设备或启动模拟器
2. 点击工具栏上的绿色播放按钮（Run 'app'）
3. 或使用快捷键 `Shift + F10`

### 构建 APK

**调试版 APK:**
```bash
gradlew.bat assembleDebug
```
输出位置：`app/build/outputs/apk/debug/app-debug.apk`

**发布版 APK:**
```bash
gradlew.bat assembleRelease
```
输出位置：`app/build/outputs/apk/release/app-release.apk`

### 常用 Gradle 任务

| 任务名 | 说明 |
|--------|------|
| `assembleDebug` | 构建调试版 APK |
| `assembleRelease` | 构建发布版 APK |
| `installDebug` | 构建并安装调试版 |
| `uninstallDebug` | 卸载调试版 |
| `clean` | 清理构建输出 |
| `test` | 运行单元测试 |
| `connectedAndroidTest` | 运行设备上的仪器化测试 |

## 依赖说明

项目使用以下主要依赖：

| 依赖 | 用途 | 版本 |
|------|------|------|
| androidx.core | AndroidX 核心库 | 1.15.0 |
| androidx.appcompat | 向后兼容 | 1.7.0 |
| com.google.android.material | Material Design | 1.12.0 |
| androidx.activity | Activity 扩展 | 1.10.1 |
| androidx.constraintlayout | 约束布局 | 2.2.0 |
| androidx.lifecycle | 生命周期管理 | 2.8.7 |
| junit | 单元测试 | 4.13.2 |
| androidx.test.ext.junit | Android 测试 | 1.2.1 |
| androidx.test.espresso | UI 测试 | 3.6.1 |

## 开发建议

### 代码风格

- 使用 Java 17 语法
- 遵循 Android 官方编码规范
- 使用 meaningful 的变量名和方法名
- 合理使用注释（但不要过度注释）

### 资源命名

- 布局文件：`activity_xxx.xml`、`fragment_xxx.xml`、`item_xxx.xml`
- 字符串：使用描述性名称，如 `app_name`、`button_submit`
- 颜色：描述用途而非颜色值，如 `primary_color`、`text_primary`
- 尺寸：`dp_16`、`sp_14` 等

### 性能优化

- 使用 ConstraintLayout 减少视图层级
- 避免在 Activity 中做耗时操作
- 使用 ViewBinding 替代 findViewById（可选）
- 合理使用 RecyclerView（如需列表）

### 版本控制

应该忽略的目录/文件：
```
.gradle/
build/
app/build/
local.properties
*.iml
.idea/
.DS_Store
```

## 故障排除

### Gradle 同步失败

1. 检查网络连接（需要下载依赖）
2. 确认 Android SDK 已正确安装
3. 尝试 `File` → `Invalidate Caches / Restart`
4. 删除 `.gradle` 目录后重新同步

### 编译错误

1. 检查 Java 版本（需要 JDK 17）
2. 确认所有依赖的版本兼容
3. 查看 Build 窗口的详细错误信息

### 运行时错误

1. 检查 Logcat 输出
2. 确认权限已在 AndroidManifest 中声明
3. 确保设备 API 级别 >= minSdk (24)

## 扩展功能建议

如果想扩展这个应用，可以考虑：

1. **保存计数状态**: 使用 `SharedPreferences` 或 `ViewModel` + `SavedStateHandle`
2. **添加动画**: 点击按钮时的缩放动画
3. **历史记录**: 记录计数变化的历史
4. **设置功能**: 允许修改主题、步长等
5. **添加更多按钮**: 支持减少计数、设置自定义值
6. **添加夜间模式切换**: 用户手动切换主题
7. **使用 ViewBinding**: 替代 findViewById，更安全
8. **迁移到 Jetpack Compose**: 使用声明式 UI 框架

## 许可证

本项目仅供学习参考使用。