一、核心装饰器

1. @Entry 标记页面入口组件，应用启动时默认渲染该组件对应的页面，一个页面文件通常仅有一个入口组件。
2. @Component 标记结构体为自定义 UI 组件，支持复用与嵌套，是 ArkTS 声明式 UI 的基本单元。
3. @State 状态装饰器，被其标记的变量为页面状态数据；变量值发生变化时，框架会自动刷新所有依赖该变量的 UI 元素，实现「数据驱动视图」。

二、基础布局组件

1. Column 垂直线性布局容器，子元素沿竖直方向排列；可通过space参数设置子元素之间的间距。
2. Row 水平线性布局容器，子元素沿水平方向排列，常用来实现「文字 + 开关」「图标 + 文本」等横向组合布局。

三、常用 UI 组件与事件

1. Text：文本展示组件，可通过fontSize、fontColor、textAlign等属性设置文本样式。
2. TextInput：文本输入框组件，placeholder设置占位提示，onChange事件监听输入内容变化。
3. Toggle：切换组件，通过type可设置为开关（Switch）、复选框（Checkbox）等样式，onChange事件监听状态切换。

四、声明式开发核心原则

二、布局容器与布局规则

布局容器用于组织子元素的排列方式，是页面结构的基础骨架。

三、常用基础组件与核心属性

1. Text 文本组件

用于展示静态 / 动态文本内容，核心属性：

2. TextInput 文本输入框

用于接收用户文本输入，核心属性与能力：

3. Toggle 切换组件

通用切换组件，支持三种样式，核心能力：

4. Button 按钮组件

用于承载点击交互，核心能力：

四、状态管理核心机制

五、事件处理体系

六、样式与尺寸体系

七、动态 UI 实现范式

三元表达式是声明式 UI 中实现动态效果的核心语法，格式为条件 ? 取值A : 取值B，可用于几乎所有组件属性：

八、声明式开发规范与最佳实践

1. 状态驱动 UI：仅修改状态变量，无需手动操作控件，框架自动完成界面刷新。
2. 链式调用：组件的样式、事件均通过.属性名()的方式链式配置，代码结构清晰直观。
3. 动态属性：可通过三元表达式让组件属性随状态动态变化，一个状态可同时控制多处 UI 表现。

   一、核心装饰器体系

   装饰器是 ArkTS 声明式 UI 的核心标识，用于标记组件、页面和状态，是框架识别代码逻辑的依据。

4. @Entry 标记页面入口组件，一个页面文件有且仅有一个入口组件；应用路由跳转或启动时，默认渲染该组件作为页面根节点。
5. @Component 标记一个结构体为自定义 UI 组件，是 ArkUI 的最小复用单元；支持嵌套组合，复杂页面可拆解为多个小组件拼接实现。
6. @State 组件内状态装饰器，是最基础的状态管理方式。
   • 被标记的变量为组件私有状态，仅在当前组件内可访问
   • 变量值发生变更时，框架自动触发build()方法重新执行，刷新所有依赖该变量的 UI 元素
   • 支持基础数据类型、对象、数组等多种数据类型的变更检测
7. Column 垂直线性布局 子元素沿竖直方向依次排列，主轴为垂直方向，交叉轴为水平方向；通过space参数可快速统一设置子元素之间的垂直间距。
8. Row 水平线性布局 子元素沿水平方向依次排列，主轴为水平方向，交叉轴为垂直方向；常用于实现「文字 + 开关」「图标 + 文本」等横向组合布局。
9. 嵌套布局 布局容器支持多层嵌套，是复杂页面的实现方式：外层大容器控制整体结构，内层小容器细化局部排列，例如Column内嵌套Row实现横向条目，再嵌套Column实现条目内的垂直排版。
10. 布局核心特性
    • 容器自身通过.width()、.height()设置尺寸，支持百分比、固定数值两种方式
    • 子元素默认沿主轴起始位置对齐，可通过alignItems调整交叉轴对齐方式
11. 内容绑定：支持直接传入字符串变量，实现文本动态更新
12. fontSize：设置字体大小，单位默认 vp（虚拟像素，自动适配屏幕密度）
13. fontColor：设置字体颜色，支持Color枚举、十六进制色值、0x 格式色值
14. textAlign：设置文本对齐方式，常用值TextAlign.Start（左对齐）、TextAlign.Center（居中）
15. text：绑定输入框的文本内容，配合状态变量可实现双向绑定
16. placeholder：输入框无内容时的占位提示文本
17. onChange：输入内容变化时触发回调，回调参数为最新输入值
18. 可通过.height()设置输入框高度，优化触控区域
19. 通过type参数指定类型：ToggleType.Switch（开关样式）、ToggleType.Checkbox（复选框样式）、ToggleType.Button（按钮样式）
20. onChange：切换状态变化时触发回调
21. 自身无状态，需配合@State变量记录开关状态
22. 构造参数直接传入按钮显示文本，支持动态绑定
23. onClick：点击事件回调，是最常用的交互事件
24. 自带默认按钮样式，可通过属性方法自定义背景、圆角、文字样式
25. 单状态多 UI 联动 一个@State状态变量可以同时控制多处 UI 表现，例如布尔变量isOpen可同时控制文本内容、背景颜色、按钮文字、开关状态，实现「一处数据变更，多处界面同步」。
26. 状态变更的最小化刷新 框架只会重新渲染依赖该状态的 UI 节点，而非整个页面全部重绘，保证了声明式 UI 的渲染性能。
27. 状态的单向数据流 声明式开发遵循「数据流向视图」的单向逻辑：永远只修改状态变量，不直接操作 UI 控件属性，由框架自动完成视图更新。
28. 变化类事件 onChange 适用于输入、切换类组件，如TextInput、Toggle；当组件的输入值、选中状态发生变化时触发，用于同步状态变量与组件状态。
29. 点击类事件 onClick 适用于按钮、可点击容器等组件，响应用户点击操作，是最基础的交互事件。
30. 回调函数规范 统一使用箭头函数写法，保证this指向当前组件实例，能够正常访问和修改@State状态变量。
31. 尺寸设置
    • 固定数值：单位默认 vp，例如.height(50)代表高度为 50vp
    • 百分比：字符串格式，相对于父容器尺寸，例如.width('100%')代表填满父容器宽度
32. 间距与内边距
    • space：布局容器专属，统一设置子元素之间的间距
    • padding：设置组件内边距，支持统一赋值（.padding(15)），也支持分方向赋值（.padding({top:15})）
33. 外观样式
    • backgroundColor：设置背景颜色，支持多种色值写法
    • borderRadius：设置圆角，数值越大圆角越明显，常用于实现卡片、按钮的圆角效果
34. 卡片布局技巧 通过给Column设置背景色、圆角、内边距，即可快速实现卡片式容器，是页面模块划分的常用手法。
35. 动态文本：根据状态切换显示内容，例如this.isOpen ? "已开启" : "已关闭"                              
36. 动态样式：根据状态切换颜色、尺寸等，例如切换背景色、切换字体颜色
37. 动态组件属性：控制组件的显示状态、可用状态等
38. 每个组件的build()方法有且仅有一个根容器组件，通常使用Column作为页面根布局。
39. 组件属性采用链式调用写法，紧贴对应组件，保证代码可读性；建议遵循「布局属性→样式属性→事件属性」的顺序排列。
40. 可变数据必须用@State等状态装饰器标记，普通变量变更不会触发 UI 刷新。
41. 复杂页面推荐拆分小组件，降低单组件代码复杂度，提升复用性与可维护性。
42. 长度优先使用 vp 单位，保证应用在不同分辨率设备上的视觉效果一致。