@zfqh/uview-x 0.0.6 → 0.0.8

package/types/index.d.ts

@@ -1,59 +1,68 @@
-/**
- * @zfqh/uview-x 全局注入类型声明。
- *
- * 入口 `index.ts` 会把 `$uv` 挂到 `uni.$uv` 与 `app.config.globalProperties.$uv`；
- * `utils/locale.ts` 的 `createI18n` 会把 i18n 实例挂到 `uni.$i18n`。
- * 本文件为 uni 全局对象与 Vue 组件实例补充类型，并声明入口默认插件类型与 i18n 公共 API。
- */
-import type { App } from 'vue';
-import type { I18n, I18nOptions } from 'vue-i18n';
-
-type UviewX$uv = (typeof import('../utils'))['$uv'];
-
-declare global {
-  interface Uni {
-    $uv: UviewX$uv;
-    /** `createI18n` 创建的全局 i18n 实例 */
-    $i18n?: I18n;
-  }
-}
-
-declare module '*.ttf' {
-  const src: string;
-  export default src;
-}
-
-declare module '*.otf' {
-  const src: string;
-  export default src;
-}
-
-declare module 'vue' {
-  interface ComponentCustomProperties {
-    $uv: UviewX$uv;
-  }
-}
-
-/**
- * 入口模块声明：包内 `types` 指向本文件时，消费者仍可从入口
- * `import { config, createI18n, useI18n, setLocale, ... } from '@zfqh/uview-x'` 获得类型提示。
- *
- * 这里声明 `config` 与 4 个 i18n 公共函数 + `useI18n`；包内其余 helper、内部状态与 default/fallback 语言均不对外导出。
- */
-declare module '@zfqh/uview-x' {
-  /** 运行时配置；颜色通过 `config.color` 访问（键为 camelCase，如 `primary`）；H5 滚动条通过 `config.scrollbar` 控制（默认隐藏） */
-  export const config: (typeof import('../utils'))['config'];
-  /** 创建 i18n 实例并挂到 `uni.$i18n`（仅注入并深合并默认中文 `zh-CN`；其他语言需自行 import 语言包后合并） */
-  export function createI18n(opts: I18nOptions): I18n;
-  /** 获取当前语言（storage `UNI_LOCALE` → `getAppBaseInfo` 的 `language` / `osLanguage` / `hostLanguage` → `zh-CN`） */
-  export function getLocale(): string;
-  /** 按当前语言取词（优先全局语言包，其次默认中文语言包；支持 `a.b.c` 路径与 `{name}` 占位符） */
-  export function getLocaleMessage(key: string, values?: Record<string, string | number>): string;
-  /** 设置当前语言：更新内部 localeState 与 `uni.$i18n.global.locale`，写 storage `UNI_LOCALE`，最后调用 `uni.setLocale` */
-  export function setLocale(locale: string): void;
-  /** i18n hook：未创建 i18n 实例时降级读默认中文语言包，不会抛错 */
-  export const useI18n: typeof import('vue-i18n').useI18n;
-}
-
-declare const plugin: { install: (app: App) => void };
-export default plugin;
+/**
+ * @zfqh/uview-x 全局注入类型声明。
+ *
+ * 入口不再注入 `$uv`；仅 `utils/locale.ts` 的 `createI18n` 会把 i18n 实例挂到 `uni.$i18n`。
+ * 本文件为 uni 全局对象补充类型，并声明入口插件、公共 API 与公共类型。
+ */
+import type { App } from 'vue';
+import type { I18n } from 'vue-i18n';
+
+declare global {
+  interface Uni {
+    /** `createI18n` 创建的全局 i18n 实例 */
+    $i18n?: I18n;
+  }
+}
+
+declare module '*.ttf' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.otf' {
+  const src: string;
+  export default src;
+}
+
+declare module '@zfqh/uview-x' {
+  export type { UViewConfigOptions, UViewColor, UViewConfig } from '../utils/config';
+  export type { UViewI18nMessages, UViewCreateI18nOptions, UViewI18nOptions } from '../utils/locale';
+  export type { UViewCompressOptions } from '../utils/compress';
+  export type { UViewDebounceFunction } from '../hooks/useDebounce';
+  export type { UViewThrottleFunction } from '../hooks/useThrottle';
+
+  /** 运行时配置；颜色通过 `config.color` 访问（键为 camelCase，如 `primary`）；H5 滚动条通过 `config.scrollbar` 控制（默认隐藏） */
+  export const config: (typeof import('../utils/config'))['default'];
+  /** 修改运行时配置；可同时传 `i18n` 初始化组件多语言 */
+  export function setConfig(options?: import('../utils/config').UViewConfigOptions): void;
+
+  export { default as compress } from '../utils/compress';
+  export { default as debounce } from '../utils/debounce';
+  export { default as http } from '../utils/http';
+  export { default as throttle } from '../utils/throttle';
+  export * from '../utils/route';
+  export const test: typeof import('../utils/test');
+
+  /** 创建 i18n 实例并挂到 `uni.$i18n`（默认注入并合并内置英文 `en`；messages 使用扁平 locale 包，可覆盖初始化配置） */
+  export function createI18n(opts?: import('../utils/locale').UViewCreateI18nOptions): I18n;
+  /** 获取当前语言（storage `UNI_LOCALE` → `uni.getLocale` → `getAppBaseInfo.appLanguage` → `en`） */
+  export function getLocale(): string;
+  /** 按当前语言取词（优先全局语言包，其次内置/初始化语言包；支持扁平 `uv.*` key 与 `{name}` 占位符） */
+  export function getLocaleMessage(key: string, values?: Record<string, string | number>): string;
+  /** 设置当前语言：更新内部 localeState 与 `uni.$i18n.global.locale`，写 storage `UNI_LOCALE`，最后调用 `uni.setLocale` */
+  export function setLocale(locale: string): void;
+
+  /** 实例级防抖 */
+  export { default as useDebounce } from '../hooks/useDebounce';
+  /** 实例级节流 */
+  export { default as useThrottle } from '../hooks/useThrottle';
+  /** i18n hook：未创建 i18n 实例时降级读内置/初始化语言包，不会抛错 */
+  export { default as useI18n } from '../hooks/useI18n';
+
+  export interface UViewPlugin {
+    install(app: App, options?: import('../utils/config').UViewConfigOptions): void;
+  }
+}
+
+declare const plugin: UViewPlugin;
+export default plugin;

package/utils/color.ts

@@ -0,0 +1,139 @@
+/**
+ * 求两个颜色之间的渐变值
+ * @param {string} startColor 开始的颜色
+ * @param {string} endColor 结束的颜色
+ * @param {number} step 颜色等分的份额
+ * */
+export function colorGradient(startColor = 'rgb(0, 0, 0)', endColor = 'rgb(255, 255, 255)', step = 10): string[] {
+  const startRGB = hexToRgb(startColor, false) as number[]; // 转换为rgb数组模式
+  const startR = startRGB[0];
+  const startG = startRGB[1];
+  const startB = startRGB[2];
+
+  const endRGB = hexToRgb(endColor, false) as number[];
+  const endR = endRGB[0];
+  const endG = endRGB[1];
+  const endB = endRGB[2];
+
+  const sR = (endR - startR) / step; // 总差值
+  const sG = (endG - startG) / step;
+  const sB = (endB - startB) / step;
+  const colorArr = [];
+  for (let i = 0; i < step; i++) {
+    // 计算每一步的hex值
+    let hex = rgbToHex(
+      `rgb(${Math.round(sR * i + startR)},${Math.round(sG * i + startG)},${Math.round(sB * i + startB)})`,
+    );
+    // 确保第一个颜色值为startColor的值
+    if (i === 0) hex = rgbToHex(startColor);
+    // 确保最后一个颜色值为endColor的值
+    if (i === step - 1) hex = rgbToHex(endColor);
+    colorArr.push(hex);
+  }
+  return colorArr;
+}
+
+/**
+ * 将颜色转换为 RGB。
+ *
+ * @param sColor 颜色字符串，支持 `#rgb`、`#rrggbb`、`rgb(...)`。
+ * @param str 为 `true`（默认）时返回 `rgb(r,g,b)` 字符串；为 `false` 时返回 `[r,g,b]` 数组。
+ * @returns `str=false` 时返回 RGB 数组；否则返回 rgb 字符串；无法识别的颜色原样返回。
+ */
+export function hexToRgb(sColor: string, str = true): string | number[] {
+  const reg = /^#([0-9a-fA-f]{3}|[0-9a-fA-f]{6})$/;
+  sColor = String(sColor).toLowerCase();
+  if (sColor && reg.test(sColor)) {
+    if (sColor.length === 4) {
+      let sColorNew = '#';
+      for (let i = 1; i < 4; i += 1) {
+        sColorNew += sColor.slice(i, i + 1).concat(sColor.slice(i, i + 1));
+      }
+      sColor = sColorNew;
+    }
+    // 处理六位的颜色值
+    const sColorChange = [];
+    for (let i = 1; i < 7; i += 2) {
+      sColorChange.push(parseInt(`0x${sColor.slice(i, i + 2)}`));
+    }
+    if (!str) {
+      return sColorChange;
+    }
+    return `rgb(${sColorChange[0]},${sColorChange[1]},${sColorChange[2]})`;
+  }
+  if (/^(rgb|RGB)/.test(sColor)) {
+    const arr = sColor.replace(/(?:\(|\)|rgb|RGB)*/g, '').split(',');
+    return arr.map((val) => Number(val));
+  }
+  return sColor;
+}
+
+// 将rgb表示方式转换为hex表示方式
+export function rgbToHex(rgb: string): string {
+  const _this = rgb;
+  const reg = /^#([0-9a-fA-f]{3}|[0-9a-fA-f]{6})$/;
+  if (/^(rgb|RGB)/.test(_this)) {
+    const aColor = _this.replace(/(?:\(|\)|rgb|RGB)*/g, '').split(',');
+    let strHex = '#';
+    for (let i = 0; i < aColor.length; i++) {
+      let hex = Number(aColor[i]).toString(16);
+      hex = String(hex).length == 1 ? `${0}${hex}` : hex; // 保证每个rgb的值为2位
+      if (hex === '0') {
+        hex += hex;
+      }
+      strHex += hex;
+    }
+    if (strHex.length !== 7) {
+      strHex = _this;
+    }
+    return strHex;
+  }
+  if (reg.test(_this)) {
+    const aNum = _this.replace(/#/, '').split('');
+    if (aNum.length === 6) {
+      return _this;
+    }
+    if (aNum.length === 3) {
+      let numHex = '#';
+      for (let i = 0; i < aNum.length; i += 1) {
+        numHex += aNum[i] + aNum[i];
+      }
+      return numHex;
+    }
+  } else {
+    return _this;
+  }
+  // 合法 hex 但长度不是 3/6 时保持原值返回，保证返回类型为 string
+  return _this;
+}
+
+/**
+ * JS颜色十六进制转换为rgb或rgba,返回的格式为 rgba（255，255，255，0.5）字符串
+ * sHex为传入的十六进制的色值
+ * alpha为rgba的透明度
+ */
+export function colorToRgba(color: string, alpha: number): string {
+  color = rgbToHex(color);
+  // 十六进制颜色值的正则表达式
+  const reg = /^#([0-9a-fA-f]{3}|[0-9a-fA-f]{6})$/;
+  /* 16进制颜色转为RGB格式 */
+  let sColor = String(color).toLowerCase();
+  if (sColor && reg.test(sColor)) {
+    if (sColor.length === 4) {
+      let sColorNew = '#';
+      for (let i = 1; i < 4; i += 1) {
+        sColorNew += sColor.slice(i, i + 1).concat(sColor.slice(i, i + 1));
+      }
+      sColor = sColorNew;
+    }
+    // 处理六位的颜色值
+    const sColorChange = [];
+    for (let i = 1; i < 7; i += 2) {
+      sColorChange.push(parseInt(`0x${sColor.slice(i, i + 2)}`));
+    }
+    // return sColorChange.join(',')
+    return `rgba(${sColorChange.join(',')},${alpha})`;
+  }
+
+  return sColor;
+}

package/utils/compress.ts

@@ -1,34 +1,34 @@
-export interface CompressOptions {
-	width?: number | string
-	height?: number | string
+export interface UViewCompressOptions {
+  width?: number | string;
+  height?: number | string;
 }
 
-function image(url: string, style?: CompressOptions): string {
-	url = String(url || '')
-	if (/^https?:\/\//.test(url)) {
-		const { width, height } = style || {}
-		let params = ''
-		if (/\d+(r?px)?$/.test(String(width))) {
-			const size = Number.parseFloat(String(width))
-			params = `imageMogr2/thumbnail/${size}x/format/webp`
-		} else if (/\d+(r?px)?$/.test(String(height))) {
-			const size = Number.parseFloat(String(height))
-			params = `imageMogr2/thumbnail/x${size}/format/webp`
-		}
-		if (params) {
-			if (url.lastIndexOf('?') === -1) {
-				return `${url}?${params}`
-			}
-			if (url.lastIndexOf('imageMogr2/') === -1) {
-				return `${url}&${params}`
-			}
-		}
-	}
-	return url
+function image(url: string, style?: UViewCompressOptions): string {
+  url = String(url || '');
+  if (/^https?:\/\//.test(url)) {
+    const { width, height } = style || {};
+    let params = '';
+    if (/\d+(r?px)?$/.test(String(width))) {
+      const size = Number.parseFloat(String(width));
+      params = `imageMogr2/thumbnail/${size}x/format/webp`;
+    } else if (/\d+(r?px)?$/.test(String(height))) {
+      const size = Number.parseFloat(String(height));
+      params = `imageMogr2/thumbnail/x${size}/format/webp`;
+    }
+    if (params) {
+      if (url.lastIndexOf('?') === -1) {
+        return `${url}?${params}`;
+      }
+      if (url.lastIndexOf('imageMogr2/') === -1) {
+        return `${url}&${params}`;
+      }
+    }
+  }
+  return url;
 }
 
 const compress: { image: typeof image } = {
-	image
-}
+  image,
+};
 
-export default compress
+export default compress;

package/utils/config.ts

@@ -1,9 +1,11 @@
 // #ifndef APP-NVUE
 import vars from '../styles/var.module.scss';
 // #endif
-import type { UviewXScrollbar } from './scrollbar';
+import { deepMerge } from './merge';
+import type { UViewI18nOptions } from './locale';
+import type { Scrollbar } from './scrollbar';
 
-export interface UviewXColor {
+export interface UViewColor {
   primary: string;
   primaryDark: string;
   primaryDisabled: string;
@@ -35,26 +37,42 @@ export interface UviewXColor {
   [key: string]: string;
 }
 
-export type UviewXProps = Record<string, Record<string, unknown>>;
+export type Props = Record<string, Record<string, unknown>>;
 
-export interface UviewXConfig {
+export interface UViewConfig {
   // 主题名称
   type: string[];
   // 颜色部分，本来可以通过 scss 的 :export 导出供 js 使用，但是 nvue 不支持
-  color: UviewXColor;
+  color: UViewColor;
   // 组件默认 props，一次性合并进各组件的 props 定义
-  props: UviewXProps;
+  props: Props;
   // 默认单位，可以通过配置为 rpx，那么在用于传入组件大小参数为数值时，就默认为 rpx
   unit: string;
   // H5 全局滚动条：false 隐藏（默认）；true 使用默认样式；对象在默认样式上自定义
-  scrollbar: UviewXScrollbar;
+  scrollbar: Scrollbar;
 }
 
-export type UviewXColorConfig = Partial<UviewXColor>;
+export type UViewConfigOptions = Omit<Partial<UViewConfig>, 'color' | 'props'> & {
+  /** 修改内置 color 属性（与默认色板深合并） */
+  color?: Partial<UViewColor>;
+  /** 修改组件默认 props（与已有 props 深合并） */
+  props?: Props;
+  /** 组件多语言初始化配置 */
+  i18n?: UViewI18nOptions;
+};
+
+type I18nConfigHandler = (options: UViewI18nOptions) => void;
+
+let i18nConfigHandler: I18nConfigHandler | undefined;
+
+/** 由 utils/locale.ts 注册 i18n 配置处理器，避免 config ↔ locale 的值循环 */
+export function registerI18nConfigHandler(handler: I18nConfigHandler): void {
+  i18nConfigHandler = handler;
+}
 
 // 兜底色板与 styles/theme.scss 默认值保持一致（nvue 无法读取 SCSS，使用常量兜底）；
 // 非 nvue 端会由 var.module.scss 覆盖为实际主题色。
-const color: UviewXColor = {
+const color: UViewColor = {
   primary: '#3c9cff',
   primaryDark: '#398ade',
   primaryDisabled: '#9acafc',
@@ -88,8 +106,8 @@ const color: UviewXColor = {
 // #ifndef APP-NVUE
 Object.assign(color, vars);
 // #endif
-
-const config: UviewXConfig = {
+console.log(vars)
+const config: UViewConfig = {
   type: ['primary', 'success', 'info', 'error', 'warning'],
   color,
   props: {},
@@ -97,4 +115,21 @@ const config: UviewXConfig = {
   scrollbar: false,
 };
 
+/**
+ * 修改 uview-x 运行时配置。
+ *
+ * - 运行时字段按现有深合并语义写入 config；
+ * - `i18n` 交给 utils/locale.ts 注册的处理器；
+ * - 与 `app.use(UviewX, options)` 共用同一实现。
+ */
+export function setConfig(options: UViewConfigOptions = {}): void {
+  const { i18n, ...configOptions } = options;
+  if (Object.keys(configOptions).length > 0) {
+    Object.assign(config, deepMerge(config, configOptions as Partial<UViewConfig>));
+  }
+  if (i18n && i18nConfigHandler) {
+    i18nConfigHandler(i18n);
+  }
+}
+
 export default config;

package/utils/debounce.ts

@@ -1,7 +1,7 @@
-import { useDebounce } from '../hooks/useDebounce'
-import type { DebounceFunction } from '../hooks/useDebounce'
+import useDebounce from '../hooks/useDebounce';
+import type { UViewDebounceFunction } from '../hooks/useDebounce';
 
 // 兼容旧用法：模块级共享实例，复用 useDebounce 实现
-const debounce: DebounceFunction = useDebounce()
+const debounce: UViewDebounceFunction = useDebounce();
 
-export default debounce
+export default debounce;

package/utils/function.ts

@@ -1,8 +1,9 @@
 import { number, empty } from './test';
 import { round } from './digit';
 import config from './config';
-import type { UviewXColor, UviewXConfig, UviewXProps } from './config';
 import { appTranslate } from './locale';
+
+export { deepClone, deepMerge } from './merge';
 /**
  * @description 如果value小于min，取min；如果value大于max，取max
  * @param {number} min
@@ -189,15 +190,22 @@ export function $parent(this: any, name?: string): any | false {
  * 对象转字符串，或者字符串转对象
  * @param {object | string} customStyle 需要转换的目标
  * @param {String} target 转换的目的，object-转为对象，string-转为字符串
- * @returns {object|string}
+ * @returns {object|string} target 为 object 时返回对象，为 string 时返回字符串
  */
+export function addStyle(customStyle: string | Record<string, any>, target: 'string'): string;
+export function addStyle(customStyle: string | Record<string, any>, target?: 'object'): Record<string, any>;
+export function addStyle(
+  customStyle: string | Record<string, any>,
+  target: 'object' | 'string',
+): Record<string, any> | string;
 export function addStyle(
   customStyle: string | Record<string, any>,
   target: 'object' | 'string' = 'object',
 ): Record<string, any> | string {
+  // 空值按目标类型归一，保证 target=object 时始终返回对象、target=string 时始终返回字符串
+  if (empty(customStyle)) return target === 'string' ? '' : {};
   // 字符串转字符串，对象转对象情形，直接返回
   if (
-    empty(customStyle) ||
     (typeof customStyle === 'object' && target === 'object') ||
     (target === 'string' && typeof customStyle === 'string')
   ) {
@@ -243,75 +251,6 @@ export function addUnit(value: string | number = 'auto', unit: string = config.u
   return number(value) ? `${value}${unit}` : value;
 }
 
-/**
- * @description 深度克隆
- * @param {object} obj 需要深度克隆的对象
- * @param cache 缓存
- * @returns {*} 克隆后的对象或者原值（不是对象）
- */
-export function deepClone<T>(obj: T, cache: WeakMap<object, any> = new WeakMap()): T {
-  if (obj === null || typeof obj !== 'object') return obj;
-  if (cache.has(obj)) return cache.get(obj);
-  let clone;
-  if (obj instanceof Date) {
-    clone = new Date(obj.getTime());
-  } else if (obj instanceof RegExp) {
-    clone = new RegExp(obj);
-  } else if (obj instanceof Map) {
-    clone = new Map(Array.from(obj, ([key, value]) => [key, deepClone(value, cache)]));
-  } else if (obj instanceof Set) {
-    clone = new Set(Array.from(obj, (value) => deepClone(value, cache)));
-  } else if (Array.isArray(obj)) {
-    clone = obj.map((value) => deepClone(value, cache));
-  } else if (Object.prototype.toString.call(obj) === '[object Object]') {
-    clone = Object.create(Object.getPrototypeOf(obj));
-    cache.set(obj, clone);
-    for (const [key, value] of Object.entries(obj)) {
-      clone[key] = deepClone(value, cache);
-    }
-  } else {
-    clone = Object.assign({}, obj);
-  }
-  cache.set(obj, clone);
-  return clone;
-}
-
-/**
- * @description JS对象深度合并
- * @param {object} target 需要拷贝的对象
- * @param {object} source 拷贝的来源对象
- * @returns {object|boolean} 深度合并后的对象或者false（入参有不是对象）
- */
-export function deepMerge<T extends object>(target: T = {} as T, source: Partial<T> = {}): T {
-  target = deepClone(target);
-  if (typeof target !== 'object' || target === null || typeof source !== 'object' || source === null) return target;
-  const merged: Record<string, any> = Array.isArray(target)
-    ? (target.slice() as unknown as Record<string, any>)
-    : Object.assign({}, target);
-  const sourceRecord = source as Record<string, any>;
-  for (const prop in sourceRecord) {
-    if (!Object.prototype.hasOwnProperty.call(sourceRecord, prop)) continue;
-    const sourceValue = sourceRecord[prop];
-    const targetValue = merged[prop];
-    if (sourceValue instanceof Date) {
-      merged[prop] = new Date(sourceValue);
-    } else if (sourceValue instanceof RegExp) {
-      merged[prop] = new RegExp(sourceValue);
-    } else if (sourceValue instanceof Map) {
-      merged[prop] = new Map(sourceValue);
-    } else if (sourceValue instanceof Set) {
-      merged[prop] = new Set(sourceValue);
-    } else if (typeof sourceValue === 'object' && sourceValue !== null) {
-      // 目标是原始值 / null 时，用对象源替换；避免 `false`、`undefined` 等无法被深合并
-      const mergedTarget = typeof targetValue === 'object' && targetValue !== null ? targetValue : {};
-      merged[prop] = deepMerge(mergedTarget, sourceValue);
-    } else {
-      merged[prop] = sourceValue;
-    }
-  }
-  return merged as T;
-}
-
 /**
  * @description error提示
  * @param {*} err 错误内容
@@ -753,20 +692,3 @@ export function getHistoryPage(back = 0): ReturnType<typeof getCurrentPages>[num
   const len = pages.length;
   return pages[len - 1 + back];
 }
-
-/**
- * @description 修改 uview-x 运行时内置属性值
- *
- * 直接传 config 字段：
- * `setConfig({ unit: 'rpx', type: [...], scrollbar: true, color: {...}, props: {...} })`
- */
-export type SetConfigOptions = Omit<Partial<UviewXConfig>, 'color' | 'props'> & {
-  /** 修改内置 color 属性（与默认色板深合并） */
-  color?: Partial<UviewXColor>;
-  /** 修改组件默认 props（与已有 props 深合并） */
-  props?: UviewXProps;
-};
-
-export function setConfig(options: SetConfigOptions = {}): void {
-  Object.assign(config, deepMerge(config, options as Partial<UviewXConfig>));
-}