@zfqh/uniapp 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.3.10](http://10.10.10.16/caoben/front-end/compare/@zfqh/uniapp@0.3.9...@zfqh/uniapp@0.3.10) (2026-07-29)
+
+**Note:** Version bump only for package @zfqh/uniapp
+
+
+
+
+
 ## [0.3.9](http://10.10.10.16/caoben/front-end/compare/@zfqh/uniapp@0.3.8...@zfqh/uniapp@0.3.9) (2026-07-29)
 
 **Note:** Version bump only for package @zfqh/uniapp

package/docs/api/hooks/index.md

@@ -18,28 +18,32 @@ const store = useStore();
 | `usePopup(visible)` | 接收一个 ref/响应式可见状态，返回 popup ref；visible 为 true 时调用 popup.open()，false 时调用 popup.close()。 |
 | `useVersion()` | 返回 { version }，version 包含 name/code；App 端会通过 plus.runtime.getProperty 补齐版本信息。 |
 | `useI18n()` | 非 nvue 直接使用 vue-i18n 的 useI18n；nvue 下返回注入的 t 与本地 locale ref。 |
+| `useReferrer()` | 返回 referrer ref。页面 onLoad 时自动读取 `__referrer` 参数并解码，用于登录页记录来源路径。 |
+| `useNeedLogin(flag = false)` | 页面登录守卫。onShow 时检测登录态，未登录则跳转登录页；flag 为 true 时额外校验当前页面是否在 needLoginPages 列表中。 |
 
 ## 示例
 
 ```ts
 import { ref } from 'vue';
-import { useOverlay, usePopup, useVersion, useI18n } from '@zfqh/uniapp';
+import { useOverlay, usePopup, useVersion, useI18n, useReferrer, useNeedLogin } from '@zfqh/uniapp';
 
 const [showOverlay, showChildren] = useOverlay(false, 300);
 const visible = ref(false);
 const popup = usePopup(visible);
 const { version } = useVersion();
 const { t } = useI18n();
+const referrer = useReferrer();
+useNeedLogin();
 ```
 
 ---
 
 ## Hooks 使用指南
 
-根入口导出 `@zfqh/uniapp/lib/hooks` 下的四个组合式函数：
+根入口导出 `@zfqh/uniapp/lib/hooks` 下的组合式函数：
 
 ```ts
-import { useOverlay, usePopup, useVersion, useI18n } from '@zfqh/uniapp';
+import { useOverlay, usePopup, useVersion, useI18n, useReferrer, useNeedLogin } from '@zfqh/uniapp';
 ```
 
 ## Store 用法
@@ -180,3 +184,58 @@ const { t, locale } = useI18n();
   <text>{{ t('common.submit') }}</text>
 </template>
 ```
+
+## useReferrer
+
+用于登录页记录来源路径。页面 `onLoad` 时自动读取 `__referrer` 参数并解码，登录成功后可跳回原页面：
+
+```ts
+import { useReferrer } from '@zfqh/uniapp';
+
+const referrer = useReferrer();
+
+console.log(referrer.value); // 解码后的来源路径
+```
+
+返回：
+
+| 返回值 | 说明 |
+| --- | --- |
+| `referrer` | 解码后的来源路径 ref；无 `__referrer` 参数时为空字符串。 |
+
+配合 `navigate` 在登录成功后跳回来源页：
+
+```ts
+import { useReferrer, navigate, getPage } from '@zfqh/uniapp';
+
+const referrer = useReferrer();
+
+// 登录成功后
+navigate.reLaunch({ url: referrer.value || getPage('index') });
+```
+
+## useNeedLogin
+
+页面登录守卫，替代 `login` mixin。`onShow` 时检测登录态，未登录则跳转登录页：
+
+```ts
+import { useNeedLogin } from '@zfqh/uniapp';
+
+useNeedLogin();
+```
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `flag` | `false` | 为 `true` 时，仅当前页面在 `needLoginPages` 列表中才跳转登录；为 `false` 时未登录即跳转。 |
+
+```vue
+<script setup lang="ts">
+import { useNeedLogin } from '@zfqh/uniapp';
+
+// 根据 needLoginPages 配置判断
+useNeedLogin(true);
+
+// 强制要求登录（不判断列表）
+useNeedLogin();
+</script>
+```

package/docs/api/index.md

@@ -48,6 +48,8 @@ export * from './hooks';
 - `usePopup`
 - `useVersion`
 - `useI18n`
+- `useReferrer`
+- `useNeedLogin`
 
 ## Utils
 

package/docs/api/mixins/login.md

@@ -2,6 +2,8 @@
 
 页面登录守卫 mixin。发布路径：`@zfqh/uniapp/lib/mixins/login`
 
+> 组合式 API 页面请改用 [`useNeedLogin`](../hooks/#useneedlogin) hook。
+
 | 项 | 说明 |
 | --- | --- |
 | `onShow()` | 页面显示时如果当前页面属于 needLoginPages 且未登录，则跳转登录。 |

package/lib/hooks/index.d.ts

@@ -2,3 +2,5 @@ export * from './useOverlay';
 export * from './usePopup';
 export * from './useVersion';
 export * from './useI18n';
+export * from './useReferrer';
+export * from './useNeedLogin';

package/lib/hooks/index.js

@@ -2,3 +2,5 @@ export * from './useOverlay';
 export * from './usePopup';
 export * from './useVersion';
 export * from './useI18n';
+export * from './useReferrer';
+export * from './useNeedLogin';

package/lib/hooks/useNeedLogin.d.ts

@@ -0,0 +1 @@
+export declare function useNeedLogin(flag?: boolean): void;

package/lib/hooks/useNeedLogin.js

@@ -0,0 +1,26 @@
+import { onShow } from '@dcloudio/uni-app';
+import { useStore } from 'vuex';
+import page from '../configs/page';
+import { inPages } from '../utils/pages';
+import navigate from '../utils/navigate';
+// #ifdef H5
+import { IS_WEBVIEW_ENV } from '../utils/consts';
+// #endif
+export function useNeedLogin(flag = false) {
+    const store = useStore();
+    onShow(() => {
+        if (uni.showAppFromBackground) {
+            // #ifdef H5
+            if (IS_WEBVIEW_ENV && store.state.login?.info?.accessToken == null) {
+                return;
+            }
+            // #endif
+            const { route } = getCurrentPages().pop() || {};
+            if (!store.getters.isLogin && !!route) {
+                if (!flag || inPages(page.needLoginPages, `/${route}`)) {
+                    navigate({ url: '', needLogin: true });
+                }
+            }
+        }
+    });
+}

package/lib/hooks/useReferrer.d.ts

@@ -0,0 +1 @@
+export declare function useReferrer(): import("vue").Ref<string>;

package/lib/hooks/useReferrer.js

@@ -0,0 +1,11 @@
+import { ref } from 'vue';
+import { onLoad } from '@dcloudio/uni-app';
+export function useReferrer() {
+    const referrer = ref('');
+    onLoad((options) => {
+        if (options?.__referrer) {
+            referrer.value = decodeURIComponent(options.__referrer);
+        }
+    });
+    return referrer;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zfqh/uniapp",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "uniapp公共模块",
   "author": "yinjiazeng@163.com",
   "license": "MIT",
@@ -46,5 +46,5 @@
     "@types/qs": "^6.9.16",
     "@types/url-parse": "^1.4.11"
   },
-  "gitHead": "5816a11cc3d4f1593a483e54fef5a9e67d20f2a6"
+  "gitHead": "5a532f7c3044e74a29f402e46836d0b5fa279242"
 }