@zfqh/uniapp 0.1.1

package/docs/components/styles/global-vars.md

@@ -0,0 +1,150 @@
+# 全局变量
+
+全局变量指 `@gmcb/uv-ui/theme.scss` 提供的 `$uv-*` Sass 变量。业务项目建议在 `uni.scss` 中先引入默认变量，再按品牌主题覆盖；后续页面、组件和工具样式编写时优先使用这些变量，非必要不要硬编码颜色。
+
+## 默认值
+
+| 变量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `$uv-main-color` | `#303133` | 主要文字 |
+| `$uv-content-color` | `#606266` | 正文文字 |
+| `$uv-tips-color` | `#909193` | 提示文字 |
+| `$uv-light-color` | `#c0c4cc` | 浅色文字 |
+| `$uv-border-color` | `#dadbde` | 边框 |
+| `$uv-bg-color` | `#f3f4f6` | 页面/区块背景 |
+| `$uv-bg-light-color` | `#fffbf4` | 浅色提示背景 |
+| `$uv-disabled-color` | `#c8c9cc` | 禁用态 |
+| `$uv-primary` | `#3c9cff` | 主色 |
+| `$uv-primary-dark` | `#398ade` | 主色深色态 |
+| `$uv-primary-disabled` | `#9acafc` | 主色禁用态 |
+| `$uv-primary-light` | `#ecf5ff` | 主色浅背景 |
+| `$uv-warning` | `#f9ae3d` | 警告色 |
+| `$uv-warning-dark` | `#f1a532` | 警告深色态 |
+| `$uv-warning-disabled` | `#f9d39b` | 警告禁用态 |
+| `$uv-warning-light` | `#fdf6ec` | 警告浅背景 |
+| `$uv-success` | `#5ac725` | 成功色 |
+| `$uv-success-dark` | `#53c21d` | 成功深色态 |
+| `$uv-success-disabled` | `#a9e08f` | 成功禁用态 |
+| `$uv-success-light` | `#f5fff0` | 成功浅背景 |
+| `$uv-error` | `#f56c6c` | 错误色 |
+| `$uv-error-dark` | `#e45656` | 错误深色态 |
+| `$uv-error-disabled` | `#f7b2b2` | 错误禁用态 |
+| `$uv-error-light` | `#fef0f0` | 错误浅背景 |
+| `$uv-info` | `#909399` | 信息色 |
+| `$uv-info-dark` | `#767a82` | 信息深色态 |
+| `$uv-info-disabled` | `#c4c6c9` | 信息禁用态 |
+| `$uv-info-light` | `#f4f4f5` | 信息浅背景 |
+
+## 覆盖方式
+
+在项目的 `uni.scss` 中先引入默认变量，再声明同名变量覆盖。这样后续导入的组件样式、工具样式和业务样式都可以读取统一主题。
+
+```scss
+/* uni.scss */
+@import '@gmcb/uv-ui/theme.scss';
+
+// 覆盖主题变量，建议与 defineConfig({ color }) 保持一致
+$uv-primary: #451709;
+$uv-primary-dark: #451709;
+$uv-primary-disabled: #d5b9b0;
+$uv-primary-light: #e8d8c9;
+$uv-bg-color: #f8f5f2;
+$uv-main-color: #2b211d;
+```
+
+## 使用约定
+
+- 文字、背景、边框和状态色优先使用 `$uv-*` 变量。
+- 业务主题色优先覆盖 `$uv-primary` 及其衍生变量，而不是在组件内重复写品牌色。
+- 没有对应语义变量时，才在局部样式中使用硬编码颜色，并保持注释说明来源或用途。
+- `uni.scss` 会影响全局样式和每个页面样式，建议只放变量覆盖，不放大量实际样式规则。
+
+## 使用示例
+
+### 文字和提示
+
+```scss
+.page-title {
+  color: $uv-main-color;
+  font-weight: 600;
+}
+
+.page-desc {
+  color: $uv-content-color;
+}
+
+.form-tip {
+  color: $uv-tips-color;
+  font-size: 24rpx;
+}
+```
+
+### 主按钮
+
+```scss
+.primary-button {
+  color: #fff;
+  background-color: $uv-primary;
+}
+
+.primary-button:active {
+  background-color: $uv-primary-dark;
+}
+
+.primary-button--disabled {
+  background-color: $uv-primary-disabled;
+}
+```
+
+### 卡片和边框
+
+```scss
+.info-card {
+  color: $uv-main-color;
+  background-color: #fff;
+  border: 1px solid $uv-border-color;
+}
+
+.page-section {
+  background-color: $uv-bg-color;
+}
+```
+
+### 状态标签
+
+```scss
+.status-tag--success {
+  color: $uv-success;
+  background-color: $uv-success-light;
+}
+
+.status-tag--warning {
+  color: $uv-warning;
+  background-color: $uv-warning-light;
+}
+
+.status-tag--error {
+  color: $uv-error;
+  background-color: $uv-error-light;
+}
+
+.status-tag--info {
+  color: $uv-info;
+  background-color: $uv-info-light;
+}
+```
+
+### 提示块
+
+```scss
+.notice {
+  color: $uv-warning-dark;
+  background-color: $uv-warning-light;
+  border-left: 6rpx solid $uv-warning;
+}
+
+.error-message {
+  color: $uv-error;
+  background-color: $uv-error-light;
+}
+```

package/docs/components/usage.md

@@ -0,0 +1,112 @@
+# 公共组件
+
+`@zfqh/uniapp` 提供一组 `g-*` 公共组件，发布路径位于 `@zfqh/uniapp/lib/components`，可通过 easycom 或构建产物路径使用。本页保留接入方式和常用组合。
+
+## easycom
+
+推荐在 `pages.json` 配置：
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "custom": {
+      "^g-(.*)": "@zfqh/uniapp/lib/components/g-$1/g-$1.vue"
+    }
+  }
+}
+```
+
+如果项目同时使用 `@gmcb/uv-ui`：
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "custom": {
+      "^g-(.*)": "@zfqh/uniapp/lib/components/g-$1/g-$1.vue",
+      "^uv-(.*)": "@gmcb/uv-ui/components/uv-$1/uv-$1.vue"
+    }
+  }
+}
+```
+
+## 组件分组
+
+| 分组 | 组件 | 说明 |
+| --- | --- | --- |
+| 页面骨架 | `g-container`、`g-page-container`、`g-refresh-view`、`g-data-list` | 页面容器、导航栏、下拉刷新、分页加载。 |
+| 基础展示 | `g-icon`、`g-dot-text`、`g-money`、`g-more`、`g-skeleton`、`g-skeleton-view` | 图标、状态文本、金额、查看更多、骨架屏。 |
+| 表单输入 | `g-search`、`g-checkbox-list`、`g-tag-editor`、`g-upload` | 搜索、选择、标签编辑、文件上传。 |
+| 图片布局 | `g-grid-image`、`g-grid-swiper`、`g-waterfall`、`g-render-image` | 图片网格、宫格轮播、瀑布流、海报渲染。 |
+| 弹层反馈 | `g-mask`、`g-popup`、`g-permission-popup`、`g-float` | 遮罩、弹窗、权限提示、悬浮入口。 |
+| 分享 | `g-share-view`、`g-share-photo`、`g-share-weixin` | 分享面板、保存图片、微信分享。 |
+| 音视频/图表 | `g-trtc`、`g-trtc-room`、`g-trtc-tui`、`g-polyline-view`、`g-polyline-chat`、`g-timer` | TRTC、TUI 通话、折线展示、计时器。 |
+| 调试 | `g-env`、`g-back-button` | 环境切换、自定义返回/首页按钮。 |
+
+## Store 用法
+
+业务组件中读取 Vuex store 时请优先使用 Vuex 的组件上下文入口：
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue';
+import { useStore } from 'vuex';
+
+const store = useStore();
+const isLogin = computed(() => store.getters.isLogin);
+</script>
+```
+
+如果组件仍使用 Options API，可使用 `this.$store`。`uni.$store` 只推荐在脱离组件上下文的普通 TS 模块中使用，例如请求拦截器、导航工具、权限工具和 webview 消息处理。
+
+## 页面骨架示例
+
+```vue
+<template>
+  <g-page-container
+    title="订单列表"
+    refresh-enabled
+    show-footer
+    @refresh="reload"
+    @scrollbottom="loadMore"
+  >
+    <template #right>
+      <g-icon name="search" @click="openSearch" />
+    </template>
+
+    <g-data-list ref="listRef" :request="queryOrders" :page-size="20" init-load>
+      <template #default="{ item }">
+        <view class="order-row">{{ item.orderNo }}</view>
+      </template>
+    </g-data-list>
+
+    <template #footer>
+      <view class="footer-actions">...</view>
+    </template>
+  </g-page-container>
+</template>
+```
+
+## 表单与上传示例
+
+```vue
+<template>
+  <g-search v-model:keywords="keyword" placeholder="搜索商品" @search="search" @clear="clear" />
+
+  <g-checkbox-list
+    :list="options"
+    multiple
+    label-field="name"
+    value-field="id"
+    @change="handleChange"
+  />
+
+  <g-upload v-model:files="files" :count="9" action="cos" @choose="handleChoose" />
+</template>
+```
+
+## 继续阅读
+
+- [配置参考](./../api/configs/)：组件依赖的 `color`、`page`、`path`、`upload` 等配置。
+- [工具](./../api/utils/)：`cosCompress`、`requestPermission`、`navigateBack` 等组件内部常用工具。

package/docs/faq/index.md

@@ -0,0 +1,78 @@
+# 常见问题
+
+## 请求没有 Authorization
+
+检查：
+
+1. 是否先注册 store，再注册 `@zfqh/uniapp`。
+2. 是否设置了 `app.config.globalProperties.$store = store`。
+3. token 是否位于 `uni.$store.state.login.info.token`。
+
+这里检查 `uni.$store` 是因为请求拦截器属于普通 TS 模块。组件或 hooks 内读取同一份状态时应使用 `useStore()`。
+
+## 401 后没有退出登录
+
+检查：
+
+1. `uni.$store.state.login.info.token` 是否存在。
+2. store 是否实现 `dispatch('logout')`。
+3. 请求配置是否设置了 `custom.reLogin: false` 或 `custom.needLogin: false`。
+
+## 环境配置未生效
+
+检查：
+
+1. 环境文件是否位于 `@env` 指向的目录。
+2. 文件名是否匹配 `.env.<env>.ts` 或 `.env.<env>.js`。
+3. 生产构建是否设置了 `BUILD_ENV`。
+4. 非小程序端是否通过 `config.env.set()` 存储了其他环境名。
+
+## navigate 未跳到登录页
+
+检查：
+
+1. `uni.$store.getters.isLogin` 是否正确。
+2. `page.needLoginPages` 是否包含目标页。
+3. `getPage('login')` 是否能返回登录页路径。
+4. 当前跳转是否显式传入 `needLogin: false`。
+
+`navigate` 内部读取 `uni.$store.getters.isLogin`。如果页面组件里自己判断登录态，请使用 `import { useStore } from 'vuex'`。
+
+## tabBar 页面 navigateTo 失败
+
+`navigate` 会自动判断 `page.tabBarPages`。如果 tabBar 页面没有配置进去，可能仍然调用 `navigateTo`。
+
+```ts
+defineConfig({
+  page: {
+    tabBarPages: ['/pages/index/index', '/pages/user/user'],
+  },
+});
+```
+
+## COS 上传失败
+
+检查：
+
+1. `upload.request({ mode: 'cos' })` 是否返回临时凭证。
+2. 返回字段是否包含 `secret_id`、`secret_key`、`session_token`、`bucket`、`region`。
+3. 临时凭证是否过期。
+4. 小程序端是否配置了 COS 域名白名单。
+
+## useI18n 在 APP-NVUE 行为不同
+
+APP-NVUE 下不会直接使用 `vue-i18n` 的 `useI18n`，而是通过 `inject('t')` 和内置 locale 逻辑适配。其他端透传 `vue-i18n`。
+
+## 深度引用找不到模块
+
+深度引用使用的是构建产物路径：
+
+```ts
+import { GET } from '@zfqh/uniapp/lib/apis/request';
+```
+
+请确认：
+
+1. 包已执行编译，生成 `lib`。
+2. 发布包的 `files` 包含 `lib`。
+3. 本地 workspace 依赖已正确链接。

package/docs/guide/getting-started.md

@@ -0,0 +1,195 @@
+# 快速开始
+
+## 安装
+
+```bash
+npm i @zfqh/uniapp
+```
+
+本包会使用 `@gmcb/uv-ui` 中的请求、时间、query 等基础能力，因此业务项目通常也会注册 `@gmcb/uv-ui`。
+
+```bash
+npm i @gmcb/uv-ui
+```
+
+## 注册插件
+
+在 uni-app Vue 3 项目的 `src/main.ts` 注册：
+
+```ts
+import { createSSRApp } from 'vue';
+import uvUI from '@gmcb/uv-ui';
+import uniapp from '@zfqh/uniapp';
+import App from './App.vue';
+import store from './store';
+
+export function createApp() {
+  const app = createSSRApp(App);
+
+  app.use(store);
+  app.use(uvUI);
+  app.use(uniapp);
+
+  return { app };
+}
+```
+
+`@zfqh/uniapp` 插件安装时会把 `app.config.globalProperties.$store` 赋值给 `uni.$store`。请求、导航、权限、登录等能力会读取 `uni.$store`，所以请先挂载 store，再注册本插件。
+
+Store 使用入口请按上下文区分：
+
+- 组件的 Composition API 或 `<script setup>` 中使用 `import { useStore } from 'vuex'`。
+- 自定义 hooks / composables 中也使用 `useStore()`。
+- Options API 组件中可使用 `this.$store`。
+- 请求、导航、权限、webview 消息等普通 TS 模块中使用 `uni.$store`。
+
+详见 [Store 使用位置](./project-frame.md#store-使用位置)。
+
+## 配置 easycom
+
+`@zfqh/uniapp` 的公共组件位于 `lib/components/g-*`，建议通过 `pages.json` 配置：
+
+```json
+{
+  "easycom": {
+    "autoscan": true,
+    "custom": {
+      "^g-(.*)": "@zfqh/uniapp/lib/components/g-$1/g-$1.vue",
+      "^uv-(.*)": "@gmcb/uv-ui/components/uv-$1/uv-$1.vue"
+    }
+  }
+}
+```
+
+页面中即可直接使用：
+
+```vue
+<template>
+  <g-container>
+    <g-search v-model="keyword" />
+    <g-data-list :list="list" />
+  </g-container>
+</template>
+```
+
+## 配置文件
+
+新建项目配置文件，例如患者端项目的 `src/config.js`。真实项目通常直接调用 `defineConfig` 完成全局配置，不一定需要 `export default`：
+
+```ts
+import { defineConfig, createPages } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+// #ifdef H5
+import pages from 'virtual:remove-json-comments@/pages.json';
+// #endif
+// #ifndef H5
+import pages from '@/pages.json';
+// #endif
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+
+defineConfig({
+  app: app.patient,
+  brand: brand.zfqh,
+  page: createPages(pages),
+  path: {
+    index: '/pages/index/index',
+    login: '/pages/public/login/login',
+    webview: '/pages/public/webview/webview',
+  },
+  tabbar: {
+    badgeIndex: 1,
+  },
+  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,
+      };
+    },
+  },
+});
+```
+
+门店端这类需要覆盖主题色或上传区域的项目，可以基于内置预设继续覆盖：
+
+```ts
+import { defineConfig } from '@zfqh/uniapp';
+import { app } from '@zfqh/uniapp/lib/configs/app';
+import { brand } from '@zfqh/uniapp/lib/configs/brand';
+import { getTencentToken } from '@zfqh/uniapp/lib/apis';
+import store from '@/store';
+
+defineConfig({
+  app: app.merchant,
+  brand: brand.zfqh,
+  path: {
+    index: '/pages/home/home',
+    webview: '/pages/webview/webview',
+  },
+  color: {
+    primary: '#451709',
+    primaryDark: '#451709',
+    primaryDisabled: '#D5B9B0',
+    primaryLight: '#E8D8C9',
+  },
+  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: store.state.storeConfig.isGlobalAccelerate ? 'accelerate' : data.region,
+      };
+    },
+  },
+});
+```
+
+关键点：
+
+- `app.patient`、`app.merchant`、`brand.zfqh` 是内置预设，位于深度路径 `@zfqh/uniapp/lib/configs/app` 和 `@zfqh/uniapp/lib/configs/brand`。
+- `page: createPages(pages)` 会从 `pages.json` 生成 `pages`、`tabBarPages`、`nativePages`、`needLoginPages`、`notRedirectPages`。
+- 如项目暂不需要自动页面集合，也可以不配置 `page`，只配置 `path`，由业务自行维护登录拦截页面集合。
+- H5 端如果 `pages.json` 带注释，可通过 `virtual:remove-json-comments@/pages.json` 导入；其他端直接导入 `@/pages.json`。
+- `path.index`、`path.login`、`path.webview` 是导航、登录拦截和 webview 承载页的核心别名。
+- `upload.request` 需要把业务接口返回的腾讯云字段映射成 `secret_id`、`secret_key`、`session_token`、`bucket`、`region` 等字段。
+- `getTencentToken` 已内置在 `@zfqh/uniapp/lib/apis`，如果项目使用不同接口，可替换成自己的请求函数，但返回字段仍需映射成 COS 工具需要的字段名。
+
+多环境配置建议放到 `env/.env.dev.ts`、`env/.env.prod.ts`，详见 [环境配置](../api/configs/env.md)。
+
+TypeScript 项目建议在 `tsconfig.json` 中添加 `"types": ["@zfqh/uniapp/types"]`，详见 [项目接入](./project-frame.md#typescript-配置)。
+
+## 常用导入
+
+```ts
+import {
+  toast,
+  navigate,
+  cos,
+  color,
+  debounce,
+  throttle,
+  copyToClipboard,
+  defineConfig,
+  defineEnvConfig,
+} from '@zfqh/uniapp';
+```
+
+业务请求优先使用内置的 `GET/POST`，详见 [请求封装](../api/apis/request.md)：
+
+```ts
+import { GET, POST } from '@zfqh/uniapp/lib/apis';
+```
+
+根入口导出清单见 [根入口导出](../api/)。