stellar-ui-v2 1.40.20 → 1.40.21

package/components/ste-pate-container/README.md

@@ -0,0 +1,149 @@
+# PageContainer 页面容器
+
+---$
+
+### 说明
+`ste-pate-container` 在不同平台的实现方式：
+
+- `MP-WEIXIN`：使用微信小程序原生 `page-container`
+- 其他平台：基于 `ste-popup` 兼容实现
+- 微信单页限制：原生 `page-container` 同一页面仅允许 1 个实例；当页面存在多个 `ste-pate-container` 时，首个实例使用原生能力，其余实例自动降级为 `ste-popup`
+
+为保持 API 一致，组件对外暴露 `page-container` 常用属性和事件。
+
+---$
+
+### 代码演示
+
+#### 基础用法
+```vue
+<template>
+	<ste-pate-container
+		:show.sync="show"
+		position="bottom"
+		:overlay="true"
+		:round="true"
+		custom-style="height: 60vh;"
+	>
+		<view class="content">内容区域</view>
+	</ste-pate-container>
+</template>
+
+<script>
+export default {
+	data() {
+		return {
+			show: false,
+		};
+	},
+};
+</script>
+```
+
+#### 方法调用
+```vue
+<template>
+	<ste-pate-container ref="pc" :show.sync="show">
+		<view>内容区域</view>
+	</ste-pate-container>
+</template>
+
+<script>
+export default {
+	data() {
+		return {
+			show: false,
+		};
+	},
+	methods: {
+		openBox() {
+			this.$refs.pc.open();
+		},
+		closeBox() {
+			this.$refs.pc.close();
+		},
+	},
+};
+</script>
+```
+
+#### 事件监听
+```vue
+<ste-pate-container
+	:show.sync="show"
+	@beforeenter="onEvent('beforeenter')"
+	@afterenter="onEvent('afterenter')"
+	@clickoverlay="onEvent('clickoverlay')"
+>
+	<view>内容区域</view>
+</ste-pate-container>
+```
+
+#### 微信专属属性
+```vue
+<ste-pate-container
+	:show.sync="show"
+	:closeOnSlideDown="true"
+	overlayStyle="background: rgba(0, 144, 255, 0.45);"
+	customStyle="height: 50vh;"
+>
+	<view>微信小程序下支持下滑关闭和自定义遮罩样式</view>
+</ste-pate-container>
+```
+
+---$
+
+### API
+
+#### Props
+
+| 属性名 | 说明 | 类型 | 默认值 | 平台支持 |
+| --- | --- | --- | --- | --- |
+| `show` | 是否显示容器 | `Boolean` | `false` | 全平台 |
+| `duration` | 动画时长，单位 ms | `Number` | `300` | 全平台 |
+| `zIndex` | 层级 | `Number/String` | `100` | 全平台 |
+| `overlay` | 是否显示遮罩 | `Boolean` | `true` | 全平台 |
+| `position` | 弹出位置：`top`/`bottom`/`right`/`center` | `String` | `bottom` | 全平台 |
+| `round` | 是否展示圆角 | `Boolean` | `false` | 全平台 |
+| `customStyle` | 容器样式 | `String` | `''` | 全平台 |
+| `safeAreaInsetBottom` | 是否适配底部安全区 | `Boolean` | `false` | 全平台（非微信为兼容实现） |
+| `closeOnSlideDown` | 是否允许下滑关闭 | `Boolean` | `false` | 仅微信小程序 |
+| `overlayStyle` | 遮罩层样式 | `String` | `''` | 仅微信小程序 |
+
+#### Events
+
+| 事件名 | 说明 | 平台支持 |
+| --- | --- | --- |
+| `beforeenter` | 进入前触发 | 全平台（非微信为兼容模拟） |
+| `enter` | 进入中触发 | 全平台（非微信为兼容模拟） |
+| `afterenter` | 进入结束触发 | 全平台 |
+| `beforeleave` | 离开前触发 | 全平台（非微信为兼容模拟） |
+| `leave` | 离开中触发 | 全平台（非微信为兼容模拟） |
+| `afterleave` | 离开结束触发 | 全平台（非微信为兼容模拟） |
+| `clickoverlay` | 点击遮罩触发 | 全平台 |
+| `update:show` | 显隐双向绑定事件 | 全平台 |
+
+#### Methods
+
+| 方法名 | 说明 | 参数 |
+| --- | --- | --- |
+| `open` | 打开容器 | - |
+| `close` | 关闭容器 | - |
+
+---$
+
+### 非微信平台兼容差异
+
+以下能力在非微信平台基于 `ste-popup` 兼容，无法完全等效原生 `page-container`：
+
+- `closeOnSlideDown`：不支持
+- `overlayStyle`：不支持
+- 原生手势与生命周期细节存在实现差异
+
+微信端多实例场景说明：
+
+- 同一页面第一个 `ste-pate-container` 使用原生 `page-container`
+- 后续实例自动降级为 `ste-popup`，避免触发 `Only one instance can exist` 报错
+
+---$
+{{fuyuwei}}

package/components/ste-pate-container/config.json

@@ -0,0 +1,5 @@
+{
+	"group": "基础组件",
+	"title": "PageContainer 页面容器",
+	"icon": "https://image.whzb.com/chain/StellarUI/组件图标/popup.png"
+}

package/components/ste-pate-container/ste-pate-container.vue

@@ -0,0 +1,220 @@
+<template>
+	<!-- #ifdef MP-WEIXIN -->
+	<page-container
+		v-if="useWxNative"
+		:show="show"
+		:duration="duration"
+		:z-index="zIndex"
+		:overlay="overlay"
+		:position="position"
+		:round="round"
+		:close-on-slide-down="closeOnSlideDown"
+		:overlay-style="overlayStyle"
+		:custom-style="customStyle"
+		:safe-area-inset-bottom="safeAreaInsetBottom"
+		@beforeenter="emitEvent('beforeenter', $event)"
+		@enter="emitEvent('enter', $event)"
+		@afterenter="emitEvent('afterenter', $event)"
+		@beforeleave="emitEvent('beforeleave', $event)"
+		@leave="emitEvent('leave', $event)"
+		@afterleave="emitEvent('afterleave', $event)"
+		@clickoverlay="onClickOverlay"
+	>
+		<slot></slot>
+	</page-container>
+
+	<ste-popup
+		v-else
+		:show.sync="innerShow"
+		:duration="duration"
+		:zIndex="zIndex"
+		:showMask="overlay"
+		:position="popupPosition"
+		:round="round"
+		:isMaskClick="overlay"
+		:showClose="false"
+		@clickMask="onClickOverlay"
+		@open-after="onPopupOpenAfter"
+	>
+		<view class="ste-pate-container-content" :class="{ 'safe-area-bottom': safeAreaInsetBottom && position === 'bottom' }" :style="customStyle">
+			<slot></slot>
+		</view>
+	</ste-popup>
+	<!-- #endif -->
+
+	<!-- #ifndef MP-WEIXIN -->
+	<ste-popup
+		:show.sync="innerShow"
+		:duration="duration"
+		:zIndex="zIndex"
+		:showMask="overlay"
+		:position="popupPosition"
+		:round="round"
+		:isMaskClick="overlay"
+		:showClose="false"
+		@clickMask="onClickOverlay"
+		@open-after="onPopupOpenAfter"
+	>
+		<view class="ste-pate-container-content" :class="{ 'safe-area-bottom': safeAreaInsetBottom && position === 'bottom' }" :style="customStyle">
+			<slot></slot>
+		</view>
+	</ste-popup>
+	<!-- #endif -->
+</template>
+
+<script>
+/**
+ * ste-pate-container 页面容器
+ * @description 微信小程序下使用原生 page-container，其他平台使用 ste-popup 兼容实现
+ * @property {Boolean} show 是否显示容器
+ * @property {Number} duration 动画时长，单位 ms
+ * @property {Number} zIndex 层级
+ * @property {Boolean} overlay 是否显示遮罩
+ * @property {String} position 弹出位置，top/bottom/right/center
+ * @property {Boolean} round 是否展示圆角
+ * @property {Boolean} closeOnSlideDown 是否允许下滑关闭（仅微信小程序）
+ * @property {String} overlayStyle 遮罩层样式（仅微信小程序）
+ * @property {String} customStyle 容器样式
+ * @property {Boolean} safeAreaInsetBottom 是否适配底部安全区
+ */
+export default {
+	group: '基础组件',
+	title: 'PageContainer 页面容器',
+	name: 'ste-pate-container',
+	props: {
+		show: { type: [Boolean, null], default: false },
+		duration: { type: [Number, null], default: 300 },
+		zIndex: { type: [Number, String, null], default: 100 },
+		overlay: { type: [Boolean, null], default: true },
+		position: {
+			type: [String, null],
+			default: 'bottom',
+			validator(value) {
+				return ['top', 'bottom', 'right', 'center'].includes(value);
+			},
+		},
+		round: { type: [Boolean, null], default: false },
+		closeOnSlideDown: { type: [Boolean, null], default: false },
+		overlayStyle: { type: [String, null], default: '' },
+		customStyle: { type: [String, null], default: '' },
+		safeAreaInsetBottom: { type: [Boolean, null], default: false },
+	},
+	data() {
+		return {
+			innerShow: this.show,
+			leaveTimer: null,
+			useWxNative: false,
+		};
+	},
+	computed: {
+		popupPosition() {
+			if (['top', 'bottom', 'right', 'center'].includes(this.position)) {
+				return this.position;
+			}
+			return 'bottom';
+		},
+	},
+	watch: {
+		show(newVal) {
+			if (!this.useWxNative) {
+				if (this.innerShow !== newVal) {
+					this.innerShow = newVal;
+				}
+				this.triggerTransition(newVal);
+			}
+		},
+		innerShow(newVal) {
+			if (!this.useWxNative && newVal !== this.show) {
+				this.$emit('update:show', newVal);
+			}
+		},
+	},
+	beforeDestroy() {
+		this.clearTimers();
+		this.releaseWxNativeOwner();
+	},
+	created() {
+		this.initMode();
+		if (!this.useWxNative && this.show) {
+			this.triggerTransition(true);
+		}
+	},
+	methods: {
+		getGlobalScope() {
+			if (typeof globalThis !== 'undefined') return globalThis;
+			if (typeof global !== 'undefined') return global;
+			return {};
+		},
+		initMode() {
+			// #ifdef MP-WEIXIN
+			const scope = this.getGlobalScope();
+			if (!scope.__stePateContainerOwnerUid) {
+				scope.__stePateContainerOwnerUid = this._uid;
+				this.useWxNative = true;
+				return;
+			}
+			this.useWxNative = scope.__stePateContainerOwnerUid === this._uid;
+			// #endif
+			// #ifndef MP-WEIXIN
+			this.useWxNative = false;
+			// #endif
+		},
+		releaseWxNativeOwner() {
+			// #ifdef MP-WEIXIN
+			const scope = this.getGlobalScope();
+			if (scope.__stePateContainerOwnerUid === this._uid) {
+				scope.__stePateContainerOwnerUid = null;
+			}
+			// #endif
+		},
+		emitEvent(eventName, e) {
+			this.$emit(eventName, e);
+		},
+		onClickOverlay(e) {
+			this.$emit('clickoverlay', e);
+		},
+		onPopupOpenAfter(e) {
+			this.$emit('afterenter', e);
+		},
+		open() {
+			this.$emit('update:show', true);
+		},
+		close() {
+			this.$emit('update:show', false);
+		},
+		clearTimers() {
+			if (this.leaveTimer) {
+				clearTimeout(this.leaveTimer);
+				this.leaveTimer = null;
+			}
+		},
+		triggerTransition(show) {
+			this.clearTimers();
+			if (show) {
+				this.$emit('beforeenter');
+				this.$emit('enter');
+				return;
+			}
+			this.$emit('beforeleave');
+			this.$emit('leave');
+			this.leaveTimer = setTimeout(() => {
+				this.$emit('afterleave');
+				this.leaveTimer = null;
+			}, this.duration);
+		},
+	},
+};
+</script>
+
+<style lang="scss" scoped>
+.ste-pate-container-content {
+	width: 100%;
+	height: 100%;
+}
+
+.safe-area-bottom {
+	padding-bottom: constant(safe-area-inset-bottom);
+	padding-bottom: env(safe-area-inset-bottom);
+	box-sizing: border-box;
+}
+</style>

package/components/ste-popup/README.md

@@ -112,22 +112,22 @@ export default {
 ### API
 #### 组件属性(Props)
 
-| 属性名		| 说明									| 类型				| 默认值		| 可选值							| 支持版本	|
-| ---			| ---									| ---				| ---		| ---							| ---		|
-| `show`		| 是否显示弹出层,使用`sync`修饰符来双向绑定	| `Boolean`			| `false`	| -								| -			|
-| `backGround`	| 内容容器的背景色						| `String`			| `#ffffff`	| -								| -			|
-| `showMask`	| 是否显示遮罩							| `Boolean`			| `true`	| -								| -			|
-| `isMaskClick`	| 是否可以点击遮罩层关闭					| `Boolean`			| `true`	| -								| -			|
-| `width`		| 内容区宽度								| `Number/String`	| `auto`	| -								| -			|
-| `height`		| 内容区高度								| `Number/String`	| `auto`	| -								| -			|
-| `position`	| 弹出位置								| `String`			| `center`	| `top` `bottom` `left` `right`	| -			|
-| `round`		| 是否圆角								| `Boolean`			| `false`	| -								| -			|
-| `showClose`	| 是否右上角显示关闭图标					| `Boolean`			| `true`	| -								| -			|
-| `offsetX`		| 根据弹出位置，设置X轴偏移量，单位px		| `Number/String`	| `0`		| -								| -			|
-| `offsetY`		| 根据弹出位置，设置Y轴偏移量，单位px		| `Number/String`	| `0`		| -								| -			|
-| `duration`	| 动画持续时间							| `Number`			| `200`		| -								| -			|
-| `zIndex`		| 弹窗层级z-index						| `Number`			| `1000`	| -								| -			|
-| `keepContent`	| 隐藏后是否不销毁弹窗内容元素				| `Boolean`			| `true`	| -								| `v1.10.1`	|
+| 属性名		| 说明									| 类型				| 默认值		| 可选值							| 支持版本	|
+| ---			| ---									| ---				| ---		| ---							| ---		|
+| `show`		| 是否显示弹出层,使用`sync`修饰符来双向绑定	| `Boolean`			| `false`	| -								| -			|
+| `backGround`	| 内容容器的背景色						| `String`			| `#ffffff`	| -								| -			|
+| `showMask`	| 是否显示遮罩							| `Boolean`			| `true`	| -								| -			|
+| `isMaskClick`	| 是否可以点击遮罩层关闭					| `Boolean`			| `true`	| -								| -			|
+| `width`		| 内容区宽度								| `Number/String`	| `auto`	| -								| -			|
+| `height`		| 内容区高度								| `Number/String`	| `auto`	| -								| -			|
+| `position`	| 弹出位置								| `String`			| `center`	| `top` `bottom` `left` `right`	| -			|
+| `round`		| 是否圆角								| `Boolean`			| `false`	| -								| -			|
+| `showClose`	| 是否右上角显示关闭图标					| `Boolean`			| `true`	| -								| -			|
+| `offsetX`		| 根据弹出位置，设置X轴偏移量，单位px		| `Number/String`	| `0`		| -								| -			|
+| `offsetY`		| 根据弹出位置，设置Y轴偏移量，单位px		| `Number/String`	| `0`		| -								| -			|
+| `duration`	| 动画持续时间							| `Number`			| `200`		| -								| -			|
+| `zIndex`		| 弹窗层级z-index						| `Number`			| `1000`	| -								| -			|
+| `keepContent`	| 隐藏后是否不销毁弹窗内容元素				| `Boolean`			| `true`	| -								| `v1.10.1`	|
 | `appendToBody`| 是否将弹窗挂载到body下（仅H5、APP有效）	| `Boolean`			| `false`	| -								| `v1.40.13`|
 
 #### 组件事件(Events)