OpenHarmony列表组件为何空白

在 OpenHarmony（ArkUI）开发中，列表组件（List / ListItem）显示空白是非常常见的问题，通常由以下几类原因导致。你可以对照排查：

一、最常见原因

1. 没有给 List 设置宽高

List 默认不会自动撑开高度，如果父容器或 List 自身没有明确的宽高，就会“看起来是空白”。

✅ 正确写法：

List() {
  ListItem() {
    Text('Item 1')
  }
}
.width('100%')
.height('100%')

❌ 错误示例（常见）：

List() {
  ListItem() {
    Text('Item 1')
  }
}
// 没有 width / height

2. ListItem 没有内容或内容不可见

ListItem() {
  // 空内容
}

或：

Text('')

都会导致空白。

3. 数据为空（ForEach 没有数据）

List() {
  ForEach(this.listData, (item) => {
    ListItem() {
      Text(item)
    }
  })
}

如果 listData = []，列表就是空白的。

✅ 排查：

console.log(this.listData.length)

二、布局与样式问题

4. 父容器没有高度

即使 List 有 height('100%')，但父容器是 Column() 且没高度，也会无效。

✅ 正确结构：

Column() {
  List() {
    ListItem() {
      Text('Hello')
    }
  }
  .width('100%')
  .height('100%')
}
.width('100%')
.height('100%')

5. 背景色和文字色一样

Text('内容')
  .fontColor(Color.White)
  .backgroundColor(Color.White)

视觉上“空白”。

三、ForEach 使用错误（高频）

6. ForEach 的 key 或写法错误

错误示例：

ForEach(this.list, (item) => {
  ListItem() {
    Text(item)
  }
})

✅ 推荐写法：

ForEach(
  this.list,
  (item) => {
    ListItem() {
      Text(item)
    }
  },
  (item) => item.id.toString()
)

四、状态更新问题

7. 数据变化但 UI 没刷新

如果 listData 不是 @State 或 @Link：

@State listData: string[] = []

否则修改数据不会触发列表刷新。

五、调试建议（快速定位）

1. 给 List 一个背景色

List()
  .backgroundColor(Color.Red)

• 能看到红 = 布局问题
• 看不到红 = 高度/父容器问题

2. 给 ListItem 一个固定高度

ListItem()
  .height(50)

六、最小可用示例（推荐对照）

@Entry
@Component
struct TestPage {
  @State data: string[] = ['A', 'B', 'C']

  build() {
    Column() {
      List() {
        ForEach(this.data, (item: string) => {
          ListItem() {
            Text(item)
              .fontSize(20)
          }
        })
      }
      .width('100%')
      .height('100%')
    }
    .width('100%')
    .height('100%')
  }
}

如果你愿意，可以把你的 List 代码贴出来，我可以直接帮你定位是哪一条原因。