xlzw-card-list
可复用的卡片列表组件（基于 Vue 3 + ant-design-vue），支持外部注入配置请求
336
| Install | |
|---|---|
npm install xlzw-card-list |
|
| Latest Version: | 0.2.0 |
| Vue: | 3 |
| License: | MIT |
| Last Updated: | Sep 20, 2026 |
| Links: | npm |
Maintainer: npmdengyan
xlzw-card-list
基于 Vue 3 + ant-design-vue 的可复用卡片列表组件。卡片列配置由外部注入（请求函数或直接传配置），组件本身不绑定任何后端接口。
安装
npm install xlzw-card-list
需要宿主项目自行提供（peerDependencies）：
npm install vue@^3.3.0 ant-design-vue@^4.0.0
引入
import { createApp } from "vue";
import CardList from "xlzw-card-list";
import "xlzw-card-list/style.css";
const app = createApp(App);
app.use(CardList); // 全局注册为 <CardList />
或按需局部引入：
<script setup>
import { CardList } from "xlzw-card-list";
import "xlzw-card-list/style.css";
</script>
用法一：外部注入请求函数（推荐）
fetchConfig(cardId) 需返回 Promise<{ propertys, width }>：
<template>
<CardList
:card="orderList"
:card-id="cardId"
:fetch-config="fetchCardConfig"
@select-item="onSelect"
@scroll="onLoadMore"
>
<template #action="{ item }">
<a-button size="small" @click.stop="onDetail(item)">详情</a-button>
</template>
</CardList>
</template>
<script setup>
import { getUiCardList } from "@/api/index";
async function fetchCardConfig(cardId) {
const res = await getUiCardList(cardId);
return {
propertys: res.data.propertys,
width: res.data.card.width,
};
}
</script>
用法二：直接传入配置
不传 fetchConfig、直接传 propertys + width 时，组件只做展示：
<CardList :card="list" :propertys="propertys" :width="320" />
列配置（propertys）
propertys 为列配置数组，每一项（group）常用字段：
| 字段 | 说明 |
|---|---|
type |
列类型：image / text / date / progress / action |
fieldName |
取数字段名；state、type 会经 data 映射，progress 用逗号分隔两个字段（如 "done,total"） |
label |
标签文本 |
span |
列宽（ant a-col 栅格） |
labelSpan / wrapperSpan |
标签 / 内容栅格宽度 |
show |
"1" 显示，其他隐藏 |
bold |
1 加粗 |
defaultValue |
image 列取值为空时的兜底图 |
data |
state / type 列的 JSON 字符串，用于值到文案的映射 |
进度条列依赖宿主项目全局注册名为
Progress的组件（本包不内置、不 import），组件接收NumberOne、NumberTwo两个 prop。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
card |
Array |
[] |
卡片展示数据 |
cardId |
String | Number |
"0" |
配置 id，配合 fetchConfig 使用 |
fetchConfig |
(cardId) => Promise<{ propertys, width }> |
null |
外部注入的配置请求函数 |
propertys |
Array |
[] |
直接传入的列配置，传入后优先于 fetchConfig |
width |
Number |
0 |
卡片宽度（px），配合 propertys 使用 |
Events
| 名称 | 参数 | 说明 |
|---|---|---|
selectItem |
item |
点击某张卡片时触发 |
scroll |
- | 列表滚动到底部时触发（用于加载更多） |
Slots
| 名称 | 参数 | 说明 |
|---|---|---|
action |
{ item } |
每张卡片的自定义操作区；仅当 propertys 中存在 type: 'action' 的列时渲染 |
Expose
| 名称 | 说明 |
|---|---|
selectItem(item, field?) |
手动选中卡片；传 field 时按该字段匹配 |
本地开发 / 发布
cd packages/card-list
npm install
npm run build # 产物在 dist/，含 card-list.js / card-list.umd.cjs / style.css
npm pack # 本地打包，检查 tarball 内容
npm publish --access public # scope 包首次发布需带 --access public
Related Packages
Version History
| Version | Released | Vue | License |
|---|---|---|---|
| 0.2.0 | ^3.3.0 | MIT | |
| 0.1.0 | ^3.3.0 | MIT |