oxy-uni-ui 2.1.2 → 2.1.4

package/components/common/props.ts

@@ -9,31 +9,54 @@ export const truthProp = {
   default: true as const
 }
 
+/**
+ * 创建必填 prop 定义。
+ * @param type prop 类型
+ */
 export const makeRequiredProp = <T>(type: T) => ({
   type,
   required: true as const
 })
 
+/**
+ * 创建数组类型 prop 定义，默认值为空数组 `[]`。
+ */
 export const makeArrayProp = <T>() => ({
   type: Array as PropType<T[]>,
   default: () => []
 })
 
+/**
+ * 创建布尔类型 prop 定义。
+ * @param defaultVal 默认值
+ */
 export const makeBooleanProp = <T>(defaultVal: T) => ({
   type: Boolean,
   default: defaultVal
 })
 
+/**
+ * 创建数字类型 prop 定义。
+ * @param defaultVal 默认值
+ */
 export const makeNumberProp = <T>(defaultVal: T) => ({
   type: Number,
   default: defaultVal
 })
 
+/**
+ * 创建 Numeric（支持 Number 和 String）类型 prop 定义。
+ * @param defaultVal 默认值
+ */
 export const makeNumericProp = <T>(defaultVal: T) => ({
   type: numericProp,
   default: defaultVal
 })
 
+/**
+ * 创建字符串类型 prop 定义。
+ * @param defaultVal 默认值
+ */
 export const makeStringProp = <T>(defaultVal: T) => ({
   type: String as unknown as PropType<T>,
   default: defaultVal

package/components/common/util.ts

@@ -687,6 +687,12 @@ export function isEmptyObj(obj: unknown): boolean {
   return !hasFields(obj)
 }
 
+/**
+ * 借由 requestAnimationFrame 实现定时 Promise，用于等待下一帧渲染完成。
+ * 小程序端降级为 `setInterval`（约 33fps）。
+ *
+ * @param cb 定时回调
+ */
 export const requestAnimationFrame = (cb = () => {}) => {
   return new AbortablePromise((resolve) => {
     const timer = setInterval(() => {
@@ -827,6 +833,16 @@ type DebounceOptions = {
   trailing?: boolean // 是否在延迟时间结束时调用函数
 }
 
+/**
+ * 防抖函数。
+ *
+ * 在连续触发中只执行最后一次或第一次（leading），
+ * 默认在延迟结束后执行（trailing=true）。
+ *
+ * @param func 要防抖的函数
+ * @param wait 等待时间（毫秒）
+ * @param options leading 是否在开始时调用，trailing 是否在结束时调用
+ */
 export function debounce<T extends (...args: any[]) => any>(func: T, wait: number, options: DebounceOptions = {}): T {
   let timeoutId: ReturnType<typeof setTimeout> | null = null
   let lastArgs: any[] | undefined
@@ -996,7 +1012,8 @@ export function isExcelUrl(url: string): boolean {
 }
 
 /**
- * 判断环境是否是H5
+ * 判断环境是否是 H5。
+ * 通过条件编译 `#ifdef H5` 在编译时静态确定。
  */
 export const isH5 = (() => {
   let isH5 = false

package/components/composables/index.ts

@@ -11,3 +11,5 @@ export { useTranslate } from './useTranslate'
 export { useUpload } from './useUpload'
 export { useVirtualScroll } from './useVirtualScroll'
 export { useWindowResize } from './useWindowResize'
+export { useImagePreview } from '../oxy-image-preview'
+export { createSharedState } from './useSharedState'

package/components/composables/useCell.ts

@@ -2,11 +2,18 @@ import { computed } from 'vue'
 import { useParent } from './useParent'
 import { CELL_GROUP_KEY } from '../oxy-cell-group/types'
 
+/**
+ * 获取 Cell Group 上下文，用于判断当前 cell 是否需要显示底部边框。
+ *
+ * 仅在父组件为 `oxy-cell-group` 且当前 cell 不是第一个子节点时返回 `border: true`。
+ *
+ * @returns `{ border }` 是否显示 cell 间分割线
+ */
 export function useCell() {
   const { parent: cellGroup, index } = useParent(CELL_GROUP_KEY)
 
   const border = computed(() => {
-    return cellGroup && cellGroup.props.border && index.value
+    return cellGroup.value && cellGroup.value.props.border && index.value
   })
 
   return { border }

package/components/composables/useChildren.ts

@@ -14,6 +14,15 @@ function isVNode(value: any): value is VNode {
   return value ? value.__v_isVNode === true : false
 }
 
+/**
+ * 展平 VNode 树，递归收集所有合法的 VNode 节点。
+ *
+ * 用于在父组件中获取所有子 VNode，以便按 DOM 顺序排序 children。
+ * 小程序端不支持 `isVNode`，因此内部提供了自定义实现。
+ *
+ * @param children 父组件的 VNode children
+ * @returns 展平后的 VNode 数组
+ */
 export function flattenVNodes(children: VNodeNormalizedChildren) {
   const result: VNode[] = []
 
@@ -49,7 +58,13 @@ const findVNodeIndex = (vnodes: VNode[], vnode: VNode) => {
   return index
 }
 
-// sort children instances by vnodes order
+/**
+ * 按 VNodes 在 DOM 中的顺序排序子组件实例。
+ *
+ * @param parent 父组件内部实例
+ * @param publicChildren 子组件公开实例数组
+ * @param internalChildren 子组件内部实例数组
+ */
 export function sortChildren(
   parent: ComponentInternalInstance,
   publicChildren: ComponentPublicInstance[],
@@ -68,6 +83,17 @@ export function sortChildren(
   })
 }
 
+/**
+ * 为父组件提供子组件管理能力，常用于父子联动场景。
+ *
+ * 父组件调用此 Hook 后，可通过 `provide` 向子组件注入上下文，
+ * 子组件通过 `useParent` 获取父组件共享的状态和自己的索引。
+ *
+ * 典型场景：tabs/tab、radio-group/radio、collapse/collapse-item。
+ *
+ * @param key 用于 provide/inject 的 InjectionKey
+ * @returns `{ children, linkChildren }`——children 为响应式子组件公开实例数组，linkChildren 用于向子组件注入上下文。
+ */
 export function useChildren<
   // eslint-disable-next-line
   Child extends ComponentPublicInstance = ComponentPublicInstance<{}, any>,

package/components/composables/useCountDown.ts

@@ -49,7 +49,16 @@ function isSameSecond(time1: number, time2: number): boolean {
   return Math.floor(time1 / 1000) === Math.floor(time2 / 1000)
 }
 
-// 定义 useCountDown 函数
+/**
+ * 倒计时 Hook。
+ *
+ * 提供毫秒级和秒级倒计时能力，基于 `useRaf` 实现帧同步。
+ * 支持开始、暂停、重置，以及结束回调和变化回调。
+ * 组件卸载时自动暂停。
+ *
+ * @param options 倒计时配置
+ * @returns `{ start, pause, reset, current }`
+ */
 export function useCountDown(options: UseCountDownOptions) {
   let endTime: number // 结束时间
   let counting: boolean // 是否计时中

package/components/composables/useDynamicVirtualScroll.ts

@@ -13,6 +13,15 @@ export interface UseDynamicVirtualScrollOptions<T extends DynamicVirtualScrollIt
   buffer?: number
 }
 
+/**
+ * 不定高虚拟滚动 Hook。
+ *
+ * 通过二分查找计算当前可视区域内的数据项，适用于列表项高度不固定的场景。
+ * 数据源的每个元素需要包含 `top`（累加偏移量）和 `height` 字段。
+ *
+ * @param options 配置项
+ * @returns `{ visibleData, getTargetIndex }` 可视数据列表和根据 scrollTop 查找索引的方法
+ */
 export function useDynamicVirtualScroll<T extends DynamicVirtualScrollItem>(options: UseDynamicVirtualScrollOptions<T>) {
   const { data, scrollTop, viewportHeight, buffer = 0 } = options
 

package/components/composables/useGlobalLoading.ts

@@ -12,6 +12,12 @@ interface GlobalLoading {
 const defaultOptions: ToastOptions = {
   show: false
 }
+/**
+ * 全局 Loading 状态管理（Pinia Store）。
+ *
+ * 通过 Pinia 跨页面共享 loading 状态，
+ * 在路由切换时自动记录当前页面并显示全屏加载遮罩。
+ */
 export const useGlobalLoading = defineStore('global-loading', {
   state: (): GlobalLoading => ({
     loadingOptions: defaultOptions,

package/components/composables/useGlobalMessage.ts

@@ -13,6 +13,12 @@ interface GlobalMessage {
   currentPage: string
 }
 
+/**
+ * 全局 Message 弹窗状态管理（Pinia Store）。
+ *
+ * 通过 Pinia 跨页面管理 message-box 的显示/隐藏，
+ * 支持 alert、confirm、prompt 三种模式。
+ */
 export const useGlobalMessage = defineStore('global-message', {
   state: (): GlobalMessage => ({
     messageOptions: null,

package/components/composables/useGlobalToast.ts

@@ -13,6 +13,12 @@ const defaultOptions: ToastOptions = {
   duration: 2000,
   show: false
 }
+/**
+ * 全局 Toast 状态管理（Pinia Store）。
+ *
+ * 通过 Pinia 跨页面管理 toast 的显示/隐藏，
+ * 提供 show、success、error、info、warning 等快捷方法。
+ */
 export const useGlobalToast = defineStore('global-toast', {
   state: (): GlobalToast => ({
     toastOptions: defaultOptions,

package/components/composables/useLockScroll.ts

@@ -1,5 +1,14 @@
 import { onBeforeUnmount, onDeactivated, ref, watch } from 'vue'
 
+/**
+ * 锁定页面滚动。
+ *
+ * 当 `shouldLock` 返回 true 时将 body 的 overflow 设为 hidden，
+ * 支持嵌套调用（通过计数器管理）。仅 H5 环境有效。
+ *
+ * @param shouldLock 返回布尔值的响应式函数，用于判断是否需要锁定滚动
+ * @returns `{ lock, unlock }` 手动锁定/解锁方法
+ */
 export function useLockScroll(shouldLock: () => boolean) {
   const scrollLockCount = ref(0)
 

package/components/composables/useParent.ts

@@ -1,8 +1,9 @@
 import {
-  ref,
   inject,
   computed,
+  onMounted,
   onUnmounted,
+  shallowRef,
   type InjectionKey,
   getCurrentInstance,
   type ComponentPublicInstance,
@@ -16,26 +17,76 @@ type ParentProvide<T> = T & {
   internalChildren: ComponentInternalInstance[]
 }
 
+function findParentProvide<T>(instance: ComponentInternalInstance, key: InjectionKey<ParentProvide<T>>): ParentProvide<T> | null {
+  let parent: ComponentInternalInstance | null = instance.parent
+  const provideKey = key as unknown as PropertyKey
+
+  while (parent) {
+    const provides = (parent as any).provides as Record<PropertyKey, unknown> | undefined
+    if (provides && provideKey in provides) {
+      return provides[provideKey] as ParentProvide<T>
+    }
+    parent = parent.parent
+  }
+
+  return null
+}
+
+/**
+ * 获取父组件提供的上下文数据。
+ *
+ * 子组件通过传入父组件 `provide` 的 InjectionKey，可以获取父组件共享的状态和子组件在同类兄弟中的索引。
+ * 常用于父子联动组件（如 tabs/tab、radio-group/radio、collapse/collapse-item）。
+ *
+ * 抖音小程序端存在父子初始化时序差异：
+ * - 非抖音端保持 setup 阶段同步注入。
+ * - 抖音端在 mounted 阶段延迟回查并完成 link。
+ *
+ * @param key 父组件 provide 时使用的 InjectionKey
+ * @returns `{ parent, index }`，parent 为父组件提供的上下文 Ref，index 为当前子组件在兄弟节点中的顺序索引。
+ */
 export function useParent<T>(key: InjectionKey<ParentProvide<T>>) {
-  const parent = inject(key, null)
+  const instance = getCurrentInstance()!
 
-  if (parent) {
-    const instance = getCurrentInstance()!
-    const { link, unlink, internalChildren } = parent
+  const parent = shallowRef<ParentProvide<T> | null>(null)
+  const linkedParent = shallowRef<ParentProvide<T> | null>(null)
 
-    link(instance)
-    onUnmounted(() => unlink(instance))
+  const tryLinkParent = () => {
+    if (!parent.value || linkedParent.value) return false
 
-    const index = computed(() => internalChildren.indexOf(instance))
+    parent.value.link(instance)
+    linkedParent.value = parent.value
+    return true
+  }
+
+  // 非抖音端保持原有 setup 同步 link 行为。
+  // #ifndef MP-TOUTIAO
+  parent.value = inject(key, null)
+  tryLinkParent()
+  // #endif
+
+  // 抖音端延迟到 mounted，规避 setup 阶段父子注入时序问题。
+  // #ifdef MP-TOUTIAO
+  onMounted(() => {
+    parent.value = findParentProvide(instance, key)
+    tryLinkParent()
+  })
+  // #endif
 
-    return {
-      parent,
-      index
+  onUnmounted(() => {
+    if (linkedParent.value) {
+      linkedParent.value.unlink(instance)
+      linkedParent.value = null
     }
-  }
+  })
+
+  const index = computed(() => {
+    if (!parent.value) return -1
+    return parent.value.internalChildren.indexOf(instance)
+  })
 
   return {
-    parent: null,
-    index: ref(-1)
+    parent,
+    index
   }
 }

package/components/composables/usePopover.ts

@@ -1,6 +1,15 @@
 import { getCurrentInstance, ref } from 'vue'
 import { getRect, isObj, unitConvert } from '../common/util'
 
+/**
+ * Popover/Tooltip 定位计算 Hook。
+ *
+ * 计算弹出层相对于目标元素的位置和箭头方向，
+ * 支持 12 种 placement（top/bottom/left/right 及其 start/end 变体）。
+ *
+ * @param visibleArrow 是否显示箭头
+ * @returns `{ popStyle, arrowStyle, arrowClass, init, control }` 定位样式和初始化/控制方法
+ */
 export function usePopover(visibleArrow = true) {
   const { proxy } = getCurrentInstance() as any
   const popStyle = ref<string>('')

package/components/composables/useQueue.ts

@@ -10,6 +10,14 @@ export interface Queue {
   closeOutside: () => void
 }
 
+/**
+ * 组件队列管理 Hook，用于管理同类型弹出组件的互斥展示。
+ *
+ * 父组件通过 `provide` 注入队列上下文，子组件通过 `inject` 获取，
+ * 在打开时关闭其他同类组件，实现唯一展示（如 swipe-action、popup 等）。
+ *
+ * @returns `{ closeOther, closeOutside }` 关闭其他组件和全部关闭的方法
+ */
 export function useQueue() {
   const queue = ref<any[]>([])
 

package/components/composables/useRaf.ts

@@ -4,6 +4,16 @@ import { isDef, isH5, isNumber } from '../common/util'
 // 定义回调函数类型
 type RafCallback = (time: number) => void
 
+/**
+ * 跨平台 requestAnimationFrame 封装。
+ *
+ * H5 环境使用原生 `requestAnimationFrame`，
+ * 小程序端使用 `setTimeout` 降级（约 33fps）。
+ * 组件卸载时自动取消未完成的动画帧。
+ *
+ * @param callback 每帧回调，接收当前时间戳
+ * @returns `{ start, cancel }` 启动和取消动画帧的方法
+ */
 export function useRaf(callback: RafCallback) {
   const requestRef = ref<number | null | ReturnType<typeof setTimeout>>(null)