HarmonyOS 鸿蒙Next 端云一体化，极简开发数独闯关游戏元服务

HarmonyOS 鸿蒙Next 端云一体化，极简开发数独闯关游戏元服务 数独闯关游戏元服务，支持24历史闯关记录卡片、44数独闯关游戏卡片，无需进入元服务，可在桌面上开始游戏，同步刷新记录。

1 基本概念

• 元服务（原名原子化服务）是一种基于HarmonyOS API的全新服务提供方式，以HarmonyOS万能卡片等多种呈现形态，向用户提供更轻量化的服务。具有即用即走、信息外显、服务直达的特性。
• 万能卡片（简称卡片）是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达、减少体验层级的目的。
• HUAWEI DevEco Studio是华为基于IntelljJ IDEA Community开源版本打造的一款面向全场景多设备，提供一站式的分布式应用开发平台，支持分布式多端开发、分布式多端调测、多端模拟仿真，为运行在HarmonyOS/OpenHarmony系统上的应用/服务提供一站式开发平台。
• HarmonyOS SDK是集成在DevEco Studio中，为应用/服务开发提供所需的一系列系统开放能力，如框架、Ability、分布式服务、安全、方舟编译器、HMS Core、基础软件服务、硬件服务等，其包含开发者可以使用的API以及调试编译等基础的工具链。
• ArkTS语言是华为自研的开发语言，基于TypeScript（简称TS）基础上匹配了ArkUI框架，扩展了声明式UI、状态管理等相应的能力。
• ArkUI框架是一套构建分布式应用界面的声明式UI开发框架，其使用极简的UI信息语法、丰富的UI组件、以及实时界面预览工具，帮助开发者提升HarmonyOS应用界面开发效率。
• ArkCompiler是华为自研的统一编程平台，包括编译器、工具链、运行时等关键部件，支持高级语言在多种芯片平台的编译与运行。
• AppGallery Connect（简称AGC）致力于为应用的创意、开发、分发、运营、经营各环节提供一站式服务，构建全场景智慧化的应用生态体验。
• 端云一体化是为丰富HarmonyOS对云端开发的支持、实现HarmonyOS生态端云联动，DevEco Studio推出了云开发功能，开发者在创建工程时选择云开发模板，即可在DevEco Studio内同时完成HarmonyOS应用/服务的端侧与云侧开发。

2 约定

• DevEco Studio 3.1.1 Release
• HarmonyOS SDK API 9
• ArkTS语言
• Stage模型
• 端云一体化元服务工程
  • 确保已使用已实名认证的华为开发者账号登录DevEco Studio。

3 创建端云一体化元服务工程

3.1 打开创建工程向导

选择以下一种方式，打开工程创建向导界面：

• 当前未打开任何工程，单击DevEco Studio欢迎页中“Create Project”创建新工程。
• 当前已打开工程，单击菜单栏“File > New > Create Project”创建新工程。

3.2 选择工程模板

在Choose Your Ability Template向导页，单击“Atomic Service”切换工程类型，选择云开发模板，单击“Next”进入下一步。

3.3 配置工程信息

在工程配置界面，配置工程的基本信息。单击“Next”按钮进入关联云开发资源界面。

3.4 关联云开发资源

为工程关联云开发所需的资源，即在DevEco Studio中选择您的华为开发者账号加入的开发者团队，将该团队在AGC的同包名应用关联到当前工程，具体操作如下：

• 若尚未登录DevEco Studio，单击“Sign in”，拉起浏览器在弹出的账号登录页面，使用已实名认证的华为开发者账号完成登录。

登录成功后，在授权界面单击“允许”按钮为DevEco Studio授权，界面将展示账号昵称。

单击“Team”下拉框，选择开发团队。选中团队后，系统根据工程包名自动查询团队下的同包名应用。若为首次创建且团队下未创建同包名的应用，则提示需要在AGC平台创建应用。

单击“AppGallery Connect”打开AGC应用创建向导，填写应用信息，单击“确认”按钮创建应用。

完成以上操作后，DevEco Studio即可获取到同包名应用对应的项目信息。

3.5 工程初始化配置

成功创建工程并关联云开发资源后，DevEco Studio会为工程自动执行一些初始化配置，并开通云开发相关服务：认证服务、云函数、云数据库、云托管、API网关、云存储。

端侧工程自动集成AGC SDK，包括AGC SDK 配置文件entry/src/main/resources/rawfile/agconnect-services.json 和在entry/oh-package.json5配置文件中引入的AGC相关云服务最新版本SDK。

云侧工程自动集成云数据库最新版本Node.js Server SDK。

4 端云协同元服务工程介绍

端云一体化元服务开发工程目录分为三个子工程：元服务开发工程（Application）、云开发工程（CloudProgram）、端侧公共库（External Libraries）。

4.1 元服务开发工程（Application）

元服务开发工程主要用于开发应用端侧的业务代码，元服务开发工程目录结构如下：

4.2 云开发工程（CloudProgram）

云开发工程中开发者可以为应用开发云函数和云数据库服务资源，云开发工程目录结构如下：

5 云函数开发指南

5.1 创建函数

在云端工程（CloudProgram）中可以创建函数、编写函数业务代码、为函数配置调用触发器。

1. 单击“cloudfunctions”目录，选择“New > Cloud Function”创建云函数。

2. 输入函数名称，单击“OK”按钮DevEco Studio自动生成函数目录。函数名称仅支持小写英文字母、数字、中划线（-），首字母必须为小写字母，结尾不能为中划线（-）。

   为当前工程创建生成数独9*9宫格二维数组算法，云函数名称为sudoku-algorithm。

3. 云函数目录结构。

4. 云函数触发器 云函数触发器在function-config.json文件中triggers属性中配置，当前支持HTTP触发器、CLOUDDB触发器、AUTH触发器、CLOUDSTORAGE触发器、CRON触发器五种。

   HTTP触发器：工程创建完成后默认自动在function-config.json文件生成HTTP触发器配置。函数部署到云端后会自动生成触发URL，开发者向URL发起HTTP请求时触发函数。

5.2 开发云函数

云函数的代码实现基于不同的语言运行环境可分为Node.js、Java、Python，还有一种比较特别运行环境为Custom Runtime（自定义运行环境）。本工程的语言运行环境为Node.js。

5.2.1 云函数的入口方法

module.exports.myHandler = function(event, context, callback, logger)

5.2.2 为云函数添加返回内容

let myHandler = async function (event, context, callback, logger) {
  logger.info(event);

  // do something here
  callback({
    code: 0,
    desc: "Success.",
    data: "请求成功！"
  });
};
export { myHandler };

5.2.3 调试云函数

函数开发过程中，开发者可在本地进行调试，或者将函数部署到AGC云端后，在本地触发调用云端函数。当前本地调试支持Run和Debug两种模式，Debug模式支持使用断点来追踪函数的运行情况。

5.2.4 部署云函数

完成函数代码开发后，开发者可将函数部署到AGC控制台，支持单个部署和批量部署。

5.3 查看触发器标识

当开发者创建的函数或函数别名中创建一个HTTP类型的触发器后，在应用客户端调用函数时需要传入HTTP触发器的标识，查询方法如下：在函数的触发器页面点击“HTTPTrigger”触发器，查看“触发URL”的后缀，获取触发器标识，格式为“函数名-版本号”。

5.4 调用云函数

应用集成云函数SDK后，可以在应用内直接通过SDK API调用AGC中的云函数，云函数SDK与AGC的函数调用基于HTTPS的安全访问。

在端侧应用（Application）中“entry > src/main/ets > services”目录创建SudokuAlgorithmFunction.ts文件，编写调用云函数方法。

在端侧应用（Application）中“entry > src/main/ets > pages > Index.ets”文件中增加请求云函数方法。

运行端侧（Application）应用程序，单击“请求自定义云函数”按钮，在Log控制台过滤日志查看返回结果。

5.5 实现云函数返回9*9宫格二位数组的数独谜题和所有解

使用回溯算法填充数独谜题，并随机移除一些数字将其作为数独谜题，然后求解指定数独谜题的所有解。

6 认证服务-邮箱认证

当前AGC认证服务为HarmonyOS应用/服务提供的登录认证方式有手机、邮箱和关联账号三种方式。本工程使用“邮箱+验证码”的方式作为应用的登录入口。

6.1 前提条件

• 需要在AGC控制台开通认证服务（工程创建时默认开通），并在“认证方式”页签中启用“邮箱地址”。
• 需要在应用中集成SDK（工程创建时默认开通）。

6.2 扩展邮箱认证

调用AGConnectAuth.requestEmailVerifyCode申请验证码，在entry/src/main/ets/services/Auth.ts认证工具类中添加邮箱验证码获取方法。

调用EmailUserBuilder生成EmailUser，然后调用AGConnectAuth.createEmailUser注册用户。注册成功后，系统会自动登录，无需再次调用登录接口。也可以使用signIn登录接口，通过第三方认证来登录AGConnect平台，在entry/src/main/ets/services/Auth.ts认证工具类中添加邮箱账号注册用户方法。

6.3 构建邮箱登录页面

通过容器组件Flex、Row、Column以及基础组件Text、Image、Button、Navigation、TextInput构建邮箱登录页面。

6.4 用户登录成功信息写入缓存

调用自定义的登录接口实现登录，并使用首选项自定义工具接口将用户信息写入缓存。

6.5 登录成功后跳转设置昵称头像界面

右键单击“entry > src/main/ets > pages”目录选择“New > Pages”新建Setting设置页面。

在页面中使用容器组件Grid实现头像选择（提供可选头像6个）和使用基础组件TextInput实现昵称设置。

头像昵称设置成功后，跳转到游戏主界面，点击“开始”按钮从云函数中获取数独谜题及对应的解，然后通过容器组件Grid和其子组件GridItem构建9*9宫格并使用ForEach渲染宫格的对应组件。

7 创建闯关游戏万能卡片

万能卡片（以下简称“卡片”）是一种界面展示形式，可以将应用的重要信息或操作前置到卡片，以达到服务直达、减少体验层级的目的。卡片常用于嵌入到其他应用（当前卡片使用方只支持系统应用，如桌面）中作为其界面显示的一部分，并支持拉起页面、发送消息等基础的交互功能。

7.1 拉起页面的2*2卡片

工程在创建初会自动创建2*2服务卡片，位于“entry > src/main/ets > widget > pages”目录。在WidgetCard.ets文件中编写服务卡片呈现内容及样式。

7.2 创建4*4闯关游戏卡片

4*4服务卡片用于在桌面玩游戏，没关通关后需要通过message事件刷新卡片内容生成新的关卡。

7.2.1 创建一个ArkTS卡片

创建ArkTS卡片有两种方式：

• 通过在”entry“目录右键单击“New > Service Widget”创建卡片。
• 通过在”entry > src/main/ets > widget > pages“目录右键单击“New > ArkTS File”创建文件，并在卡片配置文件form_config.json中配置卡片信息。

7.2.2 卡片配置文件

卡片相关的配置主要包括FormExtensionAbility的配置和卡片的配置两部分：

7.2.3 通过message事件刷新卡片内容

在卡片页面可以通过postCardAction接口触发message事件拉起FormExtensionAbility，然后由FormExtensionAbility刷新卡片内容。

7.2.4 卡片不支持TextInput的替代方案

ArkTS卡片具备JS卡片的全量能力，并且新增了动效能力和自定义绘制的能力，支持声明式的部分组件、事件、动效、数据管理、状态管理能力。在数独游戏中需要使用输入框录入谜题解，而ArkTS卡片暂时不具备TextInput组件能力，因此使用点击空白区域与数字按钮互换的方式替代TextInput组件能力。

7.2.5 卡片不支持setInterval的替代方案

在应用程序中可以使用setInterval进行计时操作，但当前ArkTS卡片不支持setInterval，因此使用new Date().getTime()开始时间和结束时间差值作为游戏时长替代setInterval方法。

7.3 闯关记录实时刷新的2*4卡片

使用第二种方式创建卡片，在"entry > src/main/ets > widget > pages"目录右键单击"New > ArkTS File"创建HistoryCard.ets文件，接着打开"entry > src/main/resources > base > profile"目录下的form_config.json文件，配置名称为history的2*4卡片。

8 结语

大家可以在华为应用市场元服务专区、服务中心入口，体验已经上架的元服务。也可以点击进入元服务官网，了解更多相关信息。