feat: add toc doc

alauda · Jun 19, 2020 · e68bd04 · e68bd04
1 parent 8fc3852
commit e68bd04
Show file tree

Hide file tree

Showing 5 changed files with 197 additions and 140 deletions.
diff --git a/stories/table-of-contents/demo.component.html b/stories/table-of-contents/demo.component.html
diff --git a/stories/table-of-contents/demo.component.scss b/stories/table-of-contents/demo.component.scss
diff --git a/stories/table-of-contents/demo.component.ts b/stories/table-of-contents/demo.component.ts
diff --git a/stories/table-of-contents/index.ts b/stories/table-of-contents/index.ts
diff --git a/stories/table-of-contents/toc.stories.mdx b/stories/table-of-contents/toc.stories.mdx
@@ -0,0 +1,197 @@
+import { Meta, Preview, Story } from '@storybook/addon-docs/blocks';
+import { moduleMetadata } from '@storybook/angular';
+
+import { TableOfContentsModule } from '@alauda/ui';
+
+<Meta
+  title="Toc"
+  decorators={[
+    moduleMetadata({
+      imports: [TableOfContentsModule],
+    }),
+  ]}
+/>
+
+# Toc
+
+## 使用方法
+
+<Preview>
+  <Story name="toc" height="400px">
+    {{
+      template: /* HTML */ `
+        <div class="demo-container">
+          <div class="links">
+            Links:
+            <ul>
+              <li>
+                <a auiTocLink="content1" [for]="toc1">
+                  content 1
+                </a>
+              </li>
+              <li>
+                <a auiTocLink="content2" [for]="toc1">
+                  content 2
+                </a>
+              </li>
+              <li>
+                <a auiTocLink="content3" [for]="toc1">
+                  content 3
+                </a>
+              </li>
+              <li *ngFor="let item of list">
+                <a [auiTocLink]="item" [for]="toc1">
+                  {{ item }}
+                </a>
+              </li>
+            </ul>
+          </div>
+          <div class="contents" auiTocContainer #toc1="auiTocContainer">
+            <div class="content" auiTocContent="content1">Content 1</div>
+            <div class="content" auiTocContent="content2">Content 2</div>
+            <div class="content" auiTocContent="content3">Content 3</div>
+            <div
+              *ngFor="let item of list"
+              class="content"
+              [auiTocContent]="item"
+              (click)="remove(item)"
+            >
+              {{ item }}
+            </div>
+            <button (click)="add(list, toc1)">{{ 'add' }}</button>
+          </div>
+        </div>
+      `,
+      styles: [
+        /* CSS */ `
+        .demo-container {
+            position: fixed;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            overflow: hidden;
+            display: flex;
+            align-items: stretch;
+            padding: 10px;
+          }
+          .demo-container .links {
+            width: 200px;
+            overflow: auto;
+          }
+          .demo-container .links ul {
+            margin: 0;
+            padding: 0;
+            list-style: none;
+            display: block;
+          }
+          .demo-container .links ul li {
+            width: unset;
+            height: unset;
+            cursor: pointer;
+          }
+          .demo-container .links ul li > a {
+            display: block;
+            padding: 20px;
+            color: gray;
+          }
+          .demo-container .links ul li > a.isActive {
+            color: deepskyblue;
+          }
+          .demo-container .contents {
+            display: block;
+            flex-grow: 1;
+            overflow: auto;
+            padding: 20px;
+          }
+          .demo-container .contents .content {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 400px;
+            margin-bottom: 18px;
+            background-color: gray;
+            color: white;
+            transition: background-color ease-in 0.3s;
+          }
+          .demo-container .contents .content:last-of-type {
+            min-height: 100%;
+          }
+          .demo-container .contents .content.isActive {
+            background-color: deepskyblue;
+          }
+      `,
+      ],
+      props: {
+        list: [],
+        add: (list, toc) => {
+          const item = `add content ${list.length + 4}`;
+          list.push(item);
+          setTimeout(() => {
+            toc.scrollTo(item);
+          });
+        },
+      },
+    }}
+  </Story>
+</Preview>
+
+## 使用场景:
+
+左侧 link 高亮显示当前 container 中显示的 content。
+点击触发 link 时，container 内平滑滚动至 link 绑定的 content。  
+提供 scrollTo 方法支持控制滚动到指定的 content。
+支持 content 内嵌自定义内容。
+
+## 使用限制:
+
+container 必须是可滚动的。
+如果滚动到底部，scrollHeight - scrollTop === clientHeight，则默认选中最后一个 content。
+
+## 基本使用方式:
+
+```html
+<!-- links -->
+<aside>
+  <a auiTocLink="content1" [for]="toc">content1</a>
+  <a auiTocLink="content2" [for]="toc">content2</a>
+  <a auiTocLink="content3" [for]="toc">content3</a>
+</aside>
+<!-- scroll container -->
+<article auiTocContainer #toc="auiTocContainer">
+  <section auiTocContent="content1">...</section>
+  <section auiTocContent="content2">...</section>
+  <section auiTocContent="content3">...</section>
+</article>
+```
+
+## 样式设置
+
+可以在 css 中为 link 和 content 设置 ‘.isActive’, 指定当 link 和 content 被选中时的样式。
+
+## Directives:
+
+### auiTocContainer Outputs
+
+| 名称          | 类型   | 默认值 | 描述                              |
+| ------------- | ------ | ------ | --------------------------------- |
+| activedChange | string | -      | 当 actived 变化时使用该方法获取。 |
+
+### auiTocContainer Functions
+
+| 方法以及参数                       | 描述                                        |
+| ---------------------------------- | ------------------------------------------- |
+| `scrollTo(content: string): void;` | 使用该方法使 container 滚动到指定 content。 |
+
+### auiTocContent Inputs
+
+| 名称          | 类型   | 默认值 | 描述                                                   |
+| ------------- | ------ | ------ | ------------------------------------------------------ |
+| auiTocContent | string | -      | 设置 content 名称, 在同一个 container 中名称必须唯一。 |
+
+### auiTocLink Inputs
+
+| 名称       | 类型                  | 默认值 | 描述                                     |
+| ---------- | --------------------- | ------ | ---------------------------------------- |
+| for        | TocContainerDirective | -      | 目标滚动 container 的 template reference |
+| auiTocLink | string                | -      | link 的目标 content 名称。               |