oxy-uni-ui 2.1.2 → 2.1.4

package/components/composables/useSharedState.ts

@@ -0,0 +1,284 @@
+import { ref, type Ref } from 'vue'
+
+/**
+ * 作用域解析器。
+ *
+ * 返回值用于隔离不同页面或不同运行上下文下的同名 selector。
+ * 默认实现会优先使用当前页面实例生成页面级 scope。
+ */
+type SharedStateScopeResolver = () => string
+
+/**
+ * 状态 key 解析器。
+ *
+ * @param selector - 组件实例标识，例如 toast 的 selector。
+ * @param scopeId - 当前作用域标识，通常是页面级 scope。
+ * @returns 存入 stateMap 的最终 key。
+ */
+type SharedStateKeyResolver = (selector: string, scopeId: string) => string
+
+type CreateSharedStateOptions = {
+  /**
+   * 状态命名空间。
+   *
+   * 同一个 namespace 会复用同一个全局状态 Map，不同 namespace 之间完全隔离。
+   * 例如 toast、message-box、notify 使用不同 namespace，避免默认 selector 相同时状态结构互相覆盖。
+   */
+  namespace?: string
+  /**
+   * 自定义作用域解析逻辑。
+   *
+   * 未传入时默认使用当前页面实例生成页面级 scope，无法获取页面时退回 defaultScopeId。
+   */
+  resolveScopeId?: SharedStateScopeResolver
+  /**
+   * 自定义最终状态 key 的生成逻辑。
+   *
+   * 未传入时默认使用 `${scopeId}_${selector}`；selector 为空时直接使用 scopeId。
+   */
+  resolveKey?: SharedStateKeyResolver
+}
+
+type SharedStateStore = {
+  /**
+   * 全局 fallback scope 种子。
+   *
+   * 用于生成页面信息不可用时的默认 scope，放在全局 store 中可避免 H5 多份组件库实例各自计数。
+   */
+  scopeSeed: number
+  /**
+   * 页面 scope 种子。
+   *
+   * 每遇到一个新的 uni-app 页面对象递增一次，用于生成稳定的页面级 scope。
+   */
+  pageScopeSeed: number
+  /**
+   * 页面对象到页面 scope 的映射。
+   *
+   * 使用 WeakMap 可以让页面对象卸载后被正常回收，不需要手动删除历史页面记录。
+   */
+  pageScopeMap: WeakMap<object, string>
+  /**
+   * namespace 到 fallback scope 的映射。
+   *
+   * 当 getCurrentPages 不可用时，同一个 namespace 仍能拿到稳定默认 scope，
+   * 保证 hook 侧和组件侧不会因为各自生成随机 scope 而读写不同状态。
+   */
+  scopeIds: Map<string, string>
+  /**
+   * namespace 到状态 Map 的映射。
+   *
+   * 每个组件类型拥有独立状态容器，Map 内部再通过 scope + selector 区分具体实例。
+   */
+  stateMaps: Map<string, Map<string, Ref<Record<string, any>>>>
+}
+
+/**
+ * 当前模块实例内的本地 store。
+ *
+ * 在不支持 globalThis 的运行环境中作为兜底；
+ * 正常情况下会挂到 globalThis，供可能存在的多份组件库代码共同复用。
+ */
+const localSharedStateStore: SharedStateStore = {
+  scopeSeed: 0,
+  pageScopeSeed: 0,
+  pageScopeMap: new WeakMap<object, string>(),
+  scopeIds: new Map(),
+  stateMaps: new Map()
+}
+
+/**
+ * 获取全局共享状态容器。
+ *
+ * 为什么放到 globalThis：
+ * - H5 或业务项目中可能同时存在组件库源码和打包产物，导致 useSharedState 模块被加载多份。
+ * - 如果每份模块都维护自己的 Map，`useToast()` 和 `<oxy-toast>` 可能读写到不同容器。
+ * - 挂到 globalThis 后，多份模块实例会落到同一个 store，从而保持状态一致。
+ *
+ * 如果当前运行环境没有可用的 globalThis，则退回模块内的 localSharedStateStore。
+ */
+function getSharedStateStore() {
+  const globalScope = typeof globalThis === 'object' ? (globalThis as Record<string, any>) : null
+  if (!globalScope) return localSharedStateStore
+
+  const storeKey = '__OXY_UNI_UI_SHARED_STATE__'
+  if (!globalScope[storeKey]) {
+    globalScope[storeKey] = localSharedStateStore
+  }
+  return globalScope[storeKey] as SharedStateStore
+}
+
+/**
+ * 创建一个随机 fallback scope。
+ *
+ * fallback scope 只用于无法解析当前页面的场景，例如：
+ * - getCurrentPages 不存在
+ * - getCurrentPages 返回空数组
+ * - 获取页面信息时出现异常
+ *
+ * 正常页面内调用时，会优先使用 createPageScopeId 生成页面级 scope。
+ */
+function createRandomScopeId() {
+  const store = getSharedStateStore()
+  store.scopeSeed += 1
+  return `shared_state_${Date.now()}_${Math.random().toString(36).slice(2, 10)}_${store.scopeSeed}`
+}
+
+/**
+ * 获取 namespace 对应的默认 fallback scope。
+ *
+ * 有 namespace 时，同一个组件类型复用同一个 fallback scope；
+ * 没有 namespace 时，每次 createSharedState 都生成独立 fallback scope，保持旧的隔离行为。
+ */
+function createDefaultScopeId(namespace?: string) {
+  if (!namespace) return createRandomScopeId()
+
+  const store = getSharedStateStore()
+  const scopeId = store.scopeIds.get(namespace)
+  if (scopeId) return scopeId
+
+  const newScopeId = createRandomScopeId()
+  store.scopeIds.set(namespace, newScopeId)
+  return newScopeId
+}
+
+/**
+ * 根据 uni-app 页面对象创建页面级 scope。
+ *
+ * 同一个页面对象会通过 WeakMap 复用同一个 scope；
+ * 不同页面对象即使 route 相同，也会分配不同 scope，避免 navigateTo 多次进入同一路由时状态串用。
+ */
+function createPageScopeId(page: object) {
+  const store = getSharedStateStore()
+  const scopeId = store.pageScopeMap.get(page)
+  if (scopeId) return scopeId
+
+  store.pageScopeSeed += 1
+  const route = 'route' in page && typeof page.route === 'string' ? page.route : 'unknown'
+  const pageScopeId = `shared_page_${route}_${store.pageScopeSeed}`
+  store.pageScopeMap.set(page, pageScopeId)
+  return pageScopeId
+}
+
+/**
+ * 获取 namespace 对应的状态 Map。
+ *
+ * 传入 namespace 时使用全局 store 中的共享 Map；
+ * 不传 namespace 时返回新的本地 Map，表示该 createSharedState 调用完全自持状态。
+ */
+function getStateMap<T extends Record<string, any>>(namespace?: string) {
+  if (!namespace) return new Map<string, Ref<T>>()
+
+  const store = getSharedStateStore()
+  const stateMap = store.stateMaps.get(namespace)
+  if (stateMap) return stateMap as Map<string, Ref<T>>
+
+  const newStateMap = new Map<string, Ref<T>>()
+  store.stateMaps.set(namespace, newStateMap as Map<string, Ref<Record<string, any>>>)
+  return newStateMap
+}
+
+/**
+ * 解析当前页面 scope。
+ *
+ * 正常情况下取页面栈最后一个页面作为当前页面，并为其生成页面级 scope。
+ * 任何平台 API 不存在或异常的情况都会回退到 defaultScopeId，保证调用方始终有可用 scope。
+ */
+function resolveCurrentPageScopeId(defaultScopeId: string) {
+  try {
+    if (typeof getCurrentPages !== 'function') return defaultScopeId
+    const pages = getCurrentPages()
+    const currentPage = pages[pages.length - 1]
+    return currentPage && typeof currentPage === 'object' ? createPageScopeId(currentPage) : defaultScopeId
+  } catch {
+    return defaultScopeId
+  }
+}
+
+/**
+ * 创建默认状态 key 解析器。
+ *
+ * 默认 key 由 scopeId 和 selector 拼接：
+ * - selector 为空：使用 scopeId，代表当前页面默认实例。
+ * - selector 非空：使用 `${scopeId}_${selector}`，代表当前页面指定实例。
+ */
+function createDefaultKeyResolver(resolveScopeId: SharedStateScopeResolver): SharedStateKeyResolver {
+  return (selector: string, scopeId: string) => {
+    const stableScopeId = scopeId || resolveScopeId()
+    return selector ? `${stableScopeId}_${selector}` : stableScopeId
+  }
+}
+
+/**
+ * 基于 Map 的模块级共享状态管理，用于替代 inject/provide 模式。
+ *
+ * 适用于 toast、message、notify 等需要基于 selector 多实例隔离的弹窗组件。
+ * 与 inject/provide 相比：
+ * - 不依赖组件树，可在任意位置（如 Pinia actions、工具函数）直接读写状态
+ * - 通过 selector 区分多实例，与原有 API 兼容
+ * - 提供显式清理方法，支持组件卸载时释放资源
+ *
+ * @param defaultFactory - 默认状态工厂函数，用于初始化新 selector 的状态
+ * @returns { getState, initState, removeState }
+ *
+ * @example
+ * ```ts
+ * const { initState, getState, removeState } = createSharedState(() => ({ show: false }))
+ *
+ * // 组件挂载时初始化
+ * const state = initState('mySelector')
+ *
+ * // 外部只读获取
+ * const current = getState('mySelector')
+ *
+ * // 组件卸载时清理
+ * onUnmounted(() => removeState('mySelector'))
+ * ```
+ */
+export function createSharedState<T extends Record<string, any>>(defaultFactory: () => T, options: CreateSharedStateOptions = {}) {
+  // 按 namespace 取得组件类型级别的状态容器，例如 toast 和 message-box 分属不同容器。
+  const stateMap = getStateMap<T>(options.namespace)
+  // 页面 scope 解析失败时使用的默认 scope；有 namespace 时同一组件类型保持稳定。
+  const defaultScopeId = createDefaultScopeId(options.namespace)
+  // 默认按当前页面对象生成 scope，确保不同页面的默认 selector 不会互相污染。
+  const resolveScopeId = options.resolveScopeId || (() => resolveCurrentPageScopeId(defaultScopeId))
+  // 默认按 scope + selector 生成最终状态 key，也允许调用方完全自定义。
+  const resolveKey = options.resolveKey || createDefaultKeyResolver(resolveScopeId)
+  // 统一收口 key 生成逻辑，保证 get/init/remove 使用完全一致的 key。
+  const resolveStateKey = (selector: string = '', scopeId: string = resolveScopeId()) => resolveKey(selector, scopeId)
+
+  /**
+   * 获取指定 selector 的共享状态（纯读，不存在返回 undefined）
+   * @param selector - 实例标识，空字符串表示默认实例
+   * @param scopeId - 指定作用域；不传时自动解析当前页面作用域
+   */
+  const getState = (selector: string = '', scopeId: string = resolveScopeId()): Ref<T> | undefined => {
+    const key = resolveStateKey(selector, scopeId)
+    return stateMap.get(key)
+  }
+
+  /**
+   * 初始化指定 selector 的共享状态（仅首次创建，已存在则复用）
+   * @param selector - 实例标识，空字符串表示默认实例
+   * @param scopeId - 指定作用域；不传时自动解析当前页面作用域
+   */
+  const initState = (selector: string = '', scopeId: string = resolveScopeId()): Ref<T> => {
+    const key = resolveStateKey(selector, scopeId)
+    if (!stateMap.has(key)) {
+      stateMap.set(key, ref(defaultFactory()) as Ref<T>)
+    }
+    return stateMap.get(key)!
+  }
+
+  /**
+   * 移除指定 selector 的共享状态
+   * @param selector - 实例标识
+   * @param scopeId - 指定作用域；不传时自动解析当前页面作用域
+   */
+  const removeState = (selector: string = '', scopeId: string = resolveScopeId()): void => {
+    const key = resolveStateKey(selector, scopeId)
+    stateMap.delete(key)
+  }
+
+  return { getState, initState, removeState, resolveScopeId, resolveStateKey }
+}

package/components/composables/useTouch.ts

@@ -1,5 +1,13 @@
 import { ref } from 'vue'
 
+/**
+ * 触摸事件处理 Hook，提供触摸方向、位移量的计算能力。
+ *
+ * 常用于滑动操作组件（如 swipe-action、slider、tabs），
+ * 通过 `touchStart` / `touchMove` 记录触摸位移，自动判断滑动方向。
+ *
+ * @returns 返回触摸状态、方向、位移量及事件处理方法。
+ */
 export function useTouch() {
   const direction = ref<string>('')
   const deltaX = ref<number>(0)

package/components/composables/useTranslate.ts

@@ -1,6 +1,15 @@
 import { camelCase, getPropByPath, isDef, isFunction } from '../common/util'
 import Locale from '../../locale'
 
+/**
+ * 国际化翻译 Hook。
+ *
+ * 根据传入的组件名称读取 locale 模块中的翻译文案，
+ * 支持带参数的动态消息（如 `translate('weekFormat', year, week)`）。
+ *
+ * @param name 组件名称（驼峰），用作翻译 key 的前缀
+ * @returns `{ translate }` 翻译函数
+ */
 export const useTranslate = (name?: string) => {
   const prefix = name ? camelCase(name) + '.' : ''
   const translate = (key: string, ...args: unknown[]) => {

package/components/composables/useUpload.ts

@@ -48,6 +48,11 @@ export interface UseUploadOptions {
   extension?: string[]
 }
 
+/**
+ * 文件上传 Composable，封装了文件选择、上传任务管理、进度回调等能力
+ * 支持自定义上传方法、自动中断前一个上传任务
+ * @returns 包含 startUpload / abort / chooseFile / UPLOAD_STATUS 的返回对象
+ */
 export function useUpload(): UseUploadReturn {
   let currentTask: UniApp.UploadTask | null = null
 
@@ -207,13 +212,16 @@ export function useUpload(): UseUploadReturn {
    * 格式化媒体信息
    */
   function formatMedia(res: UniApp.ChooseMediaSuccessCallbackResult): ChooseFile[] {
-    return res.tempFiles.map((item) => ({
-      type: item.fileType,
-      path: item.tempFilePath,
-      thumb: item.fileType === 'video' ? item.thumbTempFilePath : item.tempFilePath,
-      size: item.size,
-      duration: item.duration
-    }))
+    return res.tempFiles.map((item) => {
+      const mediaType = ((item as any).fileType || (item as any).mediaType || 'image') as 'image' | 'video'
+      return {
+        type: mediaType,
+        path: item.tempFilePath,
+        thumb: mediaType === 'video' ? item.thumbTempFilePath : item.tempFilePath,
+        size: item.size,
+        duration: item.duration
+      }
+    })
   }
 
   /**
@@ -258,7 +266,7 @@ export function useUpload(): UseUploadReturn {
           // #endif
           break
         case 'video':
-          // #ifdef MP-WEIXIN
+          // #ifdef MP-WEIXIN || MP-TOUTIAO
           uni.chooseMedia({
             count: multiple ? maxCount : 1,
             mediaType: ['video'],
@@ -269,7 +277,7 @@ export function useUpload(): UseUploadReturn {
             fail: reject
           })
           // #endif
-          // #ifndef MP-WEIXIN
+          // #ifndef MP-WEIXIN || MP-TOUTIAO
           uni.chooseVideo({
             sourceType,
             compressed,
@@ -283,10 +291,22 @@ export function useUpload(): UseUploadReturn {
           })
           // #endif
           break
-        // #ifdef MP-WEIXIN
         case 'media':
+          // #ifdef MP-WEIXIN
+          uni.chooseMedia({
+            count: multiple ? maxCount : 1,
+            sourceType,
+            sizeType,
+            camera,
+            maxDuration,
+            success: (res) => resolve(formatMedia(res)),
+            fail: reject
+          })
+          // #endif
+          // #ifdef MP-TOUTIAO
           uni.chooseMedia({
             count: multiple ? maxCount : 1,
+            mediaType: ['image', 'video'],
             sourceType,
             sizeType,
             camera,
@@ -294,8 +314,22 @@ export function useUpload(): UseUploadReturn {
             success: (res) => resolve(formatMedia(res)),
             fail: reject
           })
+          // #endif
+          // #ifndef MP-WEIXIN || MP-TOUTIAO
+          uni.chooseImage({
+            count: multiple ? maxCount : 1,
+            sizeType,
+            sourceType,
+            // #ifdef H5
+            extension,
+            // #endif
+            success: (res) => resolve(formatImage(res)),
+            fail: reject
+          })
+          // #endif
           break
         case 'file':
+          // #ifdef MP-WEIXIN
           uni.chooseMessageFile({
             count: multiple ? (isDef(maxCount) ? maxCount : 100) : 1,
             type: accept,
@@ -303,8 +337,25 @@ export function useUpload(): UseUploadReturn {
             success: (res) => resolve(res.tempFiles),
             fail: reject
           })
+          // #endif
+          // #ifdef MP-TOUTIAO
+          reject({
+            errMsg: 'chooseMessageFile is not supported in mp-toutiao'
+          })
+          // #endif
+          // #ifndef MP-WEIXIN || MP-TOUTIAO
+          uni.chooseImage({
+            count: multiple ? maxCount : 1,
+            sizeType,
+            sourceType,
+            // #ifdef H5
+            extension,
+            // #endif
+            success: (res) => resolve(formatImage(res)),
+            fail: reject
+          })
+          // #endif
           break
-        // #endif
         case 'all':
           // #ifdef H5
           uni.chooseFile({
@@ -324,6 +375,27 @@ export function useUpload(): UseUploadReturn {
             fail: reject
           })
           // #endif
+          // #ifdef MP-TOUTIAO
+          uni.chooseMedia({
+            count: multiple ? maxCount : 1,
+            mediaType: ['image', 'video'],
+            sourceType,
+            sizeType,
+            camera,
+            maxDuration,
+            success: (res) => resolve(formatMedia(res)),
+            fail: reject
+          })
+          // #endif
+          // #ifndef H5 || MP-WEIXIN || MP-TOUTIAO
+          uni.chooseImage({
+            count: multiple ? maxCount : 1,
+            sizeType,
+            sourceType,
+            success: (res) => resolve(formatImage(res)),
+            fail: reject
+          })
+          // #endif
 
           break
         default:

package/components/composables/useVirtualScroll.ts

@@ -37,6 +37,12 @@ export interface UseVirtualScrollReturn {
   onScroll: (scrollTopValue: number) => void
 }
 
+/**
+ * 虚拟滚动 Composable，基于 VirtualScrollEngine 实现高性能长列表渲染
+ * 支持虚拟/非虚拟模式切换、滚动到指定位置/元素/ID
+ * @param options - 配置项，包含 data、virtual、height、itemHeight、idKey、backToTopThreshold
+ * @returns 滚动状态、可见数据及控制方法
+ */
 export function useVirtualScroll(options: UseVirtualScrollOptions): UseVirtualScrollReturn {
   const { data, virtual, height, itemHeight, idKey, backToTopThreshold } = options
 
@@ -112,6 +118,7 @@ export function useVirtualScroll(options: UseVirtualScrollOptions): UseVirtualSc
     }
   }
 
+  /** 同步程序化滚动状态，更新内部滚动位置、回顶按钮显隐和可见数据 */
   function syncProgrammaticScrollState(scrollTopValue: number) {
     _scrollTop.value = scrollTopValue
     showBackTopBtn.value = scrollTopValue > backToTopThresholdInPx.value

package/components/composables/useWindowResize.ts

@@ -15,6 +15,15 @@ interface UseWindowResizeOptions {
   immediate?: boolean
 }
 
+/**
+ * 监听窗口大小变化。
+ *
+ * 封装 `uni.onWindowResize` / `uni.offWindowResize`，
+ * 在组件挂载时注册监听，卸载时自动移除。
+ *
+ * @param callback 窗口大小变化时的回调
+ * @param options 配置项：`immediate` 是否立即调用一次回调
+ */
 export function useWindowResize(callback: WindowResizeCallback, options: UseWindowResizeOptions = {}) {
   const { immediate = false } = options
 

package/components/oxy-action-sheet/index.scss

@@ -62,7 +62,7 @@
   margin-bottom: var(--window-bottom);
 
   @include when(float) {
-    margin: 0 20rpx calc(var(--window-bottom) + 20rpx);
+    margin: 0 $-spacing-20 calc(var(--window-bottom) + $-spacing-20);
     border-radius: $-action-sheet-radius;
     overflow: hidden;
   }
@@ -72,7 +72,7 @@
   }
 
   @include e(actions) {
-    padding: 20rpx 0;
+    padding: $-spacing-20 0;
     max-height: 50vh;
     overflow-y: auto;
     -webkit-overflow-scrolling: touch;
@@ -123,7 +123,7 @@
 
   @include e(subname) {
     display: inline-block;
-    margin-left: 12rpx;
+    margin-left: $-spacing-12;
     font-size: $-action-sheet-subname-fs;
     color: $-action-sheet-subname-color;
   }
@@ -140,7 +140,7 @@
     border: none;
     background: $-action-sheet-cancel-bg;
     outline: none;
-    margin: 0 auto 48rpx;
+    margin: 0 auto $-spacing-48;
     font-weight: $-action-sheet-weight;
 
     &:active {
@@ -177,7 +177,7 @@
     overflow-y: hidden;
 
     &:first-of-type {
-      margin-top: 40rpx;
+      margin-top: $-spacing-40;
     }
 
     &:last-of-type {

package/components/oxy-action-sheet/oxy-action-sheet.vue

@@ -59,7 +59,9 @@ export default {
   name: 'oxy-action-sheet',
   options: {
     addGlobalClass: true,
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     styleIsolation: 'shared'
   }
 }
@@ -105,6 +107,15 @@ function computedValue() {
   formatPanels.value = isPanelArray() ? [props.panels as Panel[]] : (props.panels as Panel[][])
 }
 
+/**
+ * 选择操作项/面板项。
+ * action 模式：跳过 disabled/loading 项，emit select 事件。
+ * panels 模式：区分单层面板和嵌套面板，分别 emit 对应 index。
+ * 若 closeOnClickAction 为 true，选择后自动关闭。
+ * @param rowIndex - 行索引
+ * @param type - 选择类型（'action' | 'panels'）
+ * @param colIndex - 列索引（panels 模式）
+ */
 function select(rowIndex: number, type: 'action' | 'panels', colIndex?: number) {
   if (type === 'action') {
     if (props.actions[rowIndex].disabled || props.actions[rowIndex].loading) {

package/components/oxy-backtop/index.scss

@@ -4,8 +4,8 @@
 @include b(backtop) {
   position: fixed;
   background-color: $-backtop-bg;
-  width: 80rpx;
-  height: 80rpx;
+  width: $-backtop-size;
+  height: $-backtop-size;
   display: flex;
   justify-content: center;
   align-items: center;

package/components/oxy-backtop/oxy-backtop.vue

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

package/components/oxy-badge/oxy-badge.vue

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

package/components/oxy-badge/types.ts

@@ -11,6 +11,9 @@ export const badgeProps = {
   modelValue: numericProp,
   /** 当数值为 0 时，是否展示徽标 */
   showZero: makeBooleanProp(false),
+  /**
+   * 背景颜色
+   */
   bgColor: String,
   /**
    * 最大值，超过最大值会显示 '{max}+'，要求 value 是 Number 类型