@zfqh/uniapp 0.1.1

package/docs/api/utils/navigate.md

@@ -0,0 +1,267 @@
+# 导航
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/navigate`
+:::
+
+统一处理页面跳转、登录拦截、tabBar、webview、自定义协议和重复点击节流。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { navigate } from '@zfqh/uniapp';
+```
+
+导航工具脱离组件 setup 上下文，内部会通过 `uni.$store.getters.isLogin` 判断登录态。组件或 hooks 中判断登录态时请使用 `useStore()`。
+
+## 常用跳转
+
+```ts
+// 字符串参数（默认 navigateTo）
+navigate('/pages/user/profile');
+
+// 带参数跳转
+navigate.navigateTo({
+  url: '/pages/order/detail',
+  params: { id: 123 },
+});
+
+// 重定向（关闭当前页）
+navigate.redirectTo('/pages/login/login');
+
+// 重启到首页
+navigate.reLaunch('/pages/index/index');
+
+// 切换 tabBar 页
+navigate.switchTab('/pages/index/index');
+
+// 返回
+navigate.back({ delta: 1 });
+```
+
+## 对象参数
+
+```ts
+navigate.navigateTo({
+  url: '/pages/detail/detail',
+  params: { id: 1 },               // 拼接到 URL query
+  webviewParams: { title: '详情' }, // 传给 webview 页的参数
+  needLogin: true,                  // 强制要求登录
+  native: true,                     // 作为原生页面跳转
+});
+```
+
+## 登录拦截
+
+`navigate` 会自动检查目标页是否在 `config.page.needLoginPages` 中，如果未登录则跳转登录页。
+
+```ts
+// 页面配置中声明需要登录的页面
+defineConfig({
+  page: {
+    needLoginPages: ['/pages/user/profile', '/pages/order/list'],
+  },
+});
+
+// 跳转时自动拦截
+navigate('/pages/user/profile'); // 未登录 → 跳登录页
+
+// 单次跳转中显式声明
+navigate.navigateTo({
+  url: '/pages/user/profile',
+  needLogin: true,
+});
+```
+
+登录页路径来自 `getPage('login')`，通过 `config.path.login` 配置。
+
+## 自定义拦截器
+
+```ts
+import { navigate } from '@zfqh/uniapp';
+
+// 覆盖跳转拦截器
+navigate.interceptor = (url, absoluteUrl) => {
+  if (absoluteUrl.includes('/pages/disabled/')) {
+    return '/pages/index/index'; // 重定向到首页
+  }
+  return url; // 正常跳转
+};
+
+// 返回非字符串可阻止跳转
+navigate.interceptor = (url) => {
+  if (shouldBlock(url)) {
+    return false; // 阻止跳转
+  }
+  return url;
+};
+```
+
+## navigateBack
+
+`navigateBack` 支持 3 种页面间通信方式：
+
+```ts
+import { navigateBack } from '@zfqh/uniapp';
+
+// 调用上一页的指定方法
+navigateBack({ method: 'refresh' });
+navigateBack({ method: 'handleResult', data: { id: 1 } });
+
+// 通过 uni.$emit 发送事件（上一页用 uni.$on 监听）
+navigateBack({ emit: 'orderCreated', data: { orderId: '123' } });
+
+// 普通返回
+navigateBack({ delta: 2 });
+```
+
+## 自动处理
+
+`navigate` 内部会自动处理以下情况：
+
+- 相对路径转绝对路径
+- `params` 拼接为 URL query
+- tabBar 页面自动使用 `switchTab`
+- HTTP URL 和自定义协议转 webview 页面
+- webview 容器内使用 `uni.webView` 跳转
+- 节流防止重复点击
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/navigate`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `navigate(urlOrOptions, type?)` | `default export member` | 统一跳转入口；支持字符串或对象参数，默认 type 为 navigateTo。 |
+| `navigate.navigateTo(options)` | `default export member` | 按 navigateTo 跳转。 |
+| `navigate.redirectTo(options)` | `default export member` | 按 redirectTo 跳转。 |
+| `navigate.reLaunch(options)` | `default export member` | 按 reLaunch 跳转。 |
+| `navigate.switchTab(options)` | `default export member` | 按 switchTab 跳转。 |
+| `navigate.back(options)` | `default export member` | 调用 uni.navigateBack。 |
+| `navigate.interceptor(url, absoluteUrl)` | `default export member` | 可覆盖的跳转拦截器；返回非字符串可阻止跳转。 |
+
+## navigate 使用指南
+
+根入口导出：
+
+```ts
+import { navigate } from '@zfqh/uniapp';
+```
+
+基础使用：
+
+```ts
+navigate('/pages/user/user');
+navigate.navigateTo('/pages/user/user');
+navigate.redirectTo('/pages/login/login');
+navigate.reLaunch('/pages/index/index');
+navigate.switchTab('/pages/index/index');
+navigate.back({ delta: 1 });
+```
+
+对象参数：
+
+```ts
+navigate.navigateTo({
+  url: '/pages/detail/detail',
+  params: { id: 1 },
+  webviewParams: { title: '详情' },
+  needLogin: true,
+  native: true,
+});
+```
+
+## URL 处理
+
+`navigate` 会处理：
+
+- 相对路径转绝对路径。
+- `params` 拼接为 query。
+- tabBar 页面自动使用 `switchTab`。
+- 自定义协议和 HTTP URL 转 webview 页面。
+- webview 容器内使用 `uni.webView` 跳转。
+
+## 登录拦截
+
+登录判断依赖：
+
+```ts
+uni.$store.getters.isLogin
+```
+
+`navigate` 是普通工具模块，脱离组件 setup 上下文，所以读取 `uni.$store`。如果是在组件或 hooks 中判断登录态，请使用：
+
+```ts
+import { computed } from 'vue';
+import { useStore } from 'vuex';
+
+const store = useStore();
+const isLogin = computed(() => store.getters.isLogin);
+```
+
+需要登录的页面来源：
+
+```ts
+defineConfig({
+  page: {
+    needLoginPages: ['/pages/user/user'],
+  },
+});
+```
+
+也可以在单次跳转中声明：
+
+```ts
+navigate('/pages/user/user', 'navigateTo');
+navigate.navigateTo({
+  url: '/pages/user/user',
+  needLogin: true,
+});
+```
+
+登录页路径来自 `getPage('login')`，通常通过页面别名配置提供。
+
+## 来源页策略
+
+`navigate.referrerType` 控制未登录跳转登录页时如何携带来源：
+
+| 值 | 行为 |
+| --- | --- |
+| `none` | 不携带来源。 |
+| `target` | 登录后跳转目标页。 |
+| `referrer` | 登录后回到来源页。 |
+| `combine` | 登录后先回来源页，再根据 `__navigate` 跳目标页。 |
+
+配置：
+
+```ts
+defineConfig({
+  navigate: {
+    loginType: 'navigateTo',
+    referrerType: 'combine',
+  },
+});
+```
+
+## 跳转拦截器
+
+可以覆盖 `navigate.interceptor`：
+
+```ts
+import { navigate } from '@zfqh/uniapp';
+
+navigate.interceptor = (url, absoluteUrl) => {
+  if (absoluteUrl.includes('/pages/disabled/')) {
+    return '/pages/index/index';
+  }
+  return url;
+};
+```
+
+返回非字符串会终止跳转。

package/docs/api/utils/pages.md

@@ -0,0 +1,205 @@
+# 页面配置
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/pages`
+:::
+
+根据页面配置生成 tabBar、原生页、登录页、不可重定向页等页面集合。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { getPage, inPages, createPages } from '@zfqh/uniapp';
+```
+
+## createPages
+
+从 `pages.json` 生成页面集合配置，在 `defineConfig` 中使用：
+
+```ts
+import { defineConfig, createPages } from '@zfqh/uniapp';
+// #ifdef H5
+import pages from 'virtual:remove-json-comments@/pages.json';
+// #endif
+// #ifndef H5
+import pages from '@/pages.json';
+// #endif
+
+defineConfig({
+  page: createPages(pages),
+  path: {
+    index: '/pages/index/index',
+    login: '/pages/login/login',
+    webview: '/pages/webview/webview',
+  },
+});
+```
+
+`createPages` 会从 `pages.json` 中提取：
+
+| 来源字段 | 生成配置 |
+| --- | --- |
+| `pages[].path` | `page.pages` |
+| `subPackages[].root` + `pages[].path` | `page.pages` |
+| `tabBar.list[].pagePath` | `page.tabBarPages` |
+| 页面项 `native`（默认 `true`） | `native` 为 `false` 时从 `page.nativePages` 中排除 |
+| 页面项 `needLogin: true` | `page.needLoginPages`（默认 `false`） |
+| 页面项 `notRedirect: true` | `page.notRedirectPages`（默认 `false`） |
+
+在 `pages.json` 中声明：
+
+```json
+{
+  "pages": [
+    { "path": "pages/index/index" },
+    { "path": "pages/user/profile", "needLogin": true },
+    { "path": "pages/login/login", "native": true }
+  ],
+  "globalStyle": {
+    "needLogin": false
+  }
+}
+```
+
+## native 与 webview 页面
+
+`native` 字段控制页面在 App 和小程序端的打开方式，默认为 `true`（原生页面）。
+
+当 `navigate('/pages/some/page')` 时，`navigate` 会检查目标页是否在 `nativePages` 中：
+
+- **在 `nativePages` 中**（默认） → 原生页面跳转（`uni.navigateTo`）
+- **不在 `nativePages` 中**（`native: false`） → 通过 webview 承载页打开（跳转到 `config.path.webview`，URL 作为参数传入）
+
+### 推荐方式：条件编译
+
+如果某个页面只在 H5 端存在（App/小程序端通过 webview 打开），推荐使用条件编译在 `pages.json` 中排除该页面：
+
+```json
+{
+  "pages": [
+    { "path": "pages/index/index" },
+    // #ifdef H5
+    {
+      "path": "pages/type/type",
+      "needLogin": false,
+      "style": {
+        "navigationBarTitleText": "皮肤健康深度测评",
+        "navigationStyle": "custom"
+      }
+    },
+    // #endif
+  ]
+}
+```
+
+这样 App 和小程序端的 `pages.json` 中不包含该页面，`createPages` 生成的 `nativePages` 中也没有它。`navigate` 会自动将其作为 webview 页面打开。
+
+### 替代方式：native 字段
+
+也可以通过 `native: false` 显式标记某个页面为非原生页面：
+
+```json
+{
+  "pages": [
+    { "path": "pages/index/index" },
+    { "path": "pages/webview/webview" },
+    { "path": "pages/h5-only/h5-only", "native": false }
+  ]
+}
+```
+
+- `native: true`（默认） — 原生页面，所有端均以原生方式跳转
+- `native: false` — 非原生页面，App/小程序端通过 webview 打开
+- `globalStyle.native` — 全局默认值，页面项的 `native` 会覆盖全局设置
+
+两种方式可以配合使用。推荐优先使用条件编译，效果更精确。
+
+## needLogin 登录拦截
+
+`needLogin` 字段控制页面是否需要登录才能访问，默认为 `false`。
+
+当 `needLogin: true` 时，`navigate` 会检查 `uni.$store.getters.isLogin`，如果未登录则自动跳转到 `getPage('login')` 返回的登录页路径。
+
+```json
+{
+  "pages": [
+    { "path": "pages/index/index" },
+    { "path": "pages/user/profile", "needLogin": true },
+    { "path": "pages/order/list", "needLogin": true }
+  ],
+  "globalStyle": {
+    "needLogin": false
+  }
+}
+```
+
+- `needLogin: true` — 需要登录，未登录时自动跳转登录页
+- `needLogin: false`（默认） — 不需要登录
+- `globalStyle.needLogin` — 全局默认值，页面项的 `needLogin` 会覆盖全局设置
+
+登录拦截需要配合 [login mixin](./../mixins/login) 使用。login mixin 会在页面 `onShow` 时检查当前页面是否在 `needLoginPages` 中，未登录则跳转登录页。
+
+## notRedirect 登录重定向控制
+
+`notRedirect` 字段控制登录成功后是否重定向回来源页，默认为 `false`。
+
+当页面使用了 [redirect mixin](./../mixins/redirect) 时，登录成功后会自动跳转回 `path.referrer`（来源页）。如果某个页面在登录后不希望被重定向（例如登录后需要跳转到绑定手机号页面），可以设置 `notRedirect: true`。
+
+```json
+{
+  "pages": [
+    { "path": "pages/index/index" },
+    { "path": "pages/login/login" },
+    { "path": "pages/bind-phone/bind-phone", "notRedirect": true }
+  ]
+}
+```
+
+- `notRedirect: true` — 登录跳转后不会重定向到来源页
+- `notRedirect: false`（默认） — 登录跳转后自动重定向到来源页
+- `globalStyle.notRedirect` — 全局默认值，页面项的 `notRedirect` 会覆盖全局设置
+
+**典型场景**：用户登录后需要绑定手机号，跳转到绑定页面。如果绑定页未设置 `notRedirect: true`，进入绑定页后 redirect mixin 会自动跳回 referrer（来源页），导致绑定流程被打断。设置为 `true` 后，绑定页不会被重定向，用户可以正常完成绑定操作。
+
+## getPage
+
+```ts
+import { getPage } from '@zfqh/uniapp';
+
+// 获取配置的页面别名路径
+const loginPath = getPage('login');   // '/pages/login/login'
+const indexPath = getPage('index');   // '/pages/index/index'
+const webviewPath = getPage('webview'); // '/pages/webview/webview'
+```
+
+## inPages
+
+```ts
+import { inPages, config } from '@zfqh/uniapp';
+
+// 判断页面是否需要登录
+const needLogin = inPages(config.page.needLoginPages, '/pages/user/profile');
+
+// 判断是否是 tabBar 页面
+const isTab = inPages(config.page.tabBarPages, '/pages/index/index');
+
+// 支持 ** 前缀匹配
+inPages(['/pages/user/**'], '/pages/user/profile'); // true
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/pages`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `getPage` | `export const getPage = (name: string) => {` | 按别名从 configs/path 获取页面路径。 |
+| `inPages` | `export const inPages = (pages: string[], url: string \| { url: string; [key: string]: any }) => {` | 判断 url 是否命中页面数组，支持以 ** 结尾的前缀匹配。 |
+| `createPages` | `export const createPages = (` | 从 pages.json 风格配置中生成 pages、tabBarPages、nativePages、needLoginPages、notRedirectPages。 |
+

package/docs/api/utils/permission.md

@@ -0,0 +1,28 @@
+# 权限补丁
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/permission`
+:::
+
+包含平台运行时补丁或内部实现，一般不直接调用。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import permission from '@zfqh/uniapp/lib/utils/permission';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/permission` 的导出整理。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/permission`
+
+该文件只包含运行时补丁或平台专用内部实现，没有具名导出。
+

package/docs/api/utils/permit.md

@@ -0,0 +1,62 @@
+# 权限申请
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/permit`
+:::
+
+统一申请 App/小程序权限，并在失败时引导用户打开授权设置。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { openAuthorizeSetting, requestPermission } from '@zfqh/uniapp';
+```
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/permit` 的导出整理。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/permit`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `openAuthorizeSetting` | `export function openAuthorizeSetting(name: string) {` | 打开系统或应用授权设置页。 |
+| `requestPermission` | `export async function requestPermission(name: keyof typeof permissionData, system = true) {` | 跨 App/小程序申请 location、storage、camera、record、bluetooth 权限，并在失败时弹出引导。 |
+
+## 支持的权限名称
+
+| 权限 | 说明 | App 权限 ID |
+| --- | --- | --- |
+| `location` | 定位权限 | `ACCESS_FINE_LOCATION` |
+| `storage` | 文件存储权限 | `WRITE_EXTERNAL_STORAGE` |
+| `camera` | 相机权限 | `CAMERA` |
+| `record` | 麦克风权限 | `RECORD_AUDIO` |
+| `bluetooth` | 蓝牙权限 | `BLUETOOTH` / `BLUETOOTH_SCAN` + `BLUETOOTH_CONNECT`（Android 12+） |
+
+## 典型用法
+
+先申请权限，失败后引导用户到系统设置页手动开启：
+
+```ts
+import { requestPermission, openAuthorizeSetting } from '@zfqh/uniapp';
+
+async function takePhoto() {
+  const granted = await requestPermission('camera');
+  if (!granted) {
+    // 权限被拒绝，引导用户到设置页
+    openAuthorizeSetting('camera');
+    return;
+  }
+  // 权限已获取，执行拍照逻辑
+  uni.chooseImage({ ... });
+}
+```
+
+小程序端 `requestPermission` 会调用 `uni.authorize`，App 端会通过 `plus.android.requestPermissions` 申请对应的系统权限。`system` 参数控制是否同时检测系统级开关（默认 `true`）。
+

package/docs/api/utils/query.md

@@ -0,0 +1,89 @@
+# Query 解析
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/query`
+:::
+
+解析当前页面或 H5 地址栏 query，供渠道、来源和业务参数读取。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { query } from '@zfqh/uniapp';
+```
+
+## query 对象
+
+`query` 是默认导出的当前页面或 H5 URL 的 query 参数解析结果。
+
+**H5 端**：解析 `location.search`（地址栏 query 字符串）。 **小程序端**：解析启动参数中的 query。
+
+```ts
+import { query } from '@zfqh/uniapp';
+
+// 访问 query 参数
+console.log(query.token);     // URL 中的 token 参数
+console.log(query.channel);   // 渠道参数
+console.log(query.platform);  // 平台参数
+```
+
+### 内置属性
+
+| 属性 | 类型 | 说明 |
+| --- | --- | --- |
+| `platform` | `string` | 平台标识 |
+| `token` | `string` | H5 端 URL 传入的 token |
+| `primary` | `string` | 主题色覆盖 |
+| `brand` | `string` | 品牌标识 |
+| `app` | `string` | 应用标识 |
+| `safeBottom` | `string \| number` | 安全区域底部高度 |
+| `tabbar` | `string \| number` | tabbar 配置 |
+
+同时支持任意自定义 query 参数（`[key: string]: any`）。
+
+## parseQuery
+
+```ts
+import { parseQuery } from '@zfqh/uniapp';
+```
+
+`parseQuery(search: string): Record<string, string>`
+
+解析 URL query 字符串为对象。
+
+```ts
+parseQuery('id=123&tab=detail'); // { id: '123', tab: 'detail' }
+parseQuery('name=%E5%BC%A0%E4%B8%89'); // { name: '张三' }
+```
+
+## 配合导航使用
+
+```ts
+import { query, navigate } from '@zfqh/uniapp';
+
+// H5 端通过 URL 传入 token 自动登录
+if (query.token) {
+  store.commit('setLoginInfo', { token: query.token });
+}
+
+// 根据渠道参数决定跳转目标
+if (query.channel === 'promotion') {
+  navigate('/pages/activity/activity');
+}
+```
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/query`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `parseQuery` | `export function parseQuery(search: string = '') {` | 解析 URL query 字符串。 |
+| `query` | `default export member` | 默认导出当前页面或 H5 URL query 解析结果。 |
+

package/docs/api/utils/request.md

@@ -0,0 +1,34 @@
+# 请求工厂
+
+::: tip 工具模块
+`@zfqh/uniapp/lib/utils/request`
+:::
+
+创建请求方法并安装通用拦截器，处理动态 URL、token、错误、401 退出登录。
+
+## 平台兼容性
+
+| App | H5 | 微信小程序 | 其他小程序 | WebView |
+| --- | --- | --- | --- | --- |
+| √ | √ | √ | 视平台 API 而定 | 视运行容器而定 |
+
+## 基本使用
+
+```ts
+import { formatURL, createInterceptors, createRequest } from '@zfqh/uniapp';
+```
+
+请求工具脱离组件 setup 上下文，拦截器内部会通过 `uni.$store` 读取 token 并处理 `401`。组件或 hooks 中读取 store 时请使用 `useStore()`。
+
+具体方法、参数语义和返回值以发布包类型为准；下方表格按 `@zfqh/uniapp/lib/utils/request` 的导出整理。
+
+## API
+
+发布路径：`@zfqh/uniapp/lib/utils/request`
+
+| 名称 | 签名/声明 | 说明 |
+| --- | --- | --- |
+| `formatURL` | `export function formatURL(url, data) {` | 把 /:id 或 :id 动态片段替换为 data 中的值，并删除已消费字段。 |
+| `createInterceptors` | `export function createInterceptors(req) {` | 给请求实例安装统一请求/响应拦截器，注入 token 并处理 code/401/toast/logout。 |
+| `createRequest` | `export function createRequest(req, opts = {}) {` | 基于请求实例生成 GET、DELETE、POST、PUT 方法。 |
+