Merge pull request #74 from Tzz1194593491/feature/back-top

feat(back-top): add back top component

site/sidebar.config.ts

@@ -92,6 +92,12 @@ export default [
         path: '/components/breadcrumb',
         // component: () => import('tdesign-web-components/breadcrumb/README.md'),
       },
+      {
+        title: 'BackTop 回到顶部',
+        name: 'backTop',
+        path: '/components/backTop',
+        component: () => import('tdesign-web-components/back-top/README.md'),
+      },
     ],
   },
   {

src/back-top/README.md

@@ -0,0 +1,59 @@
+---
+title: BackTop 回到顶部
+description: 用于返回页面顶部
+isComponent: true
+usage: { title: '', description: '' }
+spline: base
+---
+
+### 基础的回到顶部
+
+默认距离页面右侧24px，距离页面底部80px，滚动动画时长200ms。
+{{ base }}
+
+### 不同耗时的回到顶部
+
+设置滚动动画时长2s。
+{{ baseDuration }}
+
+### 不同组件尺寸的回到顶部
+
+提供标准（默认）、小两种尺寸。
+{{ baseSize }}
+
+### 不同组件形状的回到顶部
+
+提供方形（默认）、圆形两种形状。
+{{ baseShape }}
+
+### 不同组件主题的回到顶部
+
+{{ baseTheme }}
+
+### 可自定义内容的回到顶部
+
+{{ baseCustom }}
+
+## API
+
+[通用类型定义](https://github.com/TDesignOteam/tdesign-web-components/blob/main/src/common.ts)
+
+| 名称               | 类型                | 默认值              | 说明                                                                                                                                                                                 | 必传 |
+|------------------|-------------------|------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----|
+| className        | String            | -                | 类名                                                                                                                                                                                 | N  |
+| style            | Object            | -                | 样式，TS 类型：`Record<string, string \| number>`                                                                                                                                        | N  |
+| children         | TNode             | -                | 回到顶部内容，同 `content`。TS 类型：`string \| TNode`。[通用类型定义](https://github.com/TDesignOteam/tdesign-web-components/blob/main/src/common.ts)	                                               | N  |
+| container        | String / Function | 'body'           | 监听滚动的容器。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body。TS 类型：AttachNode。 [通用类型定义](https://github.com/TDesignOteam/tdesign-web-components/blob/main/src/common.ts) | N  |
+| content          | TNode             | -                | 回到顶部内容。TS 类型：`string\| TNode`。  [通用类型定义](https://github.com/TDesignOteam/tdesign-web-components/blob/main/src/common.ts)                                                           | N  |
+| default          | TNode             | -                | 回到顶部内容，同 content。TS 类型：`string\| TNode`。      [通用类型定义](https://github.com/TDesignOteam/tdesign-web-components/blob/main/src/common.ts)                                             | N  |
+| duration         | Number            | 200              | 回到顶部的耗时单位：毫秒                                                                                                                                                                       | N  |
+| offset           | Array             | ["24px", "80px"] | 回到顶部相对右下角的位置偏移，示例：[10, 20] 或 ['10em', '8rem']。TS 类型：`Array<string \| number>`                                                                                                      | N  |
+| shape            | String            | square           | 回到顶部的形状。可选项：circle/square。TS 类型：`BackTopShapeEnum type BackTopShapeEnum = 'circle' \| 'square'`。                                                                                   | N  |
+| size             | String            | medium           | 组件尺寸。可选项：medium/small                                                                                                                                                              | N  |
+| target           | String / Function | 'body'           | 指定回到该对象。数据类型为 String 时，会被当作选择器处理，进行节点查询。示例：'body' 或 () => document.body。TS 类型：AttachNode。[通用类型定义](https://github.com/TDesignOteam/tdesign-web-components/blob/main/src/common.ts)  | N  |
+| theme            | String            | light            | 组件主题风格，浅色、主色、深色。可选项：light/primary/dark                                                                                                                                             | N  |
+| visibleHeight    | String / Number   | '200px'          | 滚动高度达到此参数值才出现                                                                                                                                                                      | N  |
+| onClick          | Function          | -                | TS 类型：`(context: { e: MouseEvent }) => void`<br/>点击回到顶部时触发                                                                                                                         | N  |
+| ignoreAttributes | String[]          | -                | 在host标签上忽略的属性                                                                                                                                                                      | N  |
+
+

src/back-top/_example/base.tsx

@@ -0,0 +1,37 @@
+import 'tdesign-web-components/back-top';
+
+import { Component, createRef } from 'omi';
+
+export default class BackTop extends Component {
+  render() {
+    const container = createRef();
+    return (
+      <div style={{ position: 'relative' }}>
+        <div
+          ref={container}
+          class="demo-base"
+          style={{
+            position: 'relative',
+            height: '280px',
+            overflowY: 'scroll',
+            border: '1px solid rgb(220, 220, 220)',
+          }}
+        >
+          <ul>
+            {Array.from(Array(50), () => '列表内容').map((item, index) => (
+              <li key={index}>{item}</li>
+            ))}
+          </ul>
+        </div>
+        <t-back-top
+          container={() => container.current}
+          style={{ position: 'absolute' }}
+          visibleHeight={46}
+          shape="square"
+          offset={['24px', '80px']}
+          ignoreAttributes={['style']}
+        />
+      </div>
+    );
+  }
+}

src/back-top/_example/baseCustom.tsx

@@ -0,0 +1,23 @@
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/back-top';
+
+import { Component } from 'omi';
+
+export default class BackTop extends Component {
+  render() {
+    const style = {
+      position: 'relative',
+      insetInlineEnd: 0,
+      insetBlockEnd: 0,
+    };
+    return (
+      <t-space size={24}>
+        <t-back-top style={style} visibleHeight={0} container={() => document}>
+          <span className="custom-node">返回</span>
+        </t-back-top>
+        <t-back-top style={style} content={<span>TOP</span>} visibleHeight={0} container={() => document} />
+        <t-back-top style={style} content={<span>UP</span>} visibleHeight={0} container={() => document} />
+      </t-space>
+    );
+  }
+}

src/back-top/_example/baseDuration.tsx

@@ -0,0 +1,38 @@
+import 'tdesign-web-components/back-top';
+
+import { Component, createRef } from 'omi';
+
+export default class BackTop extends Component {
+  render() {
+    const container = createRef();
+    return (
+      <div style={{ position: 'relative' }}>
+        <div
+          ref={container}
+          class="demo-base"
+          style={{
+            position: 'relative',
+            height: '280px',
+            overflowY: 'scroll',
+            border: '1px solid rgb(220, 220, 220)',
+          }}
+        >
+          <ul>
+            {Array.from(Array(50), () => '列表内容').map((item, index) => (
+              <li key={index}>{item}</li>
+            ))}
+          </ul>
+        </div>
+        <t-back-top
+          container={() => container.current}
+          style={{ position: 'absolute' }}
+          visibleHeight={46}
+          shape="square"
+          duration={2000}
+          offset={['24px', '80px']}
+          ignoreAttributes={['style']}
+        />
+      </div>
+    );
+  }
+}

src/back-top/_example/baseShape.tsx

@@ -0,0 +1,62 @@
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/back-top';
+
+import { Component } from 'omi';
+
+export default class BackTop extends Component {
+  render() {
+    const style = {
+      position: 'relative',
+      insetInlineEnd: 0,
+      insetBlockEnd: 0,
+    };
+    return (
+      <t-space direction="vertical" size={32}>
+        <t-space size={24}>
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            shape="circle"
+            offset={['24px', '300px']}
+            container={() => document}
+          />
+          <t-back-top style={style} visibleHeight={0} offset={['124px', '300px']} container={() => document} />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            shape="circle"
+            theme="primary"
+            offset={['24px', '300px']}
+            container={() => document}
+          />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            theme="primary"
+            offset={['124px', '300px']}
+            container={() => document}
+          />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            shape="circle"
+            theme="dark"
+            offset={['24px', '300px']}
+            container={() => document}
+          />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            theme="dark"
+            offset={['124px', '300px']}
+            container={() => document}
+          />
+        </t-space>
+      </t-space>
+    );
+  }
+}

src/back-top/_example/baseSize.tsx

@@ -0,0 +1,70 @@
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/back-top';
+
+import { Component } from 'omi';
+
+export default class BackTop extends Component {
+  render() {
+    const style = {
+      position: 'relative',
+      insetInlineEnd: 0,
+      insetBlockEnd: 0,
+    };
+    return (
+      <t-space direction="vertical" size={32}>
+        <t-space size={24}>
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size="small"
+            offset={['24px', '300px']}
+            container={() => document}
+          />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size="medium"
+            offset={['124px', '300px']}
+            container={() => document}
+          />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size="small"
+            theme="primary"
+            offset={['24px', '300px']}
+            container={() => document}
+          />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size="medium"
+            theme="primary"
+            offset={['124px', '300px']}
+            container={() => document}
+          />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size="small"
+            theme="dark"
+            offset={['24px', '300px']}
+            container={() => document}
+          />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size="medium"
+            theme="dark"
+            offset={['124px', '300px']}
+            container={() => document}
+          />
+        </t-space>
+      </t-space>
+    );
+  }
+}

src/back-top/_example/baseTheme.tsx

@@ -0,0 +1,52 @@
+import 'tdesign-web-components/space';
+import 'tdesign-web-components/back-top';
+
+import { Component } from 'omi';
+
+export default class BackTop extends Component {
+  render() {
+    const style = {
+      position: 'relative',
+      insetInlineEnd: 0,
+      insetBlockEnd: 0,
+    };
+    return (
+      <t-space direction="vertical" size={32}>
+        <t-space size={24}>
+          <t-back-top style={style} visibleHeight={0} container={() => document} />
+          <t-back-top style={style} visibleHeight={0} theme={'primary'} container={() => document} />
+          <t-back-top style={style} visibleHeight={0} theme={'dark'} container={() => document} />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top style={style} visibleHeight={0} shape="circle" container={() => document} />
+          <t-back-top style={style} visibleHeight={0} shape="circle" theme="primary" container={() => document} />
+          <t-back-top style={style} visibleHeight={0} shape="circle" theme="dark" container={() => document} />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top style={style} visibleHeight={0} size={'small'} container={() => document} />
+          <t-back-top style={style} visibleHeight={0} size={'small'} theme={'primary'} container={() => document} />
+          <t-back-top style={style} visibleHeight={0} size={'small'} theme={'dark'} container={() => document} />
+        </t-space>
+        <t-space size={24}>
+          <t-back-top style={style} visibleHeight={0} size={'small'} shape="circle" container={() => document} />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size={'small'}
+            shape="circle"
+            theme="primary"
+            container={() => document}
+          />
+          <t-back-top
+            style={style}
+            visibleHeight={0}
+            size={'small'}
+            shape="circle"
+            theme="dark"
+            container={() => document}
+          />
+        </t-space>
+      </t-space>
+    );
+  }
+}