## 简介
@alicloud/console-components-truncate
用于截断超长文本。

## 基本用法
### 单行截断
比较常见的使用方式：

## 示例

```tsx
/**
* @title basic
*/

import React from 'react'
import Truncate from '@alicloud/console-components-truncate'

const sentence1 = 'To be or not to be, this is a question. —— Hamlet'
const sentence2 =
  '毕竟西湖六月中，风光不与四时同。接天莲叶无穷碧，映日荷花别样红。'

const Demo = () => {
  return (
    <div className="truncate-demo">
      <h1>原文</h1>
      <Truncate threshold={50}>{sentence1}</Truncate>
      <br />
      <br />
      <Truncate type="width" threshold={5000}>
        {sentence2}
      </Truncate>
      <br />
      <br />
      <h1>length 截断（20）</h1>
      <Truncate threshold={20}>{sentence1}</Truncate>
      <br />
      <br />
      <Truncate threshold={20}>{sentence2}</Truncate>
      <br />
      <br />
      <h1>width 截断（200px）</h1>
      <Truncate type="width" threshold={200} align="t">
        {sentence1}
      </Truncate>
      <br />
      <br />
      <Truncate type="width" threshold={200} omission="。。。">
        {sentence2}
      </Truncate>
      <br />
      <br />
      <h1>Disable Tooltip</h1>
      <Truncate showTooltip={false} omission="。。。">
        {sentence1}
      </Truncate>
      <br />
      <br />
      <Truncate
        showTooltip={false}
        type="width"
        threshold={200}
        omission="。。。"
      >
        {sentence2}
      </Truncate>
      <br />
      <br />
    </div>
  )
}

export default Demo


```

在宽度截断模式下，可以截断任何可渲染元素，不只是 string：

```tsx
/**
* @title non-string
*/

import React, { useRef } from 'react'
import Truncate from '@alicloud/console-components-truncate'

const sentence2 =
  '毕竟西湖六月中，风光不与四时同。接天莲叶无穷碧，映日荷花别样红。'

const Demo = () => {
  const updaterRef = useRef<null | (() => void)>(null)
  return (
    <div className="truncate-demo">
      <Truncate type="width" threshold={200}>
        <span>{sentence2}</span>
      </Truncate>
      <br />
      <br />
      <Truncate type="width" threshold={200} omission="。。。">
        <span>{sentence2}</span>
      </Truncate>

      <br />
      <br />
      <Truncate
        type="width"
        threshold={200}
        omission=""
        align="br"
        tooltipMaxWidth={1200}
        // 从Truncate拿到updater
        updaterRef={updaterRef}
      >
        <img
          src="https://img.alicdn.com/tfs/TB1Ly5oS3HqK1RjSZFPXXcwapXa-238-54.png"
          width={300}
          onLoad={() => {
            // 图片的异步加载相当于绕过React直接更新子元素的宽度，
            // 因此需要手动调用updater来检查是否需要截断
            updaterRef.current && updaterRef.current()
          }}
          alt="alicloud logo"
        />
      </Truncate>
    </div>
  )
}
export default Demo


```

可以自定义省略符号。不过注意，如果省略符号不是...的话，会在宽度截断模式下造成“字符在中间被截断”（在浏览器中没办法支持那么“智能”的截断）：

```tsx
/**
* @title custom-omission
*/

import React from 'react'
import Truncate from '@alicloud/console-components-truncate'
import { Icon } from '@alicloud/console-components'

const sentence2 =
  '毕竟西湖六月中，风光不与四时同。接天莲叶无穷碧，映日荷花别样红。'

const Demo = () => {
  return (
    <div className="truncate-demo">
      <Truncate type="length" threshold={20} omission={<Icon type="smile" />}>
        {sentence2}
      </Truncate>
      <br />
      <br />
      <Truncate
        type="width"
        threshold={200}
        omission={<Icon style={{ marginLeft: '6px' }} type="ellipsis" />}
      >
        {sentence2}
      </Truncate>
    </div>
  )
}
export default Demo


```

```tsx
```

## API

### 单行截断：

| 名称               | 类型                                     | 说明                                                                                                                                                                                                                                                                                                                                                          | 默认值       |
|--------------------|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| children           | string \| React.ReactNode               | 需要被截断的内容<br>如果想要通过字符长度来截断，则 children 必须为 string；<br>如果想要通过宽度来截断，则 children 可以为任意可渲染元素；                                                                                                                                                                                                                             |              |
| type               | 'length' \| 'width'                      | 如何判断是否需要截断：<br>'length': 内容字符串长度是否大于 threshold<br>'width': 内容渲染后的宽度是否大于 threshold                                                                                                                                                                                                                                              |              |
| threshold          | number \| 'auto'                          | 截断临界值：<br>type 为 'length' 时，threshold 限制字符串长度，必须传入 number 类型。<br>type 为 'width' 时，threshold 限制内容渲染后的宽度，可以传入 number 或 'auto'。<br>其中 'auto' 表示截断宽度自动设置为容器元素的宽度。尤其适用于 flex 布局下，截断宽度由剩余宽度决定的场景。                                                                                  | 30           |
| showTooltip        | boolean                                   | 在被截断时，是否使用气泡展示完整内容                                                                                                                                                                                                                                                                                                                         | true         |
| align              | AlignType                                 | 气泡对齐方式，可选值参见 Balloon（Tooltip）组件文档                                                                                                                                                                                                                                                                                                       | 'r' (右)     |
| omission           | React.ReactNode                           | 省略符号                                                                                                                                                                                                                                                                                                                                                        |              |
| tooltipMaxWidth    | number                                    | tooltip 的最大宽度限制，showTooltip 为 true 时才有效                                                                                                                                                                                                                                                                                                           |              |
| className          | string                                    | 容器的类名                                                                                                                                                                                                                                                                                                                                                        |              |
| style              | React.CSSProperties                       | 容器的样式                                                                                                                                                                                                                                                                                                                                                        |              |
| popupStyle         | React.CSSProperties                       | 当 tooltip 展示时，设置弹层组件 style，透传给 Popup                                                                                                                                                                                                                                                                                                             |              |
| popupClassName     | string                                    | 当 tooltip 展示时，设置弹层组件的 className，透传给 Popup                                                                                                                                                                                                                                                                                                       |              |
| patchPopupProps    | (originalProps: BalloonProps) => BalloonProps | 完全控制 tooltip 的 props。比如指定 popupContainer。<br>BalloonProps 的类型见 Balloon 组件文档。                                                                                                                                                                                                                                                                  |              |
| updaterRef         | React.MutableRefObject<(() => void) \| null> | 【极少使用】如果你绕过 React 的更新机制来更新子节点（比如直接用 JS 操作 DOM，或者加载图片造成子节点变宽），我们无法及时检查子节点是否需要截断。这种情况下，你需要通过这个 prop 来获取 updater 来手动调用。见 "non-string" 这个 Demo。<br>仅当 type 为 'width' 时有效。                                        |              |
| isOverflowChange   | (newIsOverflow: boolean) => void          | 【极少使用】方便父组件知道当前是否发生了截断，type === 'width' 时可用（type === 'length' 时你自己就很容易判断是否会截断）。<br>慎用，避免截断状态 -> 你扩大父容器 -> 非截断状态 -> 你缩小父容器 -> 截断状态 -> ... 这样的无限循环。                                                                                                                   |              |
| value              | number \| string                           | 【已废弃】，请使用 threshold                                                                                                                                                                                                                                                                                                                                       |              |
| tooltip            | boolean \| string                          | 在被截断时，是否使用气泡展示完整内容<br>【已废弃】，请使用 showTooltip                                                                                                                                                                                                                                                                                           | 'enable'     |


多行截断：

| 名称            | 类型                                               | 说明                                                                                                                                                                     | 默认值     |
|-----------------|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| lines           | number                                             | 展示的行数                                                                                                                                                               |            |
| ellipsis        | string \| React.ReactNode                         | 如何渲染省略号                                                                                                                                                           |            |
| showTooltip     | boolean                                            | 在被截断时，是否使用气泡展示完整内容                                                                                                                                       | true       |
| patchPopupProps | (originalProps: BalloonProps) => BalloonProps     | 完全控制 tooltip 的 props。比如指定 popupContainer。<br>BalloonProps 的类型见 Balloon 组件文档。                                                                         |            |
| popupClassName  | string                                             | 当 tooltip 展示时，设置弹层组件的 className，透传给 Popup                                                                                                                    |            |
| popupStyle      | React.CSSProperties                                | 当 tooltip 展示时，设置弹层组件的 style，透传给 Popup                                                                                                                       |            |
| tooltipMaxWidth | number                                             | tooltip 的最大宽度限制，showTooltip 为 true 时才有效                                                                                                                        |            |
| align           | AlignType                                          | 气泡对齐方式，可选值参见 Balloon（Tooltip）组件文档                                                                                                                         | 'b' (下)   |