docs: Add instructions for the ellipsis parameter of typography & add faq (#1789)

content/basic/typography/index-en-US.md

@@ -319,7 +319,8 @@ Show ellipsis if text is overflowed. Refer to [Ellipsis Config](#Ellipsis-Config
 <Notice title='Notice'>
     1. ellipsis only supports truncation of plain text, and does not support complex types such as reactNode. Please ensure that the content type of children is string <br/><br/>
     2. To achieve abbreviation, ellipsis needs to have a clear width or maxWidth limit for comparison and judgment. If the width is not set by itself (for example, purely relying on the flex property to expand), or the width is an indefinite value such as 100%, the parent needs to have a clear width or maxWidth<br/><br/>
-    3. Ellipsis needs to obtain information such as the width and height of the DOM to make basic judgments. If there is a display:none style in itself or the parent, the value will be incorrect, and the abbreviation will be invalid at this time<br/>
+    3. Ellipsis needs to obtain information such as the width and height of the DOM to make basic judgments. If there is a display:none style in itself or the parent, the value will be incorrect, and the abbreviation will be invalid at this time<br/><br/>
+    4. For more information on ellipsis see <a href="#faq">FAQ</a> 
 </Notice>
 
 ```jsx live=true
@@ -569,3 +570,13 @@ function Demo() {
 
 ## Design Tokens
 <DesignToken/>
+
+## FAQ
+
+- **What are the specific mechanism and precautions of Typography ellipsis?**
+
+    Semi ellipsis has two strategies, CSS ellipsis and JS ellipsis. When setting middle truncation (pos='middle')、 expandable、 suffix is not empty string、copyable, the JS ellipsis strategy is enabled. Otherwise, enable the CSS ellipsis strategy.
+
+    In general CSS truncation performance is better than JS truncation. when the children and container size remain unchanged, CSS truncation only involves 1~2 calculations, while js truncation is based on dichotomy and may require multiple calculations.
+
+    Pay attention to performance consumption when using a large number of Typography with ellipsis. For example, in Table, you can reduce performance loss by setting a reasonable pageSize for paging.

content/basic/typography/index.md

@@ -306,6 +306,7 @@ function Demo() {
     1. ellipsis 仅支持纯文本的截断，不支持 reactNode 等复杂类型，请确保 children 传入内容类型为 string <br/>
     2. ellipsis 要实现缩略，需要有明确的 width或 maxWidth 宽度限制做对比判断。若自身未设置宽度（例如纯依靠 flex 属性撑开），或 width为 100% 等不定数值，那么父级需要有明确的 width或 maxWidth <br/>
     3. ellipsis 需要获取 DOM 的宽高度等信息用以做基本判断，若自身或父级存在 display:none 样式会导致取值不正确，此时缩略会失效<br/>
+    4. 省略文本更多信息见 <a href="#faq">FAQ</a> 
 </Notice>
 
 
@@ -570,3 +571,13 @@ function Demo() {
 
 ## 设计变量
 <DesignToken/>
+
+## FAQ
+
+- **Typography 省略具体机制及注意事项?**
+
+    Semi 截断有两种策略， CSS 截断和 JS 截断。当设置中间截断（pos='middle')、可展开（expandable)、有后缀（suffix 非空）、可复制（copyable），启用 JS 截断策略；非以上场景，启用 CSS 截断策略。
+
+    通常来说，CSS 截断性能优于 JS 截断。在 children、 容器尺寸不变的情况下，CSS 截断只涉及 1~2 次计算，js 截断可能涉及多次计算。
+
+    同时使用大量带有截断功能的 Typography 需注意性能消耗，如在 Table 中，可通过设置合理的页容量进行分页减少性能损耗。

packages/semi-ui/typography/base.tsx

@@ -25,6 +25,27 @@ export interface BaseTypographyProps extends BaseProps {
     delete?: boolean;
     disabled?: boolean;
     icon?: React.ReactNode;
+    /**
+     * ellipsis 用于设置截断相关参数.  
+     * Ellipsis is used to set ellipsis related parameters.  
+     * ellipsis 仅支持纯文本的截断，不支持 reactNode 等复杂类型，请确保 children 传入内容类型为 string.  
+     * Ellipsis only supports ellipsis of plain text, and does not support complex types such as reactNode. 
+     * Please ensure that the content type of children is string.  
+     * Semi 截断有两种策略， CSS 截断和 JS 截断。  
+     * Semi ellipsis has two strategies, CSS ellipsis and JS ellipsis.   
+     *  - 当设置中间截断（pos='middle')、可展开（expandable)、有后缀（suffix 非空）、可复制（copyable），启用 JS 截断策略  
+     *  - When setting middle ellipsis (pos='middle')、expandable、suffix is not empty string、copyable,
+     * the JS ellipsis strategy is enabled
+     *  - 非以上场景，启用 CSS 截断策略  
+     *  - Otherwise, enable the CSS ellipsis strategy  
+     *   
+     * 通常来说 CSS 截断的性能优于 JS 截断。在 children 不变， 容器尺寸不变的情况下，CSS 截断只涉及 1-2 次计算，js 截断基于二分法，可能涉及多次计算。  
+     * In general CSS ellipsis performs better than JS ellipsis. when the children and container size remain unchanged, 
+     * CSS ellipsis only involves 1-2 calculations, while JS ellipsis is based on dichotomy and may require multiple calculations.  
+     * 同时使用大量带有截断功能的 Typography 需注意性能消耗，如在 Table 中，可通过设置合理的页容量进行分页减少性能损耗  
+     * Pay attention to performance consumption when using a large number of Typography with ellipsis. For example, in Table, 
+     * you can reduce performance loss by setting a reasonable pageSize for paging
+     */
     ellipsis?: Ellipsis | boolean;
     mark?: boolean;
     underline?: boolean;
@@ -406,8 +427,8 @@ export default class Base extends Component<BaseTypographyProps, BaseTypographyS
      * 获取文本的缩略class和style
      *
      * 截断类型：
-     *  - CSS 截断，仅在 rows=1 且没有 expandable、pos、suffix 时生效
-     *  - JS 截断，应对 CSS 无法阶段的场景
+     *  - 当设置中间截断（pos='middle')、可展开（expandable)、有后缀（suffix 非空）、可复制（copyable），启用 JS 截断策略 
+     *  - 非以上场景，启用 CSS 截断策略
      * 相关变量
      *  props:
      *      - ellipsis:
@@ -423,8 +444,8 @@ export default class Base extends Component<BaseTypographyProps, BaseTypographyS
      * Get the abbreviated class and style of the text
      *
      * Truncation type:
-     *  -CSS truncation, which only takes effect when rows = 1 and there is no expandable, pos, suffix
-     *  -JS truncation, dealing with scenarios where CSS cannot stage
+     *  -When setting middle ellipsis (pos='middle')、expandable、suffix is not empty、copyable, the JS ellipsis strategy is enabled
+     *  -Otherwise, enable the CSS ellipsis strategy  
      * related variables
      *  props:
      *      -ellipsis:

packages/semi-ui/typography/paragraph.tsx

@@ -21,6 +21,27 @@ export interface ParagraphProps extends Omit<React.HTMLAttributes<HTMLParagraphE
     copyable?: CopyableConfig | boolean;
     delete?: boolean;
     disabled?: boolean;
+    /**
+     * ellipsis 用于设置截断相关参数.  
+     * Ellipsis is used to set ellipsis related parameters.  
+     * ellipsis 仅支持纯文本的截断，不支持 reactNode 等复杂类型，请确保 children 传入内容类型为 string.  
+     * Ellipsis only supports ellipsis of plain text, and does not support complex types such as reactNode. 
+     * Please ensure that the content type of children is string.  
+     * Semi 截断有两种策略， CSS 截断和 JS 截断。  
+     * Semi ellipsis has two strategies, CSS ellipsis and JS ellipsis.   
+     *  - 当设置中间截断（pos='middle')、可展开（expandable)、有后缀（suffix 非空）、可复制（copyable），启用 JS 截断策略  
+     *  - When setting middle ellipsis (pos='middle')、expandable、suffix is not empty string、copyable,
+     * the JS ellipsis strategy is enabled
+     *  - 非以上场景，启用 CSS 截断策略  
+     *  - Otherwise, enable the CSS ellipsis strategy  
+     *   
+     * 通常来说 CSS 截断的性能优于 JS 截断。在 children 不变， 容器尺寸不变的情况下，CSS 截断只涉及 1-2 次计算，js 截断基于二分法，可能涉及多次计算。  
+     * In general CSS ellipsis performs better than JS ellipsis. when the children and container size remain unchanged, 
+     * CSS ellipsis only involves 1-2 calculations, while JS ellipsis is based on dichotomy and may require multiple calculations.  
+     * 同时使用大量带有截断功能的 Typography 需注意性能消耗，如在 Table 中，可通过设置合理的页容量进行分页减少性能损耗  
+     * Pay attention to performance consumption when using a large number of Typography with ellipsis. For example, in Table, 
+     * you can reduce performance loss by setting a reasonable pageSize for paging
+     */
     ellipsis?: Ellipsis | boolean;
     link?: LinkType;
     mark?: boolean;

packages/semi-ui/typography/text.tsx

@@ -15,6 +15,27 @@ export interface TextProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, O
     copyable?: CopyableConfig | boolean;
     delete?: boolean;
     disabled?: boolean;
+    /**
+     * ellipsis 用于设置截断相关参数.  
+     * Ellipsis is used to set ellipsis related parameters.  
+     * ellipsis 仅支持纯文本的截断，不支持 reactNode 等复杂类型，请确保 children 传入内容类型为 string.  
+     * Ellipsis only supports ellipsis of plain text, and does not support complex types such as reactNode. 
+     * Please ensure that the content type of children is string.  
+     * Semi 截断有两种策略， CSS 截断和 JS 截断。  
+     * Semi ellipsis has two strategies, CSS ellipsis and JS ellipsis.   
+     *  - 当设置中间截断（pos='middle')、可展开（expandable)、有后缀（suffix 非空）、可复制（copyable），启用 JS 截断策略  
+     *  - When setting middle ellipsis (pos='middle')、expandable、suffix is not empty string、copyable,
+     * the JS ellipsis strategy is enabled
+     *  - 非以上场景，启用 CSS 截断策略  
+     *  - Otherwise, enable the CSS ellipsis strategy  
+     *   
+     * 通常来说 CSS 截断的性能优于 JS 截断。在 children 不变， 容器尺寸不变的情况下，CSS 截断只涉及 1-2 次计算，js 截断基于二分法，可能涉及多次计算。  
+     * In general CSS ellipsis performs better than JS ellipsis. when the children and container size remain unchanged, 
+     * CSS ellipsis only involves 1-2 calculations, while JS ellipsis is based on dichotomy and may require multiple calculations.  
+     * 同时使用大量带有截断功能的 Typography 需注意性能消耗，如在 Table 中，可通过设置合理的页容量进行分页减少性能损耗  
+     * Pay attention to performance consumption when using a large number of Typography with ellipsis. For example, in Table, 
+     * you can reduce performance loss by setting a reasonable pageSize for paging
+     */
     ellipsis?: Ellipsis | boolean;
     icon?: React.ReactNode | string;
     link?: LinkType;

packages/semi-ui/typography/title.tsx

@@ -24,6 +24,27 @@ export interface TitleProps extends Omit<React.HTMLAttributes<HTMLHeadingElement
     copyable?: CopyableConfig | boolean;
     delete?: boolean;
     disabled?: boolean;
+    /**
+     * ellipsis 用于设置截断相关参数.  
+     * Ellipsis is used to set ellipsis related parameters.  
+     * ellipsis 仅支持纯文本的截断，不支持 reactNode 等复杂类型，请确保 children 传入内容类型为 string.  
+     * Ellipsis only supports ellipsis of plain text, and does not support complex types such as reactNode. 
+     * Please ensure that the content type of children is string.  
+     * Semi 截断有两种策略， CSS 截断和 JS 截断。  
+     * Semi ellipsis has two strategies, CSS ellipsis and JS ellipsis.   
+     *  - 当设置中间截断（pos='middle')、可展开（expandable)、有后缀（suffix 非空）、可复制（copyable），启用 JS 截断策略  
+     *  - When setting middle ellipsis (pos='middle')、expandable、suffix is not empty string、copyable,
+     * the JS ellipsis strategy is enabled
+     *  - 非以上场景，启用 CSS 截断策略  
+     *  - Otherwise, enable the CSS ellipsis strategy  
+     *   
+     * 通常来说 CSS 截断的性能优于 JS 截断。在 children 不变， 容器尺寸不变的情况下，CSS 截断只涉及 1-2 次计算，js 截断基于二分法，可能涉及多次计算。  
+     * In general CSS ellipsis performs better than JS ellipsis. when the children and container size remain unchanged, 
+     * CSS ellipsis only involves 1-2 calculations, while JS ellipsis is based on dichotomy and may require multiple calculations.  
+     * 同时使用大量带有截断功能的 Typography 需注意性能消耗，如在 Table 中，可通过设置合理的页容量进行分页减少性能损耗  
+     * Pay attention to performance consumption when using a large number of Typography with ellipsis. For example, in Table, 
+     * you can reduce performance loss by setting a reasonable pageSize for paging
+     */
     ellipsis?: Ellipsis | boolean;
     heading?: ArrayElement<typeof strings.HEADING>;
     link?: LinkType;