鸿蒙（Harmony）开发备忘录-2020606

丝雨花开

199人浏览 · 2026-01-21 15:56:08

丝雨花开 · 2026-01-21 15:56:08 发布

装饰器：

一、组件与页面装饰器

装饰器	说明
@Component	标记一个struct为自定义组件，是UI构建的基本单元
@Entry	标记当前组件为页面的入口点，一个页面有且仅有一个
@Builder	定义自定义构建函数，用于封装可复用的UI片段
@BuilderParam	引用@Builder定义的函数，实现组件插槽/模板化能力
@CustomDialog	标记一个组件为自定义弹窗
@Reusable	标记组件为可复用组件，配合reuseId提升列表性能

二、状态管理装饰器（V1 版本）

装饰器	说明
@State	组件内部状态，变量变化时自动刷新UI
@Prop	父→子单向数据传递，子组件可修改但不影响父组件
@Link	父子双向同步，变量变化会同步回父组件
@Provide	在组件树中提供数据，供后代组件使用
@Consume	接收祖先组件通过@Provide提供的数据
@Observed	装饰类，使其属性变化可被@ObjectLink感知
@ObjectLink	装饰@Observed类的对象，实现深层数据绑定
@Watch	监听状态变量变化，变化时触发自定义回调
@StorageProp	组件变量与AppStorage属性单向绑定
@StorageLink	组件变量与AppStorage属性双向绑定
@LocalStorageProp	组件变量与LocalStorage属性单向绑定
@LocalStorageLink	组件变量与LocalStorage属性双向绑定

三、状态管理装饰器（V2 版本）

装饰器	说明
@ObservedV2	V2版类装饰器，支持属性级观察
@Trace	标记类中的属性为可观察状态（需配合@ObservedV2）
@Local	组件内部状态，类似V1的@State，但性能更优
@Param	父→子单向传递，类似V1的@Prop
@Event	子→父事件回调，用于子组件向父组件传递数据
@Provider	提供数据给后代组件（V2版）
@Consumer	消费祖先组件提供的数据（V2版）
@Monitor	监听状态变量变化，类似V1的@Watch
@Computed	定义计算属性，依赖的状态变化时自动重新计算

四、样式与扩展装饰器

装饰器	说明
@Styles	定义可复用的样式函数，避免重复写属性配置
@Extend	扩展系统组件的样式，可添加自定义属性
@AnimatableExtend	扩展组件的可动画属性，实现自定义动画效果

五、并发与工具装饰器

装饰器	说明
@Concurrent	标记函数可在并发线程中执行
@Sendable	标记类或函数可在线程间安全传递（ArkTS并发模型）

补充说明

装饰器V1vsV2 选择： V2状态管理（@ObservedV2、@Trace等）提供了更精细的属性级观察，性能更优，推荐新项目使用。V1和V2不能混用在同一组件树中。
装饰器使用限制：@Entry、@Component、@Builder等是ArkUI声明式开发的基础，所有自定义组件必须使用@Component装饰。
版本支持：@Reusable、@AnimatableExtend、@Computed等装饰器需要较新版本的API（API 11+），请根据您的项目目标版本确认支持情况。

组件

六、ArkUI 容器组件

容器组件	核心用途
Column / Row	最基础的线性布局容器，分别用于纵向（Column）和横向（Row）排列子组件，支持主轴与交叉轴对齐方式。
Flex	增强版线性布局，支持子组件按比例伸缩（flexGrow / flexShrink），适合导航栏、等分栏等需要动态分配空间的场景。
Stack	层叠布局，子组件可叠加放置，常用于悬浮按钮、图片上叠加文字或图标等效果。
RelativeContainer	相对布局容器，允许子组件通过锚点（如对齐父容器边缘或兄弟组件边缘）进行二维定位，减少嵌套层级。
Grid	网格布局，通过 columnsTemplate / rowsTemplate 定义行列数及比例，支持响应式列数切换，适合商品列表、日历等二维数据展示。
List	高效滚动列表容器，支持长列表的懒加载、分组、粘性头部，适合聊天记录、设置页等场景。可配合 lanes 属性实现多列列表。
WaterFlow	瀑布流布局容器，支持动态切换列数，适合图片流、笔记应用等高度不一致的重复内容展示。
Swiper	轮播容器，支持子组件横向或纵向滑动切换，常应用于首页 Banner、引导页、图片轮播。
Tabs	标签页容器，提供底部/侧边导航切换能力，适合设置分类、资讯频道等需要保持导航可见的页面。
SideBarContainer	侧边栏容器，支持主内容区与侧边栏的分栏布局，在折叠屏或平板场景下可自动切换显隐状态。
Navigation	导航容器，支持单栏/双栏布局模式，结合 SideBarContainer 可实现三分栏（如邮件类应用）。
GridRow / GridCol	栅格布局组件，基于断点机制实现响应式列数调整，常用于图文混排、表单等需要精细控制列宽的场景。
ContainerReader	容器断点组件，基于容器自身尺寸（而非窗口尺寸）提供实时尺寸和断点信息，支持宽度/高度双模式，适合组件级自适应布局。
Scroll	可滚动容器，支持横向或纵向滚动，常作为 List、Grid 等组件的父容器，或用于包裹内容超出屏幕的普通组件。
Refresh	下拉刷新容器，包裹可滚动组件（如 List、Scroll）后提供下拉刷新交互能力。
Counter	计数器容器，用于实现数字增减操作，常用于购物车数量选择等场景。

七、列表与网格容器

在 ArkUI 中，列表与网格相关的容器组件主要用于展示同类或不同类的项目集合，支持滚动、分组、拖拽等交互。以下是核心组件及其用途：

组件	核心用途与特性
List	单列或多列等宽列表容器，适合通讯录、音乐列表等场景。支持项目吸顶（sticky属性）、拖拽排序（含内置动画和边缘自动滚动）、项目横滑（swipeAction属性）以及分割线。可通过 ListItemGroup 实现分组，结合 LazyForEach 或 Repeat 实现懒加载。
Grid	二维网格布局容器，子组件为 GridItem。支持通过 rowsTemplate 和 columnsTemplate 定义行列数量与尺寸占比（如 ‘1fr 1fr 1fr’），也可通过 GridLayoutOptions 实现单个网格跨行跨列（如计算器按键布局）。仅设置行或列模板时，Grid 可滚动。适用于九宫格图片、日历等场景。
WaterFlow	瀑布流布局容器，适合高度不一致的卡片列表（如商品流、图片墙）。支持通过 columnsTemplate 设置列数，通过 WaterFlowSections 实现同一页面内不同列数的分段混合布局。不支持吸顶、拖拽排序或横滑。
ArcList	专为圆形屏幕设备设计的弧形列表，支持列表项在接近屏幕上下两端时自动缩放，适用于智能手表等圆形穿戴设备。
LazyVGridLayout / LazyVWaterFlowLayout	懒加载布局容器，嵌套在可滚动父组件（如 Scroll、List、WaterFlow）内部，按需加载可视区域内的子组件，减少首帧渲染和内存开销。LazyVGridLayout 提供垂直网格布局，LazyVWaterFlowLayout 提供垂直瀑布流布局，可组合使用实现混合布局（如电商首页同时包含网格分类和瀑布流商品）。
Scroll	通用可滚动容器，可包裹任意内容（包括 Grid、WaterFlow 等），支持横向或纵向滚动。常与 Refresh 容器配合实现下拉刷新。
Refresh	下拉刷新容器，包裹可滚动组件（如 List、Scroll）后提供下拉刷新交互。

八、基础组件

HarmonyOS ArkTS 中常用的基础组件用于构建 UI 的基本元素，如文本、输入框、图片、按钮等。

组件	核心用途与特性
Text	显示一段文本的组件，支持设置字体大小、颜色、样式（如加粗、斜体）、对齐方式、行高、文本溢出处理等属性。
Span	Text 组件的子组件，用于实现行内文本的混合样式（如部分文字加粗、变色、添加超链接），支持嵌套使用。
TextInput	单行文本输入框组件，支持设置占位符、输入类型（如密码、数字）、最大长度、光标样式、输入事件监听等。
TextArea	多行文本输入框组件，支持设置行数、占位符、最大长度、滚动条、输入事件监听等，适用于长文本输入场景。
Image	图片组件，支持加载本地资源、网络图片、Base64 编码数据等，可设置缩放模式、占位图、失败图、边框圆角等属性。
Button	按钮组件，支持多种样式（如胶囊、圆形、文本按钮）、状态（默认、按下、禁用）、子组件（可包含图标和文字）以及点击事件。
Blank	空白填充组件，在 Row 或 Column 布局中自动填充剩余空间，用于实现弹性间距或占位。
LoadingProgress	加载进度指示器组件，用于展示加载中的状态，支持环形和线性两种样式，可自定义颜色和尺寸。

九、媒体展示组件

媒体展示组件用于在界面中呈现图片、视频等多媒体内容，并提供交互能力。

组件名称	描述	主要用途
Image	用于显示图片的基础组件，支持本地图片、网络图片和资源文件。	图片展示、图标显示、背景图等。
Video	用于播放视频的组件，支持本地视频、网络流媒体（如HLS、DASH），集成了播放控制、全屏切换等功能。	视频播放、直播流展示。
Swiper	滑块视图容器，提供轮播图能力，支持自动播放、循环滑动、导航指示器自定义。	广告轮播、图片浏览、引导页。
ArcSwiper	弧形滑块视图容器，提供弧形排列的轮播效果。	弧形卡片展示、个性化轮播。
UIMediaPreview	第三方多媒体预览组件，支持传入URL数组，以默认或宫格样式展示图片和视频，并支持全屏预览、缩放、下载。	图片/视频预览、多媒体内容浏览。

十十、按钮与选择的组件的组件用于响应用户的点击、切换和选择操作，是构建交互式界面的核心元素。

组件名称	描述
Button	基础按钮组件，用于响应用户的点击操作，支持多种样式和子组件。
ArcButton	弧形按钮组件，专为圆形屏幕（如穿戴设备）设计，提供强调、普通、警告等样式。
Radio	单选框组件，提供一组互斥的选项，用户只能选择其中一项。
Toggle	切换按钮组件，支持勾选框、状态按钮和开关三种样式，用于两种状态之间的切换。
Select	下拉选择菜单组件，提供下拉列表让用户在多个选项间选择，选中后按钮文本自动更新。
Checkbox	多选框组件，允许用户从一组选项中选择多个项。
Slider	滑动条组件，允许用户通过滑动滑块在连续范围内选择一个值。
DatePicker	日期选择器组件，提供日历视图让用户选择年、月、日。
TimePicker	时间选择器组件，提供滚轮视图让用户选择时、分、秒。
Menu	菜单组件，在指定位置弹出菜单项列表，供用户选择执行操作。

HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

灯光模拟HarmonyOS应用实战-16-重置灯光、重开考试和返回首页时要清掉哪些状态

HarmonyOS开发者社区

鸿蒙开发ArkData用户首选项实战：从夜间模式到多进程配置的完整案例

用户首选项（Preferences）是 ArkData 里最轻量的存储，但用得最频繁——几乎每个应用都要存配置。下面用一个"应用设置中心"的完整案例，把读写、订阅、存储模式选择、容易出问题的点全过一遍。

HarmonyOS开发者社区

鸿蒙ArkData键值型数据库实战：Schema 定义与商品库存同步案例

Schema 是 KV-Store 里一个容易被忽略的概念。它定义了 Value 的字段结构、类型、索引。数据有约束，写入不合规数据会被拦截建了索引，查询更快分布式同步时，两端 Schema 一致才能正确同步console.info('KVManager 未初始化');return;try {// 定义字段节点// 组装 Schema// 索引路径// 1 表示 STRICT 严格模式，0 表示