@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/app-layout/README_CN.md

@@ -0,0 +1,381 @@
+# 应用布局组件
+
+一套灵活的布局组件，用于构建带有标题栏、侧边栏和可调整面板的应用程序界面。
+
+## 可用组件
+
+- **SidebarLayout** - 带有可选侧边栏和标题栏的布局
+- **HeaderLayout** - 带有标题栏和可选下方侧边栏的布局
+- **ClassicLayout** - 传统应用程序布局，包含标题栏、侧边栏和状态栏
+- **ColumnsLayout** - 灵活的基于列的布局，带有可调整面板
+- **RowsLayout** - 灵活的基于行的布局，带有可调整面板
+
+## 导入
+
+```svelte
+<script>
+// 导入单个布局组件
+import { SidebarLayout } from '@ticatec/uniface-element/app-layout';
+import HeaderLayout from '@ticatec/uniface-element/app-layout/HeaderLayout';
+import ClassicLayout from '@ticatec/uniface-element/app-layout/ClassicLayout';
+import ColumnsLayout from '@ticatec/uniface-element/app-layout/ColumnsLayout';
+import RowsLayout from '@ticatec/uniface-element/app-layout/RowsLayout';
+</script>
+```
+
+## SidebarLayout
+
+带有可选左侧可调整侧边栏和标题区域的布局。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `sidebarResize` | `boolean` | `false` | 启用侧边栏调整大小 |
+| `headerHeight` | `string` | `"48px"` | 标题区域高度 |
+| `sidebarWidth` | `string` | `"300px"` | 侧边栏初始宽度 |
+| `sidebarMaxWidth` | `string \| null` | `null` | 侧边栏最大宽度 |
+| `sidebarMinWidth` | `string \| null` | `null` | 侧边栏最小宽度 |
+
+### 插槽
+
+- `sidebar` - 侧边栏区域内容
+- `header` - 标题区域内容
+- `default` - 主内容区域
+
+### 示例
+
+```svelte
+<SidebarLayout 
+  sidebarResize={true}
+  sidebarWidth="250px"
+  sidebarMinWidth="200px"
+  sidebarMaxWidth="400px"
+>
+  <div slot="sidebar">
+    <!-- 导航菜单 -->
+  </div>
+  
+  <div slot="header">
+    <!-- 顶部栏内容 -->
+  </div>
+  
+  <!-- 主内容 -->
+  <div>主应用程序内容</div>
+</SidebarLayout>
+```
+
+## HeaderLayout
+
+顶部带有标题栏，标题栏下方有可选侧边栏的布局。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `headerHeight` | `string` | `"48px"` | 标题栏高度 |
+| `sidebarWidth` | `string` | `"300px"` | 侧边栏宽度 |
+| `sidebarResize` | `boolean` | `false` | 启用侧边栏调整大小 |
+| `sidebarMaxWidth` | `string \| null` | `null` | 侧边栏最大宽度 |
+| `sidebarMinWidth` | `string \| null` | `null` | 侧边栏最小宽度 |
+
+### 插槽
+
+- `header` - 标题区域内容
+- `sidebar` - 侧边栏区域内容
+- `default` - 主内容区域
+
+### 示例
+
+```svelte
+<HeaderLayout headerHeight="60px" sidebarResize={true}>
+  <div slot="header">
+    <!-- 应用标题栏 -->
+  </div>
+  
+  <div slot="sidebar">
+    <!-- 侧边导航 -->
+  </div>
+  
+  <!-- 主内容 -->
+  <div>页面内容</div>
+</HeaderLayout>
+```
+
+## ClassicLayout
+
+传统桌面应用程序布局，包含标题栏、左侧边栏、可选右侧边栏和状态栏。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `headerHeight` | `string` | `"48px"` | 标题栏高度 |
+| `sidebarWidth` | `string` | `"300px"` | 左侧边栏宽度 |
+| `statusHeight` | `string` | `"22px"` | 状态栏高度 |
+| `rightBarWidth` | `string` | `"240px"` | 右侧边栏宽度 |
+| `sidebarResize` | `boolean` | `false` | 启用左侧边栏调整大小 |
+| `sidebarMaxWidth` | `string \| null` | `null` | 左侧边栏最大宽度 |
+| `sidebarMinWidth` | `string \| null` | `null` | 左侧边栏最小宽度 |
+| `rightBarResize` | `boolean` | `false` | 启用右侧边栏调整大小 |
+| `rightBarMaxWidth` | `string \| null` | `null` | 右侧边栏最大宽度 |
+| `rightBarMinWidth` | `string \| null` | `null` | 右侧边栏最小宽度 |
+
+### 插槽
+
+- `header` - 标题栏内容
+- `sidebar` - 左侧边栏内容
+- `right-sidebar` - 右侧边栏内容
+- `bottom` - 状态栏内容
+- `default` - 主内容区域
+
+### 示例
+
+```svelte
+<ClassicLayout 
+  sidebarResize={true}
+  rightBarResize={true}
+  statusHeight="24px"
+>
+  <div slot="header">
+    <!-- 应用程序标题栏 -->
+  </div>
+  
+  <div slot="sidebar">
+    <!-- 左侧导航 -->
+  </div>
+  
+  <div slot="right-sidebar">
+    <!-- 属性面板 -->
+  </div>
+  
+  <div slot="bottom">
+    <!-- 状态栏 -->
+  </div>
+  
+  <!-- 主工作区 -->
+  <div>编辑器或主内容</div>
+</ClassicLayout>
+```
+
+## ColumnsLayout
+
+灵活的基于列的布局，带有可调整的左右面板。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | 布局总宽度 |
+| `height` | `string` | `"100%"` | 布局总高度 |
+| `leftWidth` | `string \| null` | `null` | 左列宽度 |
+| `rightWidth` | `string \| null` | `null` | 右列宽度 |
+| `leftMin` | `string \| null` | `null` | 左列最小宽度 |
+| `leftMax` | `string \| null` | `null` | 左列最大宽度 |
+| `rightMin` | `string \| null` | `null` | 右列最小宽度 |
+| `rightMax` | `string \| null` | `null` | 右列最大宽度 |
+| `leftResize` | `boolean` | `false` | 启用左列调整大小 |
+| `rightResize` | `boolean` | `false` | 启用右列调整大小 |
+
+### 插槽
+
+- `left` - 左列内容
+- `right` - 右列内容
+- `default` - 中央列内容
+
+### 示例
+
+```svelte
+<ColumnsLayout 
+  leftResize={true}
+  rightResize={true}
+  leftWidth="200px"
+  rightWidth="300px"
+  leftMin="150px"
+  rightMin="250px"
+>
+  <div slot="left">
+    <!-- 左面板 -->
+  </div>
+  
+  <div slot="right">
+    <!-- 右面板 -->
+  </div>
+  
+  <!-- 中央内容 -->
+  <div>主内容区域</div>
+</ColumnsLayout>
+```
+
+## RowsLayout
+
+灵活的基于行的布局，带有可调整的上下面板。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | 布局总宽度 |
+| `height` | `string` | `"100%"` | 布局总高度 |
+| `topHeight` | `string \| null` | `null` | 顶部行高度 |
+| `bottomHeight` | `string \| null` | `null` | 底部行高度 |
+| `topMin` | `string \| null` | `null` | 顶部行最小高度 |
+| `topMax` | `string \| null` | `null` | 顶部行最大高度 |
+| `bottomMin` | `string \| null` | `null` | 底部行最小高度 |
+| `bottomMax` | `string \| null` | `null` | 底部行最大高度 |
+| `topResize` | `boolean` | `false` | 启用顶部行调整大小 |
+| `bottomResize` | `boolean` | `false` | 启用底部行调整大小 |
+
+### 插槽
+
+- `top` - 顶部行内容
+- `bottom` - 底部行内容
+- `default` - 中央行内容
+
+### 示例
+
+```svelte
+<RowsLayout 
+  topResize={true}
+  bottomResize={true}
+  topHeight="150px"
+  bottomHeight="100px"
+  topMin="100px"
+  bottomMin="80px"
+>
+  <div slot="top">
+    <!-- 顶部面板 -->
+  </div>
+  
+  <div slot="bottom">
+    <!-- 底部面板 -->
+  </div>
+  
+  <!-- 中央内容 -->
+  <div>主内容区域</div>
+</RowsLayout>
+```
+
+## 功能特性
+
+### 可调整面板
+所有布局组件在启用时都支持可调整面板：
+- 拖动分割手柄来调整面板大小
+- 遵守最小和最大宽度/高度约束
+- 平滑调整大小，带有视觉反馈
+
+### 响应式设计
+- 布局适应容器尺寸
+- 支持百分比和固定单位的灵活尺寸
+- 内容区域的溢出处理
+
+### 基于插槽的内容
+- 为不同布局区域使用命名插槽
+- 没有内容时可选插槽会被隐藏
+- 主内容区域的默认插槽
+
+## 常见模式
+
+### 应用程序外壳
+
+```svelte
+<ClassicLayout sidebarResize={true}>
+  <div slot="header" class="app-header">
+    <h1>我的应用程序</h1>
+    <!-- 导航、用户菜单等 -->
+  </div>
+  
+  <div slot="sidebar" class="navigation">
+    <!-- 菜单项 -->
+  </div>
+  
+  <div slot="bottom" class="status-bar">
+    <!-- 状态信息 -->
+  </div>
+  
+  <main class="main-content">
+    <!-- 页面内容 -->
+  </main>
+</ClassicLayout>
+```
+
+### 仪表板布局
+
+```svelte
+<ColumnsLayout leftResize={true} rightResize={true}>
+  <div slot="left" class="sidebar">
+    <!-- 筛选器、导航 -->
+  </div>
+  
+  <div slot="right" class="details-panel">
+    <!-- 项目详情、操作 -->
+  </div>
+  
+  <div class="dashboard-grid">
+    <!-- 主仪表板内容 -->
+  </div>
+</ColumnsLayout>
+```
+
+### 分割视图编辑器
+
+```svelte
+<RowsLayout topResize={true} bottomResize={true}>
+  <div slot="top" class="editor-area">
+    <!-- 代码编辑器 -->
+  </div>
+  
+  <div slot="bottom" class="output-panel">
+    <!-- 控制台、预览等 -->
+  </div>
+  
+  <div class="file-explorer">
+    <!-- 文件树、标签页 -->
+  </div>
+</RowsLayout>
+```
+
+## 样式定制
+
+所有布局组件都使用flexbox进行定位，包括：
+
+- 适当的溢出处理
+- 使用CSS自定义属性的边框样式
+- 面板间的间距
+- Box-sizing: border-box以获得可预测的尺寸
+
+### CSS自定义属性
+
+```css
+:root {
+  --uniface-plain-border-color: #f0f0f0;
+}
+```
+
+## 无障碍访问
+
+- 具有容器元素的适当语义结构
+- 通过可调整分割支持键盘导航
+- 面板调整大小期间的焦点管理
+- 屏幕阅读器友好的布局结构
+
+## 浏览器支持
+
+- 支持flexbox的现代浏览器
+- CSS自定义属性支持
+- 调整大小功能的拖放支持
+
+## 最佳实践
+
+1. **选择正确的布局**: 选择最适合您应用程序结构的布局组件
+2. **设置适当的约束**: 使用min/max宽度/高度防止面板变得太小或太大
+3. **考虑移动端**: 布局可能需要针对移动设备进行响应式调整
+4. **内容溢出**: 确保内容区域有适当的溢出处理
+5. **性能**: 最小化可调整面板中的内容以获得平滑的调整体验
+
+## 注意事项
+
+- 可调整面板功能需要支持拖放的浏览器
+- 在设置面板尺寸时考虑内容的最小可用空间
+- 某些布局组件可能需要明确的容器高度才能正常工作
+- 在移动设备上考虑禁用面板调整功能以提供更好的触摸体验