When the content of a web page is greatly adjusted, a navigation function is often needed to tell the user that a certain function has been adjusted to another position. A more general approach is to add a mask, highlight the area being adjusted, and then use text to complete the guidance. We call this functionality “navigation,” and Smartour takes that functionality out of the box and provides an out-of-the-box solution.

Project address: github.com/jrainlau/sm… Example: official jrainlau. Making. IO/smartour

Install

Smartour is built into UMD and ES Module modules that allow users to be introduced in different ways.

npm install smartour
Copy the code
/* ES Modules */
import Smartour from 'smartour/dist/index.esm.js'
/* CommandJS */
const Smartour = require('smartour')
/* <script> */
<script src="smartour/dist/index.js"></script>
Copy the code

Basic usage

Smartour provides a very simple API focus(), which is the easiest way to highlight an element.

let tour = new Smartour()

tour.focus({
  el: '#basic-usage'
})
Copy the code

Slot Slot.

Slot is an HTML string used to provide a description for the highlighted element.

Pure string:

let tour = new Smartour()

tour.focus({
  el: '#pure-string'.slot: 'This is a pure string'
})
Copy the code

Html string

let tour = new Smartour()

tour.focus({
  el: '#html-string'.slot: ` 
      
 
       
This is a html string
 
      
 `
})
Copy the code

Slot position

Slots can be positioned in four different directions: top, right, left, and bottom.

Setting the options.slotPosition property overrides the default top position.

let tour = new Smartour()

tour.focus({
  el: '#slot-positions'.slot: `top`.options: {
    slotPosition: 'top' // The default is' top '}})` `'Buttonslot-bottom' > bottom 
       ## slot Events Elements defined by slots can also be bound to events. We pass 'keyNodesAttribute to bind events to slot elements. `keyNodes'is content for a series of'keyNodeAn array of. Attribute `keyNode.el'is a CSS selector, while'keyNode.eventThe 'attribute is the event bound to the corresponding element. `` `javascript
let tour = new Smartour()

tour.focus({
  el: '.slot-events-demo'.options: {
    slotPosition: 'right'
  },
  slot: ` Click here to occur an alert event  Click here to occur an alert event  `.keyNodes: [{
    el: '.occur-1'.event: (a)= > { alert('Event!! ')}}, {el: '.occur-2'.event: (a)= > { alert('Another event!! ')]}}})Copy the code

Queue

Sometimes pages require more than one navigation. Smartour allows you to put together a series of Tours through.queue() and display them one by one.

Here’s an example:

let tour = new Smartour()

tour
  .queue([{
    el: '.li-1'.options: {
      layerEvent: tour.next.bind(tour)
    },
    slot: 'This is the 1st line.'
  }, {
    el: '.li-2'.options: {
      layerEvent: tour.next.bind(tour)
    },
    slot: 'This is the 2nd line.'
  }, {
    el: '.li-3'.options: {
      layerEvent: tour.next.bind(tour)
    },
    slot: 'This is the 3rd line.'
  }])
  .run() // Don't forget to call the 'run()' method to display the first navigation
Copy the code

options

Smartour is a builder function that takes an options argument to override its default options

Let’s see what the default options look like:

{
  prefix: 'smartour'./ / class prefix
  padding: 5.// Highlight the margins within the region
  maskColor: 'rgba(0, 0, 0, .5)'.// Mask layer color with transparency value
  animate: true.// Whether to use animation
  slotPosition: 'top' // The default slot location
  layerEvent: smartour.over // Mask layer click the event, the default is to end the tour
}
Copy the code

APIs

In addition to the.focus(),.queue(), and.run() apis, Smartour provides three other apis specifically for controlling the presentation of navigations.

  • .next() : displays the next navigation (can only be used with.queue()).

  • .prev() : displays the previous navigation (can only be used with.queue()).

  • .over() : complete the tour.

The principle of Smartour

Smartour by element. GetBoundingClientRect () API to obtain high target element’s width and location information, and then placed one with a box – shadow style elements on it as a highlighted area.

Since click events cannot be triggered in the box-shadow area, Smartour also places a full-screen transparent mask to bind layerEvents to.

The highlight area and slots are set to Absolute. When scrolling page document. The documentElement. ScrollTop or document. The documentElement. ScrollLeft values will change, and then Smartour will amend it’s real-time location information.

certificate

MIT