List

移动端设置页面风格的列表组件。

导入

import { List } from '@xcloud/ui-mobile'

示例

基础用法

import { List } from '@xcloud/ui-mobile';
import { User, Bell, Lock } from 'lucide-react';

function SettingsPage() {
  return (
    <List.Root variant="default">
      <List.Group title="账户设置">
        <List.Item
          icon={<User className="w-5 h-5" />}
          label="个人信息"
          description="管理你的个人资料"
          showArrow
          onClick={() => navigate('/profile')}
        />
        <List.Item
          icon={<Lock className="w-5 h-5" />}
          label="安全设置"
          value="已启用"
          showArrow
          onClick={() => navigate('/security')}
        />
      </List.Group>

      <List.Group title="通知">
        <List.Item
          icon={<Bell className="w-5 h-5" />}
          label="推送通知"
          rightContent={
            <Switch checked={notifications} onCheckedChange={setNotifications} />
          }
        />
      </List.Group>
    </List.Root>
  );
}

组件

List.Root

列表容器组件

Props:

属性	类型	默认值	描述
variant	'default' | 'compact'	'default'	列表变体
children	ReactNode	-	子元素
className	string	-	自定义类名

List.Group

列表分组组件

Props:

属性	类型	默认值	描述
title	string	-	分组标题
children	ReactNode	-	子元素 (List.Item)
className	string	-	自定义类名

List.Item

列表项组件

Props:

属性	类型	默认值	描述
icon	ReactNode	-	左侧图标
label	string	-	主标题
description	string	-	描述文本
value	string	-	右侧值
showArrow	boolean	false	显示右侧箭头
rightContent	ReactNode	-	自定义右侧内容
disabled	boolean	false	禁用状态
onClick	() => void	-	点击事件
className	string	-	自定义类名

变体

Default

默认间距

<List.Root variant="default">
  <List.Group title="设置">
    <List.Item label="选项 1" showArrow />
    <List.Item label="选项 2" showArrow />
  </List.Group>
</List.Root>

Compact

紧凑间距

<List.Root variant="compact">
  <List.Group>
    <List.Item label="选项 1" showArrow />
    <List.Item label="选项 2" showArrow />
  </List.Group>
</List.Root>

使用场景

带图标和描述

<List.Item
  icon={<User className="w-5 h-5 text-blue-600" />}
  label="个人信息"
  description="管理你的个人资料"
  showArrow
  onClick={() => {}}
/>

带值显示

<List.Item
  icon={<Globe className="w-5 h-5" />}
  label="语言"
  value="简体中文"
  showArrow
  onClick={() => {}}
/>

自定义右侧内容

<List.Item
  icon={<Bell className="w-5 h-5" />}
  label="推送通知"
  description="接收重要消息提醒"
  rightContent={
    <Switch checked={enabled} onCheckedChange={setEnabled} />
  }
/>

带徽章

<List.Item
  icon={<Bell className="w-5 h-5" />}
  label="消息通知"
  rightContent={
    <Badge.Root variant="error">
      <Badge.Content>3</Badge.Content>
    </Badge.Root>
  }
  showArrow
  onClick={() => {}}
/>

禁用状态

<List.Item
  label="已禁用选项"
  disabled
  onClick={() => {}}
/>

样式定制

所有组件都支持通过 className prop 进行样式定制：

<List.Root className="custom-list">
  <List.Group className="custom-group" title="自定义分组">
    <List.Item
      className="custom-item"
      label="自定义项目"
    />
  </List.Group>
</List.Root>

最佳实践

1. 使用分组组织相关项目

<List.Root>
  <List.Group title="账户">
    {/* 账户相关项 */}
  </List.Group>

  <List.Group title="隐私">
    {/* 隐私相关项 */}
  </List.Group>
</List.Root>

2. 合理使用图标

// ✅ 好 - 使用有意义的图标
<List.Item
  icon={<Lock className="w-5 h-5 text-green-600" />}
  label="安全设置"
/>

// ❌ 不好 - 图标与内容不符
<List.Item
  icon={<Music className="w-5 h-5" />}
  label="安全设置"
/>

3. 提供清晰的视觉反馈

// ✅ 好 - 可点击的项目显示箭头
<List.Item
  label="个人信息"
  showArrow
  onClick={() => navigate('/profile')}
/>

// ⚠️ 可以改进 - 不可点击的项目不需要箭头
<List.Item
  label="版本号"
  value="1.0.0"
/>

常见模式

设置页面

<List.Root>
  <List.Group title="账户">
    <List.Item icon={<User />} label="个人信息" showArrow onClick={() => {}} />
    <List.Item icon={<Lock />} label="安全设置" showArrow onClick={() => {}} />
  </List.Group>

  <List.Group title="偏好">
    <List.Item label="深色模式" rightContent={<Switch />} />
    <List.Item label="语言" value="简体中文" showArrow onClick={() => {}} />
  </List.Group>

  <List.Group>
    <List.Item icon={<LogOut />} label="退出登录" onClick={() => {}} />
  </List.Group>
</List.Root>

消息列表

<List.Root variant="compact">
  <List.Group>
    <List.Item
      label="系统通知"
      description="2 条未读"
      rightContent={<Badge variant="error">2</Badge>}
      showArrow
    />
    <List.Item
      label="评论回复"
      description="5 条未读"
      rightContent={<Badge variant="warning">5</Badge>}
      showArrow
    />
  </List.Group>
</List.Root>