VisualList 视觉列表

    一个灵活的图片列表组件，支持多种尺寸、形状和自定义渲染。基于 css-in-js 样式系统，提供良好的主题支持和样式隔离。

    代码演示

    基础用法 - 头像列表与形状

    API

    VisualList

    属性说明类型默认值版本
    data图片数据数组（必需）VisualListItem[]--
    className自定义 CSS 类名string--
    style自定义内联样式React.CSSProperties--
    filter数据过滤函数(item: VisualListItem) => boolean() => true-
    emptyRender空状态自定义渲染函数() => React.ReactNode--
    renderItem自定义列表项渲染函数(item: VisualListItem, index: number) => React.ReactNode--
    loading已废弃，请使用 isLoadingbooleanfalse-
    isLoading是否显示加载状态booleanfalse-
    loadingRender加载状态自定义渲染函数() => React.ReactNode--
    itemStyle列表项自定义样式React.CSSProperties--
    imageStyle图片自定义样式React.CSSProperties--
    linkStyle链接自定义样式React.CSSProperties--
    shape图片形状'default' | 'circle''default'-
    prefixCls样式前缀类名string'visual-list'-
    variant组件变体'default' | 'outline' | 'borderless''default'-
    description描述文字string--

    VisualListItem

    属性说明类型默认值版本
    id唯一标识符string--
    src图片地址（必需）string--
    alt图片替代文本string--
    title图片标题string--
    href链接地址，如果提供则图片可点击string--

    使用示例

    基础用法

    import { VisualList, VisualListItem } from '@ant-design/agentic-ui';

const imageData: VisualListItem[] = [
  {
    id: '1',
    src: 'https://avatars.githubusercontent.com/u/1?v=4',
    alt: 'User 1',
    title: 'GitHub User 1',
    href: 'https://github.com/user1',
  },
  {
    id: '2',
    src: 'https://avatars.githubusercontent.com/u/2?v=4',
    alt: 'User 2',
    title: 'GitHub User 2',
    href: 'https://github.com/user2',
  },
];

<VisualList data={imageData} />;

    不同形状

    // 圆形头像
<VisualList data={imageData} shape="circle" />

// 方形头像
<VisualList data={imageData} shape="default" />

    组件变体

    // 带边框
<VisualList data={imageData} variant="outline" />

// 无边框
<VisualList data={imageData} variant="borderless" />

    带描述文字

    <VisualList data={imageData} description="这里是列表的描述信息" />

    数据过滤

    // 只显示有链接的图片
<VisualList data={imageData} filter={(item) => item.href !== undefined} />

    自定义渲染

    <VisualList
  data={imageData}
  renderItem={(item, index) => (
    <li key={item.id || index} style={{ padding: '8px' }}>
      <img src={item.src} alt={item.alt} style={{ width: 50, height: 50 }} />
      <span>{item.title}</span>
    </li>
  )}
/>

    空状态和加载状态

    // 空状态
<VisualList
  data={[]}
  emptyRender={() => <div>暂无图片数据</div>}
/>

// 加载状态
<VisualList
  data={[]}
  isLoading={true}
  loadingRender={() => <div>正在加载...</div>}
/>

    样式定制

    组件使用了以下的样式变量，可以通过 CSS-in-JS 进行样式定制：

    {
  // 主容器样式
  display: 'flex',
  flexFlow: 'wrap',
  gap: '8px',

  // 列表项样式
  itemBorderRadius: '8px',
  itemBorder: '1px solid #ddd',
  itemHoverBorderColor: '#007acc',
  itemHoverShadow: '0 2px 8px rgba(0, 122, 204, 0.15)',

  // 图片尺寸
  imageSize: '24px',

  // 链接样式
  linkFocusOutline: '2px solid #007acc',
  linkFocusOutlineOffset: '2px'
}

    设计理念

    • 灵活性: 支持多种尺寸、形状和自定义渲染
    • 可访问性: 提供完整的键盘导航和屏幕阅读器支持
    • 性能: 基于 css-in-js 的样式隔离，避免样式冲突
    • 主题支持: 与项目的主题系统完全集成
    • 类型安全: 完整的 TypeScript 类型定义