oxy-uni-ui 2.1.1 → 2.1.3

package/components/oxy-toast/types.ts

@@ -1,4 +1,4 @@
-import type { ExtractPropTypes, PropType } from 'vue'
+import type { ExtractPropTypes, PropType, Ref } from 'vue'
 import { baseProps, makeStringProp } from '../common/props'
 import type { LoadingType } from '../oxy-loading/types'
 
@@ -10,6 +10,8 @@ export type ToastDirection = 'vertical' | 'horizontal' // 提示信息框的排
 
 export type ToastLoadingType = LoadingType // 提示信息加载状态类型
 
+export type ToastId = string
+
 export type ToastOptions = {
   msg?: string
   duration?: number
@@ -46,22 +48,31 @@ export type ToastOptions = {
 }
 
 export interface Toast {
+  // 当前 Toast 实例 id
+  id: ToastId
   // 打开Toast
-  show(toastOptions: ToastOptions | string): void
+  show(toastOptions: ToastOptions | string): ToastId
   // 成功提示
-  success(toastOptions: ToastOptions | string): void
+  success(toastOptions: ToastOptions | string): ToastId
   // 关闭提示
-  error(toastOptions: ToastOptions | string): void
+  error(toastOptions: ToastOptions | string): ToastId
   // 常规提示
-  info(toastOptions: ToastOptions | string): void
+  info(toastOptions: ToastOptions | string): ToastId
   // 警告提示
-  warning(toastOptions: ToastOptions | string): void
+  warning(toastOptions: ToastOptions | string): ToastId
   // 加载提示
-  loading(toastOptions: ToastOptions | string): void
+  loading(toastOptions: ToastOptions | string): ToastId
   // 关闭Toast
   close(): void
 }
 
+export type ToastProvide = {
+  /**
+   * toast 运行时选项，默认隐藏。
+   */
+  toastOption: Ref<ToastOptions>
+}
+
 export const toastProps = {
   ...baseProps,
   /**
@@ -127,9 +138,9 @@ export const toastProps = {
   /**
    * 位置
    * @type {'top' | 'middle-top' | 'middle' | 'bottom'}
-   * @default 'middle-top'
+   * @default 'middle'
    */
-  position: makeStringProp<ToastPositionType>('middle-top'),
+  position: makeStringProp<ToastPositionType>('middle'),
   /**
    * 层级
    * @type {number}

package/components/oxy-tooltip/index.scss

@@ -59,7 +59,7 @@
     right: -16rpx;
     top: -20rpx;
     transform: scale(0.5);
-    padding: 20rpx;
+    padding: $-spacing-20;
   }
 
   @include triangleArrow($-tooltip-arrow-size, $-tooltip-bg);

package/components/oxy-tooltip/oxy-tooltip.vue

@@ -27,7 +27,9 @@ export default {
   name: 'oxy-tooltip',
   options: {
     addGlobalClass: true,
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     styleIsolation: 'shared'
   }
 }

package/components/oxy-transition/index.scss

@@ -1,5 +1,7 @@
+@import '../common/abstracts/variable';
+
 .oxy-transition {
-  transition-timing-function: ease;
+  transition-timing-function: $-transition-timing-function-base;
 }
 
 .oxy-fade-enter,

package/components/oxy-transition/oxy-transition.vue

@@ -19,7 +19,9 @@ export default {
   name: 'oxy-transition',
   options: {
     addGlobalClass: true,
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     styleIsolation: 'shared'
   }
 }
@@ -31,6 +33,10 @@ import { isObj, isPromise, pause } from '../common/util'
 import { transitionProps, type TransitionName } from './types'
 import { AbortablePromise } from '../common/AbortablePromise'
 
+/**
+ * 根据 name 属性生成进入/离开的 CSS 类名
+ * name 可以是单个字符串或数组，用于组合多个过渡效果
+ */
 const getClassNames = (name?: TransitionName | TransitionName[]) => {
   let enter: string = `${props.enterClass} ${props.enterActiveClass}`
   let enterTo: string = `${props.enterToClass} ${props.enterActiveClass}`
@@ -134,6 +140,10 @@ function handleAbortPromise() {
   leaveLifeCyclePromises.value = null
 }
 
+/**
+ * 进入动画：使用 AbortablePromise 管理生命周期
+ * before-enter → enter → (显示元素) → enter-to（触发 CSS transition）
+ */
 function enter() {
   enterPromise.value = new AbortablePromise(async (resolve) => {
     try {
@@ -163,6 +173,10 @@ function enter() {
     }
   })
 }
+/**
+ * 离开动画：等待进入动画完成后执行离开
+ * before-leave → leave → leave-to（触发 CSS transition）→ after-leave
+ */
 async function leave() {
   if (!enterPromise.value) {
     transitionEnded.value = false

package/components/oxy-tree/index.scss

@@ -29,15 +29,15 @@
     display: flex;
 
     :deep(.oxy-button) {
-      min-width: 120rpx;
+      min-width: $-tree-search-btn-min-width;
     }
 
     :deep(.oxy-tree__search-input) {
       flex: 1;
       background-color: $-tree-search-input-color;
-      padding: 16rpx 24rpx;
+      padding: $-spacing-4 $-spacing-24;
       border-radius: $-tree-search-input-radius;
-      margin-bottom: 20rpx;
+      margin-bottom: $-tree-search-btn-margin-bottom;
       margin-right: $-spacing-24;
 
       .oxy-input__icon {

package/components/oxy-tree/oxy-tree.vue

@@ -11,7 +11,7 @@
           v-model="searchValue"
           @confirm="handleFilter"
         />
-        <oxy-button :round="false" @click="handleFilter">筛选</oxy-button>
+        <oxy-button :round="false" @click="handleFilter">{{ translate('filterButton') }}</oxy-button>
       </view>
     </slot>
 
@@ -39,10 +39,9 @@
 
                 <!-- 兼容支付宝、微信小程序 -->
                 <view class="oxy-tree-node-toggle" @tap.stop="handleClickExpand(item)">
-                  <oxy-icon
-                    :name="expandedKeySet.has(item.key) ? 'chevron-down-circle' : 'chevron-right-circle'"
-                    custom-class="oxy-tree-node-icon"
-                  ></oxy-icon>
+                  <slot name="expand-icon" :node="item" :data="item.data" :expanded="expandedKeySet.has(item.key)">
+                    <oxy-icon :name="expandedKeySet.has(item.key) ? expandIcon : collapseIcon" custom-class="oxy-tree-node-icon"></oxy-icon>
+                  </slot>
                 </view>
                 <oxy-checkbox
                   v-if="showCheckbox"
@@ -77,7 +76,9 @@
 export default {
   name: 'oxy-tree',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -91,9 +92,11 @@ import { treeProps, type TreeExpose } from './types'
 import { isSetsEqual, useTreeMethods } from './utils'
 import { useVirtualScroll } from '../composables/useVirtualScroll'
 import { withDefaultUnit, unitConvert, unitConvertWithDefault } from '../common/util'
+import { useTranslate } from '../composables/useTranslate'
 
 // 获取组件的 props 和 emit 函数
 const props = defineProps(treeProps)
+const { translate } = useTranslate('tree')
 const {
   modelValue,
   data,
@@ -181,6 +184,11 @@ const {
   backToTopThreshold: backToTopThreshold
 })
 
+/**
+ * 根据原始数据创建树结构。递归遍历构建 TreeNode，记录节点级别、是否叶子节点、展开状态等。
+ * @param data - 原始树数据
+ * @returns 含 treeNodeMap、levelTreeNodeMap、maxLevel、treeNodes 的树对象
+ */
 const createTree = (data: RawTreeNode[]) => {
   const treeNodeMap = new Map<string, TreeNode>()
   const levelTreeNodeMap = new Map<number, TreeNode[]>()
@@ -247,6 +255,12 @@ const toggleExpand = (node: TreeNode, flag: boolean) => {
     emit('node-collapse', node)
   }
 }
+/**
+ * 递归切换节点勾选状态。关联模式下同步更新所有子孙节点，并向上递归更新父节点状态。
+ * @param node - 当前节点
+ * @param flag - 是否选中
+ * @param isClick - 是否由点击触发（控制是否 emit node-check）
+ */
 const toggleChecked = (node: TreeNode, flag: boolean, isClick: boolean = false) => {
   if (!showCheckbox.value || !node || node.disabled) {
     return
@@ -293,6 +307,10 @@ const updateParentNode = (node: TreeNode) => {
   updateNode(node.parent)
   updateParentNode(node.parent)
 }
+/**
+ * 根据子节点状态更新当前节点的勾选/半选状态。
+ * 全选→checked，全不选→unchecked，部分选→indeterminate（半选）。
+ */
 const updateNode = (node: TreeNode | undefined) => {
   if (!node) return
   if (node.children?.every((item) => item.checked)) {
@@ -447,6 +465,11 @@ const filter = (query: string) => {
   }
 }
 
+/**
+ * 执行树节点过滤。遍历所有节点，匹配的节点及其祖先展开显示，不匹配的叶子节点和非匹配分支节点隐藏。
+ * @param query - 搜索关键词
+ * @returns 应展开的节点 key 集合
+ */
 const doFilter = (query: string) => {
   if (typeof props.filterMethod !== 'function') {
     return

package/components/oxy-tree/types.ts

@@ -35,20 +35,56 @@ export type TreeNode = {
 
 export const treeProps = {
   ...baseProps,
+  /**
+   * 树形数据源
+   */
   data: makeArrayProp<RawTreeNode>(),
+  /**
+   * 是否显示复选框
+   */
   showCheckbox: makeBooleanProp(false),
+  /**
+   * 子节点键名
+   */
   childrenKey: makeStringProp('children'),
+  /**
+   * 标签键名
+   */
   labelKey: makeStringProp('name'),
+  /**
+   * 节点唯一标识键名
+   */
   nodeKey: makeStringProp('id'),
+  /**
+   * 默认展开的节点 key 数组
+   */
   defaultExpandedKeys: makeArrayProp<string>(),
+  /**
+   * 是否默认展开所有节点
+   */
   expandAll: makeBooleanProp(false),
+  /**
+   * 是否严格模式，父子节点选中状态不关联
+   */
   checkStrictly: makeBooleanProp(false),
+  /**
+   * 是否显示连接线
+   */
   showLine: makeBooleanProp(false),
+  /**
+   * 选中的节点 key，单选为字符串，多选为数组
+   */
   modelValue: {
     type: [Array<string>, String],
     default: ''
   },
+  /**
+   * 空数据提示文案
+   */
   emptyText: makeStringProp('暂无数据'),
+  /**
+   * 容器高度，支持 `px/rpx`
+   */
   height: makeStringProp('600rpx'),
   /**
    * 是否显示回到顶部按钮
@@ -72,13 +108,33 @@ export const treeProps = {
    * 相邻级节点间的水平缩进，number 类型按 `rpx` 语义处理
    */
   indent: makeNumberProp(32),
+  /**
+   * 是否只能选择叶子节点
+   */
   selectionLeafOnly: makeBooleanProp(false),
+  /**
+   * 自定义筛选方法，接收关键字和节点数据，返回是否匹配
+   */
   filterMethod: {
     type: Function as PropType<(keyword: string, node: RawTreeNode) => boolean>,
     default: null
   },
+  /**
+   * 是否显示筛选输入框
+   */
   showFilter: makeBooleanProp(false),
-  filterPlaceholder: makeStringProp('请输入节点名称')
+  /**
+   * 筛选输入框占位符
+   */
+  filterPlaceholder: makeStringProp('请输入节点名称'),
+  /**
+   * 展开图标名称
+   */
+  expandIcon: makeStringProp('chevron-down-circle'),
+  /**
+   * 收起图标名称
+   */
+  collapseIcon: makeStringProp('chevron-right-circle')
 }
 export type TreeExpose = {
   toggleExpand: (node: TreeNode, flag: boolean) => void

package/components/oxy-upload/index.scss

@@ -39,7 +39,7 @@
     font-size: $-upload-evoke-icon-size;
     background-color: $-upload-evoke-bg;
     color: $-upload-evoke-color;
-    margin-bottom: 28rpx;
+    margin-bottom: $-upload-item-margin-bottom;
 
     @include when(disabled) {
       color: $-upload-evoke-disabled-color;
@@ -53,7 +53,7 @@
   @include e(evoke-num) {
     font-size: $-fs-content;
     line-height: $-fs-content;
-    margin-top: 20rpx;
+    margin-top: $-spacing-20;
   }
 
   @include edeep(evoke-icon) {
@@ -75,7 +75,7 @@
     position: relative;
     width: $-upload-size;
     height: $-upload-size;
-    margin: 0 24rpx 28rpx 0;
+    margin: 0 24rpx $-upload-item-margin-bottom 0;
   }
 
   @include e(preview-list) {
@@ -106,9 +106,9 @@
     font-size: $-upload-file-fs;
     color: $-upload-file-color;
     box-sizing: border-box;
-    padding: 0 12rpx;
+    padding: 0 $-spacing-12;
     text-align: center;
-    margin-top: 20rpx;
+    margin-top: $-spacing-20;
     @include lineEllipsis()
   }
 
@@ -131,7 +131,7 @@
     right: calc($-upload-close-icon-size / 2 * -1);
     top: calc($-upload-close-icon-size / 2 * -1);
     font-size: $-upload-close-icon-size;
-    z-index: 1;
+    z-index: $-z-index-sticky;
     color: $-upload-close-icon-color;
     width: $-upload-close-icon-size;
     height: $-upload-close-icon-size;
@@ -159,7 +159,7 @@
   @include e(progress-txt) {
     font-size: $-upload-progress-fs;
     line-height: $-upload-progress-fs;
-    margin-top: 20rpx;
+    margin-top: $-spacing-20;
     color: $-color-white;
   }
 
@@ -208,9 +208,9 @@
       font-size: $-upload-preview-name-fs;
       color: $-upload-file-color;
       box-sizing: border-box;
-      padding: 0 12rpx;
+      padding: 0 $-spacing-12;
       text-align: center;
-      margin-top: 20rpx;
+      margin-top: $-spacing-20;
       white-space: nowrap;
       overflow: hidden;
       text-overflow: ellipsis;

package/components/oxy-upload/oxy-upload.vue

@@ -42,7 +42,7 @@
             <!-- #ifndef MP-DINGTALK -->
             <video
               :src="file.url"
-              :title="file.name || '视频' + index"
+              :title="file.name || translate('videoType') + index"
               object-fit="contain"
               :controls="false"
               :poster="file.thumb"
@@ -123,7 +123,9 @@ export default {
   name: 'oxy-upload',
   options: {
     addGlobalClass: true,
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     styleIsolation: 'shared'
   }
 }
@@ -596,7 +598,7 @@ function handlePreviewImage(index: number, lists: string[]) {
           imgList: lists
         })
       } else {
-        uni.showToast({ title: '预览图片失败', icon: 'none' })
+        uni.showToast({ title: translate('previewImageFail'), icon: 'none' })
       }
     }
   })
@@ -626,7 +628,7 @@ function handlePreviewVieo(index: number, lists: UploadFileItem[]) {
           imgList: []
         })
       } else {
-        uni.showToast({ title: '预览视频失败', icon: 'none' })
+        uni.showToast({ title: translate('previewVideoFail'), icon: 'none' })
       }
     }
   })

package/components/oxy-verification-code/oxy-verification-code.vue

@@ -14,7 +14,9 @@ export default {
   name: 'oxy-verification-code',
   options: {
     addGlobalClass: true,
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     styleIsolation: 'shared'
   }
 }
@@ -73,6 +75,10 @@ function randomNum(min: number, max: number) {
   return Math.floor(Math.random() * (max - min) + min)
 }
 
+/**
+ * 生成随机验证码字符串
+ * 根据 codeType 从数字/字母/混合字符集中随机选取指定长度
+ */
 function getcheckCode() {
   let code = ''
   const codeLength = props.codeLength
@@ -93,6 +99,10 @@ function drawTap() {
   }
 }
 
+/**
+ * 获取 Canvas 上下文（兼容微信小程序 2D canvas 和传统 canvas）
+ * 微信小程序通过 SelectorQuery.node 获取，其他平台通过 createCanvasContext
+ */
 function getContext() {
   return new Promise<UniApp.CanvasContext>((resolve) => {
     if (ctx) {
@@ -122,6 +132,10 @@ function getContext() {
   })
 }
 
+/**
+ * 主绘制方法：生成验证码并绘制到 canvas
+ * 包含背景填充、单个字符绘制（随机旋转/颜色/位置/大小）、干扰线绘制
+ */
 function drawPic() {
   if (props.securityCode) {
     identifyCode.value = props.securityCode
@@ -140,6 +154,12 @@ function drawPic() {
   })
 }
 
+/**
+ * 绘制单个验证码字符：随机颜色、字号、位置、旋转角度
+ * @param context - Canvas 上下文
+ * @param txt - 字符
+ * @param i - 字符索引（用于计算 x 坐标）
+ */
 function drawText(context: any, txt: string, i: number) {
   let a = Math.floor(Math.random() * props.colors.length)
   context.setFillStyle(props.colors[a])
@@ -158,6 +178,10 @@ function drawText(context: any, txt: string, i: number) {
   context.translate(-x, -y)
 }
 
+/**
+ * 绘制干扰线：随机起点、终点、颜色
+ * @param context - Canvas 上下文
+ */
 function drawLine(context: any) {
   for (let i = 0; i < props.lineLength; i++) {
     let a = Math.floor(Math.random() * props.lineColors.length)

package/components/oxy-video-preview/index.scss

@@ -16,19 +16,24 @@
 
   @include e(video) {
     width: 100%;
-    height: 484rpx;
+    height: $-video-preview-video-height;
     transition: all $-transition-duration-slow ease;
   }
 
-  @include edeep(close) {
+  @include e(close) {
     position: absolute;
-    box-sizing: border-box;
-    top: 0;
-    right: 0;
-    padding: 24rpx;
-    text-align: center;
+    z-index: $-video-preview-close-z-index;
+    top: $-video-preview-close-margin;
+    right: $-video-preview-close-margin;
+    display: flex;
+    justify-content: center;
+    align-items: center;
     cursor: pointer;
+  }
+
+  @include edeep(close-icon) {
     font-size: $-video-preview-close-font-size;
+    line-height: $-video-preview-close-font-size;
     color: $-video-preview-close-color;
   }
 }

package/components/oxy-video-preview/index.ts

@@ -0,0 +1,64 @@
+import { inject, provide, ref } from 'vue'
+import type { PreviewVideo, VideoPreview, VideoPreviewOptions } from './types'
+import { deepMerge } from '../common/util'
+
+/**
+ * useVideoPreview 注入 key
+ */
+const videoPreviewDefaultOptionKey = '__VIDEO_PREVIEW_OPTION__'
+
+/**
+ * 默认配置
+ */
+export const defaultOptions: VideoPreviewOptions = {
+  url: '',
+  poster: '',
+  title: '',
+  show: false,
+  zIndex: 1000
+}
+
+const None = Symbol('None')
+
+/**
+ * 视频预览 Hook
+ * @param selector 实例标识，支持同一页面多个视频预览实例
+ */
+export function useVideoPreview(selector: string = ''): VideoPreview {
+  const videoPreviewOptionKey = getVideoPreviewOptionKey(selector)
+  const videoPreviewOption = inject(videoPreviewOptionKey, ref<VideoPreviewOptions | typeof None>(None))
+
+  if (videoPreviewOption.value === None) {
+    videoPreviewOption.value = defaultOptions
+    provide(videoPreviewOptionKey, videoPreviewOption)
+  }
+
+  /**
+   * 打开视频预览
+   * @param options 预览配置
+   */
+  const open = (options: VideoPreviewOptions | PreviewVideo) => {
+    const mergedOptions = deepMerge(defaultOptions, options) as VideoPreviewOptions
+    videoPreviewOption.value = deepMerge(mergedOptions, { show: true }) as VideoPreviewOptions
+  }
+
+  /**
+   * 关闭视频预览
+   */
+  const close = () => {
+    videoPreviewOption.value = { show: false } as VideoPreviewOptions
+  }
+
+  return {
+    previewVideo: open,
+    closeVideoPreview: close
+  }
+}
+
+/**
+ * 获取视频预览选项 key
+ * @param selector 实例标识
+ */
+export const getVideoPreviewOptionKey = (selector: string) => {
+  return selector ? `${videoPreviewDefaultOptionKey}${selector}` : videoPreviewDefaultOptionKey
+}