# js-jksearcher

**Repository Path**: jinko/js-jksearcher

## Basic Information

- **Project Name**: js-jksearcher
- **Description**: Javascript 字符串搜索器，支持拼音搜索, 全拼简拼混合中文字母数字等
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-01-14
- **Last Updated**: 2022-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 字符串搜索工具

支持拼音(全拼, 简拼, 多音字), 以及拼音中文字母数字混合搜索

## 全局对象

全局对象为 `window.JKSearcher`

## 用法用例

### 直接搜索

```javascript
//返回匹配的第一个的下标 [0,1]
JKSearcher.search('你好吗', 'nh');
```


```javascript
//返回匹配的所有下标 [[0,1]]
JKSearcher.search('你好吗', 'nh', {
    //匹配所有项目
    all: true,
    //区分大小写
    sensitive: true
});
```

```javascript
//返回匹配的所有内容
//以下返回: ["你好", "你很"]
JKSearcher.match('你好吗, 你很厉害', 'nh', {
    //匹配所有项目
    all: true,
    //区分大小写
    sensitive: true
});
```


```javascript
//高亮所有匹配项, 默认追加 <b></b>
//以下返回: <b>你好</b>吗, <b>你很</b>厉害
JKSearcher.highlight('你好吗, 你很厉害', 'nh', {
    //匹配所有项目
    all: true,
    //区分大小写
    sensitive: true
});
```


```javascript
//自定义高亮所有匹配项
//以下返回: <span class="hi">你好</span>吗, <span class="hi">你很</span>厉害
JKSearcher.highlight('你好吗, 你很厉害', 'nh', {
    //匹配所有项目
    all: true,
    //区分大小写
    sensitive: true,
    //自定义高亮回调
    callback: row => `<span class="hi">${row}</span>`
});
```

### 创建索引, 并通过索引来搜索

搜索方法和上面类似

```javascript
//返回匹配的第一个的下标 [0,1]
let s = JKSearcher.createIndexes('你好吗');
s.search('nh');
```


```javascript
//返回匹配的所有下标 [[0,1]]
let s = JKSearcher.createIndexes('你好吗');
s.search('nh',  {
   //匹配所有项目
   all: true,
   //区分大小写
   sensitive: true
});
```

```javascript
//返回匹配的所有内容
//以下返回: ["你好", "你很"]
let s = JKSearcher.createIndexes('你好吗, 你很厉害');
s.match('nh', {
    //匹配所有项目
    all: true,
    //区分大小写
    sensitive: true
});
```

```javascript
//返回匹配的所有下标
let s = JKSearcher.createIndexes('你好吗, 你很厉害');
//高亮所有匹配项, 默认追加 <b></b>
//以下返回: <b>你好</b>吗, <b>你很</b>厉害
s.highlight('nh', {
    //匹配所有项目
    all: true,
    //区分大小写
    sensitive: true
});
```

从索引中获取原来的字符串

> JKSearcher.createIndexes() 的第二个参数如果指定为true则不会有原来的字符串, 同时也不支持 match 和 highlight 方法

```javascript
let s = JKSearcher.createIndexes('你好吗, 你很厉害');
//以下输出 "你好吗, 你很厉害"
console.log(s.raw);
```

### 创建数据集合

```javascript
//指定数据
let data = [
    {
        "id": 10091056,
        "name": "Movic 咒术回战 0 狗卷棘 角色徽章（全6款）",
        "brandName": "Movic"
    },
    {
        "id": 10086261,
        "name": "异界三重奏 超神降临 限时体验 SSR魔力赏",
        "brandName": " F:NEX"
    },
    {
        "id": 10091080,
        "name": "散爆 云图计划 音乐盛典 像素头像抱枕",
        "brandName": "散爆"
    },
];

//创建数据集合
let dataSet = JKSearcher.createDataSet(data);

/**
 * 搜索指定关键字, 并高亮匹配项, 并将高亮的结果存在 hiname 字段中
 */
let matchedData = dataSet.search('yunt计划', {
    all:true,
    //区分大小写
    sensitive:true,
    //搜索字段
    labelKey: 'name',
    highlightCallback:a=>`<span class='hi'>${a}</span>`,
    //高亮后保存的字段
    highlightSaveKey: 'hiname',
    highlight: true,
});


//以下输出
/*
[
    {
        "id": 10091080,
        "name": "散爆 云图计划 音乐盛典 像素头像抱枕",
        "brandName": "散爆",
        "hiname": "散爆 <span class='hi'>云图计划</span> 音乐盛典 像素头像抱枕"
    }
]
*/
console.log(JSON.stringify(matchedData, 0, 4));


//更新数据
dataSet.updateData([
    {
        "id": 10091056,
        "name": "Movic 咒术回战 0 狗卷棘 角色徽章（全6款）",
        "brandName": "Movic"
    },
    {
        "id": 10086261,
        "name": "异界三重奏 超神降临 限时体验 SSR魔力赏",
        "brandName": " F:NEX"
    },
    {
        "id": 10091080,
        "name": "散爆 云图计划 音乐盛典 像素头像抱枕",
        "brandName": "散爆"
    },
    {
        "id": 10086261,
        "name": "异界三重奏 超神降临 限时体验 SSR魔力赏",
        "brandName": " F:NEX",
    },
    {
        "id": 10091080,
        "name": "散爆 云图计划 音乐盛典 像素头像抱枕",
        "brandName": "散爆",
    },
]);

/**
 * 重新搜索
 */
matchedData = dataSet.search('xs', {
    all:true,
    //区分大小写
    sensitive:true,
    //搜索字段
    labelKey: 'name',
    highlightCallback:a=>`<span class='hi'>${a}</span>`,
    //高亮后保存的字段
    highlightSaveKey: 'hiname',
    highlight: true,
});

//以下输出
/*
[
    {
        "id": 10086261,
        "name": "异界三重奏 超神降临 限时体验 SSR魔力赏",
        "brandName": " F:NEX",
        "hiname": "异界三重奏 超神降临 <span class='hi'>限时</span>体验 SSR魔力赏"
    },
    {
        "id": 10091080,
        "name": "散爆 云图计划 音乐盛典 像素头像抱枕",
        "brandName": "散爆",
        "hiname": "散爆 云图计划 音乐盛典 <span class='hi'>像素</span>头像抱枕"
    },
    {
        "id": 10086261,
        "name": "异界三重奏 超神降临 限时体验 SSR魔力赏",
        "brandName": " F:NEX",
        "hiname": "异界三重奏 超神降临 <span class='hi'>限时</span>体验 SSR魔力赏"
    },
    {
        "id": 10091080,
        "name": "散爆 云图计划 音乐盛典 像素头像抱枕",
        "brandName": "散爆",
        "hiname": "散爆 云图计划 音乐盛典 <span class='hi'>像素</span>头像抱枕"
    }
]
*/
console.log(JSON.stringify(matchedData, 0, 4));


let dataSet2 = JKSearcher.createDataSet(data, {
    //指定搜索返回的值
    valueKey:'id'
});

matchedData = dataSet2.search('yunt计划', {
    //搜索字段
    labelKey: 'name',
    //返回搜索值(指定该值后, all和highlight属性无效, 除非该值与highlightSaveKey的值相等)
    valueKey: 'id',
});

//以下返回
/*
[
    10091080
] 
*/
console.log(JSON.stringify(matchedData, 0, 4));
```

----------

## JKSearcher

定义在window对象中, 可以通过 `window.JKSearcher` 访问该对象

### (m) createIndexes

对文本创建搜索索引, 然后可以通过搜索索引对字符串进行关键字匹配

- **原型** 

**`createIndexes(str, withoutRaw) : JKSearcherIndexes`**

- **参数**


**str**: `string` 待生成所以的文本
**withoutRaw**: `boolean` 若为ture, 则生成的索引结构中不会有原始字符串, 默认`false`

- **返回值**

`JKSearcherIndexes`
返回创建好的索引结构 [JKSearcherIndexes](#-?JKSearcherIndexes)

### (m) search

返回匹配关键字的文本索引信息

- **原型**

**`search(str, word, option) : boolean|array<IndexArray>`**

- **参数**

**str**: `string|{JKSearch-Indexes}` 原始字符串或者[createIndexes](#-?JKSearcher//(m)%20createIndexes)方法创建的索引。*参考 [JKSearcherIndexes](#-?JKSearcherIndexes)*
**word**: `string` 搜索关键字
**option**: `{JKSearcherSearchOption}` 参考 [JKSearcherSearchOption](#-?JKSearcherSearchOption)

- **返回值**

`boolean|array<IndexArray>`
成功返回匹配结果数组, 失败返回false 

> **IndexArray** 是一个`array`类型的数据, 索引说明如下
> `0`: 关键字在原始字符串中的开始坐标
> `1`: 关键字在原始字符串中的结束坐标

### (m) match

搜索文本中匹配关键字的文本内容

- **原型**

**`match(str, word, option) : array`**

- **参数**

**str**: 参考 [JKSearcher.search()](#-?JKSearcher//(m)%20search)
**word**: 参考 [JKSearcher.search()](#-?JKSearcher//(m)%20search)
**option**: 参考 [JKSearcher.search()](#-?JKSearcher//(m)%20search)

- **返回值**

`array`
返回匹配的子串 


### (m) highlight

高亮匹配的文本

- **原型**

**`highlight(str, word, option) : string`**

- **参数**

**str**: 参考 [JKSearcher.search()](#-?JKSearcher//(m)%20search)
**word**: 参考 [JKSearcher.search()](#-?JKSearcher//(m)%20search)
**option**: `JKSearcherHighlightOption` 选项

- **返回值**

`string`
返回已经替换匹配项的原始字符串

### (m) createDataSet

创建一个数据集合,然后可以通过对象搜索满足关键字的对应的数据集成员列表

- **原型**

**`createDataSet(data, option) : JKSearcherDataSet`**

- **参数**

**data**: `array|object` 待搜索的数据集,可以是个数组,也可以是个对象类型
**option**: `JKSearcherDataSetOption` 创建选项， 参考[JKSearcherDataSetOption](#-?JKSearcherDataSetOption)

- **返回值**

`JKSearcherDataSet`
返回[JKSearcherDataSet](#-?JKSearcherDataSet)对象

----------

## JKSearcherIndexes

`Array` 类型, 索引数据列表, 由[JKSearcher.createIndexes](#-?JKSearcher//(m)%20createIndexes)方法返回

### (f) raw

`string` 原始字符串

### (m) search

搜索方法 - 从索引中搜索字符串

- **原型**

**`search(word, option): boolean|array<IndexArray>`**

参考 [JKSearcher.search()](#-?JKSearcher//(m)%20search) 

### (m) match

在调用[JKSearcher.createIndexes](#-?JKSearcher//(m)%20createIndexes)方法时, 如果指定第二个参数为true, 则此方法不可用

- **原型**

**`match(word, option): array`**

参考 [JKSearcher.match()](#-?JKSearcher//(m)%20match)

### (m) highlight

在调用[JKSearcher.createIndexes](#-?JKSearcher//(m)%20createIndexes)方法时, 如果指定第二个参数为true, 则此方法不可用

- **原型**

**`highlight(word, option): string`**

参考 [JKSearcher.highlight()](#-?JKSearcher//(m)%20highlight)

----------

## JKSearcherSearchOption

[JKSearcher.search](#-?JKSearcher//(m)%20search) 方法的参数选项

### (f) all
`boolean` 为true表示搜索返回所有匹配的项, 默认false

### (f) sensitive
`boolean` 大小写敏感, 为true表示区分大小写, 默认false

----------

## JKSearcherHighlightOption

继承 [JKSearcherSearchOption](#-?JKSearcherSearchOption) 对象

### (m) callback

- **原型**

`callback(str, matchItem) : string`

- **参数**

**str**: 匹配的字符串
**matchItem**: `object` 一个对象其成员如下:
 value: 匹配的值
 x: 匹配的开始下标
 y: 匹配的结束下标
 length: 匹配长度

- **返回值**

`string`
返回格式化后的字符串替换原来的字符串


----------

## JKSearcherDataSetOption

### (f) uniqueKey

`string|null` 指定数据成员的唯一值所在的key名称, 若提供此值则创建索引将以此值为依据. 如果提供此值请确保此值是唯一的. 若没有提供此值则会以数组的索引作为唯一值.


----------

## JKSearcherDataSet

### (m) reIndex

- **原型**

**`reIndex(labelKeys) : string`**

- **参数**

**labelKeys**: `string|array` 需要重建索引的key

- **返回值**

无

### (m) search

- **原型**

**`search(word, option) : object|array`**

- **参数**

**word**: `string` 搜索关键字
**option**: `JKSearcherDataSetSearchOption` 搜索选项 参考[JKSearcherDataSetSearchOption](#-?JKSearcherDataSetSearchOption)

- **返回值**

`object|array` 返回匹配的成员集合(返回值类型取决于原始数据集的类型)


### (m) updateData

- **原型**

**`updateData(data, reIndexAll) : JKSearcherDataSet`**

- **参数**

**data**: `object|array` 新的数据集合
**reIndexAll**: `boolean` 是否重新索引所有labelKey, 若设置为true, 则会清掉现有的索引, 重新建立索引. 默认false

- **返回值**

`JKSearcherDataSet` 返回原对象

### (m) getRawData

- **原型**

**`getRawData() : object|array`**

- **参数**

无

- **返回值**

`object|array`
返回原始数据集合

----------

## JKSearcherDataSetSearchOption

继承 [JKSearcherSearchOption](#-?JKSearcherSearchOption) 对象

### (f) labelKey

`string|null` 指定数据集合成员的匹配的key名称。默认为`label`

### (f) valueKey

`string|null` 指定数据集合成员的"值"所对应的key名称。 当调用搜索时会返回成员中该key中的值。若没有配置该值则默认返回数据成员
 若指定了此值, 且`labelKey` 的值与 `highlightSaveKey` 不相等, 则 `highlight` 值和 `all` 无效

### (f) highlight

`boolean` 是否高亮匹配项

### (f) highlightCallback

高亮回调函数

参考 [JKSearcherHighlightOption.callback()](#-?JKSearcherHighlightOption//(m)%20callback)

### (f) highlightSaveKey

`string` 高亮后的字符串保存的key