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
自定义解析规则
xxxxxxxxxx
import { 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 将继承外层组件的尺寸设置。
xxxxxxxxxx
import { 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
xxxxxxxxxx
import { 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
xxxxxxxxxx
import { 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 应用。
xxxxxxxxxx
import { 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 中,可通过设置合理的页容量进行分页减少性能损耗。