Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Highlight 高亮文本
把一段文字里的关键字标出来,常用在搜索结果、列表筛选、日志查看里。文字按纯文本显示,里面的 HTML 不会被解析。
引入
import { NsHighlight } from '@ns/ui'
基础用法
text 是要显示的文字,patterns 是要高亮的词,可以是一个字符串,也可以是字符串数组。每个词在文字里出现的每一处都会高亮,默认不区分大小写。
<template>
<NsSpace direction="vertical" align="start">
<NsHighlight text="NsUI 是一个 Vue 3 组件库" :patterns="['组件库', 'vue']" />
<NsHighlight text="订单 20260001 已发货" patterns="20260001" />
<NsHighlight text="苹果、香蕉、苹果汁、苹果派" patterns="苹果" />
</NsSpace>
</template>
patterns 是空字符串、空数组或不传时不高亮,原样显示文字;数组里的空字符串会被忽略,重复的词只算一次。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">不传</span>
<NsHighlight text="原样显示,不高亮" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">空字符串</span>
<NsHighlight text="原样显示,不高亮" patterns="" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">空数组</span>
<NsHighlight text="原样显示,不高亮" :patterns="[]" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">有空字符串</span>
<NsHighlight text="空字符串被忽略,只高亮“高亮”" :patterns="['', '高亮', '高亮']" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 80px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
搜索结果高亮
配合输入框做搜索时,把关键字传给 patterns 即可。下面把空格分开的多个词都高亮:
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsHighlight, NsInput, NsSpace } from '@ns/ui'
const keyword = ref('')
const items = ['用户管理', '角色管理', '菜单管理', '操作日志']
const patterns = computed(() => keyword.value.split(/\s+/).filter(Boolean))
</script>
<template>
<NsSpace direction="vertical" fill>
<NsInput v-model="keyword" placeholder="输入关键字" clearable />
<ul>
<li v-for="item in items" :key="item">
<NsHighlight :text="item" :patterns="patterns" />
</li>
</ul>
</NsSpace>
</template>
重叠和相邻的词
多个词的匹配位置重叠或紧挨着时,合并成一段高亮,不会拆成几个相邻的高亮块。一个词是另一个词的一部分时,按长的高亮,和词在数组里的顺序无关:
| 文字 | patterns | 高亮结果 |
|---|---|---|
北京市朝阳区 | ['北京', '北京市'] | 北京市朝阳区 |
abcdef | ['abc', 'cde'] | abcdef(重叠) |
abcdef | ['ab', 'cd'] | abcdef(相邻) |
ab cd | ['ab', 'cd'] | ab cd(分成两段) |
实际效果:
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">包含</span>
<NsHighlight text="北京市朝阳区" :patterns="['北京', '北京市']" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">重叠</span>
<NsHighlight text="abcdef" :patterns="['abc', 'cde']" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">相邻</span>
<NsHighlight text="abcdef" :patterns="['ab', 'cd']" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">分开</span>
<NsHighlight text="ab cd" :patterns="['ab', 'cd']" />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 48px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
区分大小写
case-sensitive 设为 true 后只高亮大小写一致的地方。不区分大小写时,高亮的是原文的写法。
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">不区分(默认)</span>
<!-- 高亮 Vue、vue、VUE -->
<NsHighlight text="Vue、vue 和 VUE" patterns="vue" />
</NsSpace>
<NsSpace wrap>
<span class="row-label">case-sensitive</span>
<!-- 只高亮 vue -->
<NsHighlight text="Vue、vue 和 VUE" patterns="vue" case-sensitive />
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 112px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
特殊字符和正则
默认(auto-escape 为 true)每个词按字面匹配,.、*、(、$、C++ 这类带正则特殊字符的词不用自己转义:
<template>
<NsSpace direction="vertical" align="start">
<NsHighlight text="C++ 和 C# 都支持" patterns="C++" />
<NsHighlight text="价格 $100.00" patterns="$100.00" />
<NsHighlight text="文件名是 report(1).xlsx" patterns="(1)" />
</NsSpace>
</template>
auto-escape 设为 false 时,每个词按正则表达式处理,例如高亮所有数字:
<template>
<NsSpace direction="vertical" align="start">
<NsHighlight text="订单 1024 共 3 件" patterns="\d+" :auto-escape="false" />
<NsHighlight
text="联系电话 13800001111,备用 13900002222"
patterns="1[3-9]\d{9}"
:auto-escape="false"
/>
<NsHighlight
text="2026-01-05 创建,2026-03-18 更新"
:patterns="['\\d{4}-\\d{2}-\\d{2}', '更新']"
:auto-escape="false"
/>
</NsSpace>
</template>
正则写错时(例如用户输入了 ()不会报错:写错的词被忽略,其余的词照常高亮,都写错时原样显示文字;开发环境下在控制台输出 [NsUI] 开头的警告。正则的标志位由组件决定(全局匹配,加上按 case-sensitive 决定的 i),在词里写不了标志位。能匹配空字符串的正则(例如 a*、^)里空的那部分不高亮。
下面可以输入词,切换“按正则”和“区分大小写”看效果。按正则时输入 ( 这类写错的正则,文字原样显示:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsHighlight, NsInput, NsSpace } from '@ns/ui'
const pattern = ref('ns-\\w+')
const regexp = ref(true)
const caseSensitive = ref(false)
const text = '组件的类名都以 ns- 开头,例如 ns-button、ns-input、NS-TAG。'
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsInput v-model="pattern" placeholder="要高亮的词" style="width: 200px" />
<NsCheckbox v-model="regexp">按正则(auto-escape 为 false)</NsCheckbox>
<NsCheckbox v-model="caseSensitive">区分大小写</NsCheckbox>
</NsSpace>
<NsHighlight
:text="text"
:patterns="pattern"
:auto-escape="!regexp"
:case-sensitive="caseSensitive"
/>
</NsSpace>
</template>
自定义标签和样式
默认用 <mark> 包住高亮的文字,背景是主题的警告色浅底(--ns-color-warning-bg-hover),文字颜色跟着所在的文字,暗色主题下自动变成半透明的金色。可以改:
highlight-tag:换成别的标签,例如strong、em、span;highlight-class:加类名,用法和 Vue 的class绑定一样(字符串、数组、对象);highlight-style:加内联样式,可以是对象或字符串。
<template>
<NsSpace direction="vertical" align="start">
<NsHighlight
text="订单 20260001 已发货"
patterns="20260001"
highlight-tag="strong"
:highlight-style="{ color: 'var(--ns-color-primary)', backgroundColor: 'transparent' }"
/>
<NsHighlight text="库存不足,剩余 3 件" patterns="库存不足" highlight-class="stock-warning" />
</NsSpace>
</template>
<style>
.stock-warning {
color: var(--ns-color-danger);
background-color: var(--ns-color-danger-bg);
}
</style>
默认样式的优先级是 0(写在 :where() 里),highlight-class 的类只要写了同样的属性就能盖过它,不用加 !important,也不用写在 :deep() 里(高亮元素的类名是 ns-highlight__mark,样式不是 scoped 的)。
highlight-tag 换成不同的标签时,浏览器给这些标签的默认样式会叠加在高亮背景上,例如 strong、b 加粗,em、i 斜体,u 加下划线:
<template>
<NsSpace direction="vertical" align="start">
<NsHighlight text="mark(默认):高亮这几个字" patterns="这几个字" />
<NsHighlight text="strong:高亮这几个字" patterns="这几个字" highlight-tag="strong" />
<NsHighlight text="em:高亮这几个字" patterns="这几个字" highlight-tag="em" />
<NsHighlight text="b:高亮这几个字" patterns="这几个字" highlight-tag="b" />
<NsHighlight text="u:高亮这几个字" patterns="这几个字" highlight-tag="u" />
<NsHighlight text="span:高亮这几个字" patterns="这几个字" highlight-tag="span" />
</NsSpace>
</template>
highlight-class 和 highlight-style 的几种写法:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsHighlight, NsSpace } from '@ns/ui'
const urgent = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsHighlight
text="class 字符串:库存不足"
patterns="库存不足"
highlight-class="stock-warning"
/>
<NsHighlight
text="class 数组:库存不足"
patterns="库存不足"
:highlight-class="['stock-warning', 'stock-bold']"
/>
<NsSpace wrap>
<NsHighlight
text="class 对象:库存不足"
patterns="库存不足"
:highlight-class="{ 'stock-warning': urgent, 'stock-bold': urgent }"
/>
<NsCheckbox v-model="urgent">加上类名</NsCheckbox>
</NsSpace>
<NsHighlight
text="style 对象:已发货"
patterns="已发货"
:highlight-style="{ color: 'var(--ns-color-success)', backgroundColor: 'transparent' }"
/>
<NsHighlight
text="style 字符串:已发货"
patterns="已发货"
highlight-style="background-color: transparent; text-decoration: underline wavy var(--ns-color-success)"
/>
</NsSpace>
</template>
<style>
.stock-warning {
color: var(--ns-color-danger);
background-color: var(--ns-color-danger-bg);
}
.stock-bold {
font-weight: var(--ns-font-weight-bold);
}
</style>
在段落里使用
根元素是行内的 <span>,可以直接放进段落、表格单元格、列表项里,字号、颜色、行高都跟着外层。高亮跨行时每一行的高亮块都带圆角。
<template>
<NsParagraph size="lg" style="max-width: 420px">
<NsHighlight
text="组件库的颜色、尺寸和间距都由主题变量控制,修改主题变量就能统一调整所有组件的外观,切换暗色主题时所有组件也会跟着变化。"
:patterns="['主题变量', '暗色主题时所有组件也会跟着变化']"
/>
</NsParagraph>
</template>
文字里有 HTML
text 里的内容全部按文字显示,<b>、<img onerror> 这类标签原样显示,不会被解析成元素,不需要自己转义,可以放心显示用户输入的内容。
<template>
<!-- 页面上显示的就是 <b>加粗</b> 这几个字 -->
<NsHighlight text="<b>加粗</b> 和 <i>斜体</i>" patterns="<b>" />
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| text | string | '' | 要显示的文字,按纯文本显示 |
| patterns | string | string[] | [] | 要高亮的词;空字符串被忽略,重叠或相邻的匹配合并成一段 |
| caseSensitive | boolean | false | 是否区分大小写 |
| highlightTag | string | 'mark' | 高亮部分用的标签名;script、style、iframe 等会执行或加载内容的标签和不合法的名字改用 mark |
| highlightClass | string | string[] | Record<string, boolean> | - | 加在每个高亮元素上的类名 |
| highlightStyle | StyleValue | - | 加在每个高亮元素上的样式,可以是对象或字符串 |
| autoEscape | boolean | true | 是否把词里的正则特殊字符转义、按字面匹配;为 false 时按正则处理 |
Events
无。
Slots
无。要显示的文字通过 text 传,不支持默认插槽。
方法
无。
类型
import type { HighlightProps, HighlightClass } from '@ns/ui'
type HighlightClass = string | string[] | Record<string, boolean>
注意事项
- 根元素是行内的
<span class="ns-highlight">,可以直接放进段落、表格单元格、列表项里,字号、颜色、行高都跟着外层。高亮元素的类名是ns-highlight__mark。 - 默认高亮不加左右内边距,加不加高亮文字的位置都不变;跨行时每一行的高亮块都带圆角。
- 内容是用 vnode 生成的文本节点,不经过
v-html、innerHTML,所以没有 XSS 风险。需要高亮富文本(本身带 HTML 标签的内容)时,这个组件不适用。 - 匹配按 JavaScript 字符串处理:不区分大小写只对有大小写的字母有效,全角、半角字符不互相匹配(
A不匹配A),拼音、简繁体也不互相匹配。 - 同一个词在文字里重叠出现时按从左到右不重叠的方式匹配,例如
aa在aaa里只高亮前两个a,和浏览器的页内查找一样。 highlightTag不能是script、style、iframe、frame、frameset、object、embed、link、meta、base、noscript、template,也不能是不合法的标签名(例如带空格、以数字开头),这些情况改用mark,开发环境下在控制台警告。