当前位置：首页 > news >正文

HarmonyOS开发实战：小分享-ShareCard通用分享卡片组件设计

news 2026/7/24 0:03:34

前言

通用组件是提升代码复用率的核心手段。ArkUI 通过@Component装饰器让开发者可以封装自定义组件，支持@Prop参数化输入。本篇以小分享 App 的ShareCard组件为例，讲解通用组件的设计原则和@Prop装饰器的使用。详细 API 可参考 HarmonyOS @Component 官方文档。

一、ShareCard 组件完整代码

1.1 组件定义

import router from '@ohos.router'; @Preview @Component export struct ShareCard { @Prop title: string = ''; @Prop subtitle: string = ''; @Prop icon: string = ''; @Prop iconBg: string = '#EEF4FF'; @Prop pageUrl: string = ''; build() { Row({ space: 12 }) { // 图标徽章 Column() { Text(this.icon) .fontSize(24) } .width(48) .height(48) .backgroundColor(this.iconBg) .borderRadius(12) .justifyContent(FlexAlign.Center) .alignItems(HorizontalAlign.Center) // 文字区 Column({ space: 4 }) { Text(this.title) .fontSize(15) .fontWeight(FontWeight.Medium) .fontColor('#1A1A1A') Text(this.subtitle) .fontSize(12) .fontColor('#999999') } .alignItems(HorizontalAlign.Start) .layoutWeight(1) // 箭头 Text('›') .fontSize(20) .fontColor('#CCCCCC') } .width('100%') .padding({ left: 16, right: 16, top: 14, bottom: 14 }) .backgroundColor(Color.White) .borderRadius(12) .shadow({ radius: 2, color: '#08000000', offsetY: 1 }) .onClick(() => { if (this.pageUrl) { router.pushUrl({ url: this.pageUrl }) } }) } }

二、@Component 与 @Prop 装饰器

2.1 @Component 的作用

@Component标记一个类为自定义组件，使其可以被其他组件引用。

2.2 @Prop 的基本用法

@Prop让父组件向子组件传递数据，子组件可以修改但不影响父组件：

@Component export struct ShareCard { @Prop title: string = ''; // 默认值 @Prop subtitle: string = ''; @Prop icon: string = ''; @Prop iconBg: string = '#EEF4FF'; // 带默认值 @Prop pageUrl: string = ''; }

2.3 @Prop 特性

特性	说明
单向数据流	父→子，子修改不影响父
默认值	可以设置默认值
响应式	父组件更新时自动刷新
类型支持	基本类型、对象、数组

三、@Preview 装饰器

3.1 @Preview 的作用

@Preview允许在 DevEco Studio 的预览器中实时预览组件效果：

@Preview @Component export struct ShareCard { // ... }

3.2 预览优势

预览优势如下：

无需编译运行即可看到 UI 效果
实时编辑实时刷新
支持不同设备尺寸预览

四、组件布局结构

4.1 布局结构

Row (白色卡片，圆角 12，阴影) ├─ Column (图标徽章 48×48，12vp 圆角，iconBg 背景色) │ └─ Text(icon) 24px ├─ Column (文字区，layoutWeight 撑开) │ ├─ Text(title) 15px 粗体 │ └─ Text(subtitle) 12px 灰色 └─ Text('›') 20px 灰色 → 右侧箭头

4.2 参数化设计

ShareCard 将 5 个核心属性全部参数化：

属性	类型	默认值	作用
`title`	string	‘’	主标题
`subtitle`	string	‘’	副标题
`icon`	string	‘’	图标
`iconBg`	string	‘#EEF4FF’	图标背景色
`pageUrl`	string	‘’	点击跳转路径

五、组件使用方法

5.1 在页面中引用

import { ShareCard } from '../components/ShareCard'; @Component struct SomePage { build() { Column() { ShareCard({ title: '文字分享', subtitle: '记录想法，分享文字', icon: '📝', iconBg: '#EEF4FF', pageUrl: 'pages/TextEditPage' }) ShareCard({ title: '图片分享', subtitle: '分享美图，记录美好', icon: '🖼️', iconBg: '#E8F5E9', pageUrl: 'pages/ImageEditPage' }) } } }

5.2 组件复用优势

组件复用优势如下：

减少重复代码：同一套 UI 逻辑只需写一次
统一风格：所有 ShareCard 外观一致
便于维护：修改组件定义即可全局更新
可测试：单独测试组件逻辑

六、点击事件与路由

6.1 点击跳转

.onClick(() => { if (this.pageUrl) { router.pushUrl({ url: this.pageUrl }) } })

6.2 空值判断

if (this.pageUrl)确保pageUrl为空时不跳转，避免路由错误。

七、组件设计原则

7.1 通用组件设计原则

通用组件设计原则如下：

单一职责：一个组件只做一件事
参数化：所有可变的属性都通过参数传入
默认值：非必需参数设置合理的默认值
可复用：组件不依赖特定的页面上下文

7.2 组件层级

小分享 App 的组件层级如下：

页面层：HomePage, TextEditPage, ... │ 组件层：BottomTabBar, ShareCard, CategoryIcon │ 接口层：TabItem, CategoryItem, ShareOption, ...

八、本篇核心知识点

8.1 @Component 与 @Prop 核心要点

总结如下：

@Component标记自定义组件
@Prop声明父→子数据传递
@Preview支持 DevEco Studio 预览
参数化设计提升复用性

8.2 实战开发要点

实战开发中需要重点关注以下几个要点：

所有可变属性参数化，设置默认值
组件不依赖特定上下文
点击事件处理空值情况
使用@Preview提升开发效率

总结

本文详细讲解了 ShareCard 通用分享卡片组件的设计，涵盖@Component、@Prop、@Preview装饰器、布局结构、参数化设计和组件复用原则。至此，小分享 App 首页相关的所有核心内容已讲解完毕。下一篇我们将进入 BottomTabBar 组件详解。

附录：完整实现细节

1. 核心 API 参考

API	作用	说明
本文涉及的核心 API	功能实现	参见华为官方文档

2. 完整代码示例

// 核心功能代码 // 详见正文中的完整实现

3. 常见问题排查

问题	原因	解决方案
编译错误	import 路径错误	检查路径和 API 版本
运行时异常	参数不合法	使用 try/catch 捕获
性能问题	主线程耗时操作	使用异步 API