HarmonyOS6 ArkTS ArcList 使用

一、概述

ArcList是 HarmonyOS 面向穿戴设备（Wearable）提供的弧形滚动列表专用组件，专为圆形表盘设计，呈现弧形排列的列表交互效果，支持表冠控制、链式动画、边缘渐隐、头部自定义等穿戴设备核心交互能力。

二、适用环境

• 设备类型：Wearable 穿戴设备（圆形表盘）
• 支持版本：API 18+
• 子组件限制：仅支持 ArcListItem
• 不支持：手机、平板、车机等非穿戴设备

三、核心组件结构

ArcList 采用固定层级结构，不可嵌套其他容器：

ArcList ├─ 头部（header：ComponentContent） └─ ArcListItem（必须是直接子组件）

四、代码完整示例

// xxx.etsimport{ComponentContent,LengthMetrics}from'@kit.ArkUI';import{UIContext,CircleShape}from'@kit.ArkUI';// 从API version 22开始，无需手动导入ArcListAttribute和ArcListItemAttribute。具体请参考ArcList、ArcListItem的导入模块说明。import{ArcList,ArcListItem,ArcListAttribute,ArcListItemAttribute}from'@kit.ArkUI';@BuilderfunctionbuildText(){Column(){Text('header').fontSize('60px').fontWeight(FontWeight.Bold).fontColor(Color.Black)}.margin(0)}@Entry@Componentstruct Index{@StateprivatenumItems:number[]=[0,1,2,3,4,5,6,7,8,9];privatewatchSize:string='466px';// Wearable默认宽高：466*466privatelistSize:string='414px';// item宽度context:UIContext=this.getUIContext();tabBar1:ComponentContent<Object>=newComponentContent(this.context,wrapBuilder(buildText));@BuilderbuildList2(){Stack(){Column(){}.justifyContent(FlexAlign.Center).width(this.watchSize).height(this.watchSize).clipShape(newCircleShape({width:'100%',height:'100%'})).backgroundColor(Color.White)ArcList({initialIndex:0,header:this.tabBar1}){ForEach(this.numItems,(item:number,index:number)=>{ArcListItem(){Button(''+item,{type:ButtonType.Capsule}).width(this.listSize).height('100px').fontSize('40px').focusable(true).focusOnTouch(true).backgroundColor(0x17A98D)}.align(Alignment.Center)},(item:number,index:number)=>(item+index).toString())}.space(LengthMetrics.px(10)).borderRadius(this.watchSize).focusable(true).focusOnTouch(true).defaultFocus(true)}.align(Alignment.Center).width(this.watchSize).height(this.watchSize).border({color:Color.Black,width:1}).borderRadius(this.watchSize)}build(){Column(){this.buildList2()}.width('100%').height('100%').alignItems(HorizontalAlign.Center).justifyContent(FlexAlign.Center)}}

在模拟器上的运行效果如图，但是应该放在穿戴设备上进行运行，这里为了图方便，运行出来是这样的：

五、ArcList 构造参数说明

ArcList 支持两个可选构造参数：

示例：

ArcList({initialIndex:0,header:this.tabBar1})

六、ArcList 核心属性

1. space

设置ArcListItem之间的间距。

.space(LengthMetrics.px(10))

2. borderRadius

设置弧形列表圆角，穿戴设备通常设置为表盘宽度，实现圆形裁剪。

.borderRadius(this.watchSize)

3. 焦点相关（穿戴设备必备）

.focusable(true)// 可获取焦点.focusOnTouch(true)// 触摸时获取焦点.defaultFocus(true)// 默认获取焦点

4. 常用高级属性

七、ArcListItem 使用规范

• 必须是 ArcList 的直接子组件
• 内部可放置按钮、文本、图标等
• 支持.align(Alignment.Center)居中对齐

示例：

ArcListItem(){Button(''+item,{type:ButtonType.Capsule}).width(this.listSize).height('100px').fontSize('40px')}.align(Alignment.Center)

八、Header 头部配置

ArcList 头部必须使用 ComponentContent 包装，步骤如下：

1. 定义@Builder构建器

@BuilderfunctionbuildText(){Column(){Text('header').fontSize('60px').fontWeight(FontWeight.Bold).fontColor(Color.Black)}.margin(0)}

2. 创建 ComponentContent 实例

context:UIContext=this.getUIContext();tabBar1:ComponentContent<Object>=newComponentContent(this.context,wrapBuilder(buildText));

3. 传入 ArcList 构造参数

ArcList({initialIndex:0,header:this.tabBar1})

九、圆形表盘适配（关键）

穿戴设备屏幕为圆形，必须使用clipShape+CircleShape实现圆形裁剪：

.clipShape(newCircleShape({width:'100%',height:'100%'}))

同时设置：

.borderRadius(this.watchSize)

使 ArcList 完全贴合圆形表盘。

十、数据渲染

使用ForEach遍历数据渲染ArcListItem，必须提供唯一键值：

ForEach(this.numItems,(item:number,index:number)=>{ArcListItem(){...}},(item,index)=>(item+index).toString())

总结

1. 仅支持 Wearable 设备，手机/平板无法运行。
2. 必须使用API 18+工程。
3. 子组件只能是 ArcListItem，不可嵌套 Column/Row 等容器。
4. 表冠交互仅在真实设备或穿戴模拟器生效。
5. borderRadius设置为表盘宽度才能呈现弧形列表效果。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力！