stellar-ui-v2 1.35.3

package/components/ste-tree/README.md

@@ -0,0 +1,240 @@
+# Tree 树形控件
+- 树形控件
+
+---$
+
+## 使用示例
+- 以下示例中，但凡使用到`options`属性的，都使用以下数据
+```json
+[
+	{
+		title: '标题1',
+		value: '1',
+		children: [
+			{
+				title: '标题1-1',
+				value: '1-1',
+				children: [
+					{ title: '标题-1-1', value: '1-1-1' },
+					{ title: '标题1-1-2', value: '1-1-2' },
+				],
+			},
+			{
+				title: '标题1-2',
+				value: '1-2',
+				children: [
+					{ title: '标题1-2-1', value: '1-2-1' },
+					{
+						title: '标题1-2-2',
+						value: '1-2-2',
+						children: [{ title: '标题1-2-2-1', value: '1-2-2-1' }],
+					},
+				],
+			},
+		],
+	},
+	{
+		title: '标题2',
+		value: '2',
+		children: [{ title: '标题2-1', value: '2-1' }],
+	},
+]
+		
+```
+
+
+### 基础用法
+- 属性`options`用于设置折叠面板的选项，类型为树形结构
+	- 对象属性
+		- `title`：标题展示文本，(可通过`titleKey`指定)
+		- `value`：唯一标识，(可通过`valueKey`指定)
+		- `children`：子节点数组，(可通过`childrenKey`指定)
+		- `hasChildren`：是否有`children`，懒加载没有`children`属性时，需要将该属性设置为`true`
+
+- 事件`open`用于监听打开节点
+- 事件`close`用于监听关闭节点
+```html
+<template>
+	<ste-tree :options="options" @open="onOpen" @close="onClose"></ste-tree>
+</template>
+<script>
+export default {
+	methods: {
+		onOpen(node) {
+			uni.showToast({ title: `打开节点：${node.title}`, icon: 'none' });
+		},
+		onClose(node) {
+			uni.showToast({ title: `关闭节点：${node.title}`, icon: 'none' });
+		},
+	},
+};
+</script>
+```
+### 默认展开节点，打开/关闭指定节点
+
+- 属性`openNodes`用于设置默认展开的节点，默认展开的节点数组（数组内容为节点value值，请在组件加载前设置，加载后若要展开请调用open方法）
+- 方法`open`用于打开指定节点
+- 方法`close`用于关闭指定节点
+```html
+<template>
+	<ste-tree ref="accordion" :options="options" :openNodes="['1-2-2']"></ste-tree>
+	<ste-button @click="openNode" mode="100">打开标题2</ste-button>
+	<ste-button @click="closeNode" mode="100">关闭标题2</ste-button>
+</template>
+<script>
+export default {
+	methods: {
+		openNode() {
+			this.$refs.accordion.open('2');
+		},
+		closeNode() {
+			this.$refs.accordion.close('2');
+		},
+	},
+};
+</script>
+```
+### 节点搜索
+
+- 属性`searchTitle`用于搜索节点
+- 也可以使用方法`search(keyword)`进行搜索
+
+```html
+<template>
+	<ste-input placeholder="请输入标题内容" v-model="searchTitle"></ste-input>
+	<ste-tree :options="options" :searchTitle="searchTitle"></ste-tree>
+</template>
+<script>
+export default {
+	data(){
+		return {
+			searchTitle: '',
+		}
+	}
+};
+</script>
+```
+### 非手风琴模式(展开时不关闭兄弟节点)
+
+- 属性`accordion`用于设置是否为手风琴模式，默认为`true`
+
+```html
+<template>
+	<ste-tree :options="options" :accordion="false"></ste-tree>
+</template>
+```
+
+### 懒加载
+
+- `options`中对象没有子集`children`时，将属性`hasChildren`设置为`true`可展示`open`按钮
+- 事件`beforeOpen`用于监听用户点击`open`时，打开指定节点前触发
+	- 参数一：当前`node`对象
+	- 参数二：`suspend`函数，用于等待后续操作
+	- 参数三：`next`函数，继续执行后续代码，可接收一个对象数组，该数组会替换当前节点的`children`
+	- 参数四：`stop`函数，阻止后续代码执行
+
+```html
+<template>
+	<ste-tree :options="lazyLoadOptions" @beforeOpen="beforeOpen"></ste-tree>
+</template>
+<script>
+export default {
+	data(){
+		return{
+			lazyLoadOptions: [
+				{ title: '标题1', value: '1', hasChildren: true },
+				{ title: '标题2', value: '2', hasChildren: true },
+			],
+		}
+	},
+	methods: {
+		beforeOpen(node, suspend, next, stop) {
+			// 开启等待
+			suspend();
+			setTimeout(() => {
+				// 继续后续操作，并将结果传递给next
+				next([
+					{ title: `${node.title}-1`, value: `${node.value}-1` },
+					{ title: `${node.title}-2`, value: `${node.value}-2`, hasChildren: true },
+				]);
+			}, 2000);
+		},
+	}
+}
+</script>
+```
+
+### 自定义内容
+
+- 插槽`default`用于自定义节点标题
+- 插槽`open`用于自定义节点展开按钮图标，大小不得超过30rpx
+- 插槽`loading`用于自定义懒加载动画
+```html
+<template>
+	<ste-tree :options="options">
+		<template v-slot="{ node, depth }">
+			<view class="item-title">
+				<image
+					v-if="depth === 0"
+					class="title-image"
+					src="https://image.whzb.com/chain/StellarUI/component-icons/ste-tree.png"
+				></image>
+				<image
+					v-if="depth === 1"
+					class="title-image"
+					src="https://image.whzb.com/chain/StellarUI/component-icons/ste-tree-children.png"
+				></image>
+				<view class="item-text">{{ node.title }}</view>
+			</view>
+		</template>
+		<template v-slot:open="{ open }">
+			<view class="slef-open-icon">
+				{{ open ? '-' : '+' }}
+			</view>
+		</template>
+	</ste-tree>
+</template>
+<script>
+```
+
+
+---$
+### API
+#### Props
+背景之外的颜色属性只支持`16进制`、`RGB`、`RGBA`格式
+| 属性名						| 说明																																									| 类型										| 默认值				| 可选值	| 支持版本	|
+| -----							| -----																																								| -----									| -----				| -----	| -----		|
+| `options`					| 树形结构数组（`Node`结构见基础用法详情	），若组件渲染完成后修此属性，请手动调用`init`方法	| `Array<Node>`					| `[]`				|	-			| -				|
+| `valueKey`				| 节点的值字段名																																				| `String`							| `"value"`		|	-			| -				|
+| `titleKey`				| 节点的标题字段名																																			| `String`							| `"title"`		|	-			| -				|
+| `childrenKey`			| 节点的子节点字段名																																		| `String`							| `"children"`|	-			| -				|
+| `accordion`				| 是否手风琴模式																																				| `Boolean`							| `true`			|	-			| -				|
+| `childrenPadding`	| 子节点缩进,单位rpx																																		| `Number`,`String`			| `40`				|	-			| -				|
+| `openNodes`				| 默认展开的节点数组																																		| `Array<String/Number>`| `[]`				|	-			| -				|
+
+
+#### Method
+
+| 方法名	| 说明																													| 方法参数	| 支持版本	|
+| ---			| ---																													| ---			| ---			|
+| `init`	| 初始化方法，若`options`改变时页面没有更新，可调用此方法重现渲染	| -				| -				|
+| `open`	| 打开指定节点																									| `value`	| -				|
+| `close`	| 关闭指定节点																									| `value`	| -				|
+| `search`| 节点搜索																											| `title`	| -				|
+
+
+
+#### Events
+
+| 事件名			| 说明						| 事件参数						| 支持版本	|
+| ---					| ---						| ---								| ---			|
+| `click`			| 点击节点时触发	| `node`						| -				|
+| `open`			| 打开节点时触发	| `node`						| -				|
+| `close`			| 关闭节点时触发	| `node`						| -				|
+| `beforeOpen`| 打开节点前触发	| 见`懒加载`示例详细说明	| -				|
+
+
+
+
+---$
+{{xuyajun}}

package/components/ste-tree/ste-tree.vue

@@ -0,0 +1,350 @@
+<template>
+	<view class="ste-tree-root">
+		<view
+			v-for="(node, index) in viewList"
+			:key="node[valueKey]"
+			class="tree-item"
+			:class="{ open: node.open, children: node.hasChildren }"
+		>
+			<view class="tree-item-content" :style="{ paddingLeft: `${node.depth * cmpPaddingLeft}px` }">
+				<view class="tree-item-head" @click="onClick(node)">
+					<view class="tree-item-right">
+						<slot :node="node" :depth="node.depth">
+							<view class="tree-item-title">{{ node[titleKey] }}</view>
+						</slot>
+					</view>
+					<view class="tree-item-open" v-if="node.hasChildren" @click="onOpen(node)">
+						<slot name="open" :open="node.open">
+							<view class="open-icon">
+								<ste-icon code="&#xe678;" size="30" />
+							</view>
+						</slot>
+					</view>
+				</view>
+			</view>
+
+			<view class="tree-item-loading" v-if="node.loading">
+				<slot name="loading">
+					<ste-loading size="30" />
+				</slot>
+			</view>
+		</view>
+	</view>
+</template>
+
+<script>
+import utils from '../../utils/utils.js';
+
+/**
+ * ste-tree 树形控件
+ * @description 树形控件组件
+ * @tutorial https://stellar-ui.intecloud.com.cn/pc/index/index?name=ste-tree
+ * @property {Array} options 节点数组（支持树形结构）
+ * @property {String} valueKey 节点的值字段名（默认：value）
+ * @property {String} titleKey 节点的标题字段名（默认：title）
+ * @property {String} childrenKey 节点的子节点字段名（默认：children）
+ * @property {Boolean} accordion 是否手风琴模式（默认：true）
+ * @property {Number | String} childrenPadding 子节点缩进，单位RPX（默认：40）
+ * @property {Array} openNodes 默认展开的节点数组（数组内容为节点value值，请在组件加载前设置，加载后若要展开请调用open方法）
+ * @event {Function} click 点击节点触发，参数为当前节点对象
+ * @event {Function} open 打开节点时触发，参数为当前节点对象
+ * @event {Function} close 关闭节点时触发，参数为当前节点对象
+ * @event {Function} beforeOpen 打开节点前触发，第一个参数为当前节点对象（第二个参数为suspend函数，用于等待后续操作）（第三个参数为next函数，继续执行后续代码，可接收一个对象数组，该数组会替换当前节点的children）（第四个参数为stop，阻止后续代码执行）
+ */
+
+export default {
+	group: '展示组件',
+	title: 'Tree 树形控件',
+	name: 'ste-tree',
+	props: {
+		options: { type: [Array, null], default: () => [] },
+		valueKey: { type: [String, null], default: () => 'value' },
+		titleKey: { type: [String, null], default: () => 'title' },
+		childrenKey: { type: [String, null], default: () => 'children' },
+		accordion: { type: [Boolean, null], default: () => true },
+		childrenPadding: { type: [Number, String, null], default: () => 40 },
+		openNodes: { type: [Array, null], default: () => [] },
+		searchTitle: { type: [String, null], default: () => '' },
+	},
+	data() {
+		return {
+			dataOptions: [], // 全部数据
+			viewOptions: [], // 渲染数据
+			viewList: [], // 渲染列表
+			dataSearchTitle: '',
+
+			searchTime: null,
+		};
+	},
+	computed: {
+		cmpPaddingLeft() {
+			return utils.formatPx(this.childrenPadding, 'num');
+		},
+	},
+	watch: {
+		options: {
+			handler() {
+				this.init();
+			},
+			immediate: true,
+		},
+		searchTitle: {
+			handler(v) {
+				this.dataSearchTitle = v;
+			},
+			immediate: true,
+		},
+		dataSearchTitle: {
+			handler(v) {
+				this.onSearch(v);
+			},
+			immediate: true,
+		},
+	},
+	methods: {
+		init() {
+			this.dataOptions = this.formatTree(this.options);
+			this.viewOptions = this.dataOptions;
+			if (this.openNodes?.length) this.openNodes.forEach((v) => this.open(v));
+			else this.rende();
+		},
+		async open(value) {
+			const node = this.findNode(this.viewOptions, value);
+			if (!node) return;
+			if (!this.dataSearchTitle) {
+				await this.beforeOpen(node);
+			}
+			this.setNodeOpen(node[this.valueKey], true);
+			if (node.parentNode !== '__root__') {
+				const getParents = (_node) => {
+					const parents = [];
+					const parent = this.findNode(this.viewOptions, _node.parentNode);
+					if (parent) {
+						parents.push(parent);
+						if (parent.parentNode !== '__root__') {
+							parents.push(...getParents(parent));
+						}
+					}
+					return parents;
+				};
+				const parents = getParents(node);
+				parents.forEach((parent) => {
+					if (parent.open) return;
+					this.setNodeOpen(parent[this.valueKey], true);
+				});
+			}
+
+			this.rende();
+		},
+		close(value) {
+			this.closeNode(value);
+		},
+		search(title) {
+			this.dataSearchTitle = title;
+		},
+
+		formatTree(tree, parentNode, depth) {
+			return utils.formatTree(
+				tree,
+				this.valueKey,
+				this.childrenKey,
+				(node) => {
+					return { open: false, loading: false, hasChildren: !!node[this.childrenKey]?.length };
+				},
+				parentNode,
+				depth
+			);
+		},
+		rende() {
+			this.$nextTick(() => {
+				if (!this.viewOptions?.length) {
+					this.viewList = [];
+					return;
+				}
+				this.viewList = utils.flattenTree(this.viewOptions, this.childrenKey, (node) => node.open);
+			});
+		},
+
+		onClick(node) {
+			this.$emit('click', node);
+		},
+		onOpen(node) {
+			if (node.open) this.closeNode(node[this.valueKey]);
+			else this.openNode(node);
+		},
+
+		onSearch(title) {
+			clearTimeout(this.searchTime);
+
+			this.searchTime = setTimeout(() => {
+				if (!title) {
+					if (this.viewOptions !== this.dataOptions) {
+						this.viewOptions = this.dataOptions;
+					}
+					this.rende();
+					return;
+				}
+				this.viewOptions = utils.filterTree(
+					this.dataOptions,
+					(node) => node[this.titleKey]?.indexOf(title) !== -1,
+					this.valueKey,
+					this.childrenKey
+				);
+				this.rende();
+			}, 500);
+		},
+		async beforeOpen(node, suspend, next, stop) {
+			let is_next = true;
+			const beforeOpen = new Promise((resolve, reject) => {
+				this.$emit(
+					'beforeOpen',
+					node,
+					typeof suspend === 'function'
+						? suspend
+						: () => {
+								is_next = false;
+								this.$set(node, 'loading', true);
+						  },
+					(children = []) => {
+						const _children = this.formatTree(children, node[this.valueKey], node.depth + 1);
+
+						typeof next === 'function' ? next(_children) : resolve(_children);
+					},
+					typeof stop === 'function' ? stop : () => reject()
+				);
+			});
+			if (!is_next) {
+				try {
+					const children = await beforeOpen;
+					this.$set(node, this.childrenKey, children);
+					this.$set(node, 'loading', false);
+				} catch (e) {
+					// TODO handle the exception
+					this.$set(node, 'loading', false);
+					throw e;
+				}
+			}
+		},
+
+		async openNode(node) {
+			try {
+				await this.open(node[this.valueKey]);
+				this.$emit('open', node);
+				this.rende();
+			} catch (e) {
+				//TODO handle the exception
+			}
+		},
+		closeNode(value) {
+			const node = this.setNodeOpen(value, false);
+			this.$emit('close', node);
+			this.rende();
+		},
+
+		findNode(tree, value) {
+			return utils.findTreeNode(tree, value, this.valueKey, this.childrenKey);
+		},
+		// 关闭打开的兄弟节点
+		closeSibling(node) {
+			const sibling = this.viewList.filter(
+				(s) => s.open && s.parentNode === node.parentNode && s[this.valueKey] !== node[this.valueKey]
+			);
+			sibling.forEach((s) => this.setNodeOpen(s[this.valueKey], false));
+		},
+		setNodeOpen(nodeValue, open) {
+			// 修改渲染状态
+			const node = this.findNode(this.viewOptions, nodeValue);
+			if (open && this.accordion) {
+				this.closeSibling(node);
+			}
+			if (this.dataOptions !== this.viewOptions) {
+				// 同步到数据中
+				const _node = this.findNode(this.dataOptions, nodeValue);
+				_node.open = open;
+			}
+			node.open = open;
+			return node;
+		},
+	},
+};
+</script>
+
+<style lang="scss" scoped>
+.ste-tree-root {
+	width: 100%;
+	background-color: #fff;
+	.tree-item {
+		width: 100%;
+
+		&.open {
+			& > .tree-item-content {
+				.tree-item-head {
+					box-shadow: 0px 4rpx 10rpx 2rpx rgba(0, 0, 0, 0.04);
+					.tree-item-open .open-icon {
+						transform: rotate(180deg);
+					}
+				}
+			}
+			& > .tree-children {
+				display: block;
+				margin: 8rpx 0;
+			}
+		}
+
+		&.children {
+			.tree-item-content {
+				.tree-item-head {
+					margin-bottom: 8rpx;
+					.tree-item-right {
+						width: calc(100% - 70rpx);
+					}
+					.tree-item-open {
+						width: 70rpx;
+						height: 60rpx;
+						line-height: 30rpx;
+						padding: 15rpx 20rpx;
+						line-height: 30rpx;
+					}
+				}
+			}
+		}
+
+		.tree-item-content {
+			width: 100%;
+			.tree-item-head {
+				width: 100%;
+				display: flex;
+				align-items: center;
+				justify-content: space-between;
+				font-family: PingFang SC, PingFang SC;
+				font-weight: 500;
+				font-size: 28rpx;
+				color: #000000;
+
+				.tree-item-right {
+					width: 100%;
+
+					.tree-item-title {
+						width: 100%;
+						height: 80rpx;
+						line-height: 80rpx;
+						padding-left: 20rpx;
+					}
+				}
+			}
+		}
+		.tree-item-loading {
+			width: 100%;
+			height: 80rpx;
+			display: flex;
+			justify-content: center;
+			align-items: center;
+		}
+		.tree-children {
+			display: none;
+			width: 100%;
+			padding-left: 40rpx;
+		}
+	}
+}
+</style>