@txdfe/at-lead

0.1.2 • Public • Published

TeamixLead

本组件封装了多种类型的产品引导组件,包括:

  • 产品介绍弹窗-ProductDialog
  • 功能上新弹窗-ChangelogDialog
  • 页面缺省引导-PagePlaceHolder
  • 全屏引导-FullScreenLead
  • 气泡-highlight
    • Highlight Single Element
    • Highlight With Popover
    • Highlight With Steps

Quick Start

npm install --save @teamix/lead

API

ProductDialog

参数名 说明 必填 类型 默认值 备注
visible 是否显示 false boolean
logo 左上角logo图片地址 true string height: 20px
title 标题 true string
subTitle 副标题 false string
buttons 按钮props true array 参考示例
slides 幻灯片数据 true array 参考示例
onClose 关闭按钮回调 false func
import { ProductDialog } from '@teamix/lead';

props: {
  visible: boolean 
  logo: string // 左上角logo
  title: string // 大标题
  subTitle: string // 副标题
  buttons: {  // 标题下按钮
    text: string
    type: 'primary' | 'normal' | 'secondary' 
    dance?: boolean  // 按钮是否跳动
    onClick(): void
  }[]
  slides: { // 幻灯片
    src: string;
    text: string;
  }[]
  onClose(): void
}

ChangelogDialog

参数名 说明 必填 类型 默认值 备注
visible 是否显示 true boolean
onOk 确定按钮回调 false func
onCancel 取消按钮回调 false func
onClose 关闭按钮回调 false func
cancelText 取消按钮文案 false string
okText 确定按钮文案 false string
dialogProps 弹窗 props false object
title 标题 false string
description 描述 false string
contentDataSource 内容 false contentDataSourceType[]
contentDataSourceType: {
  title?: any;
  subtitle?: any;
  substance?: any;
};

FullScreenLead

import { FullScreenLead } from '@teamix/lead';

props: {
  title: string; // 标题
  prevButtonText?: string;
  nextButtonText?: string;
  prevButtonVisible?: boolean;
  nextButtonVisible?: boolean;
  prevButtonProps?: any; // 按钮接收的参数
  nextButtonProps?: any;
  onPrevButtonClick?: (e: Event) => void;
  onNextButtonClick?: (e: Event) => void;
  tabHeaderTitle?: string; // Tabs 上方的标题
  useCardTab?: boolean; // 是否启用卡片类型的 Tab
  defaultSelectId?: number; // 默认选择的 id
  dataSource: dataSourceType[];
  onSelect: (selectedId: number | string) => void;
  useLoop?: boolean; // 是否启用轮播
  speed?: number; // 轮播速度,默认 3000
  className?: string;
  stopLoopingWhenHover?: boolean; // 是否在点击 Tab 后停止轮播,默认为 true
  customContent?: any; // 自定义内容,将不展示卡片
}

dataSourceType: {
  id: number,
  tabTitle: string,
  tabDesc?: string, // 仅在 useCardTypeTab 为 true 时生效
  img: string,
  imgDesc: string | ReactNode,
}

气泡

Lead Definition

const lead = new TeamixLead({
  className: 'scoped-class', // className to wrap popover
  animate: true,             // Animate while changing highlighted element
  opacity: 0.4,              // Background opacity (0 means only popovers and without overlay)
  padding: 10,               // Distance of element from around the edges
  allowClose: true,          // Whether clicking on overlay should close or not
  overlayClickNext: false,   // Should it move to next step on overlay click
  nextBtnText: '下一步',      // Next button text for this step
  prevBtnText: '上一步',      // Previous button text for this step
  doneBtnText: '完成',        // Text on the final button
  closeBtnText: '跳过引导',    // Text on the close button for this step
  showButtons: true,          // Do not show control buttons in footer
  keyboardControl: true,      // Allow controlling through keyboard (escape to close, arrow keys to move)
  scrollIntoViewOptions: {},  // We use `scrollIntoView()` when possible, pass here the options for it if you want any
  onHighlightStarted: (Element) => {},                     // Called when element is about to be highlighted
  onHighlighted: (Element) => {},                          // Called when element is fully highlighted
  onDeselected: (Element) {},                              // Called when element has been deselected
  onReset: (Element) => {console.log('close', Element)},   // Called when overlay is about to be cleared
  onNext: (Element) => {console.log('next', Element)},     // Called when moving to next step on any step
  onPrevious: (Element) => {console.log('pre', Element)},  // Called when moving to next step on any step
});
参数名 说明 必填 类型 默认值 备注
className className to wrap popover false string null
animate Animate while changing highlighted element false boolean true
opacity Background opacity (0 means only popovers and without overlay) false number 0.4
padding Distance of element from around the edges false number 10
allowClose Whether clicking on overlay should close or not false boolean true
overlayClickNext Should it move to next step on overlay click false boolean false
nextBtnText Next button text for this step false string "Next ->"
prevBtnText Previous button text for this step false string "<- Prev"
doneBtnText Text on the final button false string "Done"
closeBtnText Text on the close button for this step false string "Close"
showButtons Do not show control buttons in footer false boolean true
keyboardControl Allow controlling through keyboard (escape to close, arrow keys to move) false boolean true
scrollIntoViewOptions We use scrollIntoView() when possible, pass here the options for it if you want any false {} {}
onHighlightStarted Called when element is about to be highlighted false func (Element) => {}
onHighlighted Called when element is fully highlighted false func (Element) => {}
onDeselected Called when element has been deselected false func (Element) => {}
onReset Called when overlay is about to be cleared false func (Element) => {}
onNext Called when moving to next step on any step false func (Element) => {}
onPrevious Called when moving to next step on any step false func (Element) => {}

Step Definition

Here are the set of options that you can pass while defining steps defineSteps or the object that you pass to highlight method:

const stepDefinition = {
  element: '#some-item',        // Query selector string or Node to be highlighted
  stageBackground: '#ffffff',   // This will override the one set in lead
  popover: {                    // There will be no popover if empty or not given
    className: 'popover-class', // className to wrap this specific step popover in addition to the general className in lead options
    img: 'https://xxxxxx.png',  // Img on the popover 
    title: 'Title',             // Title on the popover
    description: 'Description', // Body of the popover
    showButtons: false,         // Do not show control buttons in footer
    doneBtnText: 'Done',        // Text on the last button
    closeBtnText: 'Close',      // Text on the close button
    nextBtnText: 'Next',        // Next button text
    prevBtnText: 'Previous',    // Previous button text
  },
  onNext: () => {},             // Called when moving to next step from current step
  onPrevious: () => {},         // Called when moving to previous step from current step
};

For example, here is how it would look when highlighting a single element:

const lead = new TeamixLead(leadOptions);
lead.highlight(stepDefinition);

When creating a step by step guide:

const lead = new TeamixLead(leadOptions);
lead.defineSteps([
    stepDefinition1,
    stepDefinition2,
    stepDefinition3,
    stepDefinition4,
]);

API Methods

const lead = new TeamixLead(options);

// Checks if the lead is active or not
if (lead.isActivated) {
    console.log('Lead is active');
}

// In case of the steps guide, you can call below methods
lead.defineSteps([ stepDefinition1, stepDefinition2, stepDefinition3 ]);
lead.start(stepNumber = 0);  // Starts leading through the defined steps
lead.moveNext();             // Moves to next step in the steps list
lead.movePrevious();         // Moves to previous step in the steps list
lead.hasNextStep();          // Checks if there is next step to move to
lead.hasPreviousStep();      // Checks if there is previous step to move to

// Prevents the current move. Useful in `onNext` or `onPrevious` if you want to
// perform some asynchronous task and manually move to next step
lead.preventMove();

// Highlights the element using query selector or the step definition
lead.highlight(string|stepDefinition);

// Reposition the popover and highlighted element
lead.refresh();

// Resets the overlay and clears the screen
lead.reset();

// Additionally you can pass a boolean parameter
// to clear immediately and not do the animations etc
// Could be useful when you, let's say, want to run
// a different instance of lead while one was running
lead.reset(clearImmediately = false);

// Checks if there is any highlighted element
if(lead.hasHighlightedElement()) {
    console.log('There is an element highlighted');
}

// Gets the currently highlighted element on screen
// It would be an instance of `/src/core/element.js`
const activeElement = lead.getHighlightedElement();

// Gets the last highlighted element, would be an instance of `/src/core/element.js`
const lastActiveElement = lead.getLastHighlightedElement();

activeElement.getCalculatedPosition(); // Gets screen co-ordinates of the active element
activeElement.hidePopover();           // Hide the popover
activeElement.showPopover();           // Show the popover

activeElement.getNode();  // Gets the DOM Element behind this element

Note

Do not forget to add e.stopPropagation() to the click binding that triggers lead.

Demos

Look here

Readme

Keywords

none

Package Sidebar

Install

npm i @txdfe/at-lead

Weekly Downloads

1

Version

0.1.2

License

ISC

Unpacked Size

237 kB

Total Files

44

Last publish

Collaborators

  • jiangyuanzhi
  • zhzxang
  • purple-force
  • zuoqi
  • tod.zx
  • 2ehao
  • bowei.jbw
  • teamaxy
  • cyris
  • saviio