feat(Descriptions): support Descriptions component (#2706)

* feat(support descriptions component): support Descriptions component * test(descriptions): update snap * docs(descriptions): update descriptions example n * test(descriptions): update test snap n * fix(descriptions): descriptions-item replace item * docs: rename Descriptions direction to layout * test: update snap test * docs(descriptions): update usage * docs(descriptions): update usage --------- Co-authored-by: Heising <[email protected]>
Tencent · Jan 11, 2024 · d164c94 · d164c94
1 parent d4a642e
commit d164c94
Show file tree

Hide file tree

Showing 32 changed files with 4,010 additions and 72 deletions.
diff --git a/script/generate-usage/config.js b/script/generate-usage/config.js
@@ -1062,24 +1062,6 @@ module.exports = {
       }, [changedProps]);
     `,
   },
-  Jumper: {
-    importStr: `
-      import configProps from './props.json';\n
-      import { Jumper } from 'tdesign-react';\n`,
-    configStr: `
-      const [configList, setConfigList] = useState(configProps);
-    `,
-    panelStr: `
-      const panelList = [{ label: 'jumper', value: 'jumper' }];
-    `,
-    usageStr: `
-      useEffect(() => {
-        setRenderComp((
-          <Jumper {...changedProps}></Jumper>
-        ));
-      }, [changedProps]);
-    `,
-  },
   Collapse: {
     importStr: `
     import configProps from './props.json';\n
@@ -1113,4 +1095,30 @@ module.exports = {
     }, [changedProps]);
   `,
   },
+  Descriptions: {
+    importStr: `
+    import configProps from './props.json';\n
+    import { Descriptions } from 'tdesign-react';\n`,
+    configStr: `
+    const [configList, setConfigList] = useState(configProps);
+  `,
+    panelStr: `
+    const panelList = [{ label: 'descriptions', value: 'descriptions' }];
+  `,
+    usageStr: `
+    const { DescriptionsItem } = Descriptions;
+    useEffect(() => {
+      setRenderComp((
+        <Descriptions title="Shipping address" {...changedProps}>
+        <DescriptionsItem label="Name">TDesign</DescriptionsItem>
+        <DescriptionsItem label="Telephone Number">139****0609</DescriptionsItem>
+        <DescriptionsItem label="Area">China Tencent Headquarters</DescriptionsItem>
+        <DescriptionsItem label="Address" content="test">
+          Shenzhen Penguin Island D1 4A Mail Center
+        </DescriptionsItem>
+      </Descriptions>
+      ));
+    }, [changedProps]);
+  `,
+  },
 };
diff --git a/site/site.config.mjs b/site/site.config.mjs
@@ -457,6 +457,14 @@ export const docs = [
         component: () => import('tdesign-react/comment/comment.md'),
         componentEn: () => import('tdesign-react/comment/comment.en-US.md'),
       },
+      {
+        title: 'Descriptions 描述',
+        titleEn: 'Descriptions',
+        name: 'descriptions',
+        path: '/react/components/descriptions',
+        component: () => import('tdesign-react/descriptions/descriptions.md'),
+        componentEn: () => import('tdesign-react/descriptions/descriptions.en-US.md'),
+      },
       {
         title: 'Image 图片',
         titleEn: 'Image',

diff --git a/site/test-coverage.js b/site/test-coverage.js
@@ -119,6 +119,12 @@ module.exports = {
     "functions": "60%",
     "lines": "66.07%"
   },
+  "descriptions": {
+    "statements": "98.82%",
+    "branches": "100%",
+    "functions": "95.45%",
+    "lines": "100%"
+  },
   "dialog": {
     "statements": "85%",
     "branches": "71.42%",
@@ -403,7 +409,7 @@ module.exports = {
   },
   "treeSelect": {
     "statements": "95.45%",
-    "branches": "85.95%",
+    "branches": "86.17%",
     "functions": "97.61%",
     "lines": "97.2%"
   },

diff --git a/src/collapse/_usage/index.jsx b/src/collapse/_usage/index.jsx
@@ -10,9 +10,9 @@ import BaseUsage, {
 } from "@site/src/components/BaseUsage";
 import jsxToString from "react-element-to-jsx-string";
 
-import { Collapse } from "tdesign-react";
 import configProps from "./props.json";
 
+import { Collapse } from "tdesign-react";
 
 export default function Usage() {
   const [configList, setConfigList] = useState(configProps);

diff --git a/src/common.ts b/src/common.ts
@@ -64,6 +64,11 @@ export type HorizontalAlignEnum = 'left' | 'center' | 'right';
 
 export type VerticalAlignEnum = 'top' | 'middle' | 'bottom';
 
+export enum LayoutEnum {
+  VERTICAL = 'vertical',
+  HORIZONTAL = 'horizontal',
+}
+
 export type ClassName = { [className: string]: any } | ClassName[] | string;
 
 export type CSSSelector = string;

diff --git a/src/descriptions/Descriptions.tsx b/src/descriptions/Descriptions.tsx
@@ -0,0 +1,146 @@
+import React from 'react';
+import classNames from 'classnames';
+import isArray from 'lodash/isArray';
+import assign from 'lodash/assign';
+import { TdDescriptionItemProps, TdDescriptionsProps } from './type';
+import { descriptionItemDefaultProps, descriptionsDefaultProps } from './defaultProps';
+import useDefaultProps from '../hooks/useDefaultProps';
+import useConfig from '../hooks/useConfig';
+import useCommonClassName from '../hooks/useCommonClassName';
+import { LayoutEnum } from '../common';
+import { DescriptionsContext } from './DescriptionsContext';
+import DescriptionsItem from './DescriptionsItem';
+import Row from './Row';
+
+/**
+ * 实现思路
+ * 1. 基于 table tbody tr td 来实现布局
+ * 2. 通过 span 计算总共有几行以及每一行的 item 个数，特别注意最后一行，要填充满
+ * 3. 整体布局：左右布局（column 和 span 生效）/上下布局（column 和 span 失效，一行一个 item）
+ * 4. item 布局：左右布局/上下布局
+ */
+
+/**
+ * TDescriptions：承载 header（title） 和 body（table, tbody）
+ * TDescriptionsRow：承载每一行（tr）
+ * TDescriptionsItem：获取 item 数据（span, label, content）
+ */
+
+export type DescriptionsProps = TdDescriptionsProps & {
+  children?: React.ReactNode;
+};
+
+const Descriptions = (DescriptionsProps: DescriptionsProps) => {
+  const props = useDefaultProps<DescriptionsProps>(DescriptionsProps, descriptionsDefaultProps);
+
+  const { title, bordered, column, layout, items: rowItems, children } = props;
+
+  const { classPrefix } = useConfig();
+
+  const COMPONENT_NAME = `${classPrefix}-descriptions`;
+
+  const { SIZE } = useCommonClassName();
+
+  // 计算渲染的行内容
+  const getRows = () => {
+    // 1. 两种方式：a. props 传 items b. slots t-descriptions-item; a 优先级更高
+
+    let items: TdDescriptionItemProps[] = [];
+
+    if (isArray(rowItems)) {
+      /**
+       * 2.1 a 方式获取 items
+       * ! 这里要支持 label: string / <div></div> / () =>  <div></div>
+       * ! 暂时没有这样一个全局的方法，所以先在组件内部写一个临时方法，无论之后是有了更好的处理方式要删除掉，还是其它组件也需要时再放到公共方法里面，都是可行的
+       */
+      items = rowItems.map((item) => {
+        const { span } = assign({}, descriptionItemDefaultProps, item);
+        return {
+          label: item.label,
+          content: item.content,
+          span,
+        };
+      });
+    } else {
+      // 2.2 b 方式 获取 TDescriptionsItem
+      const childrenList = React.Children.toArray(children).filter(
+        (child: JSX.Element) => child.type.displayName === DescriptionsItem.displayName,
+      );
+
+      if (childrenList.length !== 0) {
+        items = (childrenList as React.ReactElement[]).map(({ props: child }) => {
+          const { span } = assign({}, descriptionItemDefaultProps, child);
+
+          return {
+            label: child.label,
+            content: child.content ?? child.children,
+            span,
+          };
+        });
+      }
+    }
+
+    // 2. 判断布局，如果整体布局为 LayoutEnum.VERTICAL，那么直接返回即可。
+    if (layout === LayoutEnum.VERTICAL) {
+      return [items];
+    }
+    // 3. 布局为 LayoutEnum.HORIZONTAL 时，需要计算每一行的 item 个数
+    let temp: TdDescriptionItemProps[] = [];
+    let reset = column;
+    // 4. 记录结果
+    const res: TdDescriptionItemProps[][] = [];
+    items.forEach((item, index) => {
+      const { span } = item;
+      if (reset >= span) {
+        // 当前行还剩余空间
+        temp.push(item);
+        reset -= span;
+      } else {
+        // 当前行放不下了，放下一行
+        res.push(temp);
+        temp = [item];
+        reset = column - span;
+      }
+
+      if (index === items.length - 1) {
+        // 最后一个
+        Reflect.set(item, 'span', span + reset);
+        res.push(temp);
+      }
+    });
+
+    return res;
+  };
+
+  // Header
+  const renderHeader = () => (title ? <div className={`${COMPONENT_NAME}__header`}>{title}</div> : '');
+
+  // Body
+  const renderBody = () => {
+    const tableClass = [`${COMPONENT_NAME}__body`, SIZE[props.size], { [`${COMPONENT_NAME}__body--border`]: bordered }];
+    return (
+      <table className={classNames(tableClass)}>
+        <tbody>
+          {getRows().map((row, i) => (
+            <Row row={row} key={i} />
+          ))}
+        </tbody>
+      </table>
+    );
+  };
+
+  return (
+    <DescriptionsContext.Provider value={props}>
+      <div className={COMPONENT_NAME}>
+        {renderHeader()}
+        {renderBody()}
+      </div>
+    </DescriptionsContext.Provider>
+  );
+};
+
+Descriptions.displayName = 'Descriptions';
+
+Descriptions.DescriptionsItem = DescriptionsItem;
+
+export default Descriptions;
diff --git a/src/descriptions/DescriptionsContext.tsx b/src/descriptions/DescriptionsContext.tsx
@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+import { TdDescriptionsProps } from './type';
+
+export type DescriptionsContextProps = TdDescriptionsProps;
+
+export const DescriptionsContext = createContext<DescriptionsContextProps>(null);
diff --git a/src/descriptions/DescriptionsItem.tsx b/src/descriptions/DescriptionsItem.tsx
@@ -0,0 +1,10 @@
+import React from 'react';
+import { TdDescriptionItemProps } from './type';
+
+export type DescriptionsItem = TdDescriptionItemProps & { children?: React.ReactNode };
+
+const DescriptionsItem: React.FC<DescriptionsItem> = () => null;
+
+DescriptionsItem.displayName = 'DescriptionsItem';
+
+export default DescriptionsItem;
diff --git a/src/descriptions/Row.tsx b/src/descriptions/Row.tsx
@@ -0,0 +1,108 @@
+import React, { useContext } from 'react';
+import { TdDescriptionItemProps } from './type';
+import { LayoutEnum } from '../common';
+import useConfig from '../hooks/useConfig';
+import { DescriptionsContext } from './DescriptionsContext';
+
+export type RowProps = { row: TdDescriptionItemProps[] };
+
+const Row: React.FC<RowProps> = (props) => {
+  const { row } = props;
+
+  const { classPrefix } = useConfig();
+  const descriptionsContext = useContext(DescriptionsContext);
+
+  const COMPONENT_NAME = `${classPrefix}-descriptions`;
+
+  // label
+  const label = (node: TdDescriptionItemProps, layout: LayoutEnum = LayoutEnum.HORIZONTAL, rowKey?: string) => {
+    const { span } = node;
+    const labelSpan = layout === LayoutEnum.HORIZONTAL ? 1 : span;
+    return (
+      <td
+        key={rowKey}
+        colSpan={labelSpan}
+        className={`${COMPONENT_NAME}__label`}
+        style={descriptionsContext.labelStyle}
+      >
+        {node.label}
+        {descriptionsContext.colon && ':'}
+      </td>
+    );
+  };
+
+  // content
+  const content = (node: TdDescriptionItemProps, layout: LayoutEnum = LayoutEnum.HORIZONTAL, rowKey?: string) => {
+    const { span } = node;
+    const contentSpan = span > 1 && layout === LayoutEnum.HORIZONTAL ? span * 2 - 1 : span;
+    return (
+      <td
+        key={rowKey}
+        colSpan={contentSpan}
+        className={`${COMPONENT_NAME}__content`}
+        style={descriptionsContext.contentStyle}
+      >
+        {node.content}
+      </td>
+    );
+  };
+
+  // 总共有四种布局
+  // Layout horizontal vertical
+  // itemLayout horizontal vertical
+
+  const hh = () => (
+    <tr>
+      {row.map((node, i) => (
+        <React.Fragment key={i}>
+          {label(node)}
+          {content(node)}
+        </React.Fragment>
+      ))}
+    </tr>
+  );
+
+  const hv = () => (
+    <>
+      <tr>{row.map((node, i) => label(node, LayoutEnum.VERTICAL, `top_${i}`))}</tr>
+      <tr>{row.map((node, i) => content(node, LayoutEnum.VERTICAL, `bottom_${i}`))}</tr>
+    </>
+  );
+
+  const vh = () => (
+    <>
+      {row.map((node, i) => (
+        <tr key={i}>
+          {label(node)}
+          {content(node)}
+        </tr>
+      ))}
+    </>
+  );
+
+  const vv = () => (
+    <>
+      {row.map((node, i) => (
+        <React.Fragment key={i}>
+          <tr>{label(node)}</tr>
+          <tr>{content(node)}</tr>
+        </React.Fragment>
+      ))}
+    </>
+  );
+
+  if (descriptionsContext.layout === LayoutEnum.HORIZONTAL) {
+    if (descriptionsContext.itemLayout === LayoutEnum.HORIZONTAL) {
+      return hh();
+    }
+    return hv();
+  }
+  if (descriptionsContext.itemLayout === LayoutEnum.HORIZONTAL) {
+    return vh();
+  }
+  return vv();
+};
+
+Row.displayName = 'DescriptionsRow';
+
+export default Row;