错误!终端不支持 JavaScript ,请打开 JavaScript 功能!

开发者
Popper.js
Popper.js
项目总数:2
开发主体:组织
目录
编辑
核心管理
核心管理
内容

Popper.js github


🍿Positioning tooltips is difficult. Popper is here to help!


Popper

Positioning tooltips is difficult. Popper is here to help!

Given an element, such as a button, and a tooltip element describing it, Popperwill automatically put the tooltip in the right place near the button.

But Popper is not just about tooltips. It will position any UI element that"pops out" from the flow of your document. The most common example is a tooltip,but it also includes popovers, drop-downs, and more. All of these can begenerically described as a "popper element".

Why Popper?

Naive tooltip implementations generally don't consider the following:

  • Preventing overflow when the tooltip is near a boundary (e.g. window), it willget cut off;
  • Flipping to keep the tooltip visible in the viewport for the user;
  • Keeping the tooltip with the reference element when inside any number ofscrolling containers;
  • Keeping the tooltip in its original DOM context

Popper solves all of these key problems in an elegant, performant manner. It isa ~3 kB library that aims to provide a reliable and extensible positioningengine you can use to ensure all your popper elements are positioned in theright place.

Why waste your time writing your own logic every time you are programming atooltip? There are many edge cases that are easy to forget to consider, which iswhy we've done the hard work for you.

Since we write UIs using powerful abstraction libraries such as React or Angularnowadays, you'll also be glad to know Popper can fully integrate with them andbe a good citizen together with your other components. Check out react-popperfor the official Popper wrapper for React.

Installation

1. Package Manager

# With npmnpm i @popperjs/core# With Yarnyarn add @popperjs/core

2. CDN

<script src="https://unpkg.com/@popperjs/core"></script>

3. Direct Download?

Managing dependencies by "directly downloading" them and placing them into yoursource code is not recommended for a variety of reasons, including missing outon feat/fix updates easily. Please, use a versioning management system like aCDN or npm/Yarn.

Usage

The most straightforward way to get started is to import Popper from the unpkgCDN, which includes all of its features. You can call the Popper.createPopperconstructor to create new popper instances.

Here is a complete example:

<!DOCTYPE html><title>Popper example</title><style> #tooltip { background-color: rebeccapurple; padding: 20px; width: 200px; }</style><button type="button" id="button">I'm a button</button><div id="tooltip">I'm a tooltip</div><script src="https://unpkg.com/@popperjs/core"></script><script> const button = document.querySelector('#button'); const tooltip = document.querySelector('#tooltip'); // Pass the button, the tooltip, and some options, and Popper will do the // magic positioning for you: Popper.createPopper(button, tooltip, { placement: 'right', });</script>

Module bundlers

You can import the createPopper constructor from the fully-featured file:

import { createPopper } from '@popperjs/core';const button = document.querySelector('#button');const tooltip = document.querySelector('#tooltip');// Pass the button, the tooltip, and some options, and Popper will do the// magic positioning for you:createPopper(button, tooltip, { placement: 'right',});

All the modifiers listed in the docs menu will be enabled and "just work", soyou don't need to think about setting Popper up. The size of Popper includingall of its features is about 5 kB minzipped, but it may grow a bit in thefuture.

Popper Lite (tree-shaking)

If bundle size is important, you'll want to take advantage of tree-shaking. Thelibrary is built in a modular way to allow to import only the parts you reallyneed.

import { createPopper } from '@popperjs/core/lib/popper-lite.js';

The Lite version includes the most necessary modifiers that will compute theoffsets of the popper, compute and add the positioning styles, and add eventlisteners. This is close in bundle size to pure CSS tooltip libraries, andbehaves somewhat similarly.

However, this does not include the features that makes Popper truly useful.

The two most useful modifiers not included in Lite are preventOverflow andflip:

import { createPopper } from '@popperjs/core/lib/popper-lite.js';import preventOverflow from '@popperjs/core/lib/modifiers/preventOverflow.js';import flip from '@popperjs/core/lib/modifiers/flip.js';const button = document.querySelector('#button');const tooltip = document.querySelector('#tooltip');createPopper(button, tooltip, { modifiers: [preventOverflow, flip],});

As you make more poppers, you may be finding yourself needing other modifiersprovided by the library.

Distribution targets

Popper is distributed in 3 different versions, in 3 different file formats.

The 3 file formats are:

  • esm (works with import syntax — recommended)
  • umd (works with <script> tags or RequireJS)
  • cjs (works with require() syntax)

The 3 versions are:

  • popper: includes all the modifiers (features) in one file (default);
  • popper-lite: includes only the minimum amount of modifiers to provide thebasic functionality;
  • popper-base: doesn't include any modifier, you must import them separately;

Below you can find the size of each version, minified and compressed with theBrotli compression algorithm:

Hacking the library

If you want to play with the library, implement new features, fix a bug youfound, or simply experiment with it, this section is for you!

First of all, make sure to haveYarn installed.

Install the development dependencies:

yarn install

And run the development environment:

yarn dev

Then, simply open one the development server web page:

# macOS and Linuxopen localhost:5000# Windowsstart localhost:5000

From there, you can open any of the examples (.html files) to fiddle withthem.

Now any change you will made to the source code, will be automatically compiled,you just need to refresh the page.

If the page is not working properly, try to go in "Developer Tools >Application > Clear storage" and click on "Clear site data".
To run the examples you need a browser withJavaScript modules via script tag support.

Test Suite

Popper is currently tested with unit tests, and functional tests. Both of themare run by Jest.

Unit Tests

The unit tests use JSDOM to provide a primitive document object API, they areused to ensure the utility functions behave as expected in isolation.

Functional Tests

The functional tests run with Puppeteer, to take advantage of a complete browserenvironment. They are currently running on Chromium, and Firefox.

You can run them with yarn test:functional. Set the PUPPETEER_BROWSERenvironment variable to firefox to run them on the Mozilla browser.

The assertions are written in form of image snapshots, so that it's easy toassert for the correct Popper behavior without having to write a lot of offsetscomparisons manually.

You can mark a *.test.js file to run in the Puppeteer environment byprepending a @jest-environment puppeteer JSDoc comment to the interested file.

Here's an example of a basic functional test:

/** * @jest-environment puppeteer * @flow */import { screenshot } from '../utils/puppeteer.js';it('should position the popper on the right', async () => { const page = await browser.newPage(); await page.goto(`${TEST_URL}/basic.html`); expect(await screenshot(page)).toMatchImageSnapshot();});

You can find the completejest-puppeteer documentation here,and thejest-image-snapshot documentation here.


MIT 协议

页面归档进度

为开源贡献一份力量?即可加入
提示:动画按钮可以拖动并记忆位置
部分设置修改过后需刷新页面
如果过渡动画效果卡顿可关闭声音、鼠标特效

悬浮设置

系统设置

语言设置

权限设置

    当天日期

    2020-01-23 00:00:00

    昨天日期

    2020-01-22 00:00:00

    明天日期

    2020-01-24 00:00:00
    如列表太长,手持设备滚动列表时,可在屏幕靠右侧下滑,否则将调整项目位置。