@hlw-uni/mp-core 1.0.0

package/README.md

@@ -0,0 +1,229 @@
+# @hlw-uni/mp-core
+
+UniApp 运行时核心包，提供 `Composables`、`Utils`、`Components` 和统一的 `hlw` 全局命名空间，开箱即用。
+
+## 包含模块
+
+| 模块 | 说明 |
+|------|------|
+| **hlw 全局命名空间** | `hlw.$msg`、`hlw.$device`、`hlw.$http` — 在 `app.config.globalProperties` 中注入 |
+| **Composables** | `useHttp`、`useLoading`、`useMsg`、`useRefs`、`useDevice` |
+| **Utils** | `format`、`validate`、`storage`、`device` 工具函数 |
+| **Components** | `Avatar`、`Empty`、`Loading`、`MenuList` |
+
+## 安装
+
+```bash
+npm install @hlw-uni/mp-core
+```
+
+配合 `@hlw-uni/mp-vite-plugin` 使用，可自动注入环境变量、SCSS 主题和 Auto-Import。
+
+## hlw 全局命名空间
+
+通过 `app.config.globalProperties['hlw'] = hlw` 注入后，可在任何 Vue 上下文直接访问：
+
+```ts
+// 在 Options API 或模板中
+this.hlw.$msg.success('操作成功');
+this.hlw.$msg.confirm({ content: '确定删除？' });
+this.hlw.$device.platform;  // 'mp-weixin'
+this.hlw.$device.statusBarHeight;
+
+// 在 Composition API 中直接 import
+import { hlw } from '@hlw-uni/mp-core';
+hlw.$msg.toast('提示');
+```
+
+> 旧写法 `$msg` 和 `$device` 仍然保留兼容。
+
+## Composables
+
+### useHttp — HTTP 请求
+
+```ts
+import { useHttp } from '@hlw-uni/mp-core';
+
+const { loading, data, error, run, get, post } = useHttp();
+
+// GET 请求
+const res = await get<UserInfo>('/user/info');
+
+// POST 请求
+const res = await post('/user/login', { phone, code });
+
+// 状态追踪
+if (loading.value) { /* 显示加载态 */ }
+if (error.value) { /* 处理错误 */ }
+console.log(data.value);
+
+// 全局拦截器（建议在 main.ts 中集中配置）
+import { http } from '@hlw-uni/mp-core';
+http.onRequest((config) => {
+  const token = useUserStore().token;
+  if (token) config.headers!['token'] = token;
+  return config;
+});
+```
+
+请求会自动携带 `token`（从用户 store 读取）。401 时自动清除存储。
+
+> `VITE_API_BASE_URL` 通过 `@hlw-uni/mp-vite-plugin` 在编译时注入，无需手动配置。
+
+### useLoading — Loading 状态
+
+```ts
+import { useLoading } from '@hlw-uni/mp-core';
+
+const { loading, showLoading, hideLoading } = useLoading();
+
+showLoading('加载中...');
+const data = await fetchSomething();
+hideLoading();
+```
+
+### useMsg — 消息提示
+
+```ts
+import { useMsg } from '@hlw-uni/mp-core';
+
+const msg = useMsg();
+
+msg.success('保存成功');       // 成功提示
+msg.error('提交失败');         // 失败提示
+msg.toast({ message: '提示', position: 'top' });
+
+await msg.confirm({           // 确认对话框
+  title: '提示',
+  content: '确定要删除吗？',
+  confirmText: '确定',
+  cancelText: '取消',
+});
+```
+
+同时自动注入为 `this.hlw.$msg` 或 `this.$msg`。
+
+### useDevice — 设备信息
+
+```ts
+import { useDevice } from '@hlw-uni/mp-core';
+
+const device = useDevice();
+
+console.log(device.value.platform);     // 'mp-weixin'
+console.log(device.value.brand);         // 'weixin'
+console.log(device.value.statusBarHeight); // 20
+console.log(device.value.navBarHeight);   // 64 (statusBar + 44)
+```
+
+### useRefs — 模板 Refs
+
+```ts
+import { useRefs } from '@hlw-uni/mp-core';
+
+const { refs, setRefs } = useRefs();
+
+// 在 <template> 中使用
+// <view :ref="setRefs('item0')">...</view>
+// 访问: refs.value['item0']
+```
+
+## Utils
+
+### 格式化 (format)
+
+```ts
+import { formatDate, formatMoney, formatPhone, formatFileSize } from '@hlw-uni/mp-core';
+
+formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');  // '2026-04-05 12:00:00'
+formatMoney(1234567.89);                         // '1,234,567.89'
+formatPhone('13812345678');                      // '138****5678'
+formatFileSize(1024 * 1024 * 5);                // '5.00 MB'
+```
+
+### 校验 (validate)
+
+```ts
+import { validatePhone, validateEmail, validateUrl, validateIdCard, validateCarNumber, validatePassword, isEmpty } from '@hlw-uni/mp-core';
+
+validatePhone('13812345678');   // true
+validateEmail('test@example.com'); // true
+validateUrl('https://example.com'); // true
+validateIdCard('110101199001011234'); // true
+validateCarNumber('京A12345');     // true
+validatePassword('Abc12345');     // true
+isEmpty(null);                    // true
+isEmpty({});                      // true
+```
+
+### 存储 (storage)
+
+```ts
+import { getStorage, setStorage, removeStorage, clearStorage, getStorageInfoSync } from '@hlw-uni/mp-core';
+
+setStorage('token', 'abc123');
+const token = getStorage<string>('token');      // 'abc123'
+removeStorage('token');
+clearStorage();
+const info = getStorageInfoSync();             // { keys: [...], currentSize: 0, limitSize: 1024 }
+```
+
+### 设备 (device)
+
+```ts
+import { getDeviceInfo, deviceToQuery, clearDeviceCache } from '@hlw-uni/mp-core';
+
+const info = getDeviceInfo();       // 单例缓存，自动复用
+const query = deviceToQuery();      // 转换为 URL query string
+clearDeviceCache();                  // 清除缓存（如切换账号）
+```
+
+## Components（easycom 方式使用）
+
+在 `pages.json` 中配置：
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "regular": {
+      "^hlw-(.*)": "@hlw-uni/mp-core/components/$1.vue"
+    }
+  }
+}
+```
+
+使用示例：
+
+```vue
+<hlw-avatar :src="avatar" name="张三" size="medium" />
+<hlw-empty text="暂无数据" />
+<hlw-loading text="加载中..." />
+<hlw-menu-list :items="menuItems" @click="onMenuClick" />
+```
+
+## 类型
+
+```ts
+import type { RequestConfig, ApiResponse, PageResult, HlwMsg, HlwInstance, DeviceInfo } from '@hlw-uni/mp-core';
+```
+
+类型声明统一在 `@hlw-uni/mp-core/types/global.d.ts`，模板项目通过 `/// <reference types="@hlw-uni/mp-core/types/global" />` 引入即可获得完整类型提示。
+
+## 依赖
+
+```json
+{
+  "peerDependencies": {
+    "pinia": ">=2.1.0",
+    "vue": ">=3.4.0"
+  }
+}
+```
+
+## 构建
+
+```bash
+npm run build   # 构建产物到 dist/
+npm run dev     # 监听模式
+```

package/dist/app.d.ts

@@ -0,0 +1,26 @@
+import { createSSRApp } from '../node_modules/vue';
+
+export interface InterceptorOptions {
+    /** 自动注入 Token 的 header 键名 */
+    tokenHeader?: string;
+    /** Token 来源函数（需平台自行提供） */
+    getToken?: () => string;
+    /** 登录失效时的处理函数（需平台自行提供） */
+    onUnauthorized?: () => void;
+    /** 接口业务错误码是否自动 toast */
+    autoToastError?: boolean;
+}
+export declare function useApp(): {
+    install: (app: Parameters<typeof createSSRApp>[0]) => {
+        app: any;
+    };
+    hlw: import('./hlw').HlwInstance;
+    http: any;
+};
+/**
+ * 注册默认拦截器
+ * @param options 可传入平台自定义的 token/unauthorized 处理
+ */
+export declare function setupDefaultInterceptors(options?: InterceptorOptions & {
+    sigSecret?: string;
+}): void;

package/dist/assets/index.css

@@ -0,0 +1,191 @@
+.hlw-avatar[data-v-87dd25f7] {
+  border-radius: 50%;
+  overflow: hidden;
+  flex-shrink: 0;
+}
+.hlw-avatar--small[data-v-87dd25f7] {
+  width: 64rpx;
+  height: 64rpx;
+}
+.hlw-avatar--medium[data-v-87dd25f7] {
+  width: 88rpx;
+  height: 88rpx;
+}
+.hlw-avatar--large[data-v-87dd25f7] {
+  width: 120rpx;
+  height: 120rpx;
+}
+.hlw-avatar__image[data-v-87dd25f7] {
+  width: 100%;
+  height: 100%;
+}
+.hlw-avatar__placeholder[data-v-87dd25f7] {
+  width: 100%;
+  height: 100%;
+  background-color: #2979ff;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.hlw-avatar__initial[data-v-87dd25f7] {
+  color: #ffffff;
+  font-size: 36rpx;
+  font-weight: 600;
+}.hlw-empty[data-v-d78ade08] {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 60rpx 0;
+}
+.hlw-empty__image[data-v-d78ade08] {
+  width: 200rpx;
+  height: 200rpx;
+}
+.hlw-empty__icon[data-v-d78ade08] {
+  font-size: 100rpx;
+  line-height: 1;
+  margin-bottom: 24rpx;
+}
+.hlw-empty__text[data-v-d78ade08] {
+  font-size: 28rpx;
+  color: #c0c4cc;
+  margin-top: 16rpx;
+}.hlw-loading[data-v-6bf3a5a2] {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+.hlw-loading__spinner[data-v-6bf3a5a2] {
+  position: relative;
+  width: 40px;
+  height: 40px;
+}
+.hlw-loading__dot[data-v-6bf3a5a2] {
+  position: absolute;
+  width: 8px;
+  height: 8px;
+  background-color: #2979ff;
+  border-radius: 50%;
+  animation: hlw-loading-fade-6bf3a5a2 1.2s infinite ease-in-out;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(1) {
+  top: 0px;
+  left: 8px;
+  opacity: 1;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(2) {
+  top: 0px;
+  left: 20px;
+  opacity: 0.92;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(3) {
+  top: 0px;
+  left: 32px;
+  opacity: 0.84;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(4) {
+  top: 10px;
+  left: 32px;
+  opacity: 0.76;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(5) {
+  top: 20px;
+  left: 32px;
+  opacity: 0.68;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(6) {
+  top: 20px;
+  left: 20px;
+  opacity: 0.6;
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(7) {
+  top: 20px;
+  left: 8px;
+  opacity: 0.52;
+  transform: scale(0.84);
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(8) {
+  top: 10px;
+  left: 8px;
+  opacity: 0.44;
+  transform: scale(0.76);
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(9) {
+  top: 10px;
+  left: 20px;
+  opacity: 0.36;
+  transform: scale(0.68);
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(10) {
+  top: 0px;
+  left: 20px;
+  opacity: 0.28;
+  transform: scale(0.6);
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(11) {
+  top: 0px;
+  left: 8px;
+  opacity: 0.2;
+  transform: scale(0.52);
+}
+.hlw-loading__dot[data-v-6bf3a5a2]:nth-child(12) {
+  top: 10px;
+  left: 8px;
+  opacity: 0.12;
+  transform: scale(0.44);
+}
+.hlw-loading__text[data-v-6bf3a5a2] {
+  margin-top: 12rpx;
+  font-size: 24rpx;
+  color: #606266;
+}
+@keyframes hlw-loading-fade-6bf3a5a2 {
+0%, 80%, 100% {
+    transform: scale(0.6);
+    opacity: 0.4;
+}
+40% {
+    transform: scale(1);
+    opacity: 1;
+}
+}.hlw-menu-list[data-v-1dfe912b] {
+  background-color: #ffffff;
+  border-radius: 8rpx;
+}
+.hlw-menu-list__item[data-v-1dfe912b] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 28rpx 32rpx;
+  border-bottom: 1rpx solid #ebedf0;
+}
+.hlw-menu-list__item[data-v-1dfe912b]:last-child {
+  border-bottom: none;
+}
+.hlw-menu-list__left[data-v-1dfe912b] {
+  display: flex;
+  align-items: center;
+  gap: 16rpx;
+}
+.hlw-menu-list__icon[data-v-1dfe912b] {
+  font-size: 40rpx;
+}
+.hlw-menu-list__label[data-v-1dfe912b] {
+  font-size: 28rpx;
+  color: #303133;
+}
+.hlw-menu-list__right[data-v-1dfe912b] {
+  display: flex;
+  align-items: center;
+  gap: 8rpx;
+}
+.hlw-menu-list__value[data-v-1dfe912b] {
+  font-size: 28rpx;
+  color: #606266;
+}
+.hlw-menu-list__arrow[data-v-1dfe912b] {
+  font-size: 32rpx;
+  color: #c0c4cc;
+}

package/dist/composables/device/index.d.ts

@@ -0,0 +1,67 @@
+export interface DeviceInfo {
+    /** 小程序 appId */
+    appid: string;
+    /** 应用名称 */
+    app_name: string;
+    /** 小程序版本号（版本名称） */
+    app_version: string;
+    /** 小程序版本号（版本号） */
+    app_version_code: string;
+    /** 小程序来源渠道 */
+    app_channel: string;
+    /** 设备品牌。如：apple、huawei */
+    device_brand: string;
+    /** 设备型号 */
+    device_model: string;
+    /** 设备 ID */
+    device_id: string;
+    /** 设备类型：phone/pad/pc */
+    device_type: string;
+    /** 设备方向：portrait/landscape */
+    device_orientation: "portrait" | "landscape";
+    /** 手机品牌。H5 不支持 */
+    brand: string;
+    /** 手机型号 */
+    model: string;
+    /** 操作系统版本 */
+    system: string;
+    /** 操作系统版本（简写） */
+    os: string;
+    /** 设备像素比 */
+    pixel_ratio: number;
+    /** 屏幕宽度 (px) */
+    screen_width: number;
+    /** 屏幕高度 (px) */
+    screen_height: number;
+    /** 可用窗口宽度 (px) */
+    window_width: number;
+    /** 可用窗口高度 (px) */
+    window_height: number;
+    /** 状态栏高度 (px) */
+    status_bar_height: number;
+    /** 微信基础库版本 */
+    sdk_version: string;
+    /** 宿主名称。如：WeChat、alipay */
+    host_name: string;
+    /** 宿主版本。如：微信版本号 */
+    host_version: string;
+    /** 宿主语言 */
+    host_language: string;
+    /** 宿主主题：light/dark */
+    host_theme: string;
+    /** 平台类型 weapp/toutiao/h5 */
+    platform: string;
+    /** 客户端语言 */
+    language: string;
+    /** 客户端版本号 */
+    version: string;
+}
+export declare function useDevice(): any;
+/**
+ * 把 deviceInfo 对象转成 URL query string（不含前导 ?）
+ */
+export declare function deviceToQuery(): string;
+/**
+ * 手动清除缓存（切换账号等场景可能需要）
+ */
+export declare function clearDeviceCache(): void;

package/dist/composables/format/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * useFormat — 格式化工具 composable
+ */
+export declare function useFormat(): {
+    date: (date: Date | number | string, format?: string) => string;
+    fileSize: (bytes: number) => string;
+    phone: (value: string) => string;
+    money: (amount: number, decimals?: number, decPoint?: string, thousandsSep?: string) => string;
+};

package/dist/composables/http/adapters/alist.d.ts

@@ -0,0 +1,3 @@
+import { UploadAdapter } from './base';
+
+export declare const alistAdapter: UploadAdapter;

package/dist/composables/http/adapters/base.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 云存储上传适配器 — 上传上下文
+ */
+/** 上传上下文 */
+export interface UploadContext {
+    filePath: string;
+    fileName: string;
+    /** 云存储密钥凭证 */
+    credentials?: Record<string, string>;
+    /** 额外表单数据 */
+    extraData?: Record<string, string>;
+}
+/** 云存储适配器接口 */
+export interface UploadAdapter {
+    /** 适配器名称 */
+    name: string;
+    /** 根据上下文构建表单数据 */
+    buildFormData(ctx: UploadContext): Record<string, string | number>;
+}

package/dist/composables/http/adapters/cos.d.ts

@@ -0,0 +1,3 @@
+import { UploadAdapter } from './base';
+
+export declare const cosAdapter: UploadAdapter;

package/dist/composables/http/adapters/index.d.ts

@@ -0,0 +1,13 @@
+import { UploadAdapter } from './base';
+/**
+ * 云存储上传适配器统一导出
+ */
+export { cosAdapter } from './cos';
+export { ossAdapter } from './oss';
+export { qiniuAdapter } from './qiniu';
+export { alistAdapter } from './alist';
+export type { UploadAdapter, UploadContext } from './base';
+/** 所有已注册的适配器 */
+export declare const adapters: Record<string, UploadAdapter>;
+/** 获取适配器，不存在则抛错 */
+export declare function getAdapter(name: string): UploadAdapter;

package/dist/composables/http/adapters/oss.d.ts

@@ -0,0 +1,3 @@
+import { UploadAdapter } from './base';
+
+export declare const ossAdapter: UploadAdapter;

package/dist/composables/http/adapters/qiniu.d.ts

@@ -0,0 +1,3 @@
+import { UploadAdapter } from './base';
+
+export declare const qiniuAdapter: UploadAdapter;

package/dist/composables/http/client.d.ts

@@ -0,0 +1,48 @@
+import { ref } from '../../../node_modules/vue';
+import { ApiResponse, RequestConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor, UploadConfig, UploadResult } from './types';
+
+/** 组件内请求返回的状态 */
+export interface UseRequestReturn<T = unknown> {
+    loading: ReturnType<typeof ref<boolean>>;
+    data: ReturnType<typeof ref<T | null>>;
+    error: ReturnType<typeof ref<Error | null>>;
+    run: (config: RequestConfig) => Promise<ApiResponse<T>>;
+    get: (url: string, data?: unknown) => Promise<ApiResponse<T>>;
+    post: (url: string, data?: unknown) => Promise<ApiResponse<T>>;
+    put: (url: string, data?: unknown) => Promise<ApiResponse<T>>;
+    del: (url: string, data?: unknown) => Promise<ApiResponse<T>>;
+}
+export declare class HttpClient {
+    private _reqInterceptors;
+    private _resInterceptors;
+    private _errInterceptors;
+    private _baseURL;
+    private _defaultHeaders;
+    constructor(options?: {
+        baseURL?: string;
+        headers?: Record<string, string>;
+    });
+    /** 添加请求拦截器，返回取消函数 */
+    onRequest(fn: RequestInterceptor): () => void;
+    /** 添加响应拦截器 */
+    onResponse<T = unknown>(fn: ResponseInterceptor<T>): () => void;
+    /** 添加错误拦截器 */
+    onError(fn: ErrorInterceptor): () => void;
+    /**
+     * 全局请求
+     */
+    request<T = unknown>(config: RequestConfig): Promise<ApiResponse<T>>;
+    /**
+     * 组件内请求，返回带状态的 composable
+     */
+    useRequest<T = unknown>(): UseRequestReturn<T>;
+    /**
+     * 上传文件（策略模式）
+     */
+    upload(config: UploadConfig): Promise<UploadResult>;
+    private _buildUrl;
+    private _doRequest;
+    private _applyErrorInterceptors;
+}
+/** 全局 HTTP 实例 */
+export declare const http: HttpClient;

package/dist/composables/http/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP 模块统一导出
+ */
+export { http, HttpClient } from './client';
+export { useRequest, useUpload } from './useRequest';
+export type { ApiResponse, PageResult, RequestConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor, UploadConfig, UploadResult } from './types';
+export type { UseRequestReturn } from './client';
+export * from './adapters';

package/dist/composables/http/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * HTTP 类型定义
+ */
+/** API 统一响应格式 */
+export interface ApiResponse<T = unknown> {
+    code: number;
+    data: T;
+    message: string;
+}
+/** 分页数据 */
+export interface PageResult<T = unknown> {
+    list: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** 请求配置 */
+export interface RequestConfig {
+    url: string;
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    data?: unknown;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+/** 拦截器类型 */
+export type RequestInterceptor = (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+export type ResponseInterceptor<T = unknown> = (res: ApiResponse<T>) => ApiResponse<T> | Promise<ApiResponse<T>>;
+export type ErrorInterceptor = (err: Error) => void | Error | Promise<void | Error>;
+/** 上传配置 */
+export interface UploadConfig {
+    /** 上传接口地址 */
+    server: string;
+    /** 文件路径 */
+    filePath: string;
+    /** 文件名（可选，默认取 filePath） */
+    fileName?: string;
+    /** 上传类型：cos | oss | qiniu | alist */
+    type: string;
+    /** 云存储密钥凭证 */
+    credentials?: Record<string, string>;
+    /** 自定义请求头 */
+    header?: Record<string, string>;
+    /** 上传类型为 local 时，作为最终 server */
+    url?: string;
+}
+/** 上传结果 */
+export interface UploadResult {
+    code: number;
+    msg: string;
+    data: string;
+}