@fish-render/descriptions/README.md

Fish Render descriptions component for Vue 3

# @fish-render/descriptions

Vue 3 描述列表组件，支持响应式布局和多种样式引入方式。

## 安装

```bash
npm install @fish-render/descriptions
# 或
yarn add @fish-render/descriptions
# 或
pnpm add @fish-render/descriptions
```

## 使用方法

### 方式一：自动引入样式（推荐）

当你引入组件时，样式会自动加载：

```vue
<template>
  <Descriptions title="用户信息" :column="3">
    <DescriptionsItem label="姓名">张三</DescriptionsItem>
    <DescriptionsItem label="年龄">25</DescriptionsItem>
    <DescriptionsItem label="职业">工程师</DescriptionsItem>
  </Descriptions>
</template>

<script setup>
import { Descriptions, DescriptionsItem } from '@fish-render/descriptions'
// 样式会自动加载，无需额外引入
</script>
```

### 方式二：手动引入样式

如果你想要手动控制样式的引入时机：

```vue
<template>
  <Descriptions title="用户信息" :column="3">
    <DescriptionsItem label="姓名">张三</DescriptionsItem>
    <DescriptionsItem label="年龄">25</DescriptionsItem>
    <DescriptionsItem label="职业">工程师</DescriptionsItem>
  </Descriptions>
</template>

<script setup>
import { Descriptions, DescriptionsItem } from '@fish-render/descriptions'
</script>

<style>
/* 手动引入样式 */
@import '@fish-render/descriptions/style.css';
</style>
```

### 方式三：在 main.js 中全局引入

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import { Descriptions, DescriptionsItem } from '@fish-render/descriptions'
import '@fish-render/descriptions/style.css'

const app = createApp(App)

app.component('Descriptions', Descriptions)
app.component('DescriptionsItem', DescriptionsItem)

app.mount('#app')
```

### 方式四：使用插件方式

```javascript
import { createApp } from 'vue'
import App from './App.vue'
import DescriptionsPlugin from '@fish-render/descriptions'

const app = createApp(App)
app.use(DescriptionsPlugin)
app.mount('#app')
```

## 示例

### 基础用法

```vue
<template>
  <Descriptions title="用户信息">
    <DescriptionsItem label="姓名">张三</DescriptionsItem>
    <DescriptionsItem label="年龄">25</DescriptionsItem>
    <DescriptionsItem label="职业">工程师</DescriptionsItem>
    <DescriptionsItem label="邮箱">zhangsan@example.com</DescriptionsItem>
  </Descriptions>
</template>
```

### 响应式列数

```vue
<template>
  <Descriptions title="产品信息" :column="{ xs: 1, sm: 2, md: 3, lg: 4 }">
    <DescriptionsItem label="产品名称">Vue 3 组件库</DescriptionsItem>
    <DescriptionsItem label="版本">1.0.0</DescriptionsItem>
    <DescriptionsItem label="作者">Fish Render</DescriptionsItem>
    <DescriptionsItem label="许可证">MIT</DescriptionsItem>
  </Descriptions>
</template>
```

### 自定义布局

```vue
<template>
  <Descriptions title="项目详情" layout="vertical" :gutter="[16, 24]" label-width="120px">
    <DescriptionsItem label="项目名称" :span="2">Fish Render</DescriptionsItem>
    <DescriptionsItem label="技术栈">Vue 3 + TypeScript</DescriptionsItem>
    <DescriptionsItem label="描述" :span="3">
      一个现代化的 Vue 3 组件库，提供丰富的 UI 组件和优秀的开发体验
    </DescriptionsItem>
  </Descriptions>
</template>
```

### 自定义样式

```vue
<template>
  <Descriptions title="自定义样式示例" class="custom-descriptions">
    <DescriptionsItem label="标签" label-class="custom-label"> 内容 </DescriptionsItem>
    <DescriptionsItem label="标签" content-class="custom-content"> 内容 </DescriptionsItem>
  </Descriptions>
</template>

<style>
.custom-descriptions {
  border: 1px solid #e8e8e8;
  border-radius: 8px;
  padding: 16px;
}

.custom-label {
  color: #1890ff;
  font-weight: bold;
}

.custom-content {
  color: #666;
}
</style>
```

## API

### Descriptions Props

| 参数       | 类型                                     | 默认值                  | 说明           |
| ---------- | ---------------------------------------- | ----------------------- | -------------- |
| title      | string                                   | ''                      | 描述列表的标题 |
| column     | number \| Responsive                     | { xs: 1, sm: 2, lg: 3 } | 列数配置       |
| layout     | 'horizontal' \| 'vertical' \| 'auto'     | 'auto'                  | 布局方式       |
| gutter     | number \| [number, number] \| Responsive | 15                      | 间距配置       |
| labelWidth | number \| string                         | undefined               | 标签宽度       |

### DescriptionsItem Props

| 参数         | 类型                      | 默认值    | 说明       |
| ------------ | ------------------------- | --------- | ---------- |
| label        | string                    | ''        | 标签文本   |
| span         | number \| Responsive      | 1         | 跨列数     |
| labelWidth   | number \| string          | undefined | 标签宽度   |
| labelClass   | string \| object \| array | undefined | 标签样式类 |
| contentClass | string \| object \| array | undefined | 内容样式类 |

### 类型定义

```typescript
// 响应式配置类型
type Responsive = {
  xs?: number
  sm?: number
  md?: number
  lg?: number
  xl?: number
}

// 列数类型
type ColumnType = number | Responsive

// 布局类型
type LayoutType = 'auto' | 'horizontal' | 'vertical'

// Descriptions 组件 Props
interface DescriptionsProps {
  title?: string
  column?: ColumnType
  layout?: LayoutType
  gutter?: number | [number, number] | Responsive
  labelWidth?: number | string
}

// DescriptionsItem 组件 Props
interface DescriptionsItemProps {
  label?: string
  labelClass?: string | object | string[] | object[]
  contentClass?: string | object | string[] | object[]
  span?: number | Responsive
  labelWidth?: string | number
}
```

## 样式自定义

组件使用 CSS 类名，你可以通过覆盖这些类名来自定义样式：

```css
/* 描述列表容器 */
.desc-container {
  /* 自定义容器样式 */
}

/* 描述列表头部 */
.desc-header {
  /* 自定义头部样式 */
}

/* 描述列表网格 */
.desc-grid {
  /* 自定义网格样式 */
}

/* 描述列表项 */
.desc-item {
  /* 自定义项目样式 */
}

/* 描述列表标签 */
.desc-label {
  /* 自定义标签样式 */
}

/* 描述列表内容 */
.desc-content {
  /* 自定义内容样式 */
}
```

## 响应式断点

组件使用以下响应式断点，与 Tailwind CSS 保持一致：

- `xs`: 0px 及以上
- `sm`: 640px 及以上
- `md`: 768px 及以上
- `lg`: 1024px 及以上
- `xl`: 1280px 及以上

## 注意事项

1. **浏览器兼容性**：组件使用了 CSS Grid 布局，确保在现代浏览器中使用
2. **响应式设计**：响应式断点与 Tailwind CSS 保持一致
3. **样式加载**：样式是全局的，会在应用启动时自动加载
4. **Tree Shaking**：如果你使用 Tree Shaking，建议使用手动引入样式的方式
5. **TypeScript 支持**：组件完全支持 TypeScript，提供完整的类型定义

## 开发

```bash
# 安装依赖
pnpm install

# 构建组件
pnpm run build:component descriptions

# 发布组件
pnpm run publish:component descriptions
```

## 许可证

MIT License