@zfqh/uniapp 0.1.1

package/docs/api/configs/storage.md

@@ -0,0 +1,24 @@
+# storage
+
+缓存配置。发布路径：`@zfqh/uniapp/lib/configs/storage`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `prefix` | `string` | `gmcb` | 本地缓存 key 前缀。 |
+
+## 基本使用
+
+为不同项目或品牌设置缓存前缀，避免同一设备上多个端的本地缓存互相覆盖。
+
+```ts
+import { defineConfig, setStorageSync, getStorageSync } from '@zfqh/uniapp';
+
+defineConfig({
+  storage: {
+    prefix: 'zfqh-patient',
+  },
+});
+
+setStorageSync('userInfo', { id: 1, name: '张三' });
+const userInfo = getStorageSync('userInfo');
+```

package/docs/api/configs/tabbar.md

@@ -0,0 +1,29 @@
+# tabbar
+
+tabBar 配置。发布路径：`@zfqh/uniapp/lib/configs/tabbar`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `badgeIndex` | `number` | `-1` | 消息角标所在 tabBar 索引，小于等于 0 时不设置。 |
+
+## 基本使用
+
+患者端首页、消息页等使用 `badge` mixin 时，会根据 `tabbar.badgeIndex` 自动更新未读角标。
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+
+defineConfig({
+  tabbar: {
+    badgeIndex: 1,
+  },
+});
+```
+
+```ts
+import { badge } from '@zfqh/uniapp/lib/mixins';
+
+export default {
+  mixins: [badge],
+};
+```

package/docs/api/configs/toast.md

@@ -0,0 +1,35 @@
+# toast
+
+提示配置。发布路径：`@zfqh/uniapp/lib/configs/toast`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `custom` | `boolean` | `false` | 是否启用页面 $refs.toast 自定义提示。 |
+| `show(options)` | `function` | `-` | 自定义 toast 显示函数，返回 true 表示已接管。 |
+| `hide()` | `function` | `-` | 自定义 toast 隐藏函数，返回 true 表示已接管。 |
+
+## 基本使用
+
+默认使用 `uni.showToast`。如果项目有全局自定义 Toast 组件，可以在配置中接管显示和隐藏。
+
+```ts
+import { defineConfig, toast } from '@zfqh/uniapp';
+
+defineConfig({
+  toast: {
+    custom: true,
+    show(options) {
+      const page = getCurrentPages().at(-1) as any;
+      page?.$vm?.$refs?.toast?.show(options);
+      return true;
+    },
+    hide() {
+      const page = getCurrentPages().at(-1) as any;
+      page?.$vm?.$refs?.toast?.hide();
+      return true;
+    },
+  },
+});
+
+toast.success('保存成功');
+```

package/docs/api/configs/update.md

@@ -0,0 +1,25 @@
+# update
+
+更新配置。发布路径：`@zfqh/uniapp/lib/configs/update`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `request(data)` | `function` | `Promise<null>` | 获取最新版本信息；返回 hot_update、force_update、wgt_url/apk_url/ipa_url/zip_url 等字段。 |
+
+## 基本使用
+
+App.vue 全局 mixin 会在合适时机调用更新检查；业务项目只需要配置获取最新版本的请求函数。
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { POST } from '@zfqh/uniapp/lib/apis';
+
+defineConfig({
+  update: {
+    async request(data) {
+      const { data: version } = await POST('/app-api/system/app/version/get-last-version', data);
+      return version;
+    },
+  },
+});
+```

package/docs/api/configs/upload.md

@@ -0,0 +1,45 @@
+# upload
+
+上传配置。发布路径：`@zfqh/uniapp/lib/configs/upload`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `request(params)` | `function` | `Promise<null>` | 获取上传凭证；COS 上传会以 { mode: "cos" } 调用。 |
+
+COS 上传需要 `request` 返回：
+
+| 字段 | 说明 |
+| --- | --- |
+| `secret_id` | 腾讯云临时密钥 ID，常由后端 `tmpSecretId` 映射而来。 |
+| `secret_key` | 腾讯云临时密钥 Key，常由后端 `tmpSecretKey` 映射而来。 |
+| `session_token` | 临时 token，常由后端 `sessionToken` 映射而来。 |
+| `create_time` | 临时密钥创建时间，常由后端 `createTime` 映射而来。 |
+| `expire_time` | 临时密钥过期时间，常由后端 `expirationTime` 映射而来。 |
+| `bucket` | COS bucket。 |
+| `region` | COS region；如启用全球加速可传 `accelerate`。 |
+
+## 基本使用
+
+患者端和商户端上传图片时，通常从后端获取腾讯云临时密钥，并映射成 COS 工具需要的字段。
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+
+defineConfig({
+  upload: {
+    async request() {
+      const { data } = await getTencentToken();
+      return {
+        secret_id: data.tmpSecretId,
+        secret_key: data.tmpSecretKey,
+        session_token: data.sessionToken,
+        create_time: data.createTime,
+        expire_time: data.expirationTime,
+        bucket: data.bucket,
+        region: data.region,
+      };
+    },
+  },
+});
+```

package/docs/api/configs/ver.md

@@ -0,0 +1,32 @@
+# ver
+
+版本配置。发布路径：`@zfqh/uniapp/lib/configs/ver`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `code` | `number` | `0` | 资源版本号。 |
+| `name` | `string` | `''` | 资源版本名。 |
+| `suffix` | `string` | `''` | 版本名后缀。 |
+
+## 基本使用
+
+商户端环境文件会按环境维护版本号，页面或更新逻辑可读取 `config.ver` 展示当前版本。
+
+```ts
+// env/.env.sit.ts
+import { defineEnvConfig } from '@zfqh/uniapp';
+
+export default defineEnvConfig({
+  ver: {
+    code: 817,
+    name: '1.8.17',
+    suffix: 'sit',
+  },
+});
+```
+
+```ts
+import { config } from '@zfqh/uniapp';
+
+console.log(`${config.ver.name}.${config.ver.code}`);
+```

package/docs/api/configs/web.md

@@ -0,0 +1,28 @@
+# web
+
+Web 资源配置。发布路径：`@zfqh/uniapp/lib/configs/web`
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `[key]` | `string` | `-` | webview 自定义协议 app 到静态站点入口的映射。 |
+
+## 基本使用
+
+商户端和患者端都会把 H5 报告、协议或活动页面放入 webview 承载页，`web` 配置用于按业务 app key 找到对应 H5 入口。
+
+```ts
+import { defineConfig, config, navigate } from '@zfqh/uniapp';
+
+defineConfig({
+  web: {
+    patient: 'https://h5.example.com/patient',
+    merchant: 'https://h5.example.com/merchant',
+  },
+});
+
+export function openHealthReport(id: string, familyId: string) {
+  navigate('/pages/webview/webview', {
+    url: `${config.web.patient}/#/pages/healthReport/healthReport?id=${id}&familyId=${familyId}`,
+  });
+}
+```

package/docs/api/hooks/index.md

@@ -0,0 +1,182 @@
+# Hooks 参考
+
+发布路径：`@zfqh/uniapp/lib/hooks`。根入口已通过 `export * from './hooks'` 导出全部 hooks。
+
+Hooks 运行在组件 setup 上下文中。如果 hook 内需要访问 Vuex，请使用 `useStore()`：
+
+```ts
+import { useStore } from 'vuex';
+
+const store = useStore();
+```
+
+`uni.$store` 主要用于请求、导航、权限、webview 消息等普通模块。
+
+| Hook | 说明 |
+| --- | --- |
+| `useOverlay(visible = false, delay = 300)` | 返回 [showOverlay, showChildren]。showOverlay 控制遮罩是否可见；关闭后 showChildren 会延迟 delay 毫秒变为 false，适合等待关闭动画结束再卸载内容。 |
+| `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。 |
+
+## 示例
+
+```ts
+import { ref } from 'vue';
+import { useOverlay, usePopup, useVersion, useI18n } from '@zfqh/uniapp';
+
+const [showOverlay, showChildren] = useOverlay(false, 300);
+const visible = ref(false);
+const popup = usePopup(visible);
+const { version } = useVersion();
+const { t } = useI18n();
+```
+
+---
+
+## Hooks 使用指南
+
+根入口导出 `@zfqh/uniapp/lib/hooks` 下的四个组合式函数：
+
+```ts
+import { useOverlay, usePopup, useVersion, useI18n } from '@zfqh/uniapp';
+```
+
+## Store 用法
+
+Hooks 运行在组件 setup 上下文中，需要读取 Vuex 时请使用 `useStore()`，不要直接读取 `uni.$store`：
+
+```ts
+import { computed } from 'vue';
+import { useStore } from 'vuex';
+
+export function useUserName() {
+  const store = useStore();
+
+  return computed(() => store.state.login.info?.userName || '');
+}
+```
+
+`uni.$store` 主要给请求、导航、权限、webview 消息等非组件上下文的普通模块使用。完整约定见 [Store 使用位置](./../../guide/project-frame#store-使用位置)。
+
+## useOverlay
+
+用于遮罩动画场景，让外层遮罩和内部内容分开控制。`delay` 参数用于在遮罩关闭动画完成后再卸载内容，避免内容突然消失。
+
+```ts
+const [showOverlay, showChildren] = useOverlay(false, 300);
+
+showOverlay.value = true;
+showOverlay.value = false;
+```
+
+| 参数 | 默认值 | 说明 |
+| --- | --- | --- |
+| `visible` | `false` | 初始显示状态。 |
+| `delay` | `300` | 遮罩关闭后，内部内容延迟卸载时间（毫秒）。 |
+
+返回：
+
+| 返回值 | 说明 |
+| --- | --- |
+| `showOverlay` | 控制遮罩是否显示。 |
+| `showChildren` | 控制内容是否渲染。 |
+
+```vue
+<template>
+  <!-- 遮罩层 -->
+  <uv-overlay :show="showOverlay" @click="close" />
+  <!-- 内容层：延迟卸载以配合关闭动画 -->
+  <view v-if="showChildren" class="popup-content">
+    <text>弹窗内容</text>
+  </view>
+</template>
+
+<script setup>
+import { useOverlay } from '@zfqh/uniapp';
+
+const [showOverlay, showChildren] = useOverlay(false, 300);
+
+function open() {
+  showChildren.value = true;   // 先渲染内容
+  showOverlay.value = true;    // 再显示遮罩
+}
+
+function close() {
+  showOverlay.value = false;   // 先关闭遮罩
+  // 300ms 后 showChildren 自动变为 false（卸载内容）
+  setTimeout(() => { showChildren.value = false; }, 300);
+}
+</script>
+```
+
+## usePopup
+
+用于绑定 `uni-popup` 或类似组件，自动监听 `visible` 变化并调用 `open/close`：
+
+```vue
+<template>
+  <uni-popup ref="popup" @close="visible = false">内容</uni-popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { usePopup } from '@zfqh/uniapp';
+
+const visible = ref(false);
+const popup = usePopup(visible);
+
+function open() {
+  visible.value = true;  // 自动调用 popup.value.open()
+}
+</script>
+```
+
+当 `visible` 为 true 时自动调用 `popup.value.open()`，为 false 时调用 `popup.value.close()`。注意在 `@close` 回调中同步 `visible = false`，避免状态不一致。
+
+## useVersion
+
+返回响应式版本信息：
+
+```ts
+import { useVersion } from '@zfqh/uniapp';
+
+const { version } = useVersion();
+
+console.log(version.name); // '1.0.0'
+console.log(version.code); // 100
+```
+
+| 平台 | 行为 |
+| --- | --- |
+| App | 通过 `plus.runtime.getProperty` 读取版本 |
+| 非 App | 优先读取 `config.ver.name` 和 `config.ver.code` |
+
+在页面中显示版本号：
+
+```vue
+<template>
+  <text>v{{ version.name }}（{{ version.code }}）</text>
+</template>
+```
+
+## useI18n
+
+统一处理 APP-NVUE 和其他端的国际化调用：
+
+```ts
+import { useI18n } from '@zfqh/uniapp';
+
+const { t, locale } = useI18n();
+```
+
+| 平台 | 行为 |
+| --- | --- |
+| APP-NVUE | 使用内部 `inject('t')` 和 `showLocale`。 |
+| 其他平台 | 透传 `vue-i18n` 的 `useI18n`。 |
+
+```vue
+<template>
+  <text>{{ t('common.submit') }}</text>
+</template>
+```

package/docs/api/hooks/useI18n.md

@@ -0,0 +1,27 @@
+# useI18n
+
+发布路径：`@zfqh/uniapp/lib/hooks/useI18n`。
+
+| `useI18n()` | 非 nvue 直接使用 vue-i18n 的 useI18n；nvue 下返回注入的 t 与本地 locale ref。 |
+
+## 基本使用
+
+页面中需要同时兼容 vue 页面和 nvue 页面时，使用包内 `useI18n` 获取翻译函数。
+
+```vue
+<template>
+  <view>{{ t('请选择设备') }}</view>
+</template>
+
+<script setup>
+import { useI18n } from '@zfqh/uniapp';
+
+const { t, locale } = useI18n();
+
+function switchToZh() {
+  locale.value = 'zh-CN';
+}
+</script>
+```
+
+详见 [Hooks 概览](./)。

package/docs/api/hooks/useOverlay.md

@@ -0,0 +1,37 @@
+# useOverlay
+
+发布路径：`@zfqh/uniapp/lib/hooks/useOverlay`。
+
+| `useOverlay(visible = false, delay = 300)` | 返回 [showOverlay, showChildren]。showOverlay 控制遮罩是否可见；关闭后 showChildren 会延迟 delay 毫秒变为 false，适合等待关闭动画结束再卸载内容。 |
+
+## 基本使用
+
+患者端体质辨识流程中常用遮罩承载拍照、脉诊等步骤弹层。
+
+```vue
+<template>
+  <view v-if="showOverlay" class="overlay" @click="close">
+    <view v-if="showChildren" class="panel">
+      <slot />
+    </view>
+  </view>
+</template>
+
+<script setup>
+import { useOverlay } from '@zfqh/uniapp';
+
+const [showOverlay, showChildren] = useOverlay(false, 300);
+
+function open() {
+  showOverlay.value = true;
+  showChildren.value = true;
+}
+
+function close() {
+  showChildren.value = false;
+  showOverlay.value = false;
+}
+</script>
+```
+
+详见 [Hooks 概览](./)。

package/docs/api/hooks/usePopup.md

@@ -0,0 +1,35 @@
+# usePopup
+
+发布路径：`@zfqh/uniapp/lib/hooks/usePopup`。
+
+| `usePopup(visible)` | 接收一个 ref/响应式可见状态，返回 popup ref；visible 为 true 时调用 popup.open()，false 时调用 popup.close()。 |
+
+## 基本使用
+
+适合把 `uv-popup` 的命令式 open/close 同步为响应式状态。
+
+```vue
+<template>
+  <uv-popup ref="popup" mode="center">
+    <view class="confirm">确认核销会员权益？</view>
+  </uv-popup>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { usePopup } from '@zfqh/uniapp';
+
+const visible = ref(false);
+const popup = usePopup(visible);
+
+function openVerifyPopup() {
+  visible.value = true;
+}
+
+function closeVerifyPopup() {
+  visible.value = false;
+}
+</script>
+```
+
+详见 [Hooks 概览](./)。

package/docs/api/hooks/useVersion.md

@@ -0,0 +1,23 @@
+# useVersion
+
+发布路径：`@zfqh/uniapp/lib/hooks/useVersion`。
+
+| `useVersion()` | 返回 { version }，version 包含 name/code；App 端会通过 plus.runtime.getProperty 补齐版本信息。 |
+
+## 基本使用
+
+用于设置页、下载页或更新弹窗展示当前 App 版本。
+
+```vue
+<template>
+  <view>当前版本：{{ version.name }}（{{ version.code }}）</view>
+</template>
+
+<script setup>
+import { useVersion } from '@zfqh/uniapp';
+
+const { version } = useVersion();
+</script>
+```
+
+详见 [Hooks 概览](./)。