一、项目概述

（一）项目名称

“策无忧” 决策模型纯血鸿蒙应用开发项目

（二）项目背景

        在日常生活与工作中，人们时常面临各类决策选择场景，如出行方式挑选、活动方案确定、琐事优先级排序等，部分场景下需要随机化决策以避免选择困难或平衡公平性。当前市场上的决策类应用存在功能单一、适配性不足、交互体验欠佳等问题，尤其缺乏针对鸿蒙系统深度优化的纯血应用。基于此，本项目旨在开发一款功能丰富、交互流畅、适配鸿蒙生态的决策模型应用，为用户提供多样化的随机决策解决方案，解决选择困境，提升决策效率。

（三）项目目标

1. 开发一款纯血鸿蒙应用，实现九宫格抽奖、掷骰子、投硬币、抽卡牌、转轮盘、答案之书、随机数生成等七大核心决策功能，覆盖多场景决策需求。
2. 保证应用交互体验流畅，具备丰富的动画效果与音效反馈，提升用户使用趣味性。
3. 支持功能自定义配置，如选项修改、样式调整、参数设置等，满足用户个性化需求。
4. 实现数据持久化存储，保存用户操作记录与配置偏好，确保数据不丢失。
5. 适配鸿蒙系统特性，保障应用运行稳定性、兼容性与性能优化。

（四）开发环境与技术栈

• 开发环境：DevEco Studio（鸿蒙应用开发工具）
• 操作系统：HarmonyOSNEXT（纯血开发，适配多设备终端）
• 界面开发：鸿蒙 UI 组件、布局管理器（网格布局、弹性布局等）
• 状态管理：鸿蒙应用生命周期管理、组件状态监听
• 数据存储：SharedPreferences 用户首选项
• 多媒体：AVPlayer 音频播放
• 网络请求：axios 第三方库
• 工具类：ThemeUtil 主题颜色控制工具
• 动画效果：鸿蒙原生动画 API（平移、缩放、透明度变化等）

• 其他：RGB 颜色随机生成、加减器组件、滑块组件、对话框组件等

二、需求分析

（一）功能需求

1. 核心功能模块需求

功能模块	具体需求描述
九宫格抽奖模块	1. 首页展示九宫格布局，支持旋转抽奖随机选取决策选项； 允许用户修改九宫格标题及对应 9 个选项内容；. 抽奖过程具备流畅的旋转动画效果。
发现页面（多决策模型）	1. 通过 Navigation 导航实现页面切换，展示五大决策模型入口；2. 各模型入口分类清晰，支持快速跳转至对应功能页面。
掷骰子模块	1. 支持通过加减器调整骰子数量（最少 1 个，无上限限制）；>2. 掷骰子后显示每个骰子的点数及总点数；>3. 记录每一次掷骰子的历史结果，支持查看。
投硬币模块	1. 电子抛硬币功能，随机生成正反面结果；. 累加记录正反面出现次数，刷新页面或返回首页时保存记录；3. 支持设置页面自定义背景图片、硬币正反面样式；>4. 投掷过程播放对应音效，提升交互体验。
抽卡牌模块	1. 默认网格布局展示 6 张卡牌，顶部显示模块标题；. 卡牌标注自定义选项，支持点击标题或卡牌修改内容；3. 点击 “抽卡牌” 按钮触发随机抽取逻辑，伴随半透明覆盖层 + 卡牌上浮动画；4. 右上角设置功能支持修改卡牌样式、切换卡组，通过滑块调整卡牌数量（1-6 张）。
转轮盘模块	1. 轮盘中间设 “开始” 按钮，点击后触发轮盘旋转动画，随机选中一个扇区；>2. 支持 “选项编辑” 功能，可修改标题、扇区选项、添加 / 删除扇区（数量灵活调整）；3. 支持设置扇区权重，影响选中概率；>4. 扇区颜色通过 RGB 随机生成，支持保存 / 取消修改操作。
答案之书模块	1. 提供输入框供用户输入待询问问题；2. 点击 “询问答案之书” 按钮，通过 axios 发起网络请求调用 API 获取答案； 页面中间渲染返回结果，上方展示用户输入的问题。
随机数生成器模块	1. 支持用户设置最大值、最小值、生成数量、是否允许重复；2. 校验输入条件，若无法生成对应数量的随机数（如范围过小且不允许重复时数量超出上限），弹出提示框；3. 生成结果通过弹性布局展示，清晰直观。

2. 辅助功能需求

• 主题颜色适配：通过 ThemeUtil 工具类，实现应用颜色随系统主题或自定义主题同步变化。

• 数据持久化：使用 SharedPreferences 保存用户操作记录（如掷骰子结果、硬币正反面次数）、配置偏好（如硬币样式、卡牌数量）等。

• 交互反馈：除投硬币音效外，关键操作（如抽奖中奖、卡牌抽取、轮盘停止）均需具备动画或音效反馈。

• 页面导航：通过 Navigation 组件实现各功能页面之间的灵活跳转，支持返回、首页快速切换。

（二）非功能需求

1. 性能需求：应用启动时间≤3 秒，页面切换响应时间≤500 毫秒，动画播放流畅无卡顿。
2. 稳定性需求：连续运行 24 小时无崩溃，数据存储无丢失，网络请求异常时具备容错处理（如提示网络错误）。
3. 兼容性需求：适配鸿蒙系统 2.0 及以上版本，支持手机、平板等主流终端设备。
4. 易用性需求：界面设计简洁直观，操作逻辑清晰，用户无需学习成本即可快速上手。
5. 安全性需求：网络请求采用安全协议，用户数据本地存储加密，不收集无关隐私信息。

三、总体设计

（一）架构设计

本项目采用鸿蒙应用经典的 MVC（Model-View-Controller）架构模式，结合鸿蒙系统特性进行优化设计：

1. View 层：负责界面展示与用户交互，包括所有功能页面的布局、组件渲染、动画效果实现，基于鸿蒙 UI 组件构建统一风格的界面。
2. Controller 层：负责业务逻辑处理与流程控制，包括按钮点击事件、数据校验、功能跳转、网络请求调度、音频播放控制等，是连接 View 层与 Model 层的核心。
3. Model 层：负责数据管理，包括 SharedPreferences 数据存储与读取、API 返回数据解析、配置参数模型定义等，提供数据持久化与数据处理支持。

（二）模块划分

根据功能需求，项目划分为 7 个核心功能模块与 3 个辅助模块，各模块职责如下：

模块类型	模块名称	核心职责
核心功能模块	九宫格抽奖模块	实现九宫格布局渲染、旋转抽奖动画、标题及选项修改
	掷骰子模块	骰子数量调整、点数随机生成、结果记录与展示
	投硬币模块	正反面随机生成、次数统计、样式设置、音效播放
	抽卡牌模块	卡牌布局渲染、随机抽取逻辑、样式与数量配置
	转轮盘模块	轮盘绘制、旋转动画、扇区编辑与权重设置
	答案之书模块	问题输入、网络请求、结果展示
	随机数生成器模块	参数设置、条件校验、随机数生成与展示
辅助模块	导航模块	基于 Navigation 实现页面跳转与导航管理
	数据存储模块	基于 SharedPreferences 实现数据持久化
	工具模块	主题颜色控制（ThemeUtil）、音频播放（AVPlayer）、网络请求（axios）

（三）页面结构设计

1. 首页：九宫格抽奖页面（应用启动默认页面），顶部标题栏，中间九宫格布局，底部操作按钮（修改、抽奖）。
2. 发现页面：Navigation 导航栏（含返回、首页按钮），中间网格布局展示五大决策模型入口（掷骰子、投硬币、抽卡牌、转轮盘、答案之书）。
3. 功能详情页：每个核心功能对应独立详情页，包含功能操作区、配置区、结果展示区，统一风格的标题栏与操作按钮。
4. 设置页面：各功能模块对应的自定义设置页面，包含样式选择、参数调整、选项编辑等控件。

四、详细设计与实现

（一）界面设计与实现

1. 统一界面风格：采用简约现代的设计风格，配色基于 ThemeUtil 工具类适配系统主题，按钮、卡片等组件采用圆角设计，提升视觉舒适度。
2. 九宫格抽奖页面：采用 GridLayout 布局，设置 3 行 3 列网格，每个网格项绑定选项数据，通过动画 API 实现旋转效果。
3. 抽卡牌页面：默认使用 GridLayout（2 行 3 列）展示 6 张卡牌，卡牌采用自定义组件实现，包含图片、文字元素，通过动画 API 实现抽取时的上浮与半透明覆盖效果。
4. 随机数生成器页面：输入区域采用线性布局，结果展示区域采用 FlexLayout 弹性布局，支持自适应屏幕宽度展示随机数。
5. 导航实现：通过鸿蒙 Navigation 组件搭建页面导航框架，标题栏设置返回按钮、首页按钮，支持快速切换至首页或上一级页面。

（二）核心功能实现

1. 九宫格抽奖模块

• 数据绑定：通过 List 容器存储九宫格选项数据，绑定至 GridLayout 的每个网格项，支持用户通过编辑页面修改数据并实时刷新界面。

• 旋转抽奖：使用鸿蒙 AnimationController 控制旋转动画，设置动画时长、插值器，通过随机数生成器确定最终选中的网格项，动画结束后高亮展示选中结果。

2. 掷骰子模块

• 骰子数量控制：通过自定义加减器组件，实现骰子数量的增减，监听组件变化事件更新骰子展示数量。

• 点数生成与记录：点击掷骰子按钮时，根据当前骰子数量生成对应个数的随机数（1-6），计算总点数，将结果存储至 List 集合（历史记录），并通过 RecyclerView 展示历史结果。

3. 投硬币模块

• 正反面随机生成：通过 Random 类生成 0 或 1 随机数，分别对应正面、反面，触发硬币翻转动画（使用属性动画实现旋转效果）。

• 次数统计与存储：定义两个整型变量记录正反面次数，每次投掷后更新变量值，在页面刷新、返回首页时，通过 SharedPreferences 将次数数据存储至本地，下次启动应用时读取并恢复数据。

• 样式设置：提供图片选择控件，支持用户选择硬币正反面图片、背景图片，将选择结果存储至 SharedPreferences，页面初始化时加载配置。

• 音效播放：通过 AVPlayer 类加载音频文件（硬币翻转音效），在投掷动画触发时调用 play () 方法播放音效，支持音效开关控制（可选扩展功能）。

4. 抽卡牌模块

• 卡牌数据管理：使用 List 存储卡牌选项数据，支持用户点击卡牌或标题进入编辑页面修改内容，通过滑块组件调整卡牌数量（1-6），动态更新 GridLayout 的行数与列数。

• 抽取逻辑：点击抽卡牌按钮时，首先通过遮罩组件覆盖原页面（设置透明度 0.5），然后从卡牌数据 List 中随机选取一个元素，通过动画 API 将选中卡牌的缩放比例从 0.8 放大至 1.2，平移至页面中央，实现上浮效果。

5. 转轮盘模块

• 轮盘绘制：自定义 View 组件绘制轮盘，根据扇区数量分割圆形画布，通过 RGB 随机数生成每个扇区的颜色（Color.rgb (random.nextInt (256), random.nextInt (256), random.nextInt (256))），绘制扇区边界与选项文字。

• 旋转与选中逻辑：通过 AnimationController 控制轮盘旋转动画，根据扇区权重调整旋转速度与停止位置（权重越高，停止概率越大），动画结束后通过角度计算确定选中的扇区并展示结果。

• 扇区编辑：点击 “选项编辑” 按钮跳转至编辑页面，通过输入框修改标题、选项内容，使用加减按钮添加 / 删除扇区，通过滑块设置权重，点击保存按钮将修改后的数据存储并刷新轮盘，取消则放弃修改。

6. 答案之书模块

• 问题输入：使用鸿蒙 TextField 组件接收用户输入的问题，监听输入事件进行非空校验（若未输入问题，点击询问按钮时弹出提示）。

• 网络请求：通过 axios 库发起 GET/POST 请求，将用户问题作为参数传递至 API 接口，设置请求超时时间与异常处理（网络错误时提示用户检查网络连接）。

• 结果展示：解析 API 返回的 JSON 数据，提取答案内容，在页面中间的 TextView 组件中渲染，上方展示用户输入的问题，支持刷新按钮重新发起请求。

7. 随机数生成器模块

• 参数设置：通过 TextField 或 NumberPicker 组件让用户输入最大值、最小值、生成数量，通过 Switch 组件控制是否允许重复。

• 条件校验：点击生成按钮时，校验参数合法性：最小值≤最大值、生成数量≥1，若不允许重复则生成数量≤（最大值 - 最小值 + 1），不满足条件时通过 Toast 或 Dialog 提示用户调整参数。

• 随机数生成：使用 Random 类生成指定范围的随机数，若不允许重复则通过 Set 集合去重，确保生成数量符合要求，最终将随机数转换为字符串，通过 FlexLayout 展示。

（三）辅助功能实现

1、主题颜色控制：ThemeUtil 工具类通过监听系统主题变化事件，获取当前主题的主色、辅助色，动态更新应用内组件的背景色、文字颜色，实现主题适配。

import { ConfigurationConstant } from '@kit.AbilityKit';

const currentColorMode: ConfigurationConstant.ColorMode = ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET;
/**
 * 获取当前系统主题是否为深色模式
 * @returns
 */
export function isDarkMode(): boolean {
  return currentColorMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK;
}

2、数据持久化：使用 SharedPreferences 存储各类数据，如：

• 用户配置：硬币样式、卡牌数量、轮盘扇区设置等；
• 操作记录：掷骰子历史结果、硬币正反面次数等；
• 存储方式：通过 Context 获取 SharedPreferences 实例，使用 edit () 方法编辑数据，apply () 方法提交保存。

3、音频播放：通过 AVPlayer 创建音频播放器实例，设置音频文件路径（本地资源），监听播放状态，在对应操作触发时调用 play () 方法播放，播放结束后释放资源。

// 播放音效或音频

import { media } from '@kit.MediaKit';
export class AvPlayerUtil {

  static avPlayer: media.AVPlayer|null = null

  static async init(){
    // 创建AVPlayer对象
    AvPlayerUtil.avPlayer = await media.createAVPlayer()

    // 设置状态机
    AvPlayerUtil.avPlayer.on('stateChange', (state) => {
      switch (state){
        case "initialized":
          AvPlayerUtil.avPlayer?.prepare();
          break;
        case "prepared":
          AvPlayerUtil.avPlayer?.play();
          break;
      }
    })
  }

  // 播放功能
  static async playAudio(context:Context, fileName: string){
    // 通过UIAbilityContext的resourceManager成员的getRawFd接口获取媒体资源播放地址。
    // 返回类型为{fd,offset,length},fd为HAP包fd地址，offset为媒体资源偏移量，length为播放长度。
    let fileDescriptor = await context.resourceManager.getRawFd(fileName);
    let avFileDescriptor: media.AVFileDescriptor =
      { fd: fileDescriptor.fd, offset: fileDescriptor.offset, length: fileDescriptor.length };

    await AvPlayerUtil.init()

    if (AvPlayerUtil.avPlayer) {
      // 为fdSrc赋值触发initialized状态机上报
      AvPlayerUtil.avPlayer.fdSrc = avFileDescriptor
      // 播放
      AvPlayerUtil.avPlayer.play()
    }
  }

}

五、测试与验证

（一）测试环境

软件环境：DevEco Studio 4.0+、鸿蒙模拟器（API Version 18+）。

（二）测试内容与结果

1. 功能测试

测试模块	测试用例	测试结果
九宫格抽奖	1. 正常旋转抽奖；2. 修改标题及选项；3. 选中结果展示	功能正常，动画流畅，修改后实时刷新
掷骰子	1. 增减骰子数量；2. 生成点数与总点数；3. 历史记录展示	数量调整有效，点数生成随机，记录完整
投硬币	1. 投掷生成正反面；2. 次数统计与保存；3. 样式设置；4. 音效播放	结果随机，次数保存正常，样式切换有效，音效清晰
抽卡牌	1. 抽取动画效果；2. 修改卡牌内容；3. 调整卡牌数量；4. 切换样式	动画流畅，修改实时生效，数量控制在 1-6 张
转轮盘	1. 轮盘旋转与选中；2. 扇区编辑与保存；3. 权重生效；4. 颜色随机	旋转流畅，编辑功能正常，权重影响选中概率，颜色随机生成
答案之书	1. 问题输入与校验；2. 网络请求；3. 结果展示	校验有效，网络正常时成功获取答案，展示清晰
随机数生成器	1. 参数设置与校验；2. 生成随机数；3. 结果展示	校验严格，生成结果符合条件，展示布局合理

2. 非功能测试

• 性能测试：应用启动时间 2 秒，页面切换响应时间≤300 毫秒，动画播放无卡顿，连续操作 1 小时无性能下降。

• 稳定性测试：连续运行 24 小时无崩溃，数据存储无丢失，网络中断后恢复正常，无异常报错。

• 兼容性测试：在多款不同鸿蒙系统虚拟机上测试，界面适配良好，功能正常运行。

（三）问题与优化

1、问题 1：轮盘旋转动画在部分低配置设备上存在轻微卡顿。

优化方案：降低动画帧率（从 60fps 调整为 30fps），简化轮盘绘制逻辑，减少不必要的绘制次数，优化后卡顿问题解决。

2、问题 2：答案之书模块网络请求超时无提示。

优化方案：添加请求超时监听，设置超时时间为 5 秒，超时后弹出提示框告知用户 “网络请求超时，请重试”，提升用户体验。

六、源码拉取

下载代码请复制以下命令到终端执行：

（注意！需要下载git，下载过程请参考：https://blog.csdn.net/2301_80188585/article/details/155016188?spm=1001.2014.3001.5501）

git clone https://gitee.com/Augensterm-X/harmony-next-decision.git