�� 所属专栏：HarmonyOS NEXT 零基础实战教程
�� 适配版本：HarmonyOS 6.1.0（API23）/ DevEco Studio 最新版 / Stage模型
✅ 难度等级：新手入门 · UI组件与资源开发实战
�� 前言
对于鸿蒙NEXT新手来说，枯燥的API背诵、基础布局练习很难快速建立开发信心。想要快速掌握ArkUI组件化开发、资源统一管理、渐变视觉美化、状态响应式更新，天气卡片是绝佳的入门实战项目。
区别于复杂的网络请求、数据解析类项目，本案例无需第三方依赖、无需权限配置，纯粹聚焦鸿蒙基础UI布局、组件封装、资源解耦、生命周期原理四大核心知识点。通过极简的代码实现高颜值渐变天气卡片，帮新手快速吃透鸿蒙原生UI开发核心逻辑，掌握商用级页面美化技巧。
本文将从零带大家搭建完整天气卡片项目，手把手完成项目配置、资源适配、页面布局、状态绑定、生命周期调试，零基础可直接复刻，快速上手鸿蒙可视化开发！
一、项目核心亮点与学习价值
1.1 项目成品效果亮点
本次开发的天气卡片摒弃简陋原生布局，对标主流移动端UI设计，实现精致商用级视觉效果：
- 渐变视觉卡片：蓝系渐变底色+柔和阴影，打造立体悬浮质感，告别扁平单调页面
- 规范层级布局：温度、城市、天气状态、详情数据层级清晰，视觉主次分明
- 精细化样式适配：统一圆角、字号、配色体系，符合鸿蒙现代UI设计规范
- 弹性自适应布局：基于权重布局实现数据均分展示，适配全系鸿蒙手机设备
- 标准化资源管理：颜色、尺寸、字符串全部抽离资源文件，支持快速迭代与国际化
1.2 新手核心学习价值
本项目专为鸿蒙零基础开发者设计，精准覆盖新手必学核心知识点，规避新手开发陋习：
- 掌握组件化思维：理解@Component、@Entry核心装饰器用法，学会页面组件封装
- 吃透响应式状态管理：熟练使用@State实现数据与UI双向联动更新
- 规范资源开发规范：告别代码硬编码，掌握color/float/string资源分层管理
- 精通基础布局体系：熟练运用Column/Row弹性布局、权重分配、居中适配
- 理解应用生命周期：掌握UIAbility完整生命周期，明白应用启动、前台、后台、销毁完整流程
- 掌握日志调试技巧：学会使用hilog系统日志，快速排查项目报错问题
二、项目创建与整体结构解析
2.1 新建标准鸿蒙项目
- 打开DevEco Studio，选择 Create HarmonyOS Project 新建项目
- 选择Empty Ability 纯净空白模板，无冗余代码
- 自定义项目名称，API版本选择 API23，适配最新鸿蒙系统
- 工程模型选择 Stage模型，开发语言选择 ArkTS
- 等待项目初始化完成，清理默认模板冗余代码，保证工程整洁
2.2 完整工程目录结构
本项目采用鸿蒙官方标准目录结构，严格区分全局资源、模块配置、业务代码，结构清晰、便于后续拓展维护：
|
plain text
muban23/
├── AppScope/ # 全局应用级配置与资源
│ ├── app.json5 # 应用全局清单配置
│ └── resources/base/ # 全局媒体、字符串资源
│
├── entry/ # 主入口业务模块
│ ├── module.json5 # 模块能力、路由配置
│ └── src/main/
│ ├── ets/ # 核心业务代码目录
│ │ ├── entryability/ # 应用生命周期管理
│ │ │ └── EntryAbility.ets
│ │ └── pages/
│ │ └── Index.ets # 天气卡片核心UI页面
│ └── resources/ # 模块级资源文件
│ ├── base/ # 通用适配资源
│ │ ├── element/ # 颜色、尺寸、字符串资源
│ │ └── profile/ # 路由、配置文件
│ └── dark/ # 暗色模式适配资源
│
└── 项目全局构建配置文件 |
三、核心配置文件详解（零基础必懂）
3.1 应用全局配置 app.json5
该文件是整个应用的核心配置文件，定义应用唯一标识、版本、图标、名称等全局属性，是应用打包、安装、发布的核心依据。
|
json
{
"app": {
"bundleName": "com.example.muban23",
"vendor": "example",
"versionCode": 1000000,
"versionName": "1.0.0",
"buildVersion": "1",
"icon": "$media:layered_image",
"label": "$string:app_name"
}
} |
核心参数解读：bundleName为应用唯一标识，必须全局唯一，企业开发统一采用域名倒写格式，避免发布冲突；versionCode用于版本迭代更新判断，versionName为用户可见展示版本号。
3.2 模块配置 module.json5
模块配置文件负责定义主启动能力、设备适配、页面路由、扩展能力等核心模块属性，是页面正常加载运行的关键。
|
json
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": ["phone"],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"entities": ["entity.system.home"],
"actions": ["ohos.want.action.home"]
}
]
}
],
"extensionAbilities": [
{
"name": "EntryBackupAbility",
"srcEntry": "./ets/entrybackupability/EntryBackupAbility.ets",
"type": "backup",
"exported": false,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
]
}
]
}
} |
3.3 页面路由配置 main_pages.json
路由配置文件用于管理应用所有页面路径，数组第一个路径为应用默认首页，框架会自动补全文件后缀，无需手动填写。
|
json
{
"src": [
"pages/Index"
]
} |
四、标准化资源体系搭建
鸿蒙开发核心规范：样式、文本、尺寸全部抽离资源文件，代码只负责业务与布局，彻底杜绝硬编码，方便适配多设备、多语言、多主题。
4.1 颜色资源 color.json
定制天气卡片专属蓝系渐变配色，搭配深浅对比文本色，视觉清爽、层次分明，适配日间主流UI风格。
|
json
{
"color": [
{ "name": "start_window_background", "value": "#FFFFFF" },
{ "name": "weather_card_bg_start", "value": "#4A90D9" },
{ "name": "weather_card_bg_end", "value": "#7EC8E3" },
{ "name": "weather_text_primary", "value": "#FFFFFF" },
{ "name": "weather_text_secondary", "value": "#E0F0FF" },
{ "name": "weather_detail_bg", "value": "#33FFFFFF" }
]
} |
4.2 尺寸资源 float.json
统一规范字号、圆角、间距尺寸，区分fp/vp适配单位，完美适配不同分辨率鸿蒙设备。
|
json
{
"float": [
{ "name": "page_text_font_size", "value": "50fp" },
{ "name": "weather_temp_font", "value": "64fp" },
{ "name": "weather_city_font", "value": "24fp" },
{ "name": "weather_desc_font", "value": "18fp" },
{ "name": "weather_detail_font", "value": "16fp" },
{ "name": "weather_icon_font", "value": "48fp" },
{ "name": "weather_card_radius", "value": "32vp" },
{ "name": "weather_card_padding", "value": "24vp" },
{ "name": "weather_detail_radius", "value": "16vp" }
]
} |
单位规范：fp用于字体大小，跟随系统字体设置自适应；vp用于间距、圆角、布局尺寸，适配设备像素密度，杜绝适配错乱问题。
4.3 字符串资源 string.json
所有展示文本统一托管，便于后续国际化翻译、文本统一修改，符合商用开发规范。
|
json
{
"string": [
{ "name": "module_desc", "value": "module description" },
{ "name": "EntryAbility_desc", "value": "description" },
{ "name": "EntryAbility_label", "value": "label" },
{ "name": "weather_title", "value": "Weather" },
{ "name": "weather_city", "value": "Beijing" },
{ "name": "weather_temp", "value": "28°C" },
{ "name": "weather_desc", "value": "Sunny" },
{ "name": "weather_humidity", "value": "Humidity" },
{ "name": "weather_wind", "value": "Wind" },
{ "name": "weather_humidity_val", "value": "60%" },
{ "name": "weather_wind_val", "value": "12 km/h" }
]
} |
五、核心UI天气卡片开发（Index.ets）
页面采用组件化+响应式状态管理开发，通过@State绑定天气数据，Column+Row嵌套弹性布局，搭配渐变、阴影、圆角实现高颜值视觉效果，代码结构清晰、可复用性极强。
|
typescript
@Entry
@Component
struct WeatherCard {
// 响应式状态数据：数据更新自动刷新UI
@State city: string = 'Beijing';
@State temperature: string = '28°C';
@State description: string = 'Sunny';
@State humidity: string = '60%';
@State windSpeed: string = '12 km/h';
// 天气图标Emoji
private weatherIcon: string = '\u2600\uFE0F';
build() {
// 根页面容器
Column() {
// 核心天气卡片容器
Column() {
// 天气图标
Text(this.weatherIcon)
.fontSize($r('app.float.weather_icon_font'))
.textAlign(TextAlign.Center)
// 核心温度展示
Text(this.temperature)
.fontSize($r('app.float.weather_temp_font'))
.fontColor($r('app.color.weather_text_primary'))
.fontWeight(FontWeight.Bold)
.textAlign(TextAlign.Center)
.margin({ top: 4 })
// 天气状态描述
Text(this.description)
.fontSize($r('app.float.weather_desc_font'))
.fontColor($r('app.color.weather_text_secondary'))
.textAlign(TextAlign.Center)
.margin({ top: 8 })
// 城市名称
Text(this.city)
.fontSize($r('app.float.weather_city_font'))
.fontColor($r('app.color.weather_text_primary'))
.fontWeight(FontWeight.Medium)
.textAlign(TextAlign.Center)
.margin({ top: 16 })
// 装饰分隔线
Divider()
.width('60%')
.color($r('app.color.weather_detail_bg'))
.height(1)
.margin({ top: 20, bottom: 20 })
// 湿度、风速详情横向布局
Row() {
// 湿度模块
Column() {
Text('\uD83D\uDCA7')
.fontSize(20)
Text($r('app.string.weather_humidity'))
.fontSize($r('app.float.weather_detail_font'))
.fontColor($r('app.color.weather_text_secondary'))
.margin({ top: 4 })
Text(this.humidity)
.fontSize($r('app.float.weather_detail_font'))
.fontColor($r('app.color.weather_text_primary'))
.fontWeight(FontWeight.Medium)
}
.layoutWeight(1)
.alignItems(HorizontalAlign.Center)
// 垂直分隔线
Divider()
.height('80%')
.width(1)
.color($r('app.color.weather_detail_bg'))
.margin({ left: 12, right: 12 })
// 风速模块
Column() {
Text('\uD83C\uDF2C\uFE0F')
.fontSize(20)
Text($r('app.string.weather_wind'))
.fontSize($r('app.float.weather_detail_font'))
.fontColor($r('app.color.weather_text_secondary'))
.margin({ top: 4 })
Text(this.windSpeed)
.fontSize($r('app.float.weather_detail_font'))
.fontColor($r('app.color.weather_text_primary'))
.fontWeight(FontWeight.Medium)
}
.layoutWeight(1)
.alignItems(HorizontalAlign.Center)
}
.width('100%')
.padding({ top: 12, bottom: 8 })
}
.width('85%')
.padding($r('app.float.weather_card_padding'))
// 卡片渐变背景
.linearGradient({
direction: GradientDirection.RightBottom,
colors: [
[$r('app.color.weather_card_bg_start'), 0.0],
[$r('app.color.weather_card_bg_end'), 1.0]
]
})
// 卡片阴影效果，打造悬浮质感
.shadow({
radius: 24,
color: 0x334A90D9,
offsetX: 0,
offsetY: 8
})
.borderRadius($r('app.float.weather_card_radius'))
.alignItems(HorizontalAlign.Center)
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
.backgroundColor('#F0F4F8')
}
} |
5.1 核心技术点解析
- 响应式状态更新：通过@State修饰天气数据，数据变更自动触发UI局部刷新，高效且性能优异
- 渐变背景适配：采用右下方向渐变，同色系深浅过渡，视觉柔和高级，适配现代UI审美
- 悬浮阴影设计：基于主色调设置透明阴影，贴合卡片配色，避免阴影突兀，打造立体悬浮效果
- 权重弹性布局：通过layoutWeight实现湿度、风速模块均分宽度，自适应任意屏幕尺寸
- 资源统一引用：所有样式、文本均通过$r()引用资源，完全解耦业务代码与样式资源
六、UIAbility生命周期与日志调试
UIAbility是鸿蒙应用的核心运行单元，掌控应用从启动、前台展示、后台驻留到销毁的完整生命周期，是新手必须掌握的核心原理。
6.1 完整生命周期代码实现
|
typescript
import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';
const DOMAIN = 0x0000;
export default class EntryAbility extends UIAbility {
// 应用进程创建，仅执行一次
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
// 设置应用配色跟随系统主题
try {
this.context.getApplicationContext().setColorMode(
ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET
);
} catch (err) {
hilog.error(DOMAIN, 'testTag',
'Failed to set colorMode. Cause: %{public}s', JSON.stringify(err));
}
}
// 窗口舞台创建，加载首页
onWindowStageCreate(windowStage: window.WindowStage): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(DOMAIN, 'testTag',
'Failed to load the content. Cause: %{public}s', JSON.stringify(err));
return;
}
hilog.info(DOMAIN, 'testTag', 'Succeeded in loading the content.');
});
}
// 应用切换前台，页面可见
onForeground(): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
}
// 应用切换后台，页面不可见
onBackground(): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
}
// 窗口销毁
onWindowStageDestroy(): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
}
// 应用进程销毁，释放资源
onDestroy(): void {
hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
}
} |
6.2 生命周期执行顺序
应用启动：onCreate → onWindowStageCreate → onForeground
应用退后台：onBackground
应用重回前台：onForeground
应用退出：onWindowStageDestroy → onDestroy
七、项目运行与问题排查
7.1 运行环境要求
- 系统版本：HarmonyOS NEXT 6.1.0（API23）
7.2 快速运行步骤
- 打开项目，等待Gradle依赖自动同步完成
- 连接真机（开启开发者模式）或启动模拟器
- 点击顶部运行按钮或快捷键Shift+F10启动项目
- 查看底部Log面板，核对生命周期日志输出，验证项目运行状态
7.3 常见报错解决方案
|
问题现象 |
解决方案 |
|
页面空白无内容 |
核对main_pages.json路由路径是否正确，文件名大小写统一 |
|
资源引用报错 |
检查资源文件名、属性名拼写，确保与代码引用一致 |
|
项目构建失败 |
执行Clean Build清理缓存，重新同步依赖构建 |
|
模拟器启动失败 |
检查并安装HVD模拟器插件，重启DevEco Studio |
八、项目拓展与进阶方向
基础静态天气卡片完成后，可自主迭代升级，打造完整商用天气应用：
- 动态天气切换：根据天气状态自动切换图标、背景色（晴/阴/雨/雪）
- 网络数据对接：接入公开天气API，实现实时城市天气数据获取
- 多城市切换：新增城市选择功能，支持多城市天气切换查看
- 深色模式适配：完善暗色模式资源，实现昼夜主题一键切换
- 动画交互优化：新增卡片入场动画、点击缩放反馈，提升交互质感
- 数据持久化：通过Preferences缓存最近查看的天气数据
九、项目总结
本天气卡片项目是鸿蒙NEXT零基础UI开发的标杆入门案例，区别于碎片化的知识点学习，本项目完整串联了「项目配置-资源管理-布局开发-状态更新-生命周期调试」全流程开发逻辑。
通过本项目实战，你将彻底掌握：ArkTS组件化开发思想、@State响应式状态管理、鸿蒙标准化资源开发规范、弹性自适应布局、渐变与阴影视觉美化、UIAbility生命周期原理与日志调试。
该项目代码规范、拓展性极强，既能帮助新手夯实鸿蒙UI开发基础，也可作为个人练手项目、课程设计、入门作品集，为后续复杂鸿蒙应用开发筑牢核心能力！
点赞+收藏+订阅专栏，持续更新更多鸿蒙NEXT零基础架构级实战项目！
10
0
已为社区贡献2条内容
所有评论(0)