HarmonyOS鸿蒙Next Codelab 优秀样例——溪村小镇（ArkTS）

一、介绍

溪村小镇是一款展示溪流背坡村园区风貌的应用，包括园区内的导航功能，小火车行车状态查看，以及各区域的风景展览介绍，主要用于展示 HarmonyOS 的 ArkUI 能力和动画效果。具体包括如下功能：

1. 打开应用时进入启动页，启动页轮播展示溪村小镇风景图，之后进入应用首页。
2. 在首页的“地图浏览”标签页，可以拖动和缩放查看地图，并查找相应地标建筑。
3. 在首页的“区域导览”标签页，可以上下滑动查看溪村小镇不同区域的卡片，点击卡片可以进入对应的区域详情页并查看区域的详细介绍和高清建筑风景图。
4. 在首页的“小火车”标签页，可以查看溪村小火车的运行路线图。

相关概念

• Tabs组件：通过页签进行内容视图切换的容器组件，每个页签对应一个内容视图。
• List组件：列表包含一系列相同宽度的列表项，包含子组件 ListItem。
• 点击手势：支持单击、双击和多次点击事件的识别。
• 拖动手势：用于触发拖动手势事件，滑动的最小距离为 5vp 时拖动手势识别成功。
• 捏合手势：用于触发捏合手势事件，触发捏合手势的最少手指为 2 指，最大为 5 指，最小识别距离为 3vp。
• 属性动画：组件的某些通用属性变化时，可以通过属性动画实现渐变过渡效果，提升用户体验。
• 自定义弹窗：通过 CustomDialogController 类显示自定义弹窗。使用弹窗组件时，可优先考虑自定义弹窗，便于自定义弹窗的样式与内容。
• Canvas画布：用于自定义绘制图形。

完整示例

gitee源码地址

环境搭建

软件要求

• DevEco Studio版本：DevEco Studio 3.1 Release。
• HarmonyOS SDK版本：API version 9。

硬件要求

• 设备类型：华为手机或运行在 DevEco Studio 上的华为手机设备模拟器。
• HarmonyOS 系统：3.1.0 Developer Release。

环境搭建

1. 安装 DevEco Studio，详情请参考下载和安装软件。
2. 设置 DevEco Studio 开发环境，DevEco Studio 开发环境需要依赖于网络环境，需要连接上网络才能确保工具的正常使用，可以根据如下两种情况来配置开发环境：如果可以直接访问 Internet，只需进行下载HarmonyOS SDK操作。 a. 如果网络不能直接访问 Internet，需要通过代理服务器才可以访问，请参考配置开发环境。
3. 开发者可以参考以下链接，完成设备调试的相关配置： a. 使用真机进行调试 b. 使用模拟器进行调试

代码结构解读

本篇 Codelab 只对核心代码进行讲解，对于完整代码，我们会在 gitee 中提供。

应用主页面与沉浸式设计

启动页

应用首次打开会进入启动页。在启动页内分三个时间段（白天、傍晚、晚上），会根据当前时间段轮播展示溪村小镇的优美风景。

在 onWindowStageCreate 生命周期中配置启动页入口。

应用首页

应用首页包括三个标签页，分别是“地图浏览”页、“区域导览”页和“小火车”页，效果如图所示：

该页面使用 Tabs 组件实现，使用一个自定义的底部标签栏组件来控制选中对应的标签页时的视觉效果。

地图浏览

地图浏览模块提供了“溪村小镇”的全景地图，方便用户了解“溪村小镇”内部的地理概况。包含以下功能：

1. 搜索指定类型地标，并在地图上展示。
2. 通过手势对地图进行操作，包括放大、缩小和拖拽。

初始化地图

地图使用 Stack 组件实现，地图初始化的宽高是由图片的宽高和地图父组件的宽高计算得出，地图位置由地图宽度和地图父组件计算得出。

搜索并展示指定类型地标

“地图浏览”完成地图初始化后，界面会默认展示查询搜索面板。用户通过搜索框输入指定类型进行搜索，也可以直接点击面板中已展示的类型进行搜索。

搜索面板为自定义组件 CustomPanel，主要由展开/收起图标（Image 组件）、搜索栏（Search 组件）、地标网格（Grid 组件）构成。用户点击地标网格中的网格、通过搜索框搜索指定类型或点击展开/收起图标，都会改变操作面板的显示状态（展示或隐藏）。通过属性动画（animation）可以实现操作面板的渐变过渡效果。

使用手势操作地图

操作地图的手势由捏合手势（PinchGesture）、点击手势（TapGesture）、平移手势（PanGesture）组合而成，可放大、缩小和移动地图。

区域导览

区域导览卡片

区域导览页展示了一个由各个区域导览卡片组成的可上下滑动的轮播图，效果如图所示：

轮播效果是 Stack 组件结合拖动手势来实现的，根据手势拖动的距离来判断是否需要切换图片，同时根据手势拖动的方向来决定是切换到上一张还是下一张图片。在图片切换的过程中，会根据图片和最上层图片的下标的差值，来计算它的模糊度、透明度、纵向偏移量、宽度等属性值。

在区域导览页点击跳转到区域详情页时，使用 pageTransition 函数实现了界面跳转过程中的动画效果，效果如图所示：

为实现图中效果，需要在区域导览所在的 @Entry 界面和详情页所在的 @Entry 界面里使用 pageTransition 函数来改变他们入场和出场时的方向、缩放大小和透明度等。

区域详情页

区域详情页包括首图轮播、滑动缩放、标题吸顶以及图片查看等功能，效果如图所示：

首先通过 imageHeight 属性设置轮播的启用与禁用，imageHeight 为全屏时轮播启用，左右滑动可以查看不同区域的介绍信息，当 imageHeight 小于全屏时轮播禁用。

查看大图

在区域详情页的“设计风格”部分，提供了一个可以左右滑动查看的图库，展示了该区域的建筑风貌。点击当前展示的图片，将打开可以查看大图的弹窗，可以左右滑动查看对应图片的高清大图，支持双指缩放和拖动。

小火车

小火车模块提供了溪村小镇小火车的相关信息，主要功能如下：

1. 查看溪村小火车三条路线的概览图。
2. 点击对应路线展示当前时间每条路线上小火车运营状态、时刻表、所在的位置、运动方向、及实时运动轨迹。