# Box 组件

一个灵活的容器组件，带有可选的标题栏和底部区域，非常适合创建卡片、面板和内容区域。

## 功能特性

- **结构化布局**: 标题栏、内容和底部区域
- **灵活样式**: 每个区域的独立样式定制
- **可选元素**: 标题栏和底部区域仅在需要时渲染
- **圆角设计**: 可选的圆角样式
- **标题支持**: 内置标题显示或自定义标题栏内容
- **响应式**: 适应容器尺寸

## 基本用法

```svelte
<script>
import Box from '@ticatec/uniface-element/Box';
</script>

<Box title="我的盒子">
  <p>内容放在这里</p>
</Box>
```

## 属性参数

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `title` | `string` | `null` | 标题栏的标题文本 |
| `style` | `string \| null` | `null` | 主容器的自定义CSS样式 |
| `round` | `boolean` | `false` | 启用圆角 |
| `content$style` | `string \| null` | `null` | 内容区域的自定义CSS样式 |
| `header$style` | `string \| null` | `null` | 标题栏区域的自定义CSS样式 |
| `footer$style` | `string \| null` | `null` | 底部区域的自定义CSS样式 |
| `class` | `string` | `null` | 额外的CSS类名 |

## 插槽

| 插槽 | 描述 |
|------|-------------|
| `header` | 自定义标题栏内容（覆盖title属性） |
| `default` | 主内容区域 |
| `footer` | 底部内容 |

## 使用示例

### 带标题的基础盒子

```svelte
<Box title="信息">
  <p>这是一些需要在盒子中显示的重要信息。</p>
</Box>
```

### 自定义标题栏内容

```svelte
<Box>
  <div slot="header" style="display: flex; justify-content: space-between; align-items: center;">
    <h3>自定义标题栏</h3>
    <button>操作</button>
  </div>
  
  <p>带有自定义标题栏的内容</p>
</Box>
```

### 完整的带底部区域的盒子

```svelte
<Box title="用户资料">
  <div class="profile-content">
    <img src="/avatar.jpg" alt="用户头像" />
    <h4>张三</h4>
    <p>软件开发工程师</p>
  </div>
  
  <div slot="footer">
    <button>编辑资料</button>
    <button>查看详情</button>
  </div>
</Box>
```

### 圆角盒子

```svelte
<Box title="圆角卡片" round={true}>
  <p>这个盒子有圆角，外观更柔和。</p>
</Box>
```

### 样式化区域

```svelte
<Box 
  title="样式化盒子"
  style="border: 2px solid #007acc; box-shadow: 0 4px 8px rgba(0,0,0,0.1);"
  header$style="background: #007acc; color: white; padding: 16px;"
  content$style="padding: 20px; background: #f9f9f9;"
  footer$style="background: #e9e9e9; padding: 12px; text-align: right;"
>
  <p>每个区域都有自定义样式的内容。</p>
  
  <div slot="footer">
    <button>取消</button>
    <button>保存</button>
  </div>
</Box>
```

### 仪表板小部件

```svelte
<Box 
  title="销售概览"
  round={true}
  style="margin: 16px; box-shadow: 0 2px 8px rgba(0,0,0,0.1);"
>
  <div slot="header" style="display: flex; justify-content: space-between; align-items: center;">
    <h3>销售概览</h3>
    <select>
      <option>本月</option>
      <option>上月</option>
      <option>今年</option>
    </select>
  </div>
  
  <div class="metrics">
    <div class="metric">
      <span class="value">¥12,345</span>
      <span class="label">收入</span>
    </div>
    <div class="metric">
      <span class="value">89</span>
      <span class="label">订单</span>
    </div>
  </div>
  
  <div slot="footer">
    <a href="/reports/sales">查看详细报告 →</a>
  </div>
</Box>
```

### 设置面板

```svelte
<Box title="账户设置">
  <div class="settings-form">
    <div class="form-group">
      <label>邮件通知</label>
      <input type="checkbox" checked />
    </div>
    <div class="form-group">
      <label>语言</label>
      <select>
        <option>中文</option>
        <option>English</option>
        <option>日本語</option>
      </select>
    </div>
  </div>
  
  <div slot="footer" style="text-align: right; gap: 8px;">
    <button type="button">重置</button>
    <button type="submit">保存更改</button>
  </div>
</Box>
```

### 文章卡片

```svelte
<Box round={true} class="article-card">
  <div slot="header">
    <img src="/article-thumb.jpg" alt="文章" class="article-image" />
    <div class="article-meta">
      <h3>理解Svelte组件</h3>
      <p class="byline">作者：李雷 • 2024年3月15日</p>
    </div>
  </div>
  
  <p>学习在Svelte中构建可重用组件的基础知识...</p>
  
  <div slot="footer" style="display: flex; justify-content: space-between; align-items: center;">
    <div class="tags">
      <span class="tag">Svelte</span>
      <span class="tag">教程</span>
    </div>
    <button>阅读更多</button>
  </div>
</Box>
```

### 纯内容盒子

```svelte
<!-- 没有标题栏或底部区域的盒子，只是样式化的内容 -->
<Box 
  style="border: 1px solid #ddd; border-radius: 8px; padding: 0;"
  content$style="padding: 24px;"
>
  <div class="notification">
    <i class="icon-info"></i>
    <p>这是一条重要的通知消息。</p>
  </div>
</Box>
```

## 布局结构

Box组件由三个主要区域组成：

1. **标题栏**（可选）: 显示标题或自定义内容
2. **内容**（必需）: 通过默认插槽的主内容区域
3. **底部**（可选）: 操作按钮或附加信息

## 样式定制

组件使用以下CSS类：

- `.uniface-box` - 主容器
- `.box-header` - 标题栏区域容器
- `.box-content` - 内容区域容器
- `.box-footer` - 底部区域容器
- `.title` - 标题文本包装器
- `.round` - 当round属性为true时应用

### CSS示例

```css
.uniface-box {
  border: 1px solid #e0e0e0;
  background: #ffffff;
  overflow: hidden;
}

.uniface-box.round {
  border-radius: 8px;
}

.box-header {
  background: #f8f9fa;
  border-bottom: 1px solid #e0e0e0;
  padding: 16px;
}

.box-content {
  padding: 16px;
}

.box-footer {
  background: #f8f9fa;
  border-top: 1px solid #e0e0e0;
  padding: 12px 16px;
}

.title {
  font-weight: 600;
  color: #333;
}
```

## 常见模式

### 信息面板

```svelte
<Box title="系统信息" round={true}>
  <div class="info-grid">
    <div class="info-item">
      <strong>版本:</strong> 2.1.0
    </div>
    <div class="info-item">
      <strong>最后更新:</strong> 2024年3月15日
    </div>
    <div class="info-item">
      <strong>状态:</strong> 活动
    </div>
  </div>
</Box>
```

### 操作卡片

```svelte
<Box>
  <div slot="header" style="text-align: center;">
    <i class="large-icon icon-upload"></i>
    <h3>上传文件</h3>
  </div>
  
  <p style="text-align: center; color: #666;">
    将文件拖拽到这里或点击浏览
  </p>
  
  <div slot="footer" style="text-align: center;">
    <button>选择文件</button>
  </div>
</Box>
```

### 统计小部件

```svelte
<Box title="网站分析" round={true}>
  <div class="stats-grid">
    <div class="stat">
      <div class="stat-value">1,234</div>
      <div class="stat-label">访客</div>
    </div>
    <div class="stat">
      <div class="stat-value">89%</div>
      <div class="stat-label">跳出率</div>
    </div>
  </div>
  
  <div slot="footer">
    <button>查看完整报告</button>
  </div>
</Box>
```

## 响应式设计

对于响应式布局，考虑使用CSS Grid或Flexbox：

```css
.box-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 16px;
  padding: 16px;
}

@media (max-width: 768px) {
  .uniface-box {
    margin: 8px;
  }
  
  .box-header,
  .box-content,
  .box-footer {
    padding: 12px;
  }
}
```

## 无障碍访问

- 在插槽中使用语义化HTML
- 确保标题栏中的适当标题层次
- 提供足够的颜色对比度
- 使交互元素支持键盘访问

## 最佳实践

1. **一致的间距**: 在所有盒子中使用一致的内边距/外边距
2. **视觉层次**: 在标题栏中使用适当的排版
3. **操作位置**: 将主要操作放在底部区域
4. **内容组织**: 逻辑地分组相关内容
5. **响应式设计**: 在不同屏幕尺寸上测试
6. **加载状态**: 考虑为动态内容显示加载状态

## 与其他组件集成

Box组件与其他组件配合良好：

```svelte
<Box title="表单示例">
  <FormField label="姓名">
    <TextEditor value={name} />
  </FormField>
  
  <FormField label="选项">
    <OptionsSelect options={choices} bind:value={selected} />
  </FormField>
  
  <div slot="footer">
    <ActionBar buttons={formActions} />
  </div>
</Box>
```

## 注意事项

- 确保标题栏和底部区域的内容不会过于拥挤
- 在移动设备上考虑减少内边距以节省空间
- 对于长内容，考虑添加滚动或分页
- 保持与整体设计系统的一致性
- 在深色主题中测试颜色对比度