图片盒子组件
图片盒子组件 (BoxPicture) 是一个专为展示图片内容设计的网格布局组件，支持响应式设计和暗色/亮色模式切换。它可用于产品展示、服务介绍、相册集等场景。
引入组件
首先需要在 VitePress 主题配置中注册组件：
.vitepress/theme/index.ts
ts
import DefaultTheme from 'vitepress/theme'
// 导入组件
import DocBoxPicture from '../../components/DocBoxPicture.vue'
export default {
extends: DefaultTheme,
enhanceApp: ({ app }) => {
// 注册组件
app.component('BoxPicture', DocBoxPicture)
}
}基本用法
输入
vue
<BoxPicture
:items="[
{
name: '智能家居控制中心',
desc: '一键控制全屋智能设备，打造智慧生活体验',
link: '#',
image: 'https://picsum.photos/id/180/800/600',
tag: '热门'
},
{
name: '全自动清洁机器人',
desc: '家居清洁的智能解决方案',
link: '#',
image: 'https://picsum.photos/id/96/800/600',
}
]"
/>输出
自定义宽高
通过 defaultWidth 和 defaultHeight 属性可以设置所有卡片的默认尺寸，也可以为单个卡片设置特定宽高：
输入
vue
<BoxPicture
defaultWidth="250px"
defaultHeight="300px"
:items="[
{
name: '智能家居控制中心',
desc: '一键控制全屋智能设备',
link: '#',
image: 'https://picsum.photos/id/180/800/600',
},
{
name: '全自动清洁机器人',
desc: '家居清洁的智能解决方案',
link: '#',
image: 'https://picsum.photos/id/96/800/600',
width: '350px', // 特定卡片自定义宽度
height: '300px', // 特定卡片自定义高度
}
]"
/>输出
自定义对齐方式
通过 alignment 属性可以设置卡片在容器中的对齐方式，支持 start、center、end、space-between、space-around 和 space-evenly 六种对齐方式：
输入
vue
<BoxPicture
alignment="center"
:items="[
{
name: '智能家居控制中心',
desc: '一键控制全屋智能设备',
link: '#',
image: 'https://picsum.photos/id/180/800/600',
},
{
name: '全自动清洁机器人',
desc: '家居清洁的智能解决方案',
link: '#',
image: 'https://picsum.photos/id/96/800/600',
}
]"
/>输出
深色/浅色模式图片
支持为不同的显示模式设置不同的图片：
输入
vue
<BoxPicture
:items="[
{
name: '自适应模式',
desc: '根据系统模式自动切换图片',
link: '#',
image: {
light: 'https://picsum.photos/id/110/800/600',
dark: 'https://picsum.photos/id/160/800/600'
}
}
]"
/>输出
参数说明
BoxPicture 组件参数
| 参数名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
items | BoxPictureItem[] | 必填 | 图片盒子项目数组 |
defaultWidth | string | '240px' | 默认卡片宽度 |
defaultHeight | string | '240px' | 默认卡片高度 |
alignment | string | 'start' | 卡片在容器中的对齐方式，可选值：'start'、'center'、'end'、'space-between'、'space-around'、'space-evenly' |
BoxPictureItem 项目参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
name | string | 是 | 项目名称 |
desc | string | 否 | 项目描述 |
link | string | 否 | 链接地址，外部链接将在新标签页打开。如不提供，则创建不可点击的展示卡片 |
image | string | { light: string; dark: string } | 是 | 图片地址，可以是单一图片地址或深/浅模式图片对象 |
tag | string | 否 | 右上角显示的标签文本 |
tagType | string | 否 | 标签类型，决定标签的背景颜色。可选值：'default'、'primary'、'success'、'warning'、'danger'、'info'。默认为 'default' |
width | string | 否 | 单个卡片的自定义宽度，覆盖默认宽度 |
height | string | 否 | 单个卡片的自定义高度，覆盖默认高度 |
不可点击的展示卡片
当不提供 link 属性时，将创建不可点击的纯展示卡片：
输入
vue
<BoxPicture
:items="[
{
name: '展示图片1',
desc: '这是一个不可点击的展示卡片',
image: 'https://picsum.photos/id/237/800/600',
},
{
name: '展示图片2',
desc: '这个卡片可以点击',
link: '#',
image: 'https://picsum.photos/id/238/800/600',
}
]"
/>输出
彩色标签
您可以使用 tagType 属性为标签设置不同的颜色，以突出显示不同类型的内容：
输入
vue
<BoxPicture
:items="[
{
name: '默认标签',
desc: '使用默认标签颜色',
image: 'https://picsum.photos/id/231/800/600',
tag: '默认',
},
{
name: '主要标签',
desc: '使用蓝色主要标签',
image: 'https://picsum.photos/id/232/800/600',
tag: '主要',
tagType: 'primary',
},
{
name: '成功标签',
desc: '使用绿色成功标签',
image: 'https://picsum.photos/id/233/800/600',
tag: '成功',
tagType: 'success',
},
{
name: '警告标签',
desc: '使用橙色警告标签',
image: 'https://picsum.photos/id/234/800/600',
tag: '警告',
tagType: 'warning',
},
{
name: '危险标签',
desc: '使用红色危险标签',
image: 'https://picsum.photos/id/235/800/600',
tag: '危险',
tagType: 'danger',
},
{
name: '信息标签',
desc: '使用浅蓝色信息标签',
image: 'https://picsum.photos/id/236/800/600',
tag: '信息',
tagType: 'info',
}
]"
/>输出
默认标签
使用默认标签颜色
默认
主要标签
使用蓝色主要标签
主要
成功标签
使用绿色成功标签
成功
警告标签
使用橙色警告标签
警告
危险标签
使用红色危险标签
危险
信息标签
使用浅蓝色信息标签
信息
不同对齐方式的效果
左对齐 (start)
默认对齐方式，卡片从容器左侧开始排列。
居中对齐 (center)
卡片在容器中居中排列。
两端对齐 (space-between)
首尾卡片紧贴容器边缘，中间卡片平均分布。
响应式设计
BoxPicture 组件内置了响应式设计：
- 在大屏幕上（>1280px），每个卡片保持原尺寸
- 中等屏幕（768px-1280px）上，每行显示3个卡片
- 小屏幕（480px-768px）上，每行显示2个卡片
- 在移动设备（<480px）上，每行显示1个卡片
注意事项
- 图片建议使用相同比例的图片，以保持统一的视觉效果
- 描述文字超过两行会被截断显示为省略号
- 外部链接会自动在新标签页打开
- 选择合适的对齐方式可以优化不同数量卡片的布局效果