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,开发环境下在控制台警告。