feat(Highlight): add highlight component (#12434)

2025-04-06 03:57:59 +08:00 · 2023-11-12 09:14:24 +08:00 · 2023-11-12 09:14:24 +08:00 · fd63bcc3b0
commit fd63bcc3b0
parent 79834a1584
14 changed files with 570 additions and 0 deletions
--- a/packages/vant/src/config-provider/types.ts
+++ b/packages/vant/src/config-provider/types.ts
@ -102,6 +102,7 @@ export type ConfigProviderThemeVars = BaseThemeVars &
  import('../dropdown-item').DropdownItemThemeVars &
  import('../dropdown-menu').DropdownMenuThemeVars &
  import('../empty').EmptyThemeVars &
+  import('../highlight').HighlightThemeVars &
  import('../field').FieldThemeVars &
  import('../floating-bubble').FloatingBubbleThemeVars &
  import('../floating-panel').FloatingPanelThemeVars &
--- a/packages/vant/src/highlight/Highlight.tsx
+++ b/packages/vant/src/highlight/Highlight.tsx
@ -0,0 +1,66 @@
+import {
+  ref,
+  watchEffect,
+  defineComponent,
+  type PropType,
+  type ExtractPropTypes,
+} from 'vue';
+
+import { truthProp, makeStringProp, createNamespace } from '../utils';
+
+const [name, bem] = createNamespace('highlight');
+
+export const highlightProps = {
+  keywords: [String, Array] as PropType<string | string[]>,
+  autoEscape: truthProp,
+  sourceString: makeStringProp(''),
+  caseSensitive: Boolean,
+  highlightClassName: String,
+};
+
+export type HighlightProps = ExtractPropTypes<typeof highlightProps>;
+
+export default defineComponent({
+  name,
+
+  props: highlightProps,
+
+  setup(props) {
+    const highlightedString = ref('');
+
+    const getHighlightClasses = () =>
+      props.highlightClassName
+        ? props.highlightClassName + ` ${bem('tag')}`
+        : `${bem('tag')}`;
+
+    const updateHighlight = () => {
+      const { keywords, sourceString, caseSensitive, autoEscape } = props;
+      const flags = caseSensitive ? 'g' : 'gi';
+
+      let _keywords = keywords;
+
+      if (typeof keywords === 'string') {
+        _keywords = [keywords];
+      }
+
+      const regexPattern = (_keywords as string[]).map((keyword) => {
+        if (autoEscape) {
+          return keyword.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        }
+        return keyword;
+      });
+
+      const regex = new RegExp(`(${regexPattern.join('|')})`, flags);
+      const highlighted = sourceString.replace(
+        regex,
+        `<span class="${getHighlightClasses()}">$1</span>`,
+      );
+
+      highlightedString.value = highlighted;
+    };
+
+    watchEffect(() => updateHighlight());
+
+    return () => <div class={bem()} innerHTML={highlightedString.value}></div>;
+  },
+});
--- a/packages/vant/src/highlight/README.md
+++ b/packages/vant/src/highlight/README.md
@ -0,0 +1,128 @@
+# Highlight
+
+### Intro
+
+Highlight the specified text content.
+
+### Install
+
+Register component globally via `app.use`, refer to [Component Registration](#/en-US/advanced-usage#zu-jian-zhu-ce) for more registration ways.
+
+```js
+import { createApp } from 'vue';
+import { Highlight } from 'vant';
+
+const app = createApp();
+app.use(Highlight);
+```
+
+## Usage
+
+### Basic Usage
+
+You can specify keywords to be highlighted with `keywords` and source text with `source-string`.
+
+```html
+<van-highlight :keywords="keywords" :source-string="text" />
+```
+
+```ts
+export default {
+  setup() {
+    const text =
+      'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.';
+    const keywords = 'questions';
+
+    return {
+      text,
+      keywords,
+    };
+  },
+};
+```
+
+### Multiple Keywords
+
+If you need to specific more than one keywords, you can pass in `keywords` as an array.
+
+```html
+<van-highlight :keywords="keywords" :source-string="text" />
+```
+
+```ts
+export default {
+  setup() {
+    const text =
+      'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.';
+    const keywords = ['time', 'life', 'answer'];
+
+    return {
+      text,
+      keywords,
+    };
+  },
+};
+```
+
+### Custom Class
+
+Set the `highlight-class-name` of the highlighted tag to customize the style.
+
+```html
+<van-highlight
+  :keywords="keywords"
+  :source-string="text"
+  highlight-class-name="custom-class"
+/>
+```
+
+```ts
+export default {
+  setup() {
+    const text =
+      'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.';
+    const keywords = 'life';
+
+    return {
+      text,
+      keywords,
+    };
+  },
+};
+```
+
+```css
+.custom-class {
+  color: red;
+}
+```
+
+## API
+
+### Props
+
+| Attribute | Description | Type | Default |
+| --- | --- | --- | --- |
+| keywords | Expected highlighted text | _string \| string[]_ | - |
+| source-string | Source text | _string_ | - |
+| auto-escape | Whether to automatically escape | _boolean_ | `true` |
+| case-sensitive | Is case sensitive | _boolean_ | `false` |
+| highlight-class-name | Class name of the highlight tag | _string_ | - |
+
+### Types
+
+The component exports the following type definitions:
+
+```ts
+import type { HighlightProps, HighlightThemeVars } from 'vant';
+```
+
+## Theming
+
+### CSS Variables
+
+The component provides the following CSS variables, which can be used to customize styles. Please refer to [ConfigProvider component](#/en-US/config-provider).
+
+| Name | Default Value | Description |
+| --- | --- | --- |
+| --van-highlight-tag-color | _var(--van-primary-color)_ | Color of highlighted text |
--- a/packages/vant/src/highlight/README.zh-CN.md
+++ b/packages/vant/src/highlight/README.zh-CN.md
@ -0,0 +1,125 @@
+# Highlight 高亮文本
+
+### 介绍
+
+高亮指定文本内容。
+
+### 引入
+
+通过以下方式来全局注册组件，更多注册方式请参考[组件注册](#/zh-CN/advanced-usage#zu-jian-zhu-ce)。
+
+```js
+import { createApp } from 'vue';
+import { Highlight } from 'vant';
+
+const app = createApp();
+app.use(Highlight);
+```
+
+## 代码演示
+
+### 基础用法
+
+你可以通过 `keywords` 指定需要高亮的关键字，通过 `source-string` 指定源文本。
+
+```html
+<van-highlight :keywords="keywords" :source-string="text" />
+```
+
+```ts
+export default {
+  setup() {
+    const text = '慢慢来，不要急，生活给你出了难题，可也终有一天会给出答案。';
+    const keywords = '难题';
+
+    return {
+      text,
+      keywords,
+    };
+  },
+};
+```
+
+### 多字符匹配
+
+如果需要指定多个关键字，可以以数组的形式传入 `keywords`。
+
+```html
+<van-highlight :keywords="keywords" :source-string="text" />
+```
+
+```ts
+export default {
+  setup() {
+    const text = '慢慢来，不要急，生活给你出了难题，可也终有一天会给出答案。';
+    const keywords = ['难题', '终有一天', '答案'];
+
+    return {
+      text,
+      keywords,
+    };
+  },
+};
+```
+
+### 设置高亮标签类名
+
+通过 `highlight-class-name` 可以设置高亮标签的类名，以便自定义样式。
+
+```html
+<van-highlight
+  :keywords="keywords"
+  :source-string="text"
+  highlight-class-name="custom-class"
+/>
+```
+
+```ts
+export default {
+  setup() {
+    const text = '慢慢来，不要急，生活给你出了难题，可也终有一天会给出答案。';
+    const keywords = '生活';
+
+    return {
+      text,
+      keywords,
+    };
+  },
+};
+```
+
+```css
+.custom-class {
+  color: red;
+}
+```
+
+## API
+
+### Props
+
+| 参数                 | 说明           | 类型                 | 默认值  |
+| -------------------- | -------------- | -------------------- | ------- |
+| keywords             | 期望高亮的文本 | _string \| string[]_ | -       |
+| source-string        | 源文本         | _string_             | -       |
+| auto-escape          | 是否自动转义   | _boolean_            | `true`  |
+| case-sensitive       | 是否区分大小写 | _boolean_            | `false` |
+| highlight-class-name | 高亮标签的类名 | _string_             | -       |
+
+### 类型定义
+
+组件导出以下类型定义：
+
+```ts
+import type { HighlightProps, HighlightThemeVars } from 'vant';
+```
+
+## 主题定制
+
+### 样式变量
+
+组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 [ConfigProvider 组件](#/zh-CN/config-provider)。
+
+| 名称                      | 默认值                     | 描述         |
+| ------------------------- | -------------------------- | ------------ |
+| --van-highlight-tag-color | _var(--van-primary-color)_ | 高亮文本颜色 |
--- a/packages/vant/src/highlight/demo/index.vue
+++ b/packages/vant/src/highlight/demo/index.vue
@ -0,0 +1,52 @@
+<script setup lang="ts">
+import VanHighlight from '..';
+import { useTranslate } from '../../../docs/site';
+
+const t = useTranslate({
+  'zh-CN': {
+    text1: '慢慢来，不要急，生活给你出了难题，可也终有一天会给出答案。',
+    keywords1: '难题',
+    keywords2: ['难题', '终有一天', '答案'],
+    keywords3: '生活',
+    multipleKeywords: '多字符匹配',
+    highlightClassName: '设置高亮标签类名',
+  },
+  'en-US': {
+    text1:
+      'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.',
+    keywords1: 'questions',
+    keywords2: ['time', 'life', 'answer'],
+    keywords3: 'life',
+    multipleKeywords: 'Multiple Keywords',
+    highlightClassName: 'Highlight Class Name',
+  },
+});
+</script>
+
+<template>
+  <demo-block :title="t('basicUsage')">
+    <van-highlight :keywords="t('keywords1')" :source-string="t('text1')" />
+  </demo-block>
+
+  <demo-block :title="t('multipleKeywords')">
+    <van-highlight :keywords="t('keywords2')" :source-string="t('text1')" />
+  </demo-block>
+
+  <demo-block :title="t('highlightClassName')">
+    <van-highlight
+      :keywords="t('keywords3')"
+      :source-string="t('text1')"
+      highlight-class-name="custom-class"
+    />
+  </demo-block>
+</template>
+
+<style lang="less">
+.van-highlight {
+  padding: 0 16px;
+}
+
+.custom-class {
+  color: red;
+}
+</style>
--- a/packages/vant/src/highlight/index.less
+++ b/packages/vant/src/highlight/index.less
@ -0,0 +1,9 @@
+:root {
+  --van-highlight-tag-color: var(--van-primary-color);
+}
+
+.van-highlight {
+  &__tag {
+    color: var(--van-highlight-tag-color);
+  }
+}
--- a/packages/vant/src/highlight/index.ts
+++ b/packages/vant/src/highlight/index.ts
@ -0,0 +1,16 @@
+import { withInstall } from '../utils';
+import _Highlight from './Highlight';
+
+export const Highlight = withInstall(_Highlight);
+export default Highlight;
+
+export { highlightProps } from './Highlight';
+
+export type { HighlightProps } from './Highlight';
+export type { HighlightThemeVars } from './types';
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    vanHighlight: typeof Highlight;
+  }
+}
--- a/packages/vant/src/highlight/test/snapshots/demo-ssr.spec.ts.snap
+++ b/packages/vant/src/highlight/test/snapshots/demo-ssr.spec.ts.snap
@ -0,0 +1,43 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`should render demo and match snapshot 1`] = `
+<!--[-->
+<div>
+  <!--[-->
+  <div class="van-highlight">
+    Take your time and be patient. Life itself will eventually answer all those
+    <span class="van-highlight__tag">
+      questions
+    </span>
+    it once raised for you.
+  </div>
+</div>
+<div>
+  <!--[-->
+  <div class="van-highlight">
+    Take your
+    <span class="van-highlight__tag">
+      time
+    </span>
+    and be patient.
+    <span class="van-highlight__tag">
+      Life
+    </span>
+    itself will eventually
+    <span class="van-highlight__tag">
+      answer
+    </span>
+    all those questions it once raised for you.
+  </div>
+</div>
+<div>
+  <!--[-->
+  <div class="van-highlight">
+    Take your time and be patient.
+    <span class="custom-class van-highlight__tag">
+      Life
+    </span>
+    itself will eventually answer all those questions it once raised for you.
+  </div>
+</div>
+`;
--- a/packages/vant/src/highlight/test/snapshots/demo.spec.ts.snap
+++ b/packages/vant/src/highlight/test/snapshots/demo.spec.ts.snap
@ -0,0 +1,39 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`should render demo and match snapshot 1`] = `
+<div>
+  <div class="van-highlight">
+    Take your time and be patient. Life itself will eventually answer all those
+    <span class="van-highlight__tag">
+      questions
+    </span>
+    it once raised for you.
+  </div>
+</div>
+<div>
+  <div class="van-highlight">
+    Take your
+    <span class="van-highlight__tag">
+      time
+    </span>
+    and be patient.
+    <span class="van-highlight__tag">
+      Life
+    </span>
+    itself will eventually
+    <span class="van-highlight__tag">
+      answer
+    </span>
+    all those questions it once raised for you.
+  </div>
+</div>
+<div>
+  <div class="van-highlight">
+    Take your time and be patient.
+    <span class="custom-class van-highlight__tag">
+      Life
+    </span>
+    itself will eventually answer all those questions it once raised for you.
+  </div>
+</div>
+`;
--- a/packages/vant/src/highlight/test/demo-ssr.spec.ts
+++ b/packages/vant/src/highlight/test/demo-ssr.spec.ts
@ -0,0 +1,7 @@
+/**
+ * @vitest-environment node
+ */
+import Demo from '../demo/index.vue';
+import { snapshotDemo } from '../../../test/demo';
+
+snapshotDemo(Demo, { ssr: true });
--- a/packages/vant/src/highlight/test/demo.spec.ts
+++ b/packages/vant/src/highlight/test/demo.spec.ts
@ -0,0 +1,4 @@
+import Demo from '../demo/index.vue';
+import { snapshotDemo } from '../../../test/demo';
+
+snapshotDemo(Demo);
--- a/packages/vant/src/highlight/test/index.spec.ts
+++ b/packages/vant/src/highlight/test/index.spec.ts
@ -0,0 +1,69 @@
+import { Highlight } from '..';
+import { mount } from '../../../test';
+
+test('should render the specified text label highlighting correctly', () => {
+  const wrapper = mount(Highlight, {
+    props: {
+      keywords: 'questions',
+      sourceString:
+        'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.',
+    },
+  });
+
+  const highlight = wrapper.find('.van-highlight');
+  const tagText = highlight.find('.van-highlight__tag').text();
+
+  expect(tagText).toEqual('questions');
+});
+
+test('multiple keywords highlighting can be specified', () => {
+  const wrapper = mount(Highlight, {
+    props: {
+      keywords: ['time', 'life', 'questions'],
+      sourceString:
+        'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.',
+    },
+  });
+
+  const highlight = wrapper.find('.van-highlight');
+  const tags = highlight.findAll('.van-highlight__tag');
+
+  expect(tags.length).toEqual(3);
+  expect(tags[0].text()).toEqual('time');
+  expect(tags[1].text()).toEqual('Life');
+  expect(tags[2].text()).toEqual('questions');
+});
+
+test('should be correctly case sensitive', () => {
+  const wrapper = mount(Highlight, {
+    props: {
+      keywords: ['take', 'Life', 'questions'],
+      sourceString:
+        'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.',
+      caseSensitive: true,
+    },
+  });
+
+  const highlight = wrapper.find('.van-highlight');
+  const tags = highlight.findAll('.van-highlight__tag');
+
+  expect(tags.length).toEqual(2);
+  expect(tags[0].text()).toEqual('Life');
+  expect(tags[1].text()).toEqual('questions');
+});
+
+test('should set custom class of the highlight tag', () => {
+  const wrapper = mount(Highlight, {
+    props: {
+      keywords: 'time',
+      sourceString:
+        'Take your time and be patient. Life itself will eventually answer all those questions it once raised for you.',
+      highlightClassName: 'my-custom-class',
+    },
+  });
+
+  const highlight = wrapper.find('.van-highlight');
+  const tag = highlight.find('.van-highlight__tag');
+
+  expect(tag.classes()).toContain('my-custom-class');
+});
--- a/packages/vant/src/highlight/types.ts
+++ b/packages/vant/src/highlight/types.ts
@ -0,0 +1,3 @@
+export type HighlightThemeVars = {
+  highlightTagColor?: string;
+};
--- a/packages/vant/vant.config.mjs
+++ b/packages/vant/vant.config.mjs
@ -312,6 +312,10 @@ location.href = location.href.replace('youzan.github.io', 'vant-ui.github.io');
                path: 'empty',
                title: 'Empty 空状态',
              },
+              {
+                path: 'highlight',
+                title: 'Highlight 高亮文本',
+              },
              {
                path: 'image-preview',
                title: 'ImagePreview 图片预览',
@ -780,6 +784,10 @@ location.href = location.href.replace('youzan.github.io', 'vant-ui.github.io');
                path: 'empty',
                title: 'Empty',
              },
+              {
+                path: 'highlight',
+                title: 'Highlight',
+              },
              {
                path: 'image-preview',
                title: 'ImagePreview',