BreezeUI
  • 简体中文

    • List 列表

    基于 BrConfigProvider 实现全局主题配置，支持分组、选中、虚拟滚动的企业级列表组件。

    组件特性

    • 📦 完整能力：支持列表分组、分隔线、加载状态、空状态、嵌套折叠等企业级需求。
    • 🎨 主题配置：基于 BrConfigProvider，支持全局变量配置与深色模式无缝切换。
    • ⚡ 虚拟滚动：内置虚拟滚动能力，轻松应对大数据量渲染。
    • ⌨️ 键盘导航：完善的无障碍体验，支持上下键导航，Enter触发选中。

    基础列表与交互状态

    提供基础列表布局，并支持 hoverable（悬停）、clickable（可点击）等交互状态。

    <script setup lang="ts">
import { BrList, BrListItem, BrListHeader, BrListFooter } from '@breezeui/vue'
import { Bell, FileText, Settings } from 'lucide-vue-next'
</script>

<template>
  <BrList hoverable clickable class="max-w-md mx-auto" variant="bordered">
    <BrListHeader>Notification Settings</BrListHeader>
    <BrListItem>
      <Bell class="w-4 h-4 mr-2" />
      Messages
    </BrListItem>
    <BrListItem>
      <FileText class="w-4 h-4 mr-2" />
      System Announcements
    </BrListItem>
    <BrListItem>
      <Settings class="w-4 h-4 mr-2" />
      Preferences
    </BrListItem>
    <BrListFooter>You can change these settings at any time</BrListFooter>
  </BrList>
</template>

    分组列表与分隔线

    使用 BrListGroup 和 BrListDivider 进行列表项分区和分隔。

    <script setup lang="ts">
import { BrList, BrListItem, BrListGroup, BrListDivider } from '@breezeui/vue'
</script>

<template>
  <BrList class="max-w-md mx-auto" variant="bordered">
    <BrListGroup title="R&D Department">
      <BrListItem>Zhang San (Frontend Engineer)</BrListItem>
      <BrListItem>Li Si (Backend Engineer)</BrListItem>
    </BrListGroup>
    
    <BrListDivider />
    
    <BrListGroup title="Design Department">
      <BrListItem>Wang Wu (UI Designer)</BrListItem>
      <BrListItem>Zhao Liu (UX Designer)</BrListItem>
    </BrListGroup>
  </BrList>
</template>

    可选中与激活态

    支持单选或多选逻辑，通过 selected 和 active 状态区分当前列表项。

    <script setup lang="ts">
import { ref } from 'vue'
import { BrList, BrListItem } from '@breezeui/vue'
import { Check } from 'lucide-vue-next'

const selectedIndex = ref(1)
const items = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']
</script>

<template>
  <BrList selectable class="max-w-sm mx-auto" variant="bordered">
    <BrListItem
      v-for="(item, index) in items"
      :key="item"
      :selected="selectedIndex === index"
      @click="selectedIndex = index"
    >
      {{ item }}
      <template v-if="selectedIndex === index" #extra>
        <Check class="w-4 h-4 text-primary" />
      </template>
    </BrListItem>
  </BrList>
</template>

    虚拟滚动大数据列表

    针对几千到上万条数据的场景，开启 virtualScroll 即可实现高性能滚动。

    <script setup lang="ts">
import { ref } from 'vue'
import { BrList, BrListItem } from '@breezeui/vue'

const items = ref(Array.from({ length: 10000 }).map((_, i) => ({
  id: i,
  label: `Test Data - Item ${i + 1}`
})))
</script>

<template>
  <BrList
    variant="bordered"
    class="max-w-md mx-auto"
    virtual-scroll
    :items="items"
    :item-height="44"
  >
    <template #item="{ item, index }">
      <BrListItem hoverable striped>
        <span class="text-muted-foreground w-10">{{ index + 1 }}</span>
        {{ item.label }}
      </BrListItem>
    </template>
  </BrList>
</template>

    API

    BrList

    核心容器组件。

    属性类型默认值说明
    size'sm' | 'default' | 'lg''default'列表全局尺寸
    variant'default' | 'bordered' | 'ghost''default'列表外观变体
    hoverablebooleanfalse全局开启列表项悬停效果
    clickablebooleanfalse全局开启列表项可点击效果
    selectablebooleanfalse全局开启列表项可选效果
    stripedbooleanfalse是否显示斑马纹
    loadingbooleanfalse是否显示加载状态
    disabledbooleanfalse全局禁用列表
    virtualScrollbooleanfalse是否开启虚拟滚动
    itemsany[][]虚拟滚动的数据源
    itemHeightnumber40虚拟滚动的列表项预估高度

    BrListItem

    列表项组件。

    属性类型默认值说明
    align'start' | 'center' | 'end''center'内部对齐方式
    disabledbooleanfalse禁用当前项
    activebooleanfalse激活状态样式
    selectedbooleanfalse选中状态样式

    插槽 (Slots)

    • default: 主体内容
    • extra: 右侧附加内容（操作按钮/徽标）
    • nested: 嵌套子列表内容
    • expand-icon: 自定义展开图标

    BrListGroup

    列表分组组件。

    属性类型默认值说明
    titlestring-分组标题

    BrListHeader / BrListFooter / BrListDivider / BrListEmpty / BrListLoading

    辅助结构组件，支持通过 class 自定义样式。

    主题定制

    BrList 深度集成 BrConfigProvider，支持以下两种级别的主题定制：

    1. 全局配置 (BrConfigProvider)

    通过调整应用根节点的配置，直接影响 BrList 的默认颜色体系。

    
<template>
  <BrConfigProvider :theme="themeConfig">
    <BrList variant="bordered" hoverable>
      <BrListItem>支持暗黑模式</BrListItem>
    </BrList>
  </BrConfigProvider>
</template>

    2. 局部覆盖 (TailwindCSS)

    你可以通过传入 class 使用 Tailwind 原子类精准覆盖任何默认样式。

    <template>
  <!-- 自定义背景色和边框颜色 -->
  <BrList class="bg-blue-50 border-blue-200 dark:bg-blue-900/20" variant="bordered">
    <!-- 覆盖 hover 颜色和选中色 -->
    <BrListItem class="hover:bg-blue-100 dark:hover:bg-blue-800" selected>
      定制化列表项
    </BrListItem>
  </BrList>
</template>