stellar-ui-v2 1.35.3

package/components/ste-tour/README.md

@@ -0,0 +1,194 @@
+# Tour 指引
+
+> 用于创建一个带有步骤的指引
+
+---$
+
+## 使用示例
+- 示例代码中用到的公共CSS样式
+```css
+.button-box {
+	display: inline-block;
+	padding: 20rpx;
+}
+```
+
+
+### 基础用法
+- 属性`show`用于控制显示隐藏
+- 属性`steps`用于设置步骤内容，数组形式，数组中每个元素是一个对象，对象包含以下属性
+	- 对象属性`message`：步骤内容，**必须**
+	- 对象属性`target`：步骤内容对应的元素ID，**必须**
+	- 对象属性`title`：步骤标题
+	- 对象属性`position`：步骤位置
+		- 若`position`属性不设置，则自动计算合适的位置
+		- 可选值`top`、`bottom`、`top-start`、`top-center`、`top-end`、`bottom-start`、`bottom-center`、`bottom-end`
+
+```html
+<template>
+	<view class="title">基础用法</view>
+	<view id="button" class="button-box">
+		<ste-button @click="show = true">基础提示</ste-button>
+	</view>
+	<ste-tour :show.sync="show" :steps="steps"></ste-tour>
+</template>
+<script>
+export default {
+	data(){
+		return{
+			show:false,
+			steps: [{ message: '点这里', target: 'button' }],
+		}
+	},
+};
+</script>
+```
+### 位置偏移量
+- 属性`offset`用于设置位置偏移量，数组形式，数组中两个元素分别表示横纵方向上的偏移量
+
+```html
+<template>
+	<view id="button-2" class="button-box">
+		<ste-button @click="show2 = true">描述位置偏移</ste-button>
+	</view>
+	<ste-tour :show.sync="show2" :steps="steps2" :offset="[20, 10]"></ste-tour>
+</template>
+<script>
+export default {
+	data(){
+		return{
+			show2: false,
+			steps2: [{ message: '点这里', target: 'button-2' }],
+		}
+	},
+};
+</script>
+```
+- 默认插槽可以自定义描述内容，插槽参数`item`为当前步骤信息
+- 属性`messageBg`可以将默认背景改为透明，然后通过插槽自定义背景样式，实现自定义描述内容。
+- 如果需要内容区域点击不关闭提示，可使用`@click.stop`阻止内容区域点击冒泡
+```html
+<template>
+	<view
+		id="button-6"
+		style="
+			border: 1px solid #ddd;
+			width: 120rpx;
+			height: 120rpx;
+			line-height: 120rpx;
+			border-radius: 60rpx;
+			text-align: center;
+			margin-left: 60rpx;
+		"
+		@click="show6 = true"
+	>
+		插槽
+	</view>
+	<ste-tour :show.sync="show6" :steps="steps6" :offset="[-20, -30]" messageBg="transparent" radius="60">
+		<image
+			src="https://image.whzb.com/chain/StellarUI/component-icons/tour.png"
+			mode="widthFix"
+			style="width: 630rpx"
+		></image>
+	</ste-tour>
+</template>
+<script>
+export default {
+	data(){
+		return{
+			show6: false,
+			steps6: [{ message: '点这里', target: 'button-2' }],
+		}
+	},
+};
+</script>
+```
+
+### 多步骤，显示标题栏
+- 属性`offset`用于设置位置偏移量，数组形式，数组中两个元素分别表示横纵方向上的偏移量
+
+```html
+<template>
+	<ste-button @click="show3 = true">多步骤带标题</ste-button>
+	<view style="display: inline-block; padding: 6rpx 20rpx">
+		<view id="step-1" class="button-box">步骤1</view>
+		<view id="step-2" class="button-box">步骤2</view>
+		<view id="step-3" class="button-box">步骤3</view>
+	</view>
+	<ste-tour showTitleBar :show.sync="show3" :steps="steps3"></ste-tour>
+</template>
+<script>
+export default {
+	data(){
+		return{
+			show3: false,
+			steps3: [
+				{ title: '步骤1', message: '先点这里', target: 'step-1' },
+				{ title: '步骤2', message: '再点这里', target: 'step-2' },
+				{ title: '步骤3', message: '然后点这里', target: 'step-3' },
+			],
+		}
+	},
+};
+</script>
+```
+### 不显示背景蒙层
+- 属性`mask`用于设置是否显示背景蒙层，默认显示
+
+```html
+<template>
+	<view id="button-4" class="button-box">
+		<ste-button @click="show4 = true">不显示背景蒙层</ste-button>
+	</view>
+	<ste-tour :show.sync="show4" :steps="steps4" :mask="false"></ste-tour>
+</template>
+<script>
+export default {
+	data(){
+		return{
+			show4: false,
+			steps4: [{ message: '点这里', target: 'button-4' }],
+		}
+	},
+};
+</script>
+```
+
+
+
+---$
+### API
+#### Props
+背景之外的颜色属性只支持`16进制`、`RGB`、`RGBA`格式
+| 属性名				| 说明																	| 类型								| 默认值						| 可选值	| 支持版本	|
+| -----					| -----																| -----							| -----						| -----	| -----		|
+| `show`				|	是否显示，支持`.sync`双向绑定					| `Boolean`					| `false`					| -			| -				|
+| `current`			|	当前步骤，多个步骤时有效								| `Number`					| `0`							| -			| -				|
+| `steps`				|	步骤数组，`Step`对象描述见基础用法说明	| `Array<Step>`			| `[]`						| -			| -				|
+| `offset`			|	位置偏移量，格式为：[x, y]						| `[Number, Number]`| `[0, 0]`				| -			| -				|
+| `showTitleBar`|	是否显示标题栏												| `Boolean`					| `false`					| -			| -				|
+| `showFooter`	|	是否显示底部按钮栏（仅多步骤时生效）		| `Boolean`					| `true`					| -			| -				|
+| `mask`				|	是否显示遮罩层												| `Boolean`					| `true`					| -			| -				|
+| `maskColse`		|	是否点击遮罩层关闭										| `Boolean`					| `true`					| -			| -				|
+| `showPrevStep`|	是否显示上一步按钮										| `Boolean`					| `true`					| -			| -				|
+| `background`	|	遮罩层背景色													| `String`					| `rgba(0,0,0,.5)`| -			| -				|
+| `radius`			|	提示框圆角，单位rpx										| `Number`,`String`	| `18`						| -			| -				|
+| `messageBg`		|	提示框背景色													| `String`					| `#FFF`					| -			| -				|
+| `messageColor`|	提示框文字颜色												| `String`					| `#000`					| -			| -				|
+| `nextStepTxt`	|	下一步按钮文字												| `String`					| `下一步`					| -			| -				|
+| `prevStepTxt`	|	上一步按钮文字												| `String`					| `上一步`					| -			| -				|
+| `completeTxt`	|	完成按钮文字													| `String`					| `完成`						| -			| -				|
+
+
+
+#### Events
+
+| 事件名	| 说明						| 事件参数		| 支持版本	|
+| ---			| ---						| ---				| ---			|
+| `change`| 步骤切换时触发	| `current`	| -				|
+| `close`	| 关闭指引时触发	| -					| -				|
+
+
+
+---$
+{{xuyajun}}

package/components/ste-tour/ste-tour.vue

@@ -0,0 +1,355 @@
+<template>
+	<view
+		class="ste-tour-root"
+		@touchmove.stop="true"
+		:class="{ show: dataShow }"
+		:style="[cmpRootStyle]"
+		@click="clickRoot"
+	>
+		<view class="ste-tour-view" :style="[dataStyle]"></view>
+		<view class="ste-tour-message" :style="[messageStyle]">
+			<view class="message-arrows" :style="[arrowsStyle]" />
+			<view class="message-content">
+				<view class="message-head" v-if="showTitleBar" @click.stop="true">
+					<view class="head-title">{{ cmpStep.title }}</view>
+					<view class="head-close" @click="close">
+						<ste-icon code="&#xe67b;" size="30" />
+					</view>
+				</view>
+				<view class="message-content-text">
+					<slot>
+						<view class="message-text" @click.stop="true">
+							{{ cmpStep.message }}
+						</view>
+					</slot>
+				</view>
+				<view class="message-step-footer" @click.stop="true" v-if="cmpShowFooter">
+					<view class="step-num">{{ dataCurrent + 1 }}/{{ steps.length }}</view>
+					<view class="step-btns">
+						<ste-button
+							:round="false"
+							background="#fff"
+							borderColor="#0090FF"
+							color="#0090FF"
+							style="margin-right: 12rpx"
+							mode="100"
+							@click="onUp"
+							v-if="cmpShowPrevStep"
+							:rootStyle="{ padding: '0 10px' }"
+						>
+							{{ prevStepTxt }}
+						</ste-button>
+						<ste-button :round="false" :rootStyle="{ padding: '0 10px' }" mode="100" @click="onNext">
+							{{ dataCurrent < steps.length - 1 ? nextStepTxt : completeTxt }}
+						</ste-button>
+					</view>
+				</view>
+			</view>
+		</view>
+	</view>
+</template>
+
+<script>
+import utils from '../../utils/utils.js';
+/**
+ * ste-tour 指引
+ * @description 指引组件
+ * @tutorial https://stellar-ui.intecloud.com.cn/pc/index/index?name=ste-tour
+ * @property {Boolean} show 是否显示
+ * @property {Number} current 当前步骤，多个步骤时有效
+ * @property {Array} steps 步骤数组，格式为：[{title: '', message: '', target:'el-id'}]
+ * @property {Array} offset 位置偏移量，格式为：[x, y]
+ * @property {Boolean} showTitleBar 是否显示标题栏
+ * @property {Boolean} showFooter 是否显示底部按钮栏（仅多步骤时生效）
+ * @property {Boolean} mask 是否显示遮罩层
+ * @property {Boolean} maskColse 是否点击遮罩层关闭
+ * @property {Boolean} showPrevStep 是否显示上一步按钮
+ * @property {String} background 遮罩层背景色
+ * @property {Number|String} radius 提示框圆角，单位rpx，默认18
+ * @property {String} messageBg 提示框背景色
+ * @property {String} messageColor 提示框文字颜色
+ * @property {String} nextStepTxt	下一步按钮文字
+ * @property {String} prevStepTxt 上一步按钮文字
+ * @property {String} completeTxt 完成按钮文字
+ * @event {Function} change 步骤切换时触发
+ */
+export default {
+	group: '展示组件',
+	title: 'Tour 指引',
+	name: 'ste-tour',
+	props: {
+		show: { type: [Boolean, null], default: () => false },
+		current: { type: [Number, null], default: () => 0 },
+		steps: { type: [Array, null], default: () => [] },
+		offset: { type: [Array, null], default: () => [0, 0] },
+		showTitleBar: { type: [Boolean, null], default: () => false },
+		showFooter: { type: [Boolean, null], default: () => true },
+		mask: { type: [Boolean, null], default: () => true },
+		maskColse: { type: [Boolean, null], default: () => true },
+		showPrevStep: { type: [Boolean, null], default: () => true },
+		background: { type: [String, null], default: () => 'rgba(0,0,0,.5)' },
+		radius: { type: [Number, String, null], default: () => 18 },
+		messageBg: { type: [String, null], default: () => '#fff' },
+		messageColor: { type: [String, null], default: () => '#000' },
+		nextStepTxt: { type: [String, null], default: () => '下一步' },
+		prevStepTxt: { type: [String, null], default: () => '上一步' },
+		completeTxt: { type: [String, null], default: () => '完成' },
+	},
+	data() {
+		return {
+			dataShow: false,
+			dataCurrent: 0,
+			stepTimeout: null,
+			dataStyle: {},
+			messageStyle: {},
+			arrowsStyle: {},
+		};
+	},
+	computed: {
+		cmpRootStyle() {
+			return {
+				'--ste-tour-radius': utils.formatPx(this.radius),
+				'--ste-tour-mask': this.mask ? `0 0 0 250vh ${this.background}` : 'none',
+				'--ste-tour-message-shadow': this.mask ? 'none' : `0 0 ${utils.formatPx(30)} 0 #ccc`,
+				'--ste-tour-message-bg': this.messageBg,
+				'--ste-tour-message-color': this.messageColor,
+			};
+		},
+		cmpStep() {
+			return this.steps[this.dataCurrent];
+		},
+		windowSize() {
+			return {
+				vw: utils.System.getWindowWidth(),
+				vh: utils.System.getWindowHeight(),
+			};
+		},
+		cmpShowPrevStep() {
+			return this.showPrevStep && this.dataCurrent > 0;
+		},
+		cmpShowFooter() {
+			return this.showFooter && this.steps.length > 1;
+		},
+	},
+	watch: {
+		show: {
+			handler(val) {
+				this.dataShow = val;
+				if (val) this.dataCurrent = 0;
+			},
+			immediate: true,
+		},
+		current: {
+			handler(val) {
+				if (val >= 0 && val <= this.steps.length - 1) this.dataCurrent = val;
+			},
+			immediate: true,
+		},
+		dataShow: {
+			handler(val) {
+				if (val) this.showTour();
+				else this.closeTour();
+			},
+			immediate: true,
+		},
+		dataCurrent: {
+			handler(val) {
+				if (this.dataShow) this.showTour();
+				else this.closeTour();
+			},
+			immediate: true,
+		},
+	},
+	methods: {
+		clickRoot() {
+			if (!this.maskColse) return;
+			this.close();
+		},
+		close() {
+			this.dataShow = false;
+			this.$emit('update:show', false);
+			this.$emit('close');
+		},
+		showTour() {
+			clearTimeout(this.stepTimeout);
+			this.stepTimeout = setTimeout(() => {
+				const step = this.cmpStep;
+				if (!step) return;
+				utils.querySelector(`#${step.target}`, this.$parent).then((el) => {
+					if (!el) {
+						console.error(`未找到ID为${step.target}的元素`);
+						return;
+					}
+					const { top, left, bottom, right, width, height } = el;
+
+					this.dataStyle = {
+						top: `${el.top}px`,
+						left: `${el.left}px`,
+						width: `${el.width}px`,
+						height: `${el.height}px`,
+						display: 'block',
+					};
+
+					let [y, x] = step.position?.split('-') || [];
+					const { vw, vh } = this.windowSize;
+					const _bottom = vh - bottom;
+					const _right = vw - right;
+					if (!y) {
+						if (top > _bottom) {
+							y = 'top';
+						} else {
+							y = 'bottom';
+						}
+					}
+					if (!x) {
+						if (_right > 30 && _right > left) {
+							x = 'start';
+						} else if (left > 30) {
+							x = 'end';
+						} else {
+							x = 'center';
+						}
+					}
+					const [_x = 0, _y = 0] = this.offset;
+					const arrowsWidth = 18;
+					const messageStyle = { display: 'block' };
+					const arrowsStyle = {};
+
+					switch (y) {
+						case 'top':
+							messageStyle.bottom = `${_bottom + height + _y + (arrowsWidth - 5)}px`;
+							arrowsStyle.bottom = `-${arrowsWidth}px`;
+							arrowsStyle.borderColor = `${this.messageBg} transparent transparent`;
+
+							break;
+						case 'bottom':
+							messageStyle.top = `${bottom + _y + (arrowsWidth - 5)}px`;
+							arrowsStyle.top = `-${arrowsWidth}px`;
+							break;
+					}
+					switch (x) {
+						case 'start':
+							messageStyle.left = `${left + _x}px`;
+							arrowsStyle.left = `${arrowsWidth}px`;
+							break;
+						case 'end':
+							messageStyle.right = `${_right + _x}px`;
+							arrowsStyle.right = `${arrowsWidth}px`;
+							break;
+						case 'center':
+							messageStyle.left = '50%';
+							messageStyle.transform = `translateX(calc(-50% + ${_x}px))`;
+							arrowsStyle.left = '50%';
+							arrowsStyle.transform = 'translateX(-50%)';
+					}
+					this.messageStyle = messageStyle;
+					this.arrowsStyle = arrowsStyle;
+				});
+			}, 50);
+		},
+		closeTour() {
+			this.dataStyle = {};
+			this.messageStyle = {};
+			this.arrowsStyle = {};
+		},
+		onNext() {
+			if (this.dataCurrent < this.steps.length - 1) {
+				this.dataCurrent += 1;
+				this.$emit('update:current', this.dataCurrent);
+				this.$emit('change', this.dataCurrent);
+			} else {
+				this.close();
+			}
+		},
+		onUp() {
+			if (this.dataCurrent > 0) {
+				this.dataCurrent -= 1;
+				this.$emit('update:current', this.dataCurrent);
+				this.$emit('change', this.dataCurrent);
+			}
+		},
+	},
+};
+</script>
+
+<style scoped lang="scss">
+.ste-tour-root {
+	position: fixed;
+	z-index: 1001;
+	width: 100vw;
+	height: 100vh;
+	top: 0;
+	left: 0;
+	overflow: hidden;
+	display: none;
+	&.show {
+		display: block;
+	}
+	.ste-tour-view {
+		border-radius: var(--ste-tour-radius);
+		position: fixed;
+		z-index: 1001;
+		box-shadow: var(--ste-tour-mask);
+		display: none;
+	}
+	.ste-tour-message {
+		background-color: var(--ste-tour-message-bg);
+		position: fixed;
+		z-index: 1002;
+		border-radius: var(--ste-tour-radius);
+		display: none;
+		box-shadow: var(--ste-tour-message-shadow);
+		.message-arrows {
+			position: absolute;
+			width: 0;
+			height: 0;
+			border-width: 20rpx;
+			border-style: solid;
+			border-color: transparent transparent var(--ste-tour-message-bg);
+		}
+		.message-content {
+			color: var(--ste-tour-message-color);
+			font-size: 24rpx;
+
+			.message-head {
+				display: flex;
+				justify-content: space-between;
+				align-items: center;
+				min-width: 360rpx;
+				padding: 20rpx 24rpx;
+				.head-title {
+					height: 60rpx;
+					line-height: 60rpx;
+					font-size: 30rpx;
+					margin-right: 30rpx;
+				}
+
+				.head-close {
+					width: 60rpx;
+					height: 60rpx;
+					padding: 15rpx;
+					line-height: 30rpx;
+				}
+			}
+			.message-content-text {
+				.message-text {
+					padding: 20rpx 24rpx;
+				}
+			}
+
+			.message-step-footer {
+				display: flex;
+				justify-content: space-between;
+				align-items: center;
+				padding: 20rpx 24rpx;
+				min-width: 360rpx;
+				.step-num {
+					font-size: 24rpx;
+					color: var(--ste-tour-message-color);
+					margin-right: 30rpx;
+				}
+			}
+		}
+	}
+}
+</style>