GuideTour

2023-04-28 21:00

Mini-program developers can use the GuideTour component to create a mask to guide users through a series of steps or highlight key features on a mini-program page. This topic covers the attribute details and sample code for the component.

Attributes

Attribute	Data type	Default	Description
className	String	N/A	The class name for the GuideTour component.
style	String	N/A	The style for the GuideTour component.
current	Number	N/A	The index of the current step in the guide.
defaultCurrent	Number	`0`	The index of the initial step when the guide is activated.
items	Array<GuideTourItem>	N/A	The steps in the tour.
maskClassName	String	N/A	The class name for the mask layer.
maskStyle	String	N/A	The style for the mask layer.
swiperable	Boolean	`false`	Whether to enable swipe gestures for navigation.
visible	Boolean	`false`	Whether the tour is visible.
jumpText	String	`'跳过'`	The label for the button that is used to skip the tour. Note: The default label is in Chinese. Specify this attribute to display text in another language.
prevStepText	String	`'上一步'`	The label for the button that is used to go back to the previous step. Note: The default label is in Chinese. Specify this attribute to display text in another language.
nextStepText	String	`'下一步'`	The label for the button that is used to proceed to the next step. Note: The default label is in Chinese. Specify this attribute to display text in another language.
gotItText	String	`'知道了'`	The label for the button that indicates completion or understanding. Note: The default label is in Chinese. Specify this attribute to display text in another language.
onCancel	EventHandle	N/A	The callback function that is triggered when the tour is closed.
onChange	EventHandle	N/A	The callback function that is triggered when the current step is changed.

GuideTourItem

Attribute	Data type	Default	Description
left	Number	N/A	The distance from the left edge in pixels.
top	Number	N/A	The distance from the top edge in pixels.
imageMode	String	N/A	The mode of the image. For more information, refer to the mode of the basic image component.
imageStyle	String	N/A	The inline style for the image.
imageUrl	String	N/A	The URL of the image to display for the step.

Sample code

The following sample code shows how to create different types of guide tours:

.axml

copy
<ant-guide-tour
  items="{{ [list[0]] }}"
  visible="{{ baseVisible }}"
  onCancel="closeTour"
  onChange="onChange" />
<ant-guide-tour
  items="{{ list }}"
  visible="{{ moreVisible }}"
  onCancel="closeTour"
  onChange="onChange" />
<ant-guide-tour
  items="{{ list }}"
  visible="{{ swiperVisible }}"
  onCancel="closeTour"
  onChange="onChange"
  swiperable="{{ true }}" />
<ant-guide-tour
  items="{{ list }}"
  current="{{ current }}"
  visible="{{ controlledVisible }}"
  onCancel="closeTour"
  onChange="onChangeControlled" />
<ant-guide-tour
  items="{{ list }}"
  visible="{{ slotVisible }}"
  onCancel="closeTour"
  onChange="onChange">
  <view
    class="step-box"
    slot="step"
    slot-scope="props">
    step-{{ props.index }}
  </view>
</ant-guide-tour>

<ant-container
  title="General"
  className="list">
  <ant-button
    onTap="openTour"
    data-field="baseVisible">
    Single image
  </ant-button>
  <ant-button
    onTap="openTour"
    data-field="moreVisible">
    Images with button navigation
  </ant-button>
  <ant-button
    onTap="openTour"
    data-field="swiperVisible">
    Images with gesture navigation
  </ant-button>
  <ant-button
    onTap="openTour"
    data-field="controlledVisible">
    Control mode
  </ant-button>
</ant-container>

<ant-container
  title="Slot"
  className="list">
  <ant-button
    onTap="openTour"
    data-field="slotVisible">
    Start
  </ant-button>
</ant-container>

.js

copy
Page({
    data: {
        baseVisible: false,
        moreVisible: false,
        swiperVisible: false,
        slotVisible: false,
        controlledVisible: false,
        current: 0,
        list: [
            {
                left: 20,
                top: 80,
                imageUrl: 'https://gw.alipayobjects.com/zos/antfincdn/IV3MGP1qL/bianzu%25252013.png',
                imageMode: 'widthFix',
            },
            {
                left: 20,
                top: 160,
                imageUrl: 'https://gw.alipayobjects.com/zos/antfincdn/%26B6d3lBJn/bianzu%25252020.png',
            },
            {
                left: 20,
                top: 220,
                imageUrl: 'https://gw.alipayobjects.com/zos/antfincdn/lwVOkCcwb/bianzu%25252021.png',
            },
        ],
    },
    onChange(index) {
        console.log('index', index);
    },
    onChangeControlled(index) {
        this.setData({ current: index });
    },
    openTour(e) {
        this.setData({
            [e.target.dataset.field]: true,
            current: 0,
        });
    },
    closeTour() {
        this.setData({
            baseVisible: false,
            moreVisible: false,
            swiperVisible: false,
            slotVisible: false,
            controlledVisible: false,
        });
    },
});

.acss

copy
.step-box {
  background-color: #fff;
  width: 200px;
  height: 200px;
  line-height: 200px;
  text-align: center;
}
.list button {
  margin-bottom: 8px;
}

.json

copy
{
  "defaultTitle": "GuideTour",
  "usingComponents": {
    "ant-button": "antd-mini/es/Button/index",
    "ant-container": "antd-mini/es/Container/index",
    "ant-guide-tour": "antd-mini/es/GuideTour/index"
  }
}