Tippy.js 版本迁移指南：从 4.x 到 6.x 的全面解析

Tippy.js 版本迁移指南：从 4.x 到 6.x 的全面解析

tippyjs Tooltip, popover, dropdown, and menu library 项目地址: https://gitcode.com/gh_mirrors/ti/tippyjs

前言

Tippy.js 作为一款功能强大的工具提示库，在版本迭代过程中进行了多项重大改进。本文将详细解析从 4.x 到 6.x 版本的迁移要点，帮助开发者平滑过渡到新版本。

从 5.x 迁移到 6.x

核心架构变更

6.x 版本最显著的变化是升级到了 Popper.js v2，这带来了更强大的定位能力和性能优化。但同时也意味着部分 API 发生了变化：

1. instance.popperInstance 和 popperOptions API 已更新
2. 模块导入方式从 iife 改为 umd 格式

安全增强

出于安全考虑，6.x 版本默认禁用了 HTML 内容解析：

// 5.x 版本可以直接传递 HTML 字符串
tippy(target, {
  content: '<strong>HTML 内容</strong>'
});

// 6.x 需要显式启用 allowHTML
tippy(target, {
  content: '<strong>HTML 内容</strong>',
  allowHTML: true
});

主题系统重构

主题系统进行了重大重构，CSS 选择器结构发生了变化：

/* 5.x 主题定义 */
.tippy-tooltip.tomato-theme {
  background-color: tomato;
}

/* 6.x 新语法 */
.tippy-box[data-theme~='tomato'] {
  background-color: tomato;
}

箭头样式的定义方式也发生了变化：

/* 5.x 箭头样式 */
.tippy-tooltip.tomato-theme[data-placement^='top'] > .tippy-arrow {
  border-top-color: tomato;
}

/* 6.x 新语法 */
.tippy-box[data-theme~='tomato'][data-placement^='top'] > .tippy-arrow::before {
  border-top-color: tomato;
}

重要 API 变更

1. 实例属性：instance.popperChildren 已被移除，可以通过 instance.popper.firstElementChild 访问工具提示元素
2. 显示/隐藏方法：.show() 和 .hide() 不再接受持续时间参数，改为通过 .setProps() 设置
3. 定位相关属性：
   • distance 和 offset 合并为 offset 数组
   • flip、flipBehavior 和 flipOnUpdate 配置移至 popperOptions

浏览器兼容性

6.x 默认不再支持 IE11，但可以通过添加 polyfill 实现兼容。

从 4.x 迁移到 5.x

模块导入变化

5.x 版本改为无副作用的导入方式：

// 4.x 自动注入样式
import tippy from 'tippy.js';

// 5.x 需要显式导入 CSS
import tippy from 'tippy.js';
import 'tippy.js/dist/tippy.css';

动画系统改进

1. animateFill 效果不再是默认行为，需要额外导入：

   import {animateFill} from 'tippy.js';
   import 'tippy.js/dist/backdrop.css';
   
   tippy(targets, {
     animateFill: true,
     plugins: [animateFill]
   });
   

2. 动画 CSS 需要单独导入：

   import 'tippy.js/animations/scale.css';
   

重要属性变更

1. 交互式工具提示：在容器有定位或溢出隐藏时，需要额外配置：

   tippy(reference, {
     popperOptions: {
       positionFixed: true
     }
   });
   

2. 箭头类型：arrowType: 'round' 改为使用 roundArrow 导入：

   import {roundArrow} from 'tippy.js';
   import 'tippy.js/dist/svg-arrow.css';
   
   tippy(targets, {
     arrow: roundArrow
   });
   

3. 插件系统：许多功能改为插件形式：

   import {followCursor, sticky} from 'tippy.js';
   
   tippy('button', {
     followCursor: true,
     sticky: true,
     plugins: [followCursor, sticky]
   });
   

静态方法变更

1. 默认属性设置：

   // 4.x
   tippy.setDefaults({});
   
   // 5.x
   tippy.setDefaultProps({});
   

2. 工具提示组改为使用 createSingleton：

   import {createSingleton} from 'tippy.js';
   
   createSingleton(tippy('button'), {delay: 1000});
   

迁移建议

1. 逐步迁移：先升级到 5.x，再升级到 6.x
2. 测试覆盖：特别注意定位和动画相关的功能
3. CSS 适配：检查自定义主题和样式是否兼容新版本
4. 性能优化：利用 Popper.js v2 的新特性优化工具提示性能

通过遵循本指南，开发者可以顺利完成 Tippy.js 的版本迁移，享受新版本带来的改进和增强功能。

tippyjs Tooltip, popover, dropdown, and menu library 项目地址: https://gitcode.com/gh_mirrors/ti/tippyjs