From cf6ba3b42e11219c372438de263a5fbd29bc53a4 Mon Sep 17 00:00:00 2001
From: xdm <35987327+xiaodemen@users.noreply.github.com>
Date: Fri, 14 Jan 2022 12:08:26 +0800
Subject: [PATCH] docs: add docs for layout (#18)

Co-authored-by: GU Yiling <justice360@gmail.com>
---
 one/docs/components/content.md          | 15 +++++
 one/docs/components/footer.md           | 22 +++++++
 one/docs/components/header.md           | 22 +++++++
 one/docs/components/layout.md           | 27 +++++----
 one/docs/components/sidebar.md          | 44 ++++++++++++++
 one/docs/demo/layout/basic.vue          | 56 ++++++++++++++++++
 one/docs/demo/layout/global-footer.vue  | 60 +++++++++++++++++++
 one/docs/demo/layout/global-sidebar.vue | 60 +++++++++++++++++++
 one/docs/demo/layout/sticky.vue         | 69 ++++++++++++++++++++++
 one/docs/demo/sidebar/collapse-mode.vue | 76 +++++++++++++++++++++++++
 one/docs/demo/sidebar/collapsible.vue   | 56 ++++++++++++++++++
 one/docs/nav.json                       | 20 +++++++
 12 files changed, 516 insertions(+), 11 deletions(-)
 create mode 100644 one/docs/components/content.md
 create mode 100644 one/docs/components/footer.md
 create mode 100644 one/docs/components/header.md
 create mode 100644 one/docs/components/sidebar.md
 create mode 100644 one/docs/demo/layout/basic.vue
 create mode 100644 one/docs/demo/layout/global-footer.vue
 create mode 100644 one/docs/demo/layout/global-sidebar.vue
 create mode 100644 one/docs/demo/layout/sticky.vue
 create mode 100644 one/docs/demo/sidebar/collapse-mode.vue
 create mode 100644 one/docs/demo/sidebar/collapsible.vue

diff --git a/one/docs/components/content.md b/one/docs/components/content.md
new file mode 100644
index 0000000..9d802f0
--- /dev/null
+++ b/one/docs/components/content.md
@@ -0,0 +1,15 @@
+# Content <small>布局内容</small>
+
+:::tip
+`Content` 组件需要配合 [`Layout`](./layout) / [`Header`](./header) / [`Footer`](./footer) / [`Sidebar`](./sidebar) 组件使用。
+:::
+
+## 示例
+
+见 [`Layout` 示例](./layout#示例)。
+
+### 插槽
+
+| 名称 | 描述 |
+| -- | -- |
+| ``default`` | 布局内容。 |
diff --git a/one/docs/components/footer.md b/one/docs/components/footer.md
new file mode 100644
index 0000000..4b350df
--- /dev/null
+++ b/one/docs/components/footer.md
@@ -0,0 +1,22 @@
+# Footer <small>布局底部</small>
+
+:::tip
+`Footer` 组件需要配合 [`Layout`](./layout) / [`Header`](./header) / [`Sidebar`](./sidebar) / [`Content`](./content) 组件使用。
+:::
+
+## 示例
+
+见 [`Layout` 示例](./layout#示例)。
+
+## API
+
+### 属性
+| 名称 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| ``sticky`` | `boolean` | `false` | 是否吸顶。使用注意参考[`吸顶/吸底布局`](./layout#吸顶吸底布局)。 |
+
+### 插槽
+
+| 名称 | 描述 |
+| -- | -- |
+| ``default`` | 布局底部的内容。 |
diff --git a/one/docs/components/header.md b/one/docs/components/header.md
new file mode 100644
index 0000000..5740cdd
--- /dev/null
+++ b/one/docs/components/header.md
@@ -0,0 +1,22 @@
+# Header <small>布局头部</small>
+
+:::tip
+`Header` 组件需要配合 [`Layout`](./layout) / [`Sidebar`](./sidebar) / [`Footer`](./footer) / [`Content`](./content) 组件使用。
+:::
+
+## 示例
+
+见 [`Layout` 示例](./layout#示例)。
+
+## API
+
+### 属性
+| 名称 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| ``sticky`` | `boolean` | `false` | 是否吸顶。使用注意参考[`吸顶/吸底布局`](./layout#吸顶吸底布局)。 |
+
+### 插槽
+
+| 名称 | 描述 |
+| -- | -- |
+| ``default`` | 布局头部的内容。 |
diff --git a/one/docs/components/layout.md b/one/docs/components/layout.md
index d04f62c..1d5629d 100644
--- a/one/docs/components/layout.md
+++ b/one/docs/components/layout.md
@@ -10,31 +10,36 @@
 
 `Layout` 组件支持多种典型布局。
 
-// TBD
+[[ demo src="/demo/layout/basic.vue" ]]
 
-<!-- [[ demo src="/demo/layout/basic.vue" ]] -->
+### 通顶侧边栏
 
-### 收起侧边栏
+[[ demo src="/demo/layout/global-sidebar.vue" ]]
 
-`Sidebar` 组件通过 [`collapse-mode`](./Sidebar#props-collapse-mode) 属性支持两种收起模式，分别是 `slim`（部分收起）/`hidden`（完全收起）。
+### 通栏底部
 
-// TBD
-
-<!-- [[ demo src="/demo/layout/sidebar.vue" ]] -->
+[[ demo src="/demo/layout/global-footer.vue" ]]
 
 ### 吸顶/吸底布局
 
 `Header` / `Sidebar` / `Footer` 组件均支持通过 `sticky` 属性设置吸顶/吸底。
 
-// TBD
+:::tip
+当吸顶的布局头部和吸顶侧边栏一起使用需要在布局头部的父组件 `Layout` 上设置 `--dls-layout-header-height` 来指定布局头部的高度。
+:::
 
-<!-- [[ demo src="/demo/layout/sticky.vue" ]] -->
+:::tip
+当吸底的布局底部和吸顶侧边栏一起使用需要在布局底部的父组件 `Layout` 上设置 `--dls-layout-footer-height` 来指定布局底部的高度。
+:::
+
+[[ demo src="/demo/layout/sticky.vue" ]]
 
 ## API
 
 ### 属性
-
-// TBD
+| 名称 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| ``direction`` | `'column' | 'row'` | `'column'` | 布局排列方向。在有 `Sidebar` 时，默认为 `'row'`。 |
 
 ### 插槽
 
diff --git a/one/docs/components/sidebar.md b/one/docs/components/sidebar.md
new file mode 100644
index 0000000..1b172fa
--- /dev/null
+++ b/one/docs/components/sidebar.md
@@ -0,0 +1,44 @@
+# Sidebar <small>布局侧边栏</small>
+
+:::tip
+`Sidebar` 组件需要配合 [`Layout`](./layout) / [`Header`](./header) / [`Footer`](./footer) / [`Content`](./content) 组件使用。
+:::
+
+## 示例
+
+### 收起侧边栏
+
+通过 [`collapse-mode`](#props-collapse-mode) 属性指定收起模式，分别是 `slim`（部分收起） / `hidden`（完全收起）。
+
+[[ demo src="/demo/sidebar/collapse-mode.vue" ]]
+
+### 展示/隐藏切换按钮
+
+使用 `collapsible` 属性设置是否显示侧边栏展开/收起按钮。
+
+[[ demo src="/demo/sidebar/collapsible.vue" ]]
+
+## API
+
+### 属性
+| 名称 | 类型 | 默认值 | 描述 |
+| -- | -- | -- | -- |
+| ``sticky`` | `boolean` | `false` | 是否吸顶。使用注意参考[`吸顶/吸底布局`](./layout#吸顶吸底布局)。 |
+| ``collapsible`` | `boolean` | `false` | 是否显示收起/展开按钮。 |
+| ``collapsed`` | `boolean` | `false` | [^collapsed] |
+| ``autocollapse`` | `boolean` | `false` | 是否拉伸窗口到一定阈值时自动收起。 |
+| ``collapse-mode`` | `'slim' | 'hidden'` | `'slim'` | 收起模式，分别是 `slim`（部分收起）/`hidden`（完全收起）。 
+
+^^^collapsed
+:::badges
+`.sync`
+:::
+
+收起/展开的状态。
+^^^
+
+### 插槽
+
+| 名称 | 描述 |
+| -- | -- |
+| ``default`` | 布局侧边栏的内容。 |
diff --git a/one/docs/demo/layout/basic.vue b/one/docs/demo/layout/basic.vue
new file mode 100644
index 0000000..e457ec0
--- /dev/null
+++ b/one/docs/demo/layout/basic.vue
@@ -0,0 +1,56 @@
+<template>
+<article>
+  <div class="mock-window">
+    <veui-layout>
+      <veui-header>Header</veui-header>
+      <veui-layout>
+        <veui-sidebar>
+          <div class="center full">Sidebar</div>
+        </veui-sidebar>
+        <veui-layout>
+          <veui-content>Content</veui-content>
+          <veui-footer style="background: #ccc;">Footer（背景仅为演示）</veui-footer>
+        </veui-layout>
+      </veui-layout>
+    </veui-layout>
+  </div>
+</article>
+</template>
+
+<script>
+import { Layout, Header, Footer, Sidebar, Content } from 'veui'
+
+export default {
+  components: {
+    'veui-layout': Layout,
+    'veui-header': Header,
+    'veui-footer': Footer,
+    'veui-sidebar': Sidebar,
+    'veui-content': Content
+  }
+}
+</script>
+
+<style lang="less" scoped>
+.mock-window {
+  height: 384px;
+  transform: translate(0, 0); // bfc for fixed
+
+  & > .veui-layout {
+    min-width: 860px;
+  }
+}
+
+.center,
+.veui-layout-header,
+.veui-layout-footer,
+.veui-layout-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.full {
+  height: 100%;
+}
+</style>
diff --git a/one/docs/demo/layout/global-footer.vue b/one/docs/demo/layout/global-footer.vue
new file mode 100644
index 0000000..3704aae
--- /dev/null
+++ b/one/docs/demo/layout/global-footer.vue
@@ -0,0 +1,60 @@
+<template>
+<article>
+  <div class="mock-window">
+    <veui-layout>
+      <veui-header>Header</veui-header>
+      <veui-layout>
+        <veui-sidebar>
+          <div class="center full">Sidebar</div>
+        </veui-sidebar>
+        <veui-layout>
+          <veui-content>Content</veui-content>
+        </veui-layout>
+      </veui-layout>
+      <veui-footer style="background: #ccc;">Footer（背景仅为演示）</veui-footer>
+    </veui-layout>
+  </div>
+</article>
+</template>
+
+<script>
+import { Layout, Header, Footer, Sidebar, Content } from 'veui'
+
+export default {
+  components: {
+    'veui-layout': Layout,
+    'veui-header': Header,
+    'veui-footer': Footer,
+    'veui-sidebar': Sidebar,
+    'veui-content': Content
+  },
+  data () {
+    return {
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped>
+.mock-window {
+  height: 384px;
+  transform: translate(0, 0); // bfc for fixed
+
+  & > .veui-layout {
+    min-width: 860px;
+  }
+}
+
+.center,
+.veui-layout-header,
+.veui-layout-footer,
+.veui-layout-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.full {
+  height: 100%;
+}
+</style>
diff --git a/one/docs/demo/layout/global-sidebar.vue b/one/docs/demo/layout/global-sidebar.vue
new file mode 100644
index 0000000..b418ad3
--- /dev/null
+++ b/one/docs/demo/layout/global-sidebar.vue
@@ -0,0 +1,60 @@
+<template>
+<article>
+  <div class="mock-window">
+    <veui-layout>
+      <veui-sidebar>
+        <div class="center full">Sidebar</div>
+      </veui-sidebar>
+      <veui-layout>
+        <veui-header>Header</veui-header>
+        <veui-layout>
+          <veui-content>Content</veui-content>
+          <veui-footer style="background: #ccc;">Footer（背景仅为演示）</veui-footer>
+        </veui-layout>
+      </veui-layout>
+    </veui-layout>
+  </div>
+</article>
+</template>
+
+<script>
+import { Layout, Header, Footer, Sidebar, Content } from 'veui'
+
+export default {
+  components: {
+    'veui-layout': Layout,
+    'veui-header': Header,
+    'veui-footer': Footer,
+    'veui-sidebar': Sidebar,
+    'veui-content': Content
+  },
+  data () {
+    return {
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped>
+.mock-window {
+  height: 384px;
+  transform: translate(0, 0); // bfc for fixed
+
+  & > .veui-layout {
+    min-width: 860px;
+  }
+}
+
+.center,
+.veui-layout-header,
+.veui-layout-footer,
+.veui-layout-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.full {
+  height: 100%;
+}
+</style>
diff --git a/one/docs/demo/layout/sticky.vue b/one/docs/demo/layout/sticky.vue
new file mode 100644
index 0000000..05bc0aa
--- /dev/null
+++ b/one/docs/demo/layout/sticky.vue
@@ -0,0 +1,69 @@
+<template>
+<article>
+  <div class="mock-window">
+    <veui-layout style="--dls-layout-header-height: 64px;">
+      <veui-header sticky>Header</veui-header>
+      <veui-layout>
+        <veui-sidebar sticky style="max-height: 320px;">
+          <div class="center full">Sidebar</div>
+        </veui-sidebar>
+        <veui-layout>
+          <veui-content>
+            <div class="center" style="height: 800px;">Sidebar</div>
+          </veui-content>
+          <veui-footer sticky style="background: #ccc;">Footer（背景仅为演示）</veui-footer>
+        </veui-layout>
+      </veui-layout>
+    </veui-layout>
+  </div>
+</article>
+</template>
+
+<script>
+import { Layout, Header, Footer, Sidebar, Content } from 'veui'
+
+export default {
+  components: {
+    'veui-layout': Layout,
+    'veui-header': Header,
+    'veui-footer': Footer,
+    'veui-sidebar': Sidebar,
+    'veui-content': Content
+  },
+  data () {
+    return {
+      mode: 'slim',
+      modes: [
+        { label: 'slim', value: 'slim' },
+        { label: 'hidden', value: 'hidden' }
+      ]
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped>
+.mock-window {
+  height: 384px;
+  transform: translate(0, 0); // bfc for fixed
+  overflow: auto;
+  border: 1px solid #eee;
+
+  & > .veui-layout {
+    min-width: 860px;
+  }
+}
+
+.center,
+.veui-layout-header,
+.veui-layout-footer,
+.veui-layout-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.full {
+  height: 100%;
+}
+</style>
diff --git a/one/docs/demo/sidebar/collapse-mode.vue b/one/docs/demo/sidebar/collapse-mode.vue
new file mode 100644
index 0000000..968afa6
--- /dev/null
+++ b/one/docs/demo/sidebar/collapse-mode.vue
@@ -0,0 +1,76 @@
+<template>
+<article>
+  <veui-radio-button-group
+    v-model="mode"
+    :items="modes"
+  />
+  <div class="mock-window">
+    <veui-layout>
+      <veui-header>Header</veui-header>
+      <veui-layout>
+        <veui-sidebar :collapse-mode="mode">
+          <div class="center full">Sidebar</div>
+        </veui-sidebar>
+        <veui-layout>
+          <veui-content>Content</veui-content>
+          <veui-footer style="background: #ccc;">Footer（背景仅为演示）</veui-footer>
+        </veui-layout>
+      </veui-layout>
+    </veui-layout>
+  </div>
+</article>
+</template>
+
+<script>
+import { Layout, Header, Footer, Sidebar, Content, RadioButtonGroup } from 'veui'
+
+export default {
+  components: {
+    'veui-layout': Layout,
+    'veui-header': Header,
+    'veui-footer': Footer,
+    'veui-sidebar': Sidebar,
+    'veui-content': Content,
+    'veui-radio-button-group': RadioButtonGroup
+  },
+  data () {
+    return {
+      mode: 'slim',
+      modes: [
+        { label: 'slim', value: 'slim' },
+        { label: 'hidden', value: 'hidden' }
+      ]
+    }
+  }
+}
+</script>
+
+<style lang="less" scoped>
+.mock-window {
+  height: 384px;
+  transform: translate(0, 0); // bfc for fixed
+  overflow: auto;
+  border: 1px solid #eee;
+
+  & > .veui-layout {
+    min-width: 860px;
+  }
+}
+
+.center,
+.veui-layout-header,
+.veui-layout-footer,
+.veui-layout-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.veui-radio-button-group {
+  margin-bottom: 12px;
+}
+
+.full {
+  height: 100%;
+}
+</style>
diff --git a/one/docs/demo/sidebar/collapsible.vue b/one/docs/demo/sidebar/collapsible.vue
new file mode 100644
index 0000000..b2b73b5
--- /dev/null
+++ b/one/docs/demo/sidebar/collapsible.vue
@@ -0,0 +1,56 @@
+<template>
+<article>
+  <div class="mock-window">
+    <veui-layout>
+      <veui-header>Header</veui-header>
+      <veui-layout>
+        <veui-sidebar :collapsible="false">
+          <div class="center full">Sidebar</div>
+        </veui-sidebar>
+        <veui-layout>
+          <veui-content>Content</veui-content>
+          <veui-footer style="background: #ccc;">Footer（背景仅为演示</veui-footer>
+        </veui-layout>
+      </veui-layout>
+    </veui-layout>
+  </div>
+</article>
+</template>
+
+<script>
+import { Layout, Header, Footer, Sidebar, Content } from 'veui'
+
+export default {
+  components: {
+    'veui-layout': Layout,
+    'veui-header': Header,
+    'veui-footer': Footer,
+    'veui-sidebar': Sidebar,
+    'veui-content': Content
+  }
+}
+</script>
+
+<style lang="less" scoped>
+.mock-window {
+  height: 384px;
+  transform: translate(0, 0); // bfc for fixed
+
+  & > .veui-layout {
+    min-width: 860px;
+  }
+}
+
+.center,
+.veui-layout-header,
+.veui-layout-footer,
+.veui-layout-content {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.full {
+  height: 100%;
+}
+</style>
diff --git a/one/docs/nav.json b/one/docs/nav.json
index 0741bf2..7c5c75f 100644
--- a/one/docs/nav.json
+++ b/one/docs/nav.json
@@ -241,6 +241,26 @@
           "title": "Label - 标签",
           "slug": "label"
         },
+        {
+          "title": "Layout - 布局",
+          "slug": "layout"
+        },
+        {
+          "title": "Header - 布局头部",
+          "slug": "header"
+        },
+        {
+          "title": "Sidebar - 布局侧边栏",
+          "slug": "sidebar"
+        },
+        {
+          "title": "Content - 布局内容",
+          "slug": "content"
+        },
+        {
+          "title": "Footer - 布局底部",
+          "slug": "footer"
+        },
         {
           "title": "Span - 行内文本",
           "slug": "span"