鸿蒙ASCF自定义组件实践：从卡片复用看属性传递与样式隔离

鸿蒙专家

做设置页面时，最容易遇到的重复劳动就是卡片式布局：标题、描述、右侧一个开关或箭头，几乎每个页面都长一个样。一开始复制粘贴同一段结构代码还能接受，等页面多起来，想统一调整样式就得每个文件改一遍，改到怀疑人生。这种场景下，组件化就是最自然的解法。ASCF 支持自定义组件，把公共 UI 抽出来，所有页面复用，改一处就全局生效。

自定义组件的基础结构

一个自定义组件由 json + hxml + css + js 四件套组成，和 Page 相比只有两点区别：

2. components/
3. my-card/
4. my-card.json   # 声明 component: true
5. my-card.hxml   # 模板
6. my-card.css    # 样式
7. my-card.js     # 逻辑（Component 构造器）

复制代码

json 里多了一个 "component": true，js 里改用 Component({...}) 而不是 Page({...})，其他能力——数据绑定、事件处理、setData、生命周期——都和 Page 保持一致。

实现一个基础卡片组件

以卡片组件为例，需求是卡片包含标题、描述和右侧内容区，右侧可以由父页面自由塞入开关、箭头或其他内容。

先写 json 声明：

2. {
3.   "component": true
4. }

复制代码

这一句就是告诉框架：这不是页面，这是组件。

组件逻辑文件：

2. Component({
3.   properties: {
4.     title: {
5.       type: String,
6.       value: '',
7.     },
8.     desc: {
9.       type: String,
10.       value: '',
11.     },
12.     // 右侧是否显示箭头
13.     showArrow: {
14.       type: Boolean,
15.       value: false,
16.     },
17.   },
18.   data: {},
19.   methods: {
20.     onCardTap() {
21.       // 触发自定义事件，父页面监听
22.       this.triggerEvent('cardtap', { title: this.properties.title });
23.     },
24.   },
25. });

复制代码

properties 就是组件的对外接口：父组件传什么值，组件收到后在模板中展示。type 限制数据类型，value 设置默认值。

模板文件：

2. <view class="my-card" bindtap="onCardTap">
3.   <view class="card-body">
4.     <view class="card-info">
5.       <text class="card-title" has:if="{{title}}">{{title}}</text>
6.       <text class="card-desc" has:if="{{desc}}">{{desc}}</text>
7.     </view>
8.     <view class="card-right">
9.       <slot></slot>
10.       <image has:if="{{showArrow}}" class="card-arrow"
11.         src="" />
12.     </view>
13.   </view>
14. </view>

复制代码

slot 是插槽，父组件可以在组件标签中间塞内容，比如在卡片右侧放一个 switch。

样式文件：

2. .my-card {
3.   background: #fff;
4.   border-radius: 12px;
5.   padding: 16px;
6.   margin-bottom: 12px;
7.   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
8. }
9. .card-body {
10.   display: flex;
11.   justify-content: space-between;
12.   align-items: center;
13. }
14. .card-info {
15.   flex: 1;
16.   margin-right: 12px;
17. }
18. .card-title {
19.   font-size: 15px;
20.   color: #1a1a1a;
21.   font-weight: 500;
22. }
23. .card-desc {
24.   font-size: 12px;
25.   color: #999;
26.   margin-top: 4px;
27.   display: block;
28. }
29. .card-right {
30.   display: flex;
31.   align-items: center;
32. }
33. .card-arrow {
34.   width: 16px;
35.   height: 16px;
36.   margin-left: 8px;
37. }

复制代码

到这里基础卡片组件就完成了。组件内部样式默认是隔离的，组件的 css 不会影响外部，外部的全局样式也不会污染组件内部，这套机制叫样式隔离。

在页面中使用自定义组件

页面里使用时，先要在页面的 json 中声明 usingComponents：

2. {
3.   "usingComponents": {
4.     "my-card": "./components/my-card/my-card"
5.   }
6. }

复制代码

然后在 hxml 中像使用基础组件一样直接写标签：

2. <my-card title="消息推送" desc="接收订单状态通知" showArrow="{{true}}">
3.   <switch checked="{{pushEnabled}}" bindchange="onPushChange" />
4. </my-card>
5. <my-card title="夜间模式" desc="22:00-07:00 自动开启" showArrow="{{false}}">
6.   <switch checked="{{nightMode}}" />
7. </my-card>
8. <my-card title="关于应用" desc="当前版本 1.0.0" bindcardtap="onAboutTap">
9.   <!-- 不用 slot 内容也可以 -->
10. </my-card>

复制代码

最终效果就是三张统一样式的卡片，每张卡片的右侧可以放不同内容：开关、箭头或者什么都不放。

这里有一个非常容易踩的坑：在页面 json 的 usingComponents 中漏写声明，直接在 hxml 写了 <my-card>，IDE 不报错，渲染出来却是空白。排查了半天，最后发现就是 usingComponents 没写。

properties：父组件向子组件传值

properties 是接收父组件数据的入口，支持简写和完整写法：

2. Component({
3.   properties: {
4.     name: String, // 简写
5.     age: { type: Number, value: 0 }, // 完整写法
6.     user: { type: Object, value: {} },
7.     tags: { type: Array, value: [] },
8.   },
9. });

复制代码

hxml 中使用驼峰命名绑定：

2. <my-card user="{{userObj}}" age="{{25}}" />

复制代码

properties 的值在组件内部可以借助 this.properties.xxx 或 this.data.xxx 读取。要特别注意，properties 和 data 里的字段名不能相同，否则修改 properties 时会覆盖 data 的同名字段。这个问题在实际开发中出现过：在 data 里声明了与 properties 同名的字段，父组件传值后 data 里的值被覆盖，页面展示和预期完全对不上。

triggerEvent：子组件向父组件通信

子组件通过 this.triggerEvent 触发自定义事件，父组件监听后接收数据：

2. // 子组件
3. methods: {
4.   onTap() {
5.     this.triggerEvent('myevent', {
6.       value: '一些数据',
7.       timestamp: Date.now(),
8.     }, {
9.       bubbles: false, // 是否冒泡
10.       composed: false, // 是否穿越组件边界
11.       capturePhase: false, // 是否有捕获阶段
12.     });
13.   },
14. },

复制代码

2. <!-- 父页面 -->
3. <my-card bindmyevent="onMyEvent" />
4. <!-- 或者 -->
5. <my-card bind:myevent="onMyEvent" />

复制代码

2. // 父页面
3. onMyEvent(e) {
4.   console.info('收到子组件事件:', e.detail);
5.   // e.detail = { value: '一些数据', timestamp: ... }
6. }

复制代码

事件名命名上，驼峰写法在 bind 时用 bindmyevent，连字符写法用 bind:my-event，两者等价。团队协作时建议统一成一种风格。

slot 插槽：让父组件决定内容区

slot 就是在组件模板里预留的坑位，父组件往坑里填内容：

2. <!-- 组件模板 -->
3. <view class="my-card">
4.   <view class="card-header">
5.     <slot name="header"></slot>
6.   </view>
7.   <view class="card-body">
8.     <slot></slot> <!-- 默认插槽 -->
9.   </view>
10. </view>

复制代码

2. <!-- 父页面 -->
3. <my-card>
4.   <view slot="header">
5.     <text>自定义标题区域</text>
6.   </view>
7.   <switch checked="{{value}}" /> <!-- 放入默认插槽 -->
8. </my-card>

复制代码

多个 slot 时用 name 区分，不指定 name 的就是默认插槽。注意，组件模板里必须有对应的 <slot> 标签，父组件传进来的子节点才会被渲染。

组件生命周期与页面生命周期

自定义组件有 4 个核心生命周期：

2. Component({
3.   lifetimes: {
4.     created() {
5.       console.info('组件创建');
6.       // 不能 setData
7.     },
8.     attached() {
9.       console.info('组件进入页面');
10.       // 可以 setData 了
11.     },
12.     ready() {
13.       console.info('组件渲染完成');
14.       // 可以操作 DOM
15.     },
16.     detached() {
17.       console.info('组件移除');
18.       // 清理
19.     },
20.   },
21. });

复制代码

lifetimes 写法优先级最高。如果同时写了顶层 attached 和 lifetimes.attached，最终走的是 lifetimes 里的实现。

组件还可以监听所在页面的生命周期：

2. Component({
3.   pageLifetimes: {
4.     show() {
5.       // 页面显示时触发
6.       console.info('所在页面显示');
7.     },
8.     hide() {
9.       // 页面隐藏时触发
10.       console.info('所在页面隐藏');
11.     },
12.   },
13. });

复制代码

这个能力在特定场景下非常好用。比如计数器组件在页面切回来时需要刷新数据，直接在 pageLifetimes.show 里处理即可，不需要页面侧额外调用。

observers：数据监听器

observers 用于监听 properties 或 data 的变化：

2. Component({
3.   properties: {
4.     count: { type: Number, value: 0 },
5.   },
6.   observers: {
7.     // 单个字段
8.     'count': function(newVal, oldVal) {
9.       console.info('count 从', oldVal, '变为', newVal);
10.     },
11.     // 多个字段
12.     'count, step': function(count, step) {
13.       this.setData({
14.         total: count * step,
15.       });
16.     },
17.     // 子字段
18.     'user.name': function(name) {
19.       console.info('用户名变了:', name);
20.     },
21.     // 通配符：所有字段
22.     '**': function() {
23.       console.info('数据有变化');
24.     },
25.   },
26. });

复制代码

observers 在组件 attached 阶段之后才会触发。如果在 created 里 setData，observers 不会执行。

实际开发中，做一个购物车组件时商品数量变化需要自动计算总价，就可以用 observers 监听 count 变化，一变更立即重新计算，省去手动调用的麻烦。

三种通信方式对比

除了 properties + triggerEvent，还有 selectComponent 可以获取子组件实例：

2. // 父页面，通过 id 或 class 获取子组件实例
3. const child = this.selectComponent('#my-counter');
4. if (child) {
5.   console.info('子组件数据:', child.data);
6.   child.setData({ count: 100 }); // 直接操作子组件
7. }

复制代码

但用 selectComponent 直接操作子组件会破坏封装性，应优先使用 properties + triggerEvent 的通信方式，selectComponent 留作兜底方案。

另外，如果组件需要在多个页面复用，可以在 app.json 的 usingComponents 里声明为全局组件，所有页面和组件都可以直接用，不需要每个页面单独引用。实际做设置页面时，把卡片组件全局注册后，其他页面直接写 <my-card> 就能用，省事不少。

完整示例：计数器组件

把上面的知识点串起来，做一个计数器组件：

my-counter.json：

2. {
3.   "component": true
4. }

复制代码

my-counter.js：

2. Component({
3.   properties: {
4.     count: {
5.       type: Number,
6.       value: 0,
7.     },
8.     min: { type: Number, value: 0 },
9.     max: { type: Number, value: 99 },
10.     step: { type: Number, value: 1 },
11.   },
12.   observers: {
13.     'count, min, max': function(count, min, max) {
14.       // 父组件传了新的 count 时校验范围
15.       if (count < min || count > max) {
16.         console.warn('count 超出范围');
17.       }
18.     },
19.   },
20.   methods: {
21.     onDecrease() {
22.       const newVal = this.properties.count - this.properties.step;
23.       if (newVal >= this.properties.min) {
24.         this.triggerEvent('change', { value: newVal });
25.       }
26.     },
27.     onIncrease() {
28.       const newVal = this.properties.count + this.properties.step;
29.       if (newVal <= this.properties.max) {
30.         this.triggerEvent('change', { value: newVal });
31.       }
32.     },
33.   },
34. });

复制代码

my-counter.hxml：

2. <view class="counter">
3.   <view class="counter-btn" bindtap="onDecrease">-</view>
4.   <text class="counter-value">{{count}}</text>
5.   <view class="counter-btn" bindtap="onIncrease">+</view>
6. </view>

复制代码

my-counter.css：

2. .counter {
3.   display: flex;
4.   align-items: center;
5.   gap: 12px;
6. }
7. .counter-btn {
8.   width: 32px;
9.   height: 32px;
10.   border: 1px solid #ddd;
11.   border-radius: 50%;
12.   text-align: center;
13.   line-height: 32px;
14.   font-size: 18px;
15.   color: #333;
16. }
17. .counter-btn:active {
18.   background: #f0f0f0;
19. }
20. .counter-value {
21.   font-size: 16px;
22.   font-weight: 600;
23.   min-width: 24px;
24.   text-align: center;
25. }

复制代码

父页面使用：

2. {
3.   "usingComponents": {
4.     "my-counter": "./components/my-counter/my-counter"
5.   }
6. }

复制代码

2. <my-counter count="{{cartCount}}" min="0" max="10"
3.   bindchange="onCountChange" />

复制代码

2. Page({
3.   data: { cartCount: 1 },
4.   onCountChange(e) {
5.     this.setData({ cartCount: e.detail.value });
6.     console.info('数量变为:', e.detail.value);
7.   },
8. });

复制代码

这样一个可复用的计数器组件就做好了。properties 控制步长和范围，triggerEvent 通知父组件数量变化。

组件样式隔离与外部样式覆盖

默认情况下，组件样式是隔离的：组件内部 css 不影响外部，外部 css 也不影响组件内部（继承性属性如 color、font-size 除外）。

如果需要外部覆盖组件样式，可以用 externalClasses：

2. Component({
3.   externalClasses: ['my-class', 'custom-class'],
4. });

复制代码

2. <my-card my-class="custom-card-style" />

复制代码

2. /* 外部样式 */
3. .custom-card-style {
4.   border-color: #0A59F7;
5. }

复制代码

或者通过 options 调整隔离策略：

2. Component({
3.   options: {
4.     styleIsolation: 'apply-shared', // 外部样式可以影响组件
5.   },
6. });

复制代码

styleIsolation 有三个取值：

isolated：默认，完全隔离。
apply-shared：外部样式可以影响组件，但组件不影响外部。
shared：双向影响。

大部分场景默认的 isolated 已经够用。需要外部定制样式的组件，用 externalClasses 更干净，也不会破坏封装。

自定义组件和 Page 的定位差异

Page 是路由入口，Component 是 UI 零件。Page 通过组合多个 Component 来搭建页面。如果整个页面都用 Component 构造，URL 上的 query 参数会被自动赋值到 properties 里。比如访问 detail?paramA=abc，properties 里的 paramA 会自动收到 "abc"，这个行为在实际开发中容易被忽略。

踩坑清单汇总

回顾整个实践过程，有几个问题值得记录：

1. usingComponents 忘了写。最常见的错误。在声明 usingComponents 之前直接写自定义组件标签，渲染不出来也不报错。排查时先确认 json 里有没有声明。

2. properties 和 data 字段名重复。同名字段会导致 properties 覆盖 data 的值，写组件时注意命名区分。

3. created 里不能 setData。created 阶段组件还没进入页面节点树，调 setData 会报错。初始数据在 created 里直接赋值给 this.data，需要触发渲染的操作放到 attached 里。

4. slot 内容不显示。组件模板里必须有对应的 <slot> 标签，否则父组件传的任何子节点都不会渲染。

5. 组件路径写错。usingComponents 里的路径是相对路径，以页面文件所在目录为基准，不是相对于项目根目录。路径写错了不会报错，表现同样是渲染不出来。

6. 外部全局样式不生效。默认样式隔离下，外部 css 写了 * { box-sizing: border-box; } 这类全局样式，组件内部不会受影响。这是预期行为，但如果不了解样式隔离机制，容易误判为 bug。

写在最后

自定义组件最大的价值不是节省代码量，而是统一维护。卡片组件、计数器组件、按钮组件——抽出来之后，改样式、改逻辑都集中在一个地方。ASCF 的组件机制和常见小程序组件模型很相似，properties + triggerEvent 的通信模式熟练之后，页面开发的整体效率会有明显提升。

这次把卡片组件抽出来，从动手到跑通总共花了半小时，其中还包括一次 usingComponents 漏写的排查时间。后续再做类似页面，直接复用组件即可，样式调整也只需改一处。

热心网友1

写得很清楚，正好最近在弄类似设置页，卡片复用这个痛点很真实。用 slot 塞开关这个思路方便，父页面不用重复写卡片结构，改样式也集中了。 有个小疑问：`card-arrow` 的 `src` 目前是空的，实际用的时候是不是要在 properties 里加个 arrowSrc 之类的属性让父页面传？还有 slot 里如果同时要放多个控件，或者根据条件切换右侧内容，是建议在父页面用 `has:if` 包一层插槽，还是组件里再扩展一下？

热心网友1

感谢楼主分享！这波组件化思路很实用，正好解决了我设置页改样式改到吐的问题。之前都是复制粘贴，加了新页面想统一调间距就得全盘翻一遍，确实痛苦。 有个小问题想请教下：slot 里如果放多个元素，比如开关加个小图标，组件这边的样式隔离会不会影响 slot 内容的布局？我理解 slot 内容是在父页面作用域下渲染的，但不太确定它在组件内部 flex 布局里表现如何，楼主有测试过类似场景吗？

热心网友1

感谢分享，这篇把 ASKF 自定义组件的完整流程讲得很清楚。尤其是“四件套”和 `properties` 作为对外接口的说明，对刚接触组件化的同学来说很友好。卡片复用加插槽这个思路也很实用，确实能避免大量重复代码，改样式也方便。顺便问下：样式隔离下，如果父页面想微调某个卡片内部的间距或颜色，除了给组件加 `properties` 传样式变量，还有别的推荐做法吗？期待你后续能聊聊这块。