cnd-components-mcp
Version:
An MCP service for Cnd components query | 一个减少 Cnd 组件代码生成幻觉的 MCP 服务，包含系统提示词、组件文档、API 文档、代码示例和更新日志查询
210 lines (178 loc) • 15.1 kB
Markdown
## 简介
@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' (下) |