#星光不负 码向未来# 鸿蒙ArkUI入门笔记：用UIDesignKit快速撸一个音乐列表 原创

@[toc]

前言

Hey，兄弟们！

刚开始摸鸿蒙ArkUI，感觉就像打开了新世界大门。声明式UI写起来确实爽。为了练手，我照着官方文档和一些Codelab，写了个简单的音乐列表Demo。

这个Demo特别适合像我一样的新手，因为它用了一个超好用的组件库——@kit.UIDesignKit。你不需要自己去吭哧吭哧地堆Row和Column来造轮子，用它现成的HdsListItemCard就能快速搞定漂亮的列表行，而且还帮你处理好了点击态、多端适配这些琐碎问题。

废话不多说，先上我写的Demo全代码。这是一个简单的音乐清单页面，但麻雀虽小，五脏俱全。

import { promptAction, ImageModifier, TextModifier } from '@kit.ArkUI';
import { HdsListItemCard, IconSize, PrefixImage, PrefixIcon, SuffixIcon, SuffixSwitch, SuffixBadgeAndArrow } from '@kit.UIDesignKit';

@Entry
@Component
struct HdsMusicListDemo {
  private scroller: ListScroller = new ListScroller();

  build() {
    Column() {
      // 顶部标题
      Text('我的音乐清单')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .fontColor('#2c3e50')
        .margin({ top: 16, bottom: 8, left: 16 })

      // 简介文案
      Text('三种常见列表行：图标、图片、徽标与开关，适合新手快速上手')
        .fontSize(12)
        .fontColor('#7f8c8d')
        .margin({ left: 16, bottom: 12 })

      List({ space: 8, scroller: this.scroller }) {
        // 1. 前缀系统图标 + 右侧点击图标
        ListItem() {
          HdsListItemCard({
            prefixItem: new PrefixIcon({
              iconSize: IconSize.SYSTEM_ICON,
              iconValue: { symbol: $r('sys.symbol.music_note_icolud') }
            }),
            textItem: {
              primaryText: { text: '夜的钢琴曲 · Kevin Kern' },
              secondaryText: { text: '新世纪 / 轻音乐' },
              description: { text: '一曲温柔的钢琴，适合夜晚放松入眠' },
            },
            suffixItem: new SuffixIcon({
              iconValue: { symbol: $r('sys.symbol.heart') },
              onClick: () => promptAction.openToast({ message: '已加入收藏' })
            }),
            onClick: () => promptAction.openToast({ message: '打开歌曲详情' })
          })
        }

        // 2. 前缀封面图片 + 右侧开关
        ListItem() {
          HdsListItemCard({
            prefixItem: new PrefixImage({
              image: $r('app.media.startIcon'),
              modifier: new ImageModifier().width(64).height(64).borderRadius(16)
            }),
            textItem: {
              primaryText: { text: 'Random Access Memories · Daft Punk' },
              secondaryText: { text: '电子 / 复古迪斯科' },
              description: { text: '标志性合成器音色，节奏律动强烈' },
            },
            suffixItem: new SuffixSwitch({
              isCheck: false,
              selectColor: Color.Orange,
              onChange: (on: boolean) => {
                promptAction.openToast({ message: on ? '已开启循环播放' : '已关闭循环播放' });
              },
            })
          })
        }

        // 3. 特定行高亮文字 + 右侧徽标与箭头
        ListItem() {
          HdsListItemCard({
            prefixItem: new PrefixIcon({
              iconSize: IconSize.SYSTEM_ICON,
              iconValue: { symbol: $r('sys.symbol.album_compose') }
            }),
            textItem: {
              primaryText: {
                text: '每日推荐歌单',
                modifier: new TextModifier().fontColor(Color.Pink)
              },
              secondaryText: { text: '根据你的听歌偏好智能生成' },
            },
            suffixItem: new SuffixBadgeAndArrow({
              badgeValue: 12,
              badgeColor: Color.Orange,
              textColor: Color.Blue
            }, {
              color: Color.Orange
            })
          })
        }
      }
      .margin({ left: 12, right: 12, bottom: 12 })
      .width('100%')
      .layoutWeight(1)
    }
    .backgroundColor('#F7F9FC')
    .width('100%')
    .height('100%')
  }
}

拆解时间：咱们一行行看

OK，代码贴上来了。咱们来简单拆解一下这里面的知识点，特别适合刚上手的哥们。

1. 依赖导入 (Import)

开头那两行 import 很关键：

• @kit.ArkUI: 这是ArkUI框架的基础库，我们从里面拿了 promptAction（用来弹Toast提示）、ImageModifier 和 TextModifier（用来修改组件样式）。
• @kit.UIDesignKit: 这就是我们今天的主角——官方的高阶组件库。我们把列表行卡片 HdsListItemCard 和它的小伙伴们（如 PrefixIcon, SuffixSwitch 等）都导入进来了。

2. 页面骨架 (@Entry, Column, List)

• @Entry 和 @Component 是ArkUI声明式UI的标配装饰器，告诉系统“嘿，这是一个UI组件，@Entry 这个是页面的入口”。
• build() 方法就是组件的“绘制蓝图”。
• 最外层我用了个 Column()，让里面的元素（标题、简介、列表）垂直排列。
• Text() 组件就是显示文字，后面跟的 .fontSize()、.fontWeight() 都是链式调用的样式设置，非常直观。
• List() 组件就是滚动列表容器。我给它传了个 space: 8，让列表项之间有8fp的间距。

3. 核心组件：HdsListItemCard

这才是这个Demo的精髓。UIDesignKit 里的 HdsListItemCard 把一个复杂的列表行给抽象化、配置化了。

它把一个列表行分成了经典的三段式：

• prefixItem：前缀，放左边的图标或者图片。
• textItem：中间的文字区域，支持多行文本。
• suffixItem：后缀，放右边的箭头、开关、图标等。

我们这个Demo里演示了三种最常见的用法。

示例1：图标 + 三行文案 + 点击图标

这是最标准的一种列表行。左边一个图标，中间三行文字（主标题、副标题、描述），右边一个可点击的图标（比如“收藏”）。

// 1. 前缀系统图标 + 右侧点击图标
ListItem() {
  HdsListItemCard({
    prefixItem: new PrefixIcon({
      iconSize: IconSize.SYSTEM_ICON,
      iconValue: { symbol: $r('sys.symbol.music_note_icolud') } // 使用系统内置符号
    }),
    textItem: {
      primaryText: { text: '夜的钢琴曲 · Kevin Kern' },
      secondaryText: { text: '新世纪 / 轻音乐' },
      description: { text: '一曲温柔的钢琴，适合夜晚放松入眠' }, // 第三行描述
    },
    suffixItem: new SuffixIcon({
      iconValue: { symbol: $r('sys.symbol.heart') }, // 右侧心形图标
      onClick: () => promptAction.openToast({ message: '已加入收藏' }) // 给图标单独加点击事件
    }),
    onClick: () => promptAction.openToast({ message: '打开歌曲详情' }) // 给整个列表行加点击事件
  })
}

知识点Get√：

1. PrefixIcon：用这个来显示前缀图标。iconValue: { symbol: $r('sys.symbol.music_note_icolud') } 这种写法是用了鸿蒙的系统内置符号（Symbol），好处是不用自己切图，而且自适应主题色。
2. textItem：可以同时塞 primaryText, secondaryText, description，组件库会自动帮你排好版。
3. SuffixIcon：后缀图标。注意它内部可以定义 onClick，只响应这个小图标的点击。
4. HdsListItemCard 本身也可以定义 onClick，响应整个列表行的点击。
5. promptAction.openToast(...)：弹Toast的API，简单粗暴。

示例2：封面图 + 两行文案 + 开关

这种常用于“设置”项，或者需要展示封面图的场景。

// 2. 前缀封面图片 + 右侧开关
ListItem() {
  HdsListItemCard({
    prefixItem: new PrefixImage({
      image: $r('app.media.startIcon'), // 使用本地资源图片
      modifier: new ImageModifier().width(64).height(64).borderRadius(16) // 自定义修饰
    }),
    textItem: {
      primaryText: { text: 'Random Access Memories · Daft Punk' },
      secondaryText: { text: '电子 / 复古迪斯科' },
      // 这次没传 description，它就自动显示两行
    },
    suffixItem: new SuffixSwitch({
      isCheck: false, // 默认状态
      selectColor: Color.Orange, // 选中的颜色
      onChange: (on: boolean) => { // 状态变化的回调
        promptAction.openToast({ message: on ? '已开启循环播放' : '已关闭循环播放' });
      },
    })
  })
}

知识点Get√：

1. PrefixImage：用这个来显示前缀图片。image: $r('app.media.startIcon') 是在引用项目 resources/base/media 目录下的图片资源。
2. modifier：这个参数牛逼了！UIDesignKit 允许你传入一个 ImageModifier (或者 TextModifier) 来“魔改”它内部组件的样式。这里我就用 .width(64).height(64).borderRadius(16) 把它强制改成了64x64的圆角矩形。
3. SuffixSwitch：一个带回调的开关，onChange 事件会返回开关的最新状态（true 或 false）。

示例3：高亮文字 + 徽标与箭头

这种一般用于“每日推荐”或者有新消息提示的入口。

// 3. 特定行高亮文字 + 右侧徽标与箭头
ListItem() {
  HdsListItemCard({
    prefixItem: new PrefixIcon({
      iconSize: IconSize.SYSTEM_ICON,
      iconValue: { symbol: $r('sys.symbol.album_compose') }
    }),
    textItem: {
      primaryText: {
        text: '每日推荐歌单',
        modifier: new TextModifier().fontColor(Color.Pink) // 重点：单独修改主标题样式
      },
      secondaryText: { text: '根据你的听歌偏好智能生成' },
    },
    suffixItem: new SuffixBadgeAndArrow({
      badgeValue: 12, // 徽标数字
      badgeColor: Color.Orange,
      textColor: Color.Blue
    }, {
      color: Color.Orange // 箭头的颜色
    })
  })
}

知识点Get√：

1. TextModifier：跟上面的 ImageModifier 类似，这里我用 new TextModifier().fontColor(Color.Pink) 把主标题 primaryText 的颜色单独改成了粉色，非常醒目。
2. SuffixBadgeAndArrow：一个复合组件，直接把“徽标（Badge）”和“箭头（Arrow）”给你组合好了，你只需要传数字和颜色就行，省事儿。

总结

怎么样，是不是还挺简单的？

通过这个Demo，我们学到了：

1. 页面基本布局：Column 和 List。
2. 如何使用 UIDesignKit 里的 HdsListItemCard 来快速构建列表。
3. 如何配置 prefixItem（图标/图片）、textItem（多行文本）和 suffixItem（图标/开关/徽标）。
4. 如何使用 Modifier (ImageModifier/TextModifier) 来“魔改” UIDesignKit 组件的局部样式。
5. 如何使用 promptAction.openToast 弹提示。

HdsListItemCard 帮我们省了大量布局和状态管理的活儿，让我们能更专注于业务逻辑。对于新手来说，先学会用这些官方的轮子，再去看它们源码是怎么实现的，学习曲线会平滑很多。

OK，今天的笔记就到这，代码敲起来！