Typography 版式
文字,图片,段落,数值的基本格式。
使用场景
- 对文章、博客、日志等的文本内容进行展示时。
- 对文本进行复制和省略等基础操作时。
代码演示
如何引入
import { Typography } from '@kousum/semi-ui-vue';标题组件
通过设置 heading 可以展示不同级别的标题。
xxxxxxxxxx<template> <div> <TypographyTitle :style="{ margin: '8px 0' }" >h1. Semi Design</TypographyTitle> <TypographyTitle :heading="2" :style="{ margin: '8px 0' }" >h2. Semi Design</TypographyTitle> <TypographyTitle :heading="3" :style="{ margin: '8px 0' }" >h3. Semi Design</TypographyTitle> <TypographyTitle :heading="4" :style="{ margin: '8px 0' }" >h4. Semi Design</TypographyTitle> <TypographyTitle :heading="5" :style="{ margin: '8px 0' }" >h5. Semi Design</TypographyTitle> <TypographyTitle :heading="6" :style="{ margin: '8px 0' }" >h6. Semi Design</TypographyTitle> </div></template><script setup lang="ts">import {TypographyTitle} from "@kousum/semi-ui-vue"</script>文本组件
内置不同样式的文本。可以通过 icon 属性传入图标,这种方式传入的图标默认与文本有间距,同时在链接文本的情况不会出现下划线符合设计规范。
xxxxxxxxxx<template> <div> <Text>Text</Text> <br /> <br /> <Text type="secondary">Secondary</Text> <br /> <br /> <Text type="tertiary">{{`Tertiary v>=1.2.0`}}</Text> <br /> <br /> <Text type="quaternary">{{`Quaternary v>=1.2.0`}}</Text> <br /> <br /> <Text type="warning">Warning</Text> <br /> <br /> <Text type="danger">Danger</Text> <br /> <br /> <Text type="success">{{`Success v>=1.7.0`}}</Text> <br /> <br /> <Text disabled>Disabled</Text> <br /> <br /> <Text mark>Default Mark</Text> <br /> <br /> <Text code>Example Code</Text> <br /> <br /> <Text underline>Underline</Text> <br /> <br />链接文本支持传入 object,将对应的属性挂在 <a> 标签上。
v>=1.0 后默认不再有下划线,可以配合 underline 属性在 hover,active 态增加下划线的样式。
xxxxxxxxxx<template> <div> <Text :link="{ href: 'https://semi.design/' }">链接文本</Text> <br /> <br /> <Text :link="{ href: 'https://semi.design/' }">打开网站</Text> <br /> <br /> <Text :link="{ href: 'https://semi.design/' }" :icon="h(IconLink)" :underline="true">带下划线的网页链接</Text> </div></template><script setup>import { TypographyText } from '@kousum/semi-ui-vue';import { IconLink } from '@kousum/semi-icons-vue';import { h } from 'vue';const Text = TypographyText;</script>段落组件
段落组件拥有两种行距,可以通过设置 spacing='extended' 使用更宽松的行距。
xxxxxxxxxx<template> <div> <TypographyTitle :heading="5">默认行距</TypographyTitle> <TypographyParagraph> Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件,帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。 </TypographyParagraph> <br /> <TypographyTitle :heading="5">宽松行距</TypographyTitle> <TypographyParagraph spacing="extended"> Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件,帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。 </TypographyParagraph> </div></template><script setup lang="ts">import { TypographyParagraph, TypographyTitle } from '@kousum/semi-ui-vue';</script>数值组件
Numeral 组件在Text组件的基础上,添加了属性: rule, precision, truncate, parser, 以提供需要单独处理文本中数值的能力。
对于 rule 为 percentage 的 Numeral 组件,数据处理规则有变化。在 v2.22.0-v2.29.0 中,对于绝对值大于等于 1 的 num,结果为 num%; 对于绝对值小于等于 1 的 num,结果为 (num*100)%。在 v2.30.0 版本及之后统一为 (num*100)%。
precision 可以设置小数点后保留位数, 用于设置精度truncate 小数点后保留位截段取整方式,可选 ceil, floor, round,作用与 Math.ceil、Math.floor、Math.round 对齐rule 用于设置解析规则
- 设为
percentages会将数字自动转换为百分比形式展示 - 设为
bytes-decimal会将数字自动换算为字节对应的单位展示, 1 KB 定义为等于 1000 字节,(B, KB, MB, GB, TB, PB, EB, ZB, YB) - 设为
bytes-binary会将数字自动换算为字节对应的单位展示,1 KiB 定义为等于 1024字节,(B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB) - 设为
text时,仅自动对数字进行取整,根据precision和truncate属性 - 设为
numbers时,会将非数字字符进行过滤,仅展示数字 - 设为
exponential时,会将数字自动转换为科学计数法形式展示
xxxxxxxxxx<template> <div> <TypographyNumeral :precision="1"> <p>点赞量:1.6111e1 K</p> </TypographyNumeral> <p> 播放量: <TypographyNumeral rule="numbers" :precision="1"> 2.4444e2 </TypographyNumeral> K </p> <TypographyNumeral rule="percentages" :precision="2" :style="{ marginBottom: '12px' }"> <p>好评率: 0.915</p> </TypographyNumeral> <TypographyNumeral rule="percentages" :style="{ marginBottom: '12px' }"> 这场比赛我的胜率是0.6,输的概率是0.4 </TypographyNumeral> <TypographyNumeral rule="bytes-decimal" :precision="2" truncate="floor"> <p>已使用: 1000</p> <p>未使用: {{ 1024*1000 }}</p> </TypographyNumeral> <TypographyNumeral rule="bytes-binary" :precision="2" truncate="floor"> <p>已使用: 1024</p> <p>未使用: {{ 2e12 }}</p>可以通过 parser 自定义解析规则
xxxxxxxxxximport { TypographyNumeral } from '@kousum/semi-ui-vue';const Numeral = TypographyNumeral;export default function () { function parserTCH(oldVal) { return oldVal.split(' ').map(item => Number(item) ? `${item.replace(/(\d)(?=(?:\d{3})+(?:\.|$))/g, '$1,')}+` : item ).join(' '); } function Infos() { const data = [ { type: 'Stars', min: '7100' }, { type: 'Fork', min: '560' }, { type: 'Downloads', min: '5000000' }, { type: 'Contributors', min: '100' } ]; return data.map(item => <p key={item.min}> {item.type}: <b style={{ color: 'rgba(var(--semi-violet-5),1)' }}> {item.min} </b> </p> ); } return ( <div> <Numeral parser={parserTCH} component="div"> Semi Design 重视我们的用户,加入并助力我们不断完善 {Infos()} </Numeral> <br /> <Numeral link={{ href: 'https://semi.design', target: '_blank' }} parser={parserTCH}> 现已服务 {1e5} 用户,前往官网 >> </Numeral> </div>文本大小
段落组件和文本组件支持两种尺寸,small(12px) 和 normal(14px) 和 inherit,默认为normal。
当段落组件或者文本组件嵌套使用时候,设置内层组件的 size 属性为 inherit,内层组件的 size 将继承外层组件的尺寸设置。
xxxxxxxxxximport { TypographyParagraph, TypographyText } from '@kousum/semi-ui-vue';export default function () { return ( <div> <TypographyText>正常文本</TypographyText> <TypographyParagraph spacing="extended"> Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件,帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。 </TypographyParagraph> <br /> <TypographyText size='small'>小文本</TypographyText> <TypographyParagraph size='small'> Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件,帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。 </TypographyParagraph> <br /> <TypographyText size="small">这是一段文本,样式为 small <TypographyText link size="inherit">这是一段链接,设置 size 为 inherit 继承外部样式设置</TypographyText> </TypographyText> </div> );}可复制文本
可通过配置 copyable 属性支持文本的复制。
当 copyable 配置为 true时,默认复制内容为 children 本身,注意,此时 children 只支持 string类型传入
当 copyable 配置为 object 时,可通过 copyable.content 指定复制至粘贴板的内容,与 children 不再强关联, 此时 children 将不再限定类型,但 copyable.content 仍需要为 string
xxxxxxxxxximport { Typography, TextArea, Toast } from '@kousum/semi-ui-vue';import { IconSetting } from '@kousum/semi-icons-vue';const { Paragraph, Text, Numeral } = Typography;export default function () { return ( <div> <Paragraph copyable>点击右边的图标复制文本。</Paragraph> <Paragraph copyable={{ content: 'Hello, Semi Design!' }}>点击复制文本。</Paragraph> <Paragraph copyable={{ onCopy: () => Toast.success({ content: '复制文本成功' }) }}>点击右边的图标复制文本。</Paragraph> 时间戳: <Numeral truncate="ceil" copyable underline>{new Date().getTime()/1000}s</Numeral> <Paragraph copyable={{ icon: <IconSetting style={{ color: 'var(--semi-color-link)' }}/> }}>自定义复制节点</Paragraph> <br/> <br/> <Text type="secondary">粘贴区域:</Text> <br/> <TextArea autosize style={{ width: 320, marginTop: 4 }} rows={3} /> </div> );}省略文本
支持文本的省略,可以通过 ellipsis 配置相关参数,具体参考 Ellipsis Config。
2. ellipsis 要实现缩略,需要有明确的 width或 maxWidth 宽度限制做对比判断。若自身未设置宽度(例如纯依靠 flex 属性撑开),或 width为 100% 等不定数值,那么父级需要有明确的 width或 maxWidth
3. ellipsis 需要获取 DOM 的宽高度等信息用以做基本判断,若自身或父级存在 display:none 样式会导致取值不正确,此时缩略会失效
4. 省略文本的计算,分为CSS 截断和 JS 截断,强依赖 DOM 元素的相关状态获取。在结构复杂的页面,大量使用 Typography 可能会导致过多的 reflow 重排,建议选择合适的省略方式避免造成性能负担。更多信息见 FAQ
xxxxxxxxxximport { Typography, Tooltip } from '@kousum/semi-ui-vue';const { Paragraph, Title, Text } = Typography;export default function () { const customRenderTooltip = (content, children) => { return <Tooltip content={content} style={{ backgroundColor: 'var(--semi-color-primary)' }}>{children}</Tooltip>; }; return ( <div> <Title heading={5} ellipsis={{ showTooltip: true }} style={{ width: '250px' }}> 是一个很长很长很长很长5号标题 </Title> <br /> <Text ellipsis={{ showTooltip: { opts: { content: '这是自定义要展示的内容' } } }} style={{ width: 150 }} > 可以自定义浮层里的展示内容试试看吧 </Text> <br/> {/* link还可以传入object,如link={{ href: 'https://semi.design/zh-CN/basic/typography', target: '_blank' }} */} <Text link ellipsis={{ showTooltip: true, pos: 'middle' }} style={{ width: '150px' }}> 是一个很长很长很长很长的链接 </Text> <br/> <Paragraph ellipsis={{ suffix: '小尾巴' }} style={{ width: '300px' }}> 有后缀的情况:Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。 </Paragraph> <br/> <Paragraph ellipsis={{ rows: 3 }} style={{ width: '300px' }}> 这是一个多行截断的例子:Semi Design 是由抖音前端团队与 UED 团队共同设计开发并维护的设计系统。设计系统包含设计语言以及一整套可复用的前端组件,帮助设计师与开发者更容易地打造高质量的、用户体验一致的、符合设计规范的 Web 应用。xxxxxxxxxximport { Typography } from '@kousum/semi-ui-vue';const { Text } = Typography;export default function () { return ( <div> <Text ellipsis={{ showTooltip: { opts: { content: '架构|Semi-inf|graph.cheet.relation' } } }} style={{ width: '150px' }} > 有问题的超长文本发生截断时可按需进行自定义配置 </Text> <br /> <Text ellipsis={{ showTooltip: { opts: { content: '架构|Semi-inf|graph.cheet.relation', className: 'components-typography-demo' } } }} style={{ width: '150px' }} > 覆盖类名超长文本发生截断时可使用类名覆盖进行自定义配置 </Text>// 按需配置 word-break
.components-typography-demo {
word-break: break-word;
// 或
word-break: break-all;
}API参考
Typography.Text
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| component | 自定义渲染元素 | html element | span | |
| code | 是否被 code 元素包裹 | boolean | - | |
| copyable | 是否可拷贝 | boolean | object:Copyable Config | false | 0.27.0 |
| delete | 添加删除线样式 | boolean | false | 0.27.0 |
| disabled | 禁用文本 | boolean | false | 0.27.0 |
| ellipsis | 设置自动溢出省略 | boolean|object:Ellipsis Config | false | 0.34.0 |
| icon | 前缀图标 | ReactNode | - | 0.27.0 |
| link | 是否为链接,传object时,属性将透传给a标签 | boolean|object | false | 0.27.0 |
| mark | 添加标记样式 | boolean | false | 0.27.0 |
| size | 文本大小,可选normal,small,inherit | string | normal | 0.27.0 |
| strong | 是否加粗 | boolean | false | 0.27.0 |
| type | 文本类型,可选 primary, secondary, warning, danger, tertiary(v>=1.2.0), quaternary(v>=1.2.0), success(v>=1.7.0) | string | primary | 0.27.0 |
| underline | 添加下划线样式 | boolean | false | 0.27.0 |
| weight | 设置字重 | number | 2.34.0 |
Typography.Title
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| component | 自定义渲染元素,默认由 heading 决定 | html element | h1~h6 | |
| copyable | 是否可拷贝 | boolean | object:Copyable Config | false | 0.27.0 |
| delete | 添加删除线样式 | boolean | false | 0.27.0 |
| disabled | 禁用文本 | boolean | false | 0.27.0 |
| ellipsis | 设置自动溢出省略 | boolean|object:Ellipsis Config | false | 0.34.0 |
| heading | 标题级别,可选1, 2, 3,4,5,6,对应相应的标题 | number | 1 | 0.27.0 |
| link | 是否为链接,传object时,属性将透传给a标签 | boolean|object | false | 0.27.0 |
| mark | 添加标记样式 | boolean | false | 0.27.0 |
| type | 文本类型,可选 primary, secondary, warning, danger, tertiary(v>=1.2.0), quaternary(v>=1.2.0), success(v>=1.7.0) | string | primary | 0.27.0 |
| underline | 添加下划线样式 | boolean | false | 0.27.0 |
| weight | 设置字重, 可选 light, regular, medium, semibold, bold, default | string, number | 2.34.0 |
Typography.Paragraph
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| component | 自定义渲染元素 | html element | p | |
| copyable | 是否可拷贝 | boolean | object:Copyable Config | false | 0.27.0 |
| delete | 添加删除线样式 | boolean | false | 0.27.0 |
| disabled | 禁用文本 | boolean | false | 0.27.0 |
| ellipsis | 设置自动溢出省略 | boolean|object:Ellipsis Config | false | 0.34.0 |
| link | 是否为链接,传object时,属性将透传给a标签 | boolean|object | false | 0.27.0 |
| mark | 添加标记样式 | boolean | false | 0.27.0 |
| size | 文本大小,可选normal,small | string | normal | 0.27.0 |
| spacing | 行距大小,可选normal,extended | string | normal | 0.27.0 |
| strong | 是否加粗 | boolean | false | 0.27.0 |
| type | 文本类型,可选 primary, secondary, warning, danger, tertiary(v>=1.2.0), quaternary(v>=1.2.0), success(v>=1.7.0) | string | primary | 0.27.0 |
| underline | 添加下划线样式 | boolean | false | 0.27.0 |
Typography.Numeral
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| rule | 解析规则,可选 text, numbers, bytes-decimal, bytes-binary, percentages, exponential | string | text | 2.22.0 |
| precision | 可以设置小数点后保留位数, 用于设置精度 | number | 0 | 2.22.0 |
| truncate | 小数点后保留位截段取整方式,可选 ceil, floor, round,作用与 Math.ceil、Math.floor、Math.round 对齐 | string | round | 2.22.0 |
| parser | 自定义数值解析函数 | (str: string) => string | - | 2.22.0 |
| component | 自定义渲染元素 | html element | span | 2.22.0 |
| code | 是否被 code 元素包裹 | boolean | - | 2.22.0 |
| copyable | 是否可拷贝 | boolean | object:Copyable Config | false | 2.22.0 |
| delete | 添加删除线样式 | boolean | false | 2.22.0 |
| disabled | 禁用文本 | boolean | false | 2.22.0 |
| ellipsis | 设置自动溢出省略 | boolean| object:Ellipsis Config | false | 2.22.0 |
| icon | 前缀图标 | ReactNode | - | 2.22.0 |
| link | 是否为链接,传object时,属性将透传给a标签 | boolean|object | false | 2.22.0 |
| mark | 添加标记样式 | boolean | false | 2.22.0 |
| size | 文本大小,可选normal,small | string | normal | 2.22.0 |
| strong | 是否加粗 | boolean | false | 2.22.0 |
| type | 文本类型,可选 primary, secondary, warning, danger, tertiary, quaternary, success | string | primary | 2.22.0 |
| underline | 添加下划线样式 | boolean | false | 2.22.0 |
Ellipsis Config
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| collapseText | 折叠的展示文本 | string | 收起 |
| collapsible | 是否支持折叠 | boolean | false |
| expandText | 展开的展示文本 | string | 展开 |
| expandable | 是否支持展开 | boolean | false |
| pos | 省略截断的位置,支持末尾和中间截断:end, middle | string | end |
| rows | 省略溢出行数 | number | 1 |
| showTooltip | 是否展示 tooltip 及相关配置: type,浮层内容承载的组件,支持 Tooltip| Popover;opts,其他需要透传给浮层组件的属性; renderTooltip,自定义渲染弹出层组件 | boolean | {type: 'tooltip'|'popover', opts: object, renderTooltip: (content: ReactNode, children: ReactNode) => ReactNode} | false |
| suffix | 始终展示的后缀 | string | - |
| onExpand | 展开/收起的回调 | function(expanded: bool, Event: e) | - |
Copyable Config
| 属性 | 说明 | 类型 | 默认值 | 版本 |
|---|---|---|---|---|
| content | 复制出的文本 | string | - | 0.27.0 |
| copyTip | 复制图标的 tooltip 展示内容 | React.node | - | 1.0.0 |
| icon | 自定义渲染复制节点 | React.node | - | 2.31.0 |
| onCopy | 复制回调 | Function(e:Event, content:string, res:boolean) | - | 0.27.0 |
| successTip | 复制成功的展示内容 | React.node | - | 0.33.0 |
文案规范
- Link
- 文字链接需要清晰且可预测,用户应该能够预测他们点击链接时会发生什么
- 切勿通过错误标记链接来误导用户
- 避免使用“Click here”或“Here”作为独立链接
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| No spaces yet? Create space | No spaces yet? Click here |
- 避免将整个句子作为可点击的文字链接,而是将描述具体去向的文字作为链接内容
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| Views user documentation for details | View user documentation for details |
- 使用短术语或词作为链接文本会更有利于国际化,以避免由于不同的语言的语法和语序不同,而出现链接文字被拆分的问题
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| Manage notifications to | Manage notifications to |
- 以文字链接结尾时,不需要跟随标点符号,除了问号“?”
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| No spaces yet? Create space | No spaces yet? Click here |
| Forgot password ? | Forgot password |
- 链接文字不要包含冠词“the, a, an”
| ✅ 推荐用法 | ❌ 不推荐用法 |
|---|---|
| View user documentation for details | View the user documentation for details |
设计变量
FAQ
Typography 省略具体机制及注意事项?
Semi 截断有两种策略, CSS 截断和 JS 截断。当设置中间截断(pos='middle')、可展开(expandable)、有后缀(suffix 非空)、可复制(copyable),启用 JS 截断策略;非以上场景,启用 CSS 截断策略。
通常来说,CSS 截断性能优于 JS 截断。在 children、 容器尺寸不变的情况下,CSS 截断只涉及 1~2 次计算,js 截断可能涉及多次计算。
同时使用大量带有截断功能的 Typography 需注意性能消耗,如在 Table 中,可通过设置合理的页容量进行分页减少性能损耗。