目录
一、引言：ArkUI 自定义组件的魅力开场
在 HarmonyOS 应用开发的广袤天地中，ArkUI 作为强大的声明式 UI 框架，为开发者们提供了构建精美界面的有力工具。想象一下，你正在开发一款电商应用，其中商品列表页面和订单列表页面都需要一个带有特定样式的标题栏。如果每次都重新编写标题栏的代码，不仅繁琐，还容易出错，且后期维护成本极高。此时，ArkUI 自定义组件就如同救星一般登场。
通过自定义组件，我们可以将标题栏的样式和逻辑封装起来，只需在不同页面中引用这个组件，并传入不同的标题文本等参数，就能轻松实现复用，极大地提高了开发效率，减少了重复代码。这就好比拥有了一个万能模板，只要根据不同需求填入不同内容，就能快速产出符合要求的成果。
而在自定义组件的使用过程中，参数规定起着至关重要的作用。它就像是组件与外界沟通的桥梁，决定了组件如何接收和处理外部传入的数据，直接影响着组件的灵活性和复用性。所以，深入了解 ArkUI 自定义组件的参数规定，是我们充分发挥自定义组件优势，打造高效、优质 HarmonyOS 应用的关键一步 。
二、自定义组件初相识
在 ArkUI 的世界里，组件是构建用户界面的基石，就如同搭积木时的一块块积木。其中，自定义组件是开发者根据特定需求亲手打造的 “积木” ，与框架直接提供的系统组件（如 Text、Button、Image 等）有着明显区别。
系统组件就像是标准化生产的通用积木，它们具有固定的功能和样式，能满足常见的 UI 构建需求。例如，Button 组件，只要使用它，就自带基本的点击交互功能和默认样式，开发者无需从头实现这些基础功能。而自定义组件则像是按照独特设计图纸，将这些通用积木重新组合、加工而成的特殊积木。它可以整合多个系统组件，添加特定的业务逻辑，以实现一些系统组件无法直接达成的复杂功能。
以电商应用中的商品展示卡片为例，系统组件里没有现成的能完全符合商品展示需求的组件，它可能需要将 Image（展示商品图片）、Text（展示商品名称、价格、描述等信息）以及一些可能的 Button（如加入购物车按钮）等系统组件进行组合，并添加点击商品图片放大预览、点击加入购物车按钮触发添加到购物车逻辑等业务逻辑。此时，自定义组件就派上用场了，通过自定义组件，开发者可以将这些功能和样式封装起来，形成一个独立的商品展示卡片组件，方便在不同的商品展示页面中复用。
在复杂 UI 开发中，自定义组件的作用更是不可替代。随着应用功能日益丰富，界面复杂度不断提高，如果全部依赖系统组件，代码量会迅速膨胀，变得难以维护和管理。自定义组件可以将复杂的 UI 结构和相关逻辑封装成一个个独立的模块，使得代码结构更加清晰，开发者可以专注于每个组件的功能实现，而无需在多个页面中重复编写相似的代码。同时，当某个组件的样式或功能需要修改时，只需在自定义组件内部进行调整，而不会影响到其他部分的代码，大大提高了代码的可维护性和可扩展性 。
三、参数规定大揭秘
（一）参数的基本类型与限制
在 ArkUI 自定义组件中，参数支持多种基本数据类型，这为开发者提供了丰富的数据处理选择 。常见的基本数据类型包括：
- 数值类型：如number，可用于表示各种数值，像商品价格、数量等。例如，在一个商品展示组件中，number类型的参数可以用来传递商品的价格，@Component struct ProductDisplay {@Prop price: number; build() { Text(价格: ${this.price}) } } 。
- 字符串类型：string用于传递文本信息，比如组件的标题、描述等。以一个标题栏组件为例，@Component struct TitleBar {@Prop title: string; build() { Text(this.title).fontSize(20) } } ，这里的title参数就是string类型，用于显示不同的标题内容。
- 布尔类型：boolean通常用于控制组件的某些状态或行为，比如控制一个开关组件的开启或关闭状态 。@Component struct SwitchComponent {@Prop isOn: boolean; build() { // 根据isOn的值显示不同的UI } } 。
- 枚举类型：enum能定义一组命名常量，使代码更具可读性和可维护性。比如在一个选择组件中，定义一个枚举来表示不同的选项类型 。enum OptionType { OPTION_ONE, OPTION_TWO, OPTION_THREE } @Component struct SelectComponent {@Prop option: OptionType; build() { // 根据option的值显示相应的选项内容 } } 。
在使用这些基本类型作为参数时，必须严格匹配声明类型，这是确保组件正常运行的关键。例如，如果一个组件声明接受number类型的参数，就不能传入string类型的值。同时，不允许使用undefined、null作为参数值，也不允许传入返回undefined、null的表达式。这是因为undefined和null可能会导致组件在处理参数时出现异常，影响组件的功能和稳定性。比如，在一个计算组件中，如果意外传入undefined作为数值参数，计算逻辑就会出错 。
（二）状态变量与参数传递
状态变量在参数传递中扮演着至关重要的角色，它是实现数据驱动 UI 刷新的核心机制 。简单来说，状态变量就像是一个 “数据源头”，当它的值发生变化时，与之关联的 UI 部分会自动更新，从而实现界面的动态交互效果。
我们来看一个实际案例，假设我们有一个计数器组件，通过状态变量来实现计数和 UI 的同步更新 。代码如下：
@Component
struct CounterComponent {
@State count: number = 0;
build() {
Column() {
Text(`计数: ${this.count}`).fontSize(20);
Button('增加计数').onClick(() => {
this.count++;
});
}
}
}
在这个例子中，@State修饰的count就是状态变量。当点击 “增加计数” 按钮时，count的值增加，由于count与Text组件中的显示内容相关联，所以Text组件会自动刷新，显示最新的计数值，实现了 UI 的动态更新 。
在参数传递过程中，状态变量的传递方式有按引用传递和按值传递两种，它们有着不同的表现 。
- 按值传递：当状态变量按值传递时，子组件接收到的是状态变量的一个副本。这意味着，子组件对该副本的修改不会影响到父组件中原始状态变量的值。例如：
@Component
struct ParentComponent {
@State value: number = 10;
build() {
Column() {
ChildComponent({ value: this.value });
Text(`父组件值: ${this.value}`).fontSize(16);
}
}
}
@Component
struct ChildComponent {
@Prop value: number;
build() {
Button('子组件修改值').onClick(() => {
this.value++;
});
Text(`子组件值: ${this.value}`).fontSize(16);
}
}
在这个例子中，ParentComponent将value按值传递给ChildComponent。当在ChildComponent中点击按钮修改value时，只会改变子组件中value副本的值，父组件中的value不会受到影响 。
- 按引用传递：而按引用传递时，子组件和父组件共享同一个状态变量的引用。此时，子组件对状态变量的修改会直接反映在父组件中，因为它们操作的是同一个数据。在 ArkUI 中，对于@Builder装饰的函数，如果要实现按引用传递参数，需要满足特定条件（后面会详细介绍@Builder装饰器相关内容
最低0.47元/天 解锁文章
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
