# simply-ellipsis

> 简易ellipsis效果，只需要一个class名便搞定

Latest version **4.0.4** (published 2023-02-08) · ISC license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install simply-ellipsis
pnpm add simply-ellipsis
yarn add simply-ellipsis
bun add simply-ellipsis
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 4.0.4 |
| Published | 2023-02-08 |
| First published | 2021-10-19 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 83.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | MusiCoder |
| Maintainers | musi32 |
| Keywords | simply-ellipsis, ellipsis |

## Links

- npm: https://www.npmjs.com/package/simply-ellipsis
- Repository: https://gitee.com/sichuan_meiyijia_industry_w327134/ellipsis
- npm.io page: https://npm.io/package/simply-ellipsis

## Recent versions

- 4.0.4 (latest) — 2023-02-08
- 4.0.3 — 2022-10-14
- 4.0.1 — 2022-10-14
- 4.0.0 — 2022-10-14
- 3.2.0 — 2022-10-10
- 3.1.0 — 2022-10-09
- 3.0.0 — 2022-04-08
- 2.2.3 — 2022-03-30
- 2.2.2 — 2021-12-14
- 2.1.2 — 2021-12-08
- 2.1.1 — 2021-12-07
- 2.1.0 — 2021-12-07
- 2.0.2 — 2021-10-25
- 2.0.1 — 2021-10-24
- 1.0.9 — 2021-10-20
- … 9 more at https://npm.io/package/simply-ellipsis/versions

## README

# 简介
**simply-ellipsis是纯原生技术实现的tooltip工具，具备以下功能**
1. tooltip超出边界时自动调整其位置，保证提示框在视界内；
2. 可配置单行是否超长才提示；
3. 可配置多行提示；
4. 可自定义提示内容；

**在线预览 [http://sichuan_meiyijia_industry_w327134.gitee.io/ellipsis/](http://sichuan_meiyijia_industry_w327134.gitee.io/ellipsis/)**

**gif展示**
![请添加图片描述](https://img-blog.csdnimg.cn/ea87e21685ab483eae4a7484e7e988e1.gif)

### 1.集成方式
#### 原生
```html
<link rel="stylesheet" href="ellipsis.css"/>
<script src="../dist/simply-ellipsis.js"></script>
<script>
	window.addEventListener('load',()=>{
  		ellipsis.setEll()
  		ellipsis.setObserver('根节点id,必传','主题名，可选')
	})
</script>
```

1. 在head引入example文件夹下的ellipsis.css
2. 引入dist文件夹下的simply-ellipsis.js
3. 调用ellipsis方法，传入id，指定监听的dom

   ###### 具体可参考根目录下index.html中的使用方法，react、angler、vue等项目采用全局监听时均可采取该方式；
   ###### 若采取手动维护的方式，即不执行setObserver监听的情况下，则需在组件生命周期勾子函数中，代表dom挂载完成的勾子函数中执行setEll方法，对于vue框架,则是在每个组件的mounted勾子函数中执行setEll。

#### VUE
```javascript
//安装
npm i simply-ellipsis -S

//main.js/ts中引入
import ellipsis from 'simply-ellipsis'
import 'simply-ellipsis/example/ellipsis.scss'

// main.js中全局调用
window.addEventListener('load', () => {
    ellipsis.setEll()
    ellipsis.setObserver('根节点id,','主题名，可选')//默认为element-dark,还内置了element-light，其余样式请自行设置
   // ellipsis.setObserver('app','element-light')//对于根节点id为app的项目，使用element-ui的light风格提示框
})
```

### 2.使用方式
框架集成到项目后，只需在需要省略提示的div中,使用示例中的class。目前有三类class，两个额外配置项。
**三类class：**
1. .ell-t、.ell-b、.ell-r、.ell-l
   用于智能判断，文本超长时才提示，不超长时则不提示，元素本身需设置固定宽度，参考在线预览《2.演示单行文字超长情况下进行提示》；
2. .ell-a-t、.ell-a-b、.ell-a-r、.ell-a-l"
   "a"代表always,即不管是否超长，均进行提示。参考在线预览《3.演示单行、多行无论是否超长均提示》；
3. .ell-m-t、.ell-m-b、.ell-m-r、.ell-m-l
   m代表multiply,即应用于多行超长提示，**该类class必须搭配--ell-line样式变量方可生效**。参考在线预览《5.演示多行仅超长时进行提示》；

**两个配置项：**
1. ell-value
   用于自定义toottip提示内容，可与上面三类class搭配。参考在线预览《4.演示单行、多行无论是否超长均提示》；
2. style="--ell-line:行数"
   搭配多行超长提示，用于设置多行文本行数。参考在线预览《3.演示单行、多行无论是否超长均提示》；

```html
<!--单行超长提示-->
<div class="ell-t">ellipsis在顶部提示</div>
<!--多行超长提示，--ell-line指定行数-->
<div class="ell-m-t" style="--ell-line:3">ellipsis多行顶部提示,行数设置为3</div>
<!--无论是否超长均提示-->
<div class="ell-a-t">ellipsis在顶部提示</div>
<!--自定义提示内容-->
<div class="ell-t" ell-value="自定义内容">ellipsis在顶部提示</div>

```

### 3.自定义tooltip样式
1. 重写html下定义的样式变量来修改tooltip样式，目前只定义了以下变量。
2. 调用ellipsis.setObserver('节点id',[主题名])方法时，传递第二个主题参数
如在下方css中自定义的主题名为‘ant-dark’,ellipsis.setObserver('节点id','ant-dark')

```css
html[data-ellipsis='自定义的主题名'] {
   /*提示框最大宽度，超过后自动换行*/
   --ell-max-width: 350px;
   /*提示框背景色*/
   --ell-background: #fff;
   /*提示框字体大小*/
   --ell-font-size: 12px;
   /*提示框间距*/
   --ell-padding: 5px 11px;
   /*提示框行高*/
   --ell-line-height: 20px;
   /*提示框字体颜色*/
   --ell-color: rgb(48 49 51);
   /*提示框倒角*/
   --ell-border-radius: 4px;
   /*提示框边框颜色*/
   --ell-border-color: rgb(228 231 237);
   /*提示枉边框宽度*/
   --ell-border-size: 1px;
}
```
### 4.Api说明
框架暴露了一个ellipsis的对象，该对象提供了两个方法，分别为setEll,setObserver

1. setEll介绍

   该工具的核心方法，调用时会通过document.querySelectorAll方法查找所有应用了"ell-r,ell-l,ell-t,ell-b"Class类的dom元素，进行了以下三个步骤的计算。

        a.计算dom元素文本内容是否超长，若不超长，计算结束，不会出现tooltip提示效果
        b.计算tooltip是否超出对应方向的视图边界，如"ell-b"计算方向为视图底部，若超出视图底部，则将方向改为"ell-t"
        c.根据确定好的方向，计算出tooltip应用fixed定位后的left与top
2. setObserver

   a. 该方法是一个MutationObserver的监听器，通过传入id,获取需要监听的dom,能够监听该dom及其子元素的dom节点删除和添加。

   b. MutationObserver为原生api，只要防止MutationObserver回调函数的频繁执行，则无需担心性能，这点可以采用防抖函数解决，即MutationObserver的回调函数最好使用防抖函数包裹。
   c. setObserver会开启MutationObserver监听，监听事件触发后，会通过防抖的方式调用setEll，防抖时间为1000ms。所以在某些极端情况下，dom处于不断创建删除的情况时，会导致tooltip的位置得到不更新。目前容易遇到的一种情况是，页面存在计时器时。原因在于采用innerHtml或者innerText的方式更新文字内容，实际上在更改text这个Node,会触发MutationObserver，解决方法见疑难解答。

   d.看完上述所有描述，即可明白，重要的是setEll方法,setObserve是可用可不用的。setObserve只配置了观察dom节点变化，无法应对更为复杂的页面变化。在实际项目中，应根据实际情况选择，可以自己配置MutationObserver,也可在页面状态发生改变后，手动调用一次setEll。


### 5.版本更新记录
**3.0.0**
1. 多行class名由".elln-方向"改为".ell-m-方向",仍兼容2.x用法；
2. 新增不论是否超长均提示功能，class名为".ell-a-方向"；
3. 新增自定义tooltip功能，在应用了class的元素中，设置自定义属性ell-value;

**2.1.0**
1. 向现实妥协，放弃纯css的hover触发tooltip方式，采用dom的mouseover事件触发tooltip,解决上一版本需单独处理scroll与transform的情况;
2. 最初的想法过于极端，一方面表现在希望使用时极简，靠一个class名搞定；二是在触发上也做到极简，不依赖于dom的mouseover监听事件,靠css的hover触发；以至于在实现过程中总是无法完美解决面临的所有情况，有了上面关于《fixed与absolution方案论述》
3. 目前版本单行超长省略提示基本算ok了，下一步目标是实现多行超长省略提示
### 6.疑难解答
1. 问：完全按照教程使用，大部分生效，部分不生效，主要是高德地图与百度地图的信息弹窗中使用不生效？

   ###### 答：全局监听的方式没有监听style的变化，故对于通过style="display:none"来实现dom显隐时，不能自动触发setEll方法执行，在元素display更改后，手动执行一次setEll方法即可生效。
2. 问完全按照教程全局引入方式使用，所有tooltip效果均不生效？
   ###### 答：全局监听使用了防抖节约性能，若页面中存在持续的文本变化，如计时器，秒表，当前时间等随时间不断变化功能，会持续的触发setObserver，导致setEll始终无法执行，tooltip自然无法生效。具体触发原理在Api说明setObserver介绍中。解决方式为放弃框架双向绑定的方式来更新值，采用原生方式更新text节点的值，在线预览中当前时间采取了该方式


```javascript
<div id="timer" class="f12">{{ time }}</div>

//dom无初值时先赋初值，具有初值后，会有childNodes,更新时采取如下方式
setTime() {
    let nowTime = new Date()
    let date = moment(nowTime).format('YYYY年MM月DD日')
    let time = moment(nowTime).format('HH:mm:ss')
    if (!this.time) {
        this.time = date + '  ' + '  ' + time
    } else {
        this._dom.childNodes[0].data = date + '  ' + '  ' + time //重要，重要，重要
    }
}
```

---
_Source: https://npm.io/package/simply-ellipsis · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._