oxy-uni-ui 2.1.1 → 2.1.3

package/components/oxy-image-preview/types.ts

@@ -0,0 +1,164 @@
+import type { ComponentPublicInstance, ExtractPropTypes, PropType } from 'vue'
+import { baseProps, makeBooleanProp, makeNumberProp, makeStringProp } from '../common/props'
+
+export type ImagePreviewCloseIconPosition = 'top-left' | 'top-right'
+
+export type ImagePreviewOptions = {
+  /**
+   * 图片地址列表
+   */
+  images?: string[]
+  /**
+   * 初始展示的图片下标
+   */
+  startPosition?: number
+  /**
+   * 是否显示页码
+   */
+  showIndex?: boolean
+  /**
+   * 是否循环切换
+   */
+  loop?: boolean
+  /**
+   * 是否显示关闭按钮
+   */
+  closeable?: boolean
+  /**
+   * 关闭图标名称
+   */
+  closeIcon?: string
+  /**
+   * 关闭图标位置
+   */
+  closeIconPosition?: ImagePreviewCloseIconPosition
+  /**
+   * 点击图片或蒙层是否关闭
+   */
+  closeOnClick?: boolean
+  /**
+   * 是否开启长按菜单
+   */
+  showMenuByLongpress?: boolean
+  /**
+   * 是否显示预览层
+   */
+  show?: boolean
+  /**
+   * 预览层级
+   */
+  zIndex?: number
+  /**
+   * 打开回调
+   */
+  onOpen?: () => void
+  /**
+   * 关闭回调
+   */
+  onClose?: () => void
+  /**
+   * 切换回调
+   */
+  onChange?: (index: number) => void
+  /**
+   * 长按回调
+   */
+  onLongPress?: (image: string) => void
+}
+
+export interface ImagePreview {
+  /**
+   * 打开图片预览
+   */
+  previewImage: (options: ImagePreviewOptions | string[]) => void
+  /**
+   * 关闭图片预览
+   */
+  closeImagePreview: () => void
+}
+
+export const imagePreviewProps = {
+  ...baseProps,
+  /**
+   * 指定实例标识
+   */
+  selector: makeStringProp(''),
+  /**
+   * 图片地址列表
+   */
+  images: {
+    type: Array as PropType<string[]>,
+    default: () => []
+  },
+  /**
+   * 初始展示的图片下标
+   */
+  startPosition: makeNumberProp(0),
+  /**
+   * 是否显示页码
+   */
+  showIndex: makeBooleanProp(true),
+  /**
+   * 是否循环切换
+   */
+  loop: makeBooleanProp(true),
+  /**
+   * 是否显示关闭按钮
+   */
+  closeable: makeBooleanProp(true),
+  /**
+   * 关闭图标名称
+   */
+  closeIcon: makeStringProp('close'),
+  /**
+   * 关闭图标位置
+   */
+  closeIconPosition: makeStringProp<ImagePreviewCloseIconPosition>('top-right'),
+  /**
+   * 点击图片或蒙层是否关闭
+   */
+  closeOnClick: makeBooleanProp(true),
+  /**
+   * 是否开启长按菜单
+   */
+  showMenuByLongpress: makeBooleanProp(true),
+  /**
+   * 打开回调
+   */
+  onOpen: Function as PropType<() => void>,
+  /**
+   * 关闭回调
+   */
+  onClose: Function as PropType<() => void>,
+  /**
+   * 切换回调
+   */
+  onChange: Function as PropType<(index: number) => void>,
+  /**
+   * 长按回调
+   */
+  onLongPress: Function as PropType<(image: string) => void>,
+  /**
+   * 预览层级
+   */
+  zIndex: makeNumberProp(1000)
+}
+
+export type ImagePreviewProps = ExtractPropTypes<typeof imagePreviewProps>
+
+export type ImagePreviewExpose = {
+  /**
+   * 打开图片预览
+   */
+  open: (options?: ImagePreviewOptions | string[]) => void
+  /**
+   * 关闭图片预览
+   */
+  close: () => void
+  /**
+   * 切换到指定图片
+   */
+  setActive: (index: number) => void
+}
+
+export type ImagePreviewInstance = ComponentPublicInstance<ImagePreviewProps, ImagePreviewExpose>

package/components/oxy-img/oxy-img.vue

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

package/components/oxy-img-cropper/index.scss

@@ -8,7 +8,7 @@
   left: 0;
   width: 100vw;
   height: 100vh;
-  z-index: 1;
+  z-index: $-z-index-sticky;
 
   // 裁剪框包裹器
   @include e(wrapper) {
@@ -202,7 +202,7 @@
     @include m(button) {
       position: relative;
       text-align: left;
-      margin: 0 40rpx;
+      margin: 0 $-spacing-40;
       padding-top: 4vh;
       box-sizing: border-box;
 

package/components/oxy-img-cropper/oxy-img-cropper.vue

@@ -69,7 +69,9 @@
 export default {
   name: 'oxy-img-cropper',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -170,6 +172,10 @@ const updateSystemInfo = (res?: WindowResizeResult) => {
   }
 }
 
+/**
+ * 计算裁剪布局。根据 aspectRatio 和窗口尺寸计算裁剪框（cutWidth/cutHeight），
+ * 裁剪框垂直居中于窗口上部 85% 区域，并初始化 canvas 输出尺寸和 exportScale。
+ */
 function updateCropLayout() {
   INIT_IMGWIDTH = props.imgWidth
   INIT_IMGHEIGHT = props.imgHeight

package/components/oxy-img-lazy/oxy-img-lazy.vue

@@ -55,7 +55,9 @@
 export default {
   name: 'oxy-img-lazy',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -196,6 +198,10 @@ const init = async () => {
 }
 
 // 检查组件是否在视口内
+/**
+ * 检查组件是否在视口内。通过 boundingClientRect 与窗口尺寸对比判断。
+ * @returns 是否在视口内
+ */
 const isComponentInViewport = (): Promise<boolean> => {
   return new Promise((resolve) => {
     try {
@@ -287,6 +293,9 @@ const setupScrollDetection = () => {
 }
 
 // 滚动时检查可见性
+/**
+ * 滚动停止后检查可见性。若未加载且进入视口则触发加载，用于 scroll-view/swiper 等场景的降级方案。
+ */
 const checkVisibilityOnScroll = async () => {
   if (status.value === 0) {
     // 只有在未加载状态下检查

package/components/oxy-index-anchor/index.scss

@@ -22,7 +22,7 @@
 
 @include b(index-anchor) {
   background-color: $-color-gray-2;
-  padding: 24rpx;
+  padding: $-spacing-24;
   font-size: $-fs-content;
   color: $-color-title;
 

package/components/oxy-index-anchor/oxy-index-anchor.vue

@@ -30,12 +30,12 @@ const { proxy } = getCurrentInstance()!
 const top = ref<number>(0)
 
 const isSticky = computed(() => {
-  return indexBar && indexBar.props.sticky && indexBar.anchorState.activeIndex === props.index
+  return indexBar.value && indexBar.value.props.sticky && indexBar.value.anchorState.activeIndex === props.index
 })
 
 function getInfo() {
   getRect(`#${indexAnchorId.value}`, false, proxy).then((res) => {
-    if (isDef(indexBar)) {
+    if (isDef(indexBar.value)) {
       top.value = Math.floor(res.top!)
     }
   })

package/components/oxy-index-bar/index.scss

@@ -30,7 +30,7 @@
     font-size: $-index-bar-index-font-size;
     font-weight: $-fw-medium;
     color: $-color-title;
-    padding: 12rpx 16rpx;
+    padding: $-spacing-12 $-spacing-16;
 
     @include when(active) {
       color: $-color-theme;

package/components/oxy-index-bar/oxy-index-bar.vue

@@ -75,6 +75,10 @@ let sidebarInfo = {
   indexHeight: 24
 }
 
+/**
+ * 初始化组件位置信息。
+ * 并行查询 indexBar 容器、侧边栏、索引项的 rect，用于后续滚动定位计算。
+ */
 function init() {
   setTimeout(() => {
     Promise.all([
@@ -93,6 +97,10 @@ onMounted(() => {
   init()
 })
 
+/**
+ * 处理滚动事件，根据当前 scrollTop 找到对应的锚点索引。
+ * 遍历子项 top 值，匹配 scrollTop 所在区间来确定 activeIndex。
+ */
 function hanleScroll(scrollEvent: any) {
   if (scrollState.touching) {
     return
@@ -110,6 +118,11 @@ function hanleScroll(scrollEvent: any) {
   scrollState.prevScrollTop = scrolltop
 }
 
+/**
+ * 根据触摸点的 pageY 坐标计算对应的侧边栏索引项。
+ * @param pageY - 触摸点的垂直坐标
+ * @returns 对应的子组件
+ */
 function getAnchorByPageY(pageY: number) {
   const y = pageY - sidebarInfo.offsetTop
   let idx = Math.floor(y / sidebarInfo.indexHeight)
@@ -139,6 +152,11 @@ async function handleTouchEnd(e: TouchEvent) {
   scrollState.touching = false
 }
 
+/**
+ * 设置滚动位置。
+ * 当目标位置与当前相同时，先重置到上一次位置再跳转，解决 scroll-view 同值不触发滚动的问题。
+ * @param top - 目标滚动位置
+ */
 function setScrollTop(top: number) {
   if (scrollState.scrollTop === top) {
     scrollState.scrollTop = scrollState.prevScrollTop

package/components/oxy-input/index.scss

@@ -158,6 +158,7 @@
   }
 
   @include when(disabled) {
+    opacity: $-opacity-disabled;
 
     .oxy-input__inner {
       color: $-input-disabled-color;
@@ -278,7 +279,7 @@
     position: absolute;
     top: 0;
     left: 0;
-    z-index: 2;
+    z-index: $-z-index-sticky;
     width: 100%;
     height: 100%;
   }

package/components/oxy-input/oxy-input.vue

@@ -80,7 +80,9 @@
 export default {
   name: 'oxy-input',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -171,18 +173,22 @@ const showWordCount = computed(() => {
  * 表单错误提示信息
  */
 const errorMessage = computed(() => {
-  if (form && props.prop && form.errorMessages && form.errorMessages[props.prop]) {
-    return form.errorMessages[props.prop]
+  if (form.value && props.prop && form.value.errorMessages && form.value.errorMessages[props.prop]) {
+    return form.value.errorMessages[props.prop]
   } else {
     return ''
   }
 })
 
 // 是否展示必填
+/**
+ * 判断是否显示必填标记
+ * 综合检查：props.required、props.rules 中的 required、以及 form.value 父组件的 rules
+ */
 const isRequired = computed(() => {
   let formRequired = false
-  if (form && form.props.rules) {
-    const rules = form.props.rules
+  if (form.value && form.value.props.rules) {
+    const rules = form.value.props.rules
     for (const key in rules) {
       if (Object.prototype.hasOwnProperty.call(rules, key) && key === props.prop && Array.isArray(rules[key])) {
         formRequired = rules[key].some((rule: FormItemRule) => rule.required)
@@ -237,6 +243,10 @@ function formatValue(value: string | number) {
 function togglePOxyVisible() {
   isPOxyVisible.value = !isPOxyVisible.value
 }
+/**
+ * 清空输入框。若 focusWhenClear 为 true，先失焦清空值，再重新聚焦，
+ * 确保小程序端键盘保持打开状态。
+ */
 async function handleClear() {
   focusing.value = false
   inputValue.value = ''
@@ -252,6 +262,10 @@ async function handleClear() {
   emit('update:modelValue', inputValue.value)
   emit('clear')
 }
+/**
+ * 失焦处理：延迟 150ms 等待 clear 操作完成
+ * 避免清空时重复触发 blur + clear 的连锁反应
+ */
 async function handleBlur() {
   // 等待150毫秒，clear执行完毕
   await pause(150)

package/components/oxy-input/types.ts

@@ -14,7 +14,13 @@ export type InputMode = 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'searc
 
 export const inputProps = {
   ...baseProps,
+  /**
+   * 自定义输入框外部样式类
+   */
   customInputClass: makeStringProp(''),
+  /**
+   * 自定义标签外部样式类
+   */
   customLabelClass: makeStringProp(''),
   // 原生属性
   /**

package/components/oxy-input-number/index.scss

@@ -29,6 +29,8 @@
 @include b(input-number) {
   display: inline-flex;
   align-items: center;
+  vertical-align: middle;
+  line-height: 1;
   user-select: none;
 
   @include e(action) {
@@ -82,7 +84,7 @@
     display: block;
     width: $-input-number-input-width;
     height: $-input-number-height;
-    padding: 0 4rpx;
+    padding: 0 $-spacing-4;
     box-sizing: border-box;
     z-index: 1;
     background: transparent;

package/components/oxy-input-number/oxy-input-number.vue

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

package/components/oxy-keyboard/index.scss

@@ -28,7 +28,7 @@
     justify-content: center;
     box-sizing: content-box;
     height: $-keyboard-title-height;
-    padding-top: 12rpx;
+    padding-top: $-spacing-12;
     color: $-keyboard-title-color;
     font-size: $-keyboard-title-font-size;
   }
@@ -45,7 +45,7 @@
 
   @include e(body) {
     display: flex;
-    padding: 12rpx 0 0 12rpx;
+    padding: $-spacing-12 0 0 $-spacing-12;
   }
 
   @include e(keys) {
@@ -57,7 +57,7 @@
   &-car {
     @include e(body) {
       display: flex;
-      padding: 12rpx 0 0 12rpx;
+      padding: $-spacing-12 0 0 $-spacing-12;
     }
   }
 

package/components/oxy-keyboard/key/index.vue

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

package/components/oxy-keyboard/oxy-keyboard.vue

@@ -45,7 +45,9 @@
 export default {
   name: 'oxy-keyboard',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -59,10 +61,12 @@ import OxyKey from './key/index.vue'
 import { keyboardProps, type Key, type CarKeyboardLang } from './types'
 import type { NumberKeyType } from './key/types'
 import { CAR_KEYBOARD_AREAS, CAR_KEYBOARD_KEYS } from './constants'
+import { useTranslate } from '../composables/useTranslate'
 
 const props = defineProps(keyboardProps)
 const emit = defineEmits(['update:visible', 'input', 'close', 'delete', 'update:modelValue', 'update:carLang'])
 const slots = useSlots()
+const { translate } = useTranslate('keyboard')
 
 const show = ref(props.visible)
 watch(
@@ -149,7 +153,7 @@ function genCarKeys(): Array<Key> {
   const [keys, remainKeys] = splitCarKeys()
   return [
     ...keys,
-    { text: carKeyboardLang.value === 'zh' ? 'ABC' : '省份', type: 'extra', wider: true },
+    { text: carKeyboardLang.value === 'zh' ? 'ABC' : translate('carProvince'), type: 'extra', wider: true },
     ...remainKeys,
     { text: props.deleteText, type: 'delete', wider: true }
   ]
@@ -165,11 +169,16 @@ const handleClose = () => {
   emit('update:visible', false)
 }
 
+/**
+ * 键盘按键处理：根据按键类型执行输入、删除、关闭、中英切换等操作
+ * @param text - 按键文本
+ * @param type - 按键类型：extra/delete/close
+ */
 const handlePress = (text: string, type: NumberKeyType) => {
   if (type === 'extra') {
     if (text === '') {
       return handleClose()
-    } else if (text === 'ABC' || text === '省份') {
+    } else if (text === 'ABC' || text === translate('carProvince')) {
       const newLang = carKeyboardLang.value === 'zh' ? 'en' : 'zh'
       if (props.carLang) {
         emit('update:carLang', newLang)

package/components/oxy-link/index.scss

@@ -4,8 +4,8 @@
 @include b(link) {
   display: inline-block;
 
-  @include m(medium) {
-    font-size: $-link-font-size-medium;
+  @include m(default) {
+    font-size: $-link-font-size-default;
   }
 
   @include m(small) {
@@ -20,6 +20,10 @@
     display: inline-block;
   }
 
+  @include e(content) {
+    display: inline-block;
+  }
+
   @include when(underline) {
     text-decoration: underline;
   }
@@ -49,10 +53,10 @@
   }
 
   .#{$B}__prefix-icon:not(:empty) + .#{$B}__content:not(:empty) {
-    padding-left: 8rpx;
+    padding-left: $-spacing-8;
   }
 
   .#{$B}__content:not(:empty) + .#{$B}__suffix-icon:not(:empty) {
-    padding-left: 8rpx;
+    padding-left: $-spacing-8;
   }
 }

package/components/oxy-link/oxy-link.vue

@@ -22,9 +22,9 @@
         <oxy-icon :size="fontSize" :color="color" :name="prefixIcon"></oxy-icon>
       </view>
     </slot>
-    <text class="oxy-link__content" ref="textRef">
+    <view class="oxy-link__content">
       <slot>{{ content }}</slot>
-    </text>
+    </view>
     <slot name="suffix-icon">
       <view class="oxy-link__icon oxy-link__suffix-icon" v-if="suffixIcon">
         <oxy-icon :size="fontSize" :color="color" :name="suffixIcon"></oxy-icon>
@@ -37,7 +37,9 @@
 export default {
   name: 'oxy-link',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -56,7 +58,7 @@ const emit = defineEmits(['click', 'success', 'fail', 'complete'])
 // 存储超链接类名的响应式变量
 const linkClass = ref<string>('')
 const fontSize = computed<string>(() => {
-  if (!['small', 'medium', 'large'].includes(props.size)) {
+  if (!['small', 'default', 'large'].includes(props.size)) {
     return props.size
   }
   return ''
@@ -109,6 +111,10 @@ function computeLinkClass() {
   linkClass.value = linkClassList.join(' ')
 }
 
+/**
+ * 点击处理。href 模式下根据平台差异处理外链跳转：
+ * APP-PLUS 使用 plus.runtime.openURL，H5 使用 window.open，小程序使用 uni.setClipboardData 复制链接。
+ */
 function handleClick(event: Event) {
   if (!props.url && props.href) {
     // #ifdef APP-PLUS

package/components/oxy-link/types.ts

@@ -3,7 +3,7 @@ import { baseProps, makeBooleanProp, makeStringProp } from '../common/props'
 
 export type OpenType = 'navigate' | 'redirect' | 'switchTab' | 'reLaunch' | 'navigateBack' | 'exit'
 export type LinkType = 'default' | 'primary' | 'error' | 'warning' | 'success'
-export type SizeEnum = 'small' | 'medium' | 'large'
+export type SizeEnum = 'small' | 'default' | 'large'
 
 export const linkProps = {
   ...baseProps,
@@ -54,7 +54,7 @@ export const linkProps = {
    * 类型：string
    * 默认值：'空字符串'
    */
-  size: makeStringProp<SizeEnum>('medium'),
+  size: makeStringProp<SizeEnum>('default'),
   /**
    * 文本颜色
    * 类型：string

package/components/oxy-list/oxy-list.vue

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

package/components/oxy-list/types.ts

@@ -7,6 +7,13 @@ import { virtualScrollProps } from '../oxy-virtual-scroll/types'
 export const listProps = {
   ...virtualScrollProps,
 
+  /**
+   * 加载更多状态，对应 oxy-loadmore 的 loadmoreState
+   * - `'loading'`：加载中
+   * - `'finished'`：全部加载完成
+   * - `'error'`：加载失败
+   * - `''`：不显示加载更多
+   */
   loadmoreState: String as PropType<LoadMoreState | ''>,
 
   /**

package/components/oxy-loading/oxy-loading.vue

@@ -9,7 +9,9 @@
 export default {
   name: 'oxy-loading',
   options: {
+    // #ifndef MP-TOUTIAO
     virtualHost: true,
+    // #endif
     addGlobalClass: true,
     styleIsolation: 'shared'
   }
@@ -81,6 +83,10 @@ onBeforeMount(() => {
   buildSvg()
 })
 
+/**
+ * 根据 type（ring/outline）和 color 构建 loading SVG 的 base64 编码。
+ * outline 类型仅使用主色，ring 类型使用主色和中间色渐变。
+ */
 function buildSvg() {
   const { type, color } = props
   let ringType: 'outline' | 'ring' = isDef(type) ? type : 'ring'

package/components/oxy-loadmore/index.scss

@@ -26,7 +26,7 @@
     vertical-align: middle;
 
     @include when(light) {
-      margin: 0 12rpx;
+      margin: $-loadmore-text-margin;
       color: $-loadmore-error-color;
     }
   }