@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/box/README_CN.md

@@ -0,0 +1,393 @@
+# 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>
+```
+
+## 注意事项
+
+- 确保标题栏和底部区域的内容不会过于拥挤
+- 在移动设备上考虑减少内边距以节省空间
+- 对于长内容，考虑添加滚动或分页
+- 保持与整体设计系统的一致性
+- 在深色主题中测试颜色对比度