@zfqh/uview-x 0.0.0-stage → 0.0.1

package/utils/http.ts

@@ -0,0 +1,5 @@
+import Request from '../libs/luch-request'
+
+const http = new Request()
+
+export default http

package/utils/index.ts

@@ -0,0 +1,57 @@
+import * as utils from './function';
+import * as test from './test';
+import * as colorGradientModule from './colorGradient';
+import { route } from './route';
+import config from './config';
+import http from './http';
+import compress from './compress';
+import platform from './platform';
+import debounce from './debounce';
+import throttle from './throttle';
+
+/**
+ * uview-x 工具聚合对象。
+ *
+ * - 组件通过 `import { $uv } from '../../utils'` 使用，模板中沿用 `$uv.addStyle()` 等写法；
+ * - 包入口（`index.ts`）通过 `export * from './utils'` 统一出口，并负责全局注入：
+ *   入口把 `$uv` 挂到 `uni` 全局对象，`install` 内再挂载到 `app.config.globalProperties.$uv`；
+ * - 组件/工具内部仍必须显式具名导入，不依赖全局对象；
+ * - 单位读取 `$uv.config.unit`，运行时修改 `config.unit` 后立即生效。
+ */
+export const $uv = {
+  route,
+  config,
+  test,
+  compress,
+  date: utils.timeFormat,
+  ...utils,
+  colorGradient: colorGradientModule.colorGradient,
+  hexToRgb: colorGradientModule.hexToRgb,
+  rgbToHex: colorGradientModule.rgbToHex,
+  colorToRgba: colorGradientModule.colorToRgba,
+  http,
+  debounce,
+  throttle,
+  platform,
+};
+
+// 保持原有入口的具名导出（命名空间形式）
+export { utils, test, colorGradientModule, route, config, http, compress, platform, debounce, throttle };
+
+// 所有工具方法扁平导出，可直接从 `@zfqh/uview-x` 具名导入
+export * from './function';
+export * from './test';
+export * from './digit';
+export * from './compat';
+// i18n 只对外暴露 4 个公共 API，其余 helper / 内部状态不导出（见 utils/locale.ts）
+export { createI18n, getLocale, getLocaleMessage, setLocale } from './locale';
+export { colorGradient, hexToRgb, rgbToHex, colorToRgba } from './colorGradient';
+// `utils/function.ts` 与 `utils/test.ts` 都存在 `range`：入口取主工具实现，
+// `test.range` 仍可通过 `test` 命名空间或深引用 `utils/test.ts` 使用。
+export { range } from './function';
+
+// 对外类型：工具配置、路由、压缩与平台
+export type { UviewXConfig } from './config';
+export type { CompressOptions } from './compress';
+export type { RouteFunction, RouteOptions, RouteParams, RouteType } from './route';
+export type { UviewXPlatform } from './platform';

package/utils/locale.ts

@@ -0,0 +1,296 @@
+import { ref } from 'vue';
+import type { Ref } from 'vue';
+import { createI18n as _createI18n } from 'vue-i18n';
+import type { I18n, I18nOptions } from 'vue-i18n';
+import { getBuiltinMessage, mergeComponentMessages } from '../locales';
+
+/**
+ * 国际化能力（组件内置语言包 + 4 个公共 API）。
+ *
+ * 公共 API（由 `utils/index.ts` 导出到包入口）：
+ * `createI18n`、`getLocale`、`getLocaleMessage`、`setLocale`。
+ *
+ * 其余导出（`localeState`、`getI18nGlobal`、`getI18nMessages`、`appTranslate`、`unwrapI18nValue`
+ * 与 `I18nMessageValue` / `I18nMessages` / `I18nGlobalLike`）是包内实现的 internal helper，
+ * 供 components / hooks / locales 深引用，不进入 barrel 与 `types/index.d.ts`。
+ */
+
+/** i18n 消息树：值为字符串，或继续嵌套的对象 */
+export type I18nMessageValue = string | { [key: string]: I18nMessageValue };
+
+/** 语言包：语言 → 消息树 */
+export type I18nMessages = Record<string, I18nMessageValue>;
+
+/** 兼容 vue-i18n legacy / composition 两种 global 形态的运行时视图 */
+export interface I18nGlobalLike {
+  t: (key: string, values?: Record<string, string | number>) => string;
+  locale: string | { value: string };
+  messages: I18nMessages | { value: I18nMessages };
+}
+
+interface RefLike<T> {
+  value: T;
+}
+
+/**
+ * `uni` 全局对象的最小运行时视图（含 i18n 实例挂载点）。
+ *
+ * 对外 `$i18n` 声明在 `types/index.d.ts`；这里再留一份最小结构，保证其他包深引用
+ * `@zfqh/uview-x/utils/locale`（不会加载本包 types 入口）时仍能编译。
+ * 纯 Node / 单测环境可能没有 `uni` 全局，所有访问都要容错。
+ */
+interface UniWithI18n {
+  $i18n?: I18n;
+  getStorageSync?: (key: string) => unknown;
+  setStorageSync?: (key: string, value: unknown) => void;
+  getLocale?: () => string;
+  setLocale?: (locale: string) => void;
+  getAppBaseInfo?: () => { appLanguage?: string; language?: string };
+}
+
+/** 读取 uni 全局对象；不存在时返回 undefined */
+function getUni(): UniWithI18n | undefined {
+  return typeof uni === 'undefined' ? undefined : (uni as unknown as UniWithI18n);
+}
+
+/** 读取挂到 `uni.$i18n` 上的 i18n 实例 */
+function getUniI18n(): I18n | undefined {
+  const uniApi = getUni();
+  return uniApi ? uniApi.$i18n : undefined;
+}
+
+/** 语言持久化 key：App 端切换语言可能触发重启，必须先落盘 */
+const STORAGE_KEY = 'UNI_LOCALE';
+
+/** 回退语言（内部使用，不对外导出） */
+const fallbackLocale = 'zh-Hans';
+
+/** 读取上次选择的语言；storage 不可用或无有效值时返回空字符串 */
+function readStorageLocale(): string {
+  const uniApi = getUni();
+  if (uniApi && typeof uniApi.getStorageSync === 'function') {
+    try {
+      const stored: unknown = uniApi.getStorageSync(STORAGE_KEY);
+      if (typeof stored === 'string' && stored) {
+        return stored;
+      }
+    } catch (e) {
+      // storage 不可用时忽略，继续走系统语言
+    }
+  }
+  // #ifdef WEB || H5
+  // H5 nvue 页面上下文可能拿到非共享的 uni 存储视图，浏览器 localStorage 仍为同一来源
+  if (typeof localStorage !== 'undefined') {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        return stored;
+      }
+    } catch (e) {
+      // localStorage 不可用时忽略
+    }
+  }
+  // #endif
+  return '';
+}
+
+/**
+ * 获取当前语言。
+ *
+ * 顺序：
+ * 1. 本地存储 `UNI_LOCALE`（用户上次通过 `setLocale` 选择的语言）；
+ * 2. `uni.getLocale()`（H5 / 小程序 / 经典 App）；
+ * 3. `uni.getAppBaseInfo().appLanguage`（uni-app x App）；
+ * 4. `uni.getAppBaseInfo().language`（经典端已废弃字段，兜底）；
+ * 5. `zh-Hans`。
+ */
+export function getLocale(): string {
+  const stored = readStorageLocale();
+  if (stored) {
+    return stored;
+  }
+  const uniApi = getUni();
+  if (uniApi && typeof uniApi.getLocale === 'function') {
+    const systemLocale = uniApi.getLocale();
+    if (systemLocale) {
+      return systemLocale;
+    }
+  }
+  if (uniApi && typeof uniApi.getAppBaseInfo === 'function') {
+    const info = uniApi.getAppBaseInfo();
+    const systemLocale = info.appLanguage || info.language;
+    if (systemLocale) {
+      return systemLocale;
+    }
+  }
+  return fallbackLocale;
+}
+
+/** 初始语言（内部使用，不对外导出） */
+const defaultLocale: string = getLocale();
+
+/**
+ * 当前语言的内部响应式状态（internal，不进 barrel）。
+ *
+ * - 无 i18n 实例时是 `appTranslate` / `useI18n` 的唯一语言来源；
+ * - 创建实例时用 `opts.locale` 初始化，`setLocale` 时同步更新，保证语言切换后组件重新渲染。
+ */
+export const localeState: Ref<string> = ref<string>(defaultLocale);
+
+/** 兼容 vue-i18n legacy（字符串）与 composition（Ref）两种模式，取出实际值 */
+export function unwrapI18nValue<T>(value: T | { value: T }): T {
+  if (value !== null && typeof value === 'object' && 'value' in value) {
+    return (value as RefLike<T>).value;
+  }
+  return value as T;
+}
+
+function isI18nGlobalLike(value: unknown): value is I18nGlobalLike {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  return typeof (value as I18nGlobalLike).t === 'function';
+}
+
+/** 当前 `uni.$i18n.global` 的运行时视图；实例不存在时返回 undefined */
+export function getI18nGlobal(): I18nGlobalLike | undefined {
+  const global = getUniI18n()?.global;
+  return isI18nGlobalLike(global) ? global : undefined;
+}
+
+/** APP 下不支持动态变量，需要重写占位符替换 */
+function replacePlaceholders(str: string, values?: Record<string, string | number>): string {
+  if (!values || typeof str !== 'string') {
+    return str;
+  }
+  let out = str;
+  for (const k of Object.keys(values)) {
+    out = out.split(`{${k}}`).join(String(values[k]));
+  }
+  return out;
+}
+
+/** 按 `a.b.c` 路径从语言包中取消息 */
+function getMessage(messages: I18nMessages, locale: string, key: string): string | undefined {
+  const segments = String(key).split('.');
+  let current: I18nMessageValue | undefined = messages[locale];
+  for (const segment of segments) {
+    if (current == null || typeof current === 'string') {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return typeof current === 'string' ? current : undefined;
+}
+
+/**
+ * 翻译（App / 小程序 / 无 i18n 实例时的统一实现）。
+ *
+ * locale 优先级：storage `UNI_LOCALE` → `uni.$i18n.global.locale` → 内部 `localeState` → `zh-Hans`；
+ * 消息优先级：全局语言包（当前语言 → 回退语言）→ 组件内置语言包（当前语言 → 回退语言）→ key。
+ * storage 优先用于 nvue 等页面上下文模块副本不同、实例未共享的场景（setLocale 已先落盘）。
+ */
+export function appTranslate(key: string, values?: Record<string, string | number>): string {
+  const global = getI18nGlobal();
+  const messages = unwrapI18nValue(global?.messages) || {};
+  const globalLocale = String(unwrapI18nValue(global?.locale) || '');
+  const locale = readStorageLocale() || globalLocale || localeState.value || fallbackLocale;
+  const message = getMessage(messages, locale, key) || getMessage(messages, fallbackLocale, key);
+  if (message) {
+    return replacePlaceholders(message, values);
+  }
+  const builtin = getBuiltinMessage(locale, key, values) || getBuiltinMessage(fallbackLocale, key, values);
+  return builtin || key;
+}
+
+/**
+ * 创建 i18n 实例并挂到 `uni.$i18n`。
+ *
+ * - 自动把组件内置语言包合并进 `opts.messages`（用户同名 key 优先）；
+ * - App 端不依赖 vue-i18n 注入，直接把 `global.t` 替换为包内 `appTranslate`；
+ * - 用 `opts.locale` 初始化内部 `localeState`，无实例时也能保持语言一致。
+ */
+export function createI18n(opts: I18nOptions): I18n {
+  const mergedMessages: I18nMessages = mergeComponentMessages(opts.messages as I18nMessages | undefined);
+  const mergedOptions: I18nOptions = {
+    ...opts,
+    // #ifdef WEB || H5
+    // vue-i18n 9.1.9 的 globalInjection 默认 false；H5 开启后 app.use(i18n) 会注入
+    // `app.config.globalProperties.$i18n`，useI18n 才能检测到实例并走 vue-i18n 分支
+    //（可显式传 globalInjection: false 关闭；App / 小程序不需要，保持 vue-i18n 默认）
+    globalInjection: opts.globalInjection !== false,
+    // #endif
+    messages: mergedMessages,
+  } as unknown as I18nOptions;
+  const i18n: I18n = _createI18n(mergedOptions);
+  // #ifdef APP
+  i18n.global.t = appTranslate as unknown as typeof i18n.global.t;
+  // #endif
+  const uniApi = getUni();
+  if (uniApi) {
+    uniApi.$i18n = i18n;
+  }
+  if (typeof opts.locale === 'string' && opts.locale) {
+    localeState.value = opts.locale;
+  }
+  return i18n;
+}
+
+/** 当前语言包（兼容 composition 模式的 Ref；internal，不进 barrel） */
+export function getI18nMessages(): I18nMessages {
+  const messages = unwrapI18nValue(getI18nGlobal()?.messages);
+  return messages || {};
+}
+
+/**
+ * 设置当前语言。
+ *
+ * 顺序（关键，防止 App 端重启后丢失语言）：
+ * 1. 更新内部 `localeState`；
+ * 2. 更新项目自己的 `uni.$i18n.global.locale`（兼容 WritableComputedRef 写 `.value` / legacy 字符串）；
+ * 3. 写入 storage 的 `UNI_LOCALE`；
+ * 4. 最后才调用 `uni.setLocale`（App 端可能引起重启，此时前两步已落盘）。
+ *
+ * 注意：`useI18n()` 返回的 `locale` 的 setter 只更新 `global.locale` / `localeState`，不会调用本函数；
+ * 需要持久化 / 通知系统时请显式调用 `setLocale`。
+ */
+export function setLocale(locale: string): void {
+  localeState.value = locale;
+  const global = getI18nGlobal();
+  if (global) {
+    try {
+      const target: unknown = global.locale;
+      if (target && typeof target === 'object' && 'value' in target) {
+        (target as RefLike<string>).value = locale;
+      } else {
+        global.locale = locale;
+      }
+    } catch (e) {
+      // 实例不可写时忽略，继续持久化
+    }
+  }
+  const uniApi = getUni();
+  if (uniApi && typeof uniApi.setStorageSync === 'function') {
+    try {
+      uniApi.setStorageSync(STORAGE_KEY, locale);
+    } catch (e) {
+      // storage 不可用时忽略
+    }
+  }
+  if (uniApi && typeof uniApi.setLocale === 'function') {
+    try {
+      uniApi.setLocale(locale);
+    } catch (e) {
+      // App 端 setLocale 可能触发重启 / 平台不支持，忽略
+    }
+  }
+}
+
+/**
+ * 按当前语言取词（公共 API）。
+ * 统一走 `appTranslate`（优先读 `uni.$i18n` 语言包，其次组件内置语言包），
+ * 避免小程序端 vue-i18n runtime-only 构建缺少消息编译器导致翻译空白 / 占位符不插值。
+ */
+export function getLocaleMessage(key: string, values?: Record<string, string | number>): string {
+  return appTranslate(key, values);
+}

package/utils/platform.ts

@@ -0,0 +1,71 @@
+/**
+ * 运行平台判断（uni-app x 蒸汽模式 / H5 / 小程序）。
+ *
+ * 仅保留 x 支持的平台条件；旧版 VUE2、APP-PLUS、APP-NVUE、H5 宏不再使用。
+ */
+export type UviewXPlatform =
+	| 'none'
+	| 'vue3'
+	| 'app'
+	| 'app-nvue'
+	| 'h5'
+	| 'mp'
+	| 'weixin'
+	| 'alipay'
+	| 'baidu'
+	| 'toutiao'
+	| 'qq'
+	| 'kuaishou'
+	| '360'
+
+let platform: UviewXPlatform = 'none'
+
+// #ifdef VUE3
+platform = 'vue3'
+// #endif
+
+// #ifdef APP
+platform = 'app'
+// #endif
+
+// #ifdef APP-NVUE
+platform = 'app-nvue'
+// #endif
+
+// #ifdef WEB || H5
+platform = 'h5'
+// #endif
+
+// #ifdef MP
+platform = 'mp'
+// #endif
+
+// #ifdef MP-WEIXIN
+platform = 'weixin'
+// #endif
+
+// #ifdef MP-ALIPAY
+platform = 'alipay'
+// #endif
+
+// #ifdef MP-BAIDU
+platform = 'baidu'
+// #endif
+
+// #ifdef MP-TOUTIAO
+platform = 'toutiao'
+// #endif
+
+// #ifdef MP-QQ
+platform = 'qq'
+// #endif
+
+// #ifdef MP-KUAISHOU
+platform = 'kuaishou'
+// #endif
+
+// #ifdef MP-360
+platform = '360'
+// #endif
+
+export default platform

package/utils/route.ts

@@ -0,0 +1,142 @@
+/**
+ * 路由跳转方法，该方法相对于直接使用 uni.xxx 更简单快捷，
+ * 并支持路由拦截。
+ */
+import { queryParams, deepMerge, page } from './function'
+
+export type RouteType =
+	| 'navigateTo'
+	| 'to'
+	| 'redirectTo'
+	| 'redirect'
+	| 'switchTab'
+	| 'tab'
+	| 'reLaunch'
+	| 'launch'
+	| 'navigateBack'
+	| 'back'
+
+export interface RouteParams {
+	[key: string]: any
+	intercept?: boolean | ((config: RouteOptions, resolve: (next: boolean) => void) => void)
+}
+
+export interface RouteOptions {
+	type?: RouteType
+	url?: string
+	delta?: number
+	params?: RouteParams
+	animationType?: string
+	animationDuration?: number
+	intercept?: boolean | ((config: RouteOptions, resolve: (next: boolean) => void) => void)
+	events?: Record<string, (...args: any[]) => void>
+}
+
+export type RouteFunction = (
+	options?: string | RouteOptions,
+	params?: RouteParams
+) => Promise<void>
+
+type RouterConfig = Required<Pick<RouteOptions,
+	'type' | 'url' | 'delta' | 'params' | 'animationType' | 'animationDuration' | 'intercept' | 'events'>>
+
+class Router {
+	config: RouterConfig
+
+	constructor() {
+		this.config = {
+			type: 'navigateTo',
+			url: '',
+			delta: 1,
+			params: {},
+			animationType: 'pop-in',
+			animationDuration: 300,
+			intercept: false,
+			events: {}
+		}
+		// route 需要作为独立方法传递，先绑定 this
+		this.route = this.route.bind(this)
+	}
+
+	// 判断 url 前面是否有 "/"，如果没有则加上，否则无法跳转
+	addRootPath(url: string): string {
+		return url[0] === '/' ? url : `/${url}`
+	}
+
+	// 整合路由参数
+	mixinParam(url: string, params: RouteParams): string {
+		url = url && this.addRootPath(url)
+
+		let query = ''
+		if (/.*\/.*\?.*=.*/.test(url)) {
+			query = queryParams(params, false)
+			return url += `&${query}`
+		}
+		query = queryParams(params)
+		return url += query
+	}
+
+	// 对外的方法名称
+	async route(options: string | RouteOptions = {}, params: RouteParams = {}): Promise<void> {
+		let mergeConfig: RouteOptions = {}
+
+		if (typeof options === 'string') {
+			mergeConfig.url = this.mixinParam(options, params)
+			mergeConfig.type = 'navigateTo'
+		} else {
+			mergeConfig = deepMerge(this.config as RouteOptions, options)
+			mergeConfig.url = this.mixinParam(options.url as string, options.params as RouteParams)
+		}
+		if (mergeConfig.url === page()) return
+
+		if (params.intercept) {
+			mergeConfig.intercept = params.intercept
+		}
+		mergeConfig.params = params
+		mergeConfig = deepMerge(this.config as RouteOptions, mergeConfig)
+
+		if (typeof mergeConfig.intercept === 'function') {
+			const interceptor = mergeConfig.intercept
+			const isNext = await new Promise<boolean>((resolve) => {
+				interceptor(mergeConfig, resolve)
+			})
+			isNext && this.openPage(mergeConfig)
+		} else {
+			this.openPage(mergeConfig)
+		}
+	}
+
+	// 执行路由跳转
+	openPage(config: RouteOptions): void {
+		const {
+			url = '',
+			type,
+			delta,
+			animationType,
+			animationDuration,
+			events
+		} = config
+		if (type == 'navigateTo' || type == 'to') {
+			uni.navigateTo({
+				url,
+				animationType: animationType as any,
+				animationDuration,
+				events: events as any
+			})
+		}
+		if (type == 'redirectTo' || type == 'redirect') {
+			uni.redirectTo({ url })
+		}
+		if (type == 'switchTab' || type == 'tab') {
+			uni.switchTab({ url })
+		}
+		if (type == 'reLaunch' || type == 'launch') {
+			uni.reLaunch({ url })
+		}
+		if (type == 'navigateBack' || type == 'back') {
+			uni.navigateBack({ delta })
+		}
+	}
+}
+
+export const route: RouteFunction = (new Router()).route