misp-ui-library-test 0.0.1

package/src/utils/playground/index.js

@@ -0,0 +1,37 @@
+/**
+ * @file playground 工具函数
+ * @description 提供组件库开发调试相关的工具方法
+ * @module @vue2-ui/utils/playground
+ */
+
+/**
+ * 获取所有组件包的 Class 定义
+ * @description 遍历 src/packages 目录，读取各包的 prop.js 文件中导出的 Class
+ * @function getClassPackage
+ * @returns {Record<string, Function>} 包含所有包 Class 信息的数组
+ */
+export function getClassPackage() {
+  const packages = {}
+  
+  try {
+    if (typeof require !== 'undefined') {
+      const context = require.context('../../packages', true, /prop\.js$/)
+      const keys = context.keys()
+      
+      keys.forEach(key => {
+        const module = context(key)
+        const packageName = key.match(/\/([^/]+)\/prop\.js$/)?.[1]
+        // 转换包名为类名，将形如'auto-grid-layout'的路径名转为'AutoGridLayout'
+        const className = packageName.split('-').map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join('')
+        if (className && module) {
+          packages[className] = module[className]
+        }
+      })
+    }
+  } catch (error) {
+    console.error('getClassPackage: 获取包信息失败', error)
+  }
+  return packages
+}
+
+export const classPack = getClassPackage()

package/src/utils/popper/index.js

@@ -0,0 +1,308 @@
+/**
+ * @fileoverview Vue2 UI Library - Popper 工具模块
+ * @description 基于 Popper.js 的弹出层定位工具 mixin，用于管理弹出层的位置、显示状态和生命周期
+ */
+
+import Vue from 'vue'
+import { PopupManager } from './popup'
+
+/**
+ * PopperJS 构造函数
+ * 服务端渲染时为空函数，客户端时加载实际的 PopperJS
+ * @type {Function}
+ */
+const PopperJS = Vue.prototype.$isServer ? function () {} : require('./popper')
+
+/**
+ * 阻止事件冒泡的辅助函数
+ * @param {Event} e - 事件对象
+ */
+const stop = (e) => e.stopPropagation()
+
+export default {
+  /**
+   * @namespace Props
+   * @description 组件属性配置
+   */
+  props: {
+    /**
+     * 是否启用变换原点设置，或自定义变换原点字符串
+     * @type {Boolean|String}
+     * @default true
+     */
+    transformOrigin: { type: [Boolean, String], default: true },
+
+    /**
+     * 弹出层的位置方向
+     * @type {String}
+     * @default 'bottom'
+     * @values top, bottom, left, right, top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end
+     */
+    placement: { type: String, default: 'bottom' },
+
+    /**
+     * 边界内边距，防止弹出层超出可视区域
+     * @type {Number}
+     * @default 5
+     */
+    boundariesPadding: { type: Number, default: 5 },
+
+    /**
+     * 参考元素，用于定位的基准元素
+     * @type {HTMLElement|VueComponent}
+     */
+    reference: {},
+
+    /**
+     * 弹出层元素
+     * @type {HTMLElement|VueComponent}
+     */
+    popper: {},
+
+    /**
+     * 弹出层与参考元素的偏移距离
+     * @type {Number}
+     * @default 0
+     */
+    offset: { default: 0 },
+
+    /**
+     * 弹出层显示状态（支持 v-model）
+     * @type {Boolean}
+     */
+    value: Boolean,
+
+    /**
+     * 是否显示指示箭头
+     * @type {Boolean}
+     */
+    visibleArrow: Boolean,
+
+    /**
+     * 箭头的偏移距离
+     * @type {Number}
+     * @default 35
+     */
+    arrowOffset: { type: Number, default: 35 },
+
+    /**
+     * 是否将弹出层追加到 body 元素下
+     * @type {Boolean}
+     * @default true
+     */
+    appendToBody: { type: Boolean, default: true },
+
+    /**
+     * Popper.js 的额外配置选项
+     * @type {Object}
+     * @default { gpuAcceleration: false }
+     */
+    popperOptions: { type: Object, default: () => ({ gpuAcceleration: false }) },
+  },
+
+  /**
+   * @namespace Data
+   * @description 组件响应式数据
+   */
+  data() {
+    return {
+      /**
+       * 弹出层显示状态
+       * @type {Boolean}
+       */
+      showPopper: false,
+
+      /**
+       * 当前实际使用的位置方向
+       * @type {String}
+       */
+      currentPlacement: '',
+    }
+  },
+
+  /**
+   * @namespace Watch
+   * @description 侦听器配置
+   */
+  watch: {
+    /**
+     * 监听 value 属性变化，同步更新 showPopper 状态
+     * @param {Boolean} val - 新的值
+     * @emits input
+     */
+    value: {
+      handler(val) {
+        this.showPopper = val
+        this.$emit('input', val)
+      },
+      immediate: true,
+    },
+
+    /**
+     * 监听 showPopper 状态变化，触发弹出层的更新或销毁
+     * @param {Boolean} val - 新的显示状态
+     * @emits input
+     */
+    showPopper(val) {
+      if (this.disabled) return
+      val ? this.updatePopper() : this.destroyPopper()
+      this.$emit('input', val)
+    },
+  },
+
+  /**
+   * @namespace Methods
+   * @description 组件方法集合
+   */
+  methods: {
+    /**
+     * 创建 Popper 实例
+     * 初始化弹出层的定位、样式和事件监听
+     * @description 根据 reference 和 popper 元素创建 PopperJS 实例，配置位置、偏移等参数
+     * @emits created - 当 Popper 实例创建完成时触发
+     * @returns {void}
+     */
+    createPopper() {
+      if (this.$isServer) return
+      this.currentPlacement = this.currentPlacement || this.placement
+      if (!/^(top|bottom|left|right)(-start|-end)?$/g.test(this.currentPlacement)) return
+
+      const options = this.popperOptions
+      const popper = (this.popperElm = this.popperElm || this.popper || this.$refs.popper)
+      let reference = (this.referenceElm = this.referenceElm || this.reference || this.$refs.reference)
+      if (!reference && this.$slots.reference && this.$slots.reference[0]) {
+        reference = this.referenceElm = this.$slots.reference[0].elm
+      }
+
+      if (!popper || !reference) return
+      this.visibleArrow && this.appendArrow(popper)
+      this.appendToBody && document.body.appendChild(this.popperElm)
+      this.popperJS && this.popperJS.destroy && this.popperJS.destroy()
+
+      options.placement = this.currentPlacement
+      options.offset = this.offset
+      options.arrowOffset = this.arrowOffset
+      this.popperJS = new PopperJS(reference, popper, options)
+      this.popperJS.onCreate(() => {
+        this.$emit('created', this)
+        this.resetTransformOrigin()
+        this.$nextTick(this.updatePopper)
+      })
+      if (typeof options.onUpdate === 'function') {
+        this.popperJS.onUpdate(options.onUpdate)
+      }
+      this.popperJS._popper.style.zIndex = PopupManager.nextZIndex()
+      this.popperElm.addEventListener('click', stop)
+    },
+
+    /**
+     * 更新 Popper 位置
+     * @description 调用 PopperJS 的 update 方法重新计算位置，或创建新的 Popper 实例
+     * @returns {void}
+     */
+    updatePopper() {
+      const popperJS = this.popperJS
+      if (popperJS) {
+        popperJS.update()
+        if (popperJS._popper) {
+          popperJS._popper.style.zIndex = PopupManager.nextZIndex()
+        }
+      } else {
+        this.createPopper()
+      }
+    },
+
+    /**
+     * 销毁 Popper 实例
+     * @description 清理 PopperJS 实例，释放相关资源
+     * @param {Boolean} forceDestroy - 是否强制销毁（忽略 showPopper 状态）
+     * @returns {void}
+     */
+    doDestroy(forceDestroy) {
+      if (!this.popperJS || (this.showPopper && !forceDestroy)) return
+      this.popperJS.destroy()
+      this.popperJS = null
+    },
+
+    /**
+     * 销毁弹出层
+     * @description 重置变换原点，准备销毁
+     * @returns {void}
+     */
+    destroyPopper() {
+      if (this.popperJS) {
+        this.resetTransformOrigin()
+      }
+    },
+
+    /**
+     * 重置变换原点
+     * @description 根据弹出层位置设置 CSS transform-origin，确保动画效果正确
+     * @returns {void}
+     */
+    resetTransformOrigin() {
+      if (!this.transformOrigin) return
+      let placementMap = {
+        top: 'bottom',
+        bottom: 'top',
+        left: 'right',
+        right: 'left',
+      }
+      let placement = this.popperJS._popper.getAttribute('x-placement').split('-')[0]
+      let origin = placementMap[placement]
+      this.popperJS._popper.style.transformOrigin = 
+        typeof this.transformOrigin === 'string'
+          ? this.transformOrigin
+          : ['top', 'bottom'].indexOf(placement) > -1
+            ? `center ${origin}`
+            : `${origin} center`;
+    },
+
+    /**
+     * 添加指示箭头元素
+     * @description 在弹出层元素中创建并添加箭头指示器
+     * @param {HTMLElement} element - 弹出层 DOM 元素
+     * @returns {void}
+     */
+    appendArrow(element) {
+      if (this.appended) return
+      let hash
+      this.appended = true
+      for (let item in element.attributes) {
+        if (/^_v-/.test(element.attributes[item].name)) {
+          hash = element.attributes[item].name
+          break
+        }
+      }
+      const arrow = document.createElement('div')
+      if (hash) {
+        arrow.setAttribute(hash, '')
+      }
+      arrow.setAttribute('x-arrow', '')
+      arrow.className = 'popper__arrow'
+      element.appendChild(arrow)
+    },
+  },
+
+  /**
+   * 组件销毁前钩子
+   * @description 清理 Popper 实例和事件监听，移除 DOM 元素
+   * @returns {void}
+   */
+  beforeDestroy() {
+    this.doDestroy(true)
+    if (this.popperElm && this.popperElm.parentNode === document.body) {
+      this.popperElm.removeEventListener('click', stop)
+      document.body.removeChild(this.popperElm)
+    }
+  },
+
+  /**
+   * 组件停用时钩子（keep-alive 场景）
+   * @description 调用 beforeDestroy 逻辑清理资源
+   * @returns {void}
+   */
+  deactivated() {
+    this.$options.beforeDestroy[0].call(this)
+  },
+}