uni-oaview 1.9.0 → 1.9.2

package/README.md

@@ -54,6 +54,33 @@ app.use(OaView, {
 });
 ```
 
+当前配置定义位于 `src/configs/oa-view-config.ts`，用于统一维护：
+
+- `OaViewOptions` - 插件配置项类型定义
+- `OaViewConfig` - 运行时配置对象类型定义
+- `defaultWhiteUrls` - 默认白名单地址列表
+- `OA_VIEW_CONFIG_KEY` - `oa-page` 读取运行时配置时使用的注入 key
+
+### 配置生效机制
+
+`whiteUrls` 的生效链路如下：
+
+1. 业务项目在 `main.ts` 中通过 `app.use(OaView, options)` 安装插件
+2. 插件在 `install()` 中通过 `app.provide()` 注入运行时配置
+3. `oa-page` 组件通过 `inject()` 读取配置
+4. 当 `baseUrl` 命中白名单，或者本地 `isDebug` 为 `true` 时，自动展示 `oa-vconsole`
+
+如果你发现配置没有生效，请优先检查以下几项：
+
+1. 是否已在业务项目入口文件中执行 `app.use(OaView, { whiteUrls: [...] })`
+2. 页面是否使用了 `oa-page` 组件包裹
+3. `baseUrl` 是否已正确写入本地存储
+4. 白名单地址是否与 `baseUrl` 的协议、域名、端口保持一致
+
+### whiteUrls 完整教程
+
+`whiteUrls` 用于控制 `oa-vconsole` 在哪些业务地址下自动显示，适用于开发联调、测试环境排障和定向灰度调试。
+
 ### whiteUrls
 
 配置 vconsole 调试工具自动显示的白名单 URL。
@@ -68,6 +95,82 @@ app.use(OaView, {
 
 **说明**: 当应用运行在白名单内的 URL 时，`oa-page` 组件会自动显示 vconsole 调试工具。传入空数组 `[]` 可禁用自动显示。
 
+#### 步骤 1：在入口文件安装插件
+
+```ts
+import { createSSRApp } from 'vue';
+import App from './App.vue';
+import OaView from 'getui-oa-oaview-sdk-uniapp';
+
+export function createApp() {
+  const app = createSSRApp(App);
+
+  app.use(OaView, {
+    whiteUrls: ['http://192.168.18.136:31080', 'http://192.168.104.127'],
+  });
+
+  return { app };
+}
+```
+
+#### 步骤 2：确保页面使用 `oa-page`
+
+```vue
+<template>
+  <oa-page>
+    <view>页面内容</view>
+  </oa-page>
+</template>
+```
+
+如果页面没有包裹 `oa-page`，即使已经安装插件，白名单配置也不会触发 `oa-vconsole` 的展示逻辑。
+
+#### 步骤 3：确认 `baseUrl` 已初始化
+
+`oa-page` 会根据本地存储中的 `baseUrl` 与 `whiteUrls` 做匹配，因此需要在应用启动阶段先正确写入：
+
+```ts
+uni.setStorageSync('baseUrl', 'http://192.168.18.136:31080');
+```
+
+#### 步骤 4：检查匹配结果
+
+建议优先保证以下内容一致：
+
+- 协议一致，例如都为 `http://` 或都为 `https://`
+- 域名或 IP 一致
+- 端口一致
+- 尽量不要混用带尾斜杠和不带尾斜杠的写法
+
+推荐写法：
+
+```ts
+whiteUrls: ['http://192.168.18.136:31080', 'http://192.168.104.127'];
+```
+
+#### 常见问题
+
+**1. 已传入 `whiteUrls`，但 `oa-page` 里还是默认值**
+
+通常是以下原因之一：
+
+- 插件未在业务入口安装
+- 页面未使用 `oa-page`
+- 当前联调方式没有正确加载最新包内容
+
+**2. `whiteUrls` 已正确注入，但 `showLog` 仍然是 `false`**
+
+通常需要继续检查：
+
+- `baseUrl` 是否为空
+- `baseUrl` 是否是目标业务地址，而不是其他临时字符串
+- `isDebug` 是否为 `false`
+
+**3. 什么时候应该使用 `whiteUrls`，什么时候使用 `isDebug`**
+
+- `whiteUrls` 适合固定地址环境自动开启调试
+- `isDebug` 适合手动强制开启调试
+
 更多配置详情请参考 [SDK 配置文档](../../docs/zh/sdk-configuration.md)。
 
 ---

package/components/oa-page/oa-page.vue

@@ -12,18 +12,10 @@
   import OaVconsole from '../oa-vconsole/oa-vconsole.vue';
   import NetworkError from './nextwork-error.vue';
   import GlobalComponents from './global-components.vue';
-  import { OA_VIEW_CONFIG_KEY } from '../../src/index';
+  import { defaultWhiteUrls, OA_VIEW_CONFIG_KEY } from '../../src/configs/oa-view-config';
 
   const globalComponentsRef = ref<InstanceType<typeof GlobalComponents>>();
 
-  // 默认白名单（兜底值）
-  const defaultWhiteUrls = [
-    'http://192.168.11.231:6174',
-    'http://192.168.10.11:6174',
-    'http://dev-oa.ge.cn:6174',
-    'http://test-oa.ge.cn:6174',
-  ];
-
   // 注入配置，未配置时使用默认
   const config = inject(OA_VIEW_CONFIG_KEY, { whiteUrls: defaultWhiteUrls });
   const whiteUrls = config.whiteUrls;
@@ -33,7 +25,7 @@
   const windowHeight = uni.getSystemInfoSync()?.windowHeight ?? 'auto';
   const baseUrl = uni.getStorageSync('baseUrl');
   /** 如果在debug状态，或者是在白名单里面，则展示vconsole */
-  const showLog = ref(whiteUrls.some((url) => url.includes(baseUrl)) || !!uni.getStorageSync('isDebug'));
+  const showLog = ref(whiteUrls.some((url) => baseUrl?.includes(url)) || !!uni.getStorageSync('isDebug'));
   let isLock = false;
   setTimeout(function () {
     isLock = true;

package/components/oa-vconsole/network.vue

@@ -87,7 +87,7 @@
     failed: boolean;
   }
 
-  const MAX_NETWORK_LOGS = 100;
+  const MAX_NETWORK_LOGS = 1000;
 
   const collapseRef = ref<{ resize?: () => void } | null>(null);
   // uni-collapse 的 v-model 在不同模式下可能是 string 或 string[]

package/dist/index.d.ts

@@ -319,18 +319,42 @@ declare function useCookieTempFileUrl(url: string): {
     tempUrl: _mp_rt1_vue___Ref<string>;
 };
 
+/**
+ * OA 页面插件配置项。
+ */
 interface OaViewOptions {
+    /**
+     * 允许展示调试能力的白名单地址列表。
+     */
     whiteUrls?: string[];
 }
-declare const OA_VIEW_CONFIG_KEY: unique symbol;
+/**
+ * OA 页面运行时配置对象。
+ */
+interface OaViewConfig {
+    /**
+     * 当前生效的白名单地址列表。
+     */
+    whiteUrls: string[];
+}
+/**
+ * 默认白名单地址列表。
+ */
+declare const defaultWhiteUrls: string[];
+/**
+ * OA 页面运行时配置注入 key。
+ * 使用字符串常量是为了兼容 dist 与源码组件并存时的 provide/inject 匹配。
+ */
+declare const OA_VIEW_CONFIG_KEY: "oa-view-config";
+
 declare const plugin: Plugin;
 /**
- * 向客户端获取数据
- * @param eventName  事件名称
- * @param params 客户端传递事件的参数
- * @param immediate 是否立即返回
- * @returns
+ * 根据原生事件名称向客户端请求数据。
+ * @param eventName 原生事件名称。
+ * @param params 发送给客户端的参数对象。
+ * @param immediate 是否启用超时保护。
+ * @returns 返回客户端回传的数据结果。
  */
 declare function getDataByApp(eventName: string, params: Record<string, any>, immediate?: boolean): Promise<any>;
 
-export { CreateModalReturn, Message, MessageBox, ModalBaseEvents, ModalCloseReason, ModalHeaderEvents, ModalHeaderOptions, ModalOptions, OA_VIEW_CONFIG_KEY, OaViewOptions, RouteMethodName, VersionCheckRuntimeOptions, VersionCheckRuntimeState, VersionCheckSource, VersionCheckTriggerContext, closeAllModals, compareVersions, createDebounceFn, createModal, createVersionCheckRuntime, plugin as default, getAppVersion, getDataByApp, getTempFilePathForCookie, isCurrentVersionHigher, sendLaunchAppParamsLog, useCookieTempFileUrl, versionCheckRuntime };
+export { CreateModalReturn, Message, MessageBox, ModalBaseEvents, ModalCloseReason, ModalHeaderEvents, ModalHeaderOptions, ModalOptions, OA_VIEW_CONFIG_KEY, OaViewConfig, OaViewOptions, RouteMethodName, VersionCheckRuntimeOptions, VersionCheckRuntimeState, VersionCheckSource, VersionCheckTriggerContext, closeAllModals, compareVersions, createDebounceFn, createModal, createVersionCheckRuntime, plugin as default, defaultWhiteUrls, getAppVersion, getDataByApp, getTempFilePathForCookie, isCurrentVersionHigher, sendLaunchAppParamsLog, useCookieTempFileUrl, versionCheckRuntime };

package/dist/index.esm.js

@@ -509,7 +509,7 @@ function _toPropertyKey(arg) {
  */
 function sendLaunchAppParamsLog(params) {
   var _a;
-  console.log('小程序启动入参：', params);
+  console.log('【OA View】小程序启动入参：', params);
   // #ifndef H5
   try {
     var outputData = JSON.parse(JSON.stringify((_a = params === null || params === void 0 ? void 0 : params.referrerInfo) === null || _a === void 0 ? void 0 : _a.extraData));
@@ -1071,6 +1071,16 @@ function createVersionCheckRuntime() {
 /** 默认版本检测运行时单例 */
 var versionCheckRuntime = createVersionCheckRuntime();
 
+/**
+ * 默认白名单地址列表。
+ */
+var defaultWhiteUrls = ['http://192.168.11.231:6174', 'http://192.168.10.11:6174', 'http://dev-oa.ge.cn:6174', 'http://test-oa.ge.cn:6174'];
+/**
+ * OA 页面运行时配置注入 key。
+ * 使用字符串常量是为了兼容 dist 与源码组件并存时的 provide/inject 匹配。
+ */
+var OA_VIEW_CONFIG_KEY = 'oa-view-config';
+
 var _PatchFlagNames, _slotFlagsText;
 /**
  * Make a map and return a function for checking if a key
@@ -3908,10 +3918,11 @@ function useCookieTempFileUrl(url) {
   };
 }
 
-// 默认白名单
-var defaultWhiteUrls = ['http://192.168.11.231:6174', 'http://192.168.10.11:6174', 'http://dev-oa.ge.cn:6174', 'http://test-oa.ge.cn:6174'];
-// 配置注入 key
-var OA_VIEW_CONFIG_KEY = Symbol('oa-view-config');
+/**
+ * 安装 OA 页面插件，并注入全局运行时配置。
+ * @param app Vue 应用实例。
+ * @param options 插件配置项。
+ */
 var install = function install(app) {
   var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
   var _a;
@@ -3931,11 +3942,11 @@ var plugin = {
   install: install
 };
 /**
- * 向客户端获取数据
- * @param eventName  事件名称
- * @param params 客户端传递事件的参数
- * @param immediate 是否立即返回
- * @returns
+ * 根据原生事件名称向客户端请求数据。
+ * @param eventName 原生事件名称。
+ * @param params 发送给客户端的参数对象。
+ * @param immediate 是否启用超时保护。
+ * @returns 返回客户端回传的数据结果。
  */
 function getDataByApp(eventName, params) {
   var immediate = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
@@ -3960,4 +3971,4 @@ function getDataByApp(eventName, params) {
   });
 }
 
-export { Message, MessageBox, OA_VIEW_CONFIG_KEY, closeAllModals, compareVersions, createDebounceFn, createModal, createVersionCheckRuntime, plugin as default, getAppVersion, getDataByApp, getTempFilePathForCookie, isCurrentVersionHigher, sendLaunchAppParamsLog, useCookieTempFileUrl, versionCheckRuntime };
+export { Message, MessageBox, OA_VIEW_CONFIG_KEY, closeAllModals, compareVersions, createDebounceFn, createModal, createVersionCheckRuntime, plugin as default, defaultWhiteUrls, getAppVersion, getDataByApp, getTempFilePathForCookie, isCurrentVersionHigher, sendLaunchAppParamsLog, useCookieTempFileUrl, versionCheckRuntime };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uni-oaview",
-  "version": "1.9.00",
+  "version": "1.9.02",
   "description": "uniapp小程序组件库",
   "main": "dist/index.esm.js",
   "typings": "dist/index.d.ts",

package/src/configs/oa-view-config.ts

@@ -0,0 +1,35 @@
+/**
+ * OA 页面插件配置项。
+ */
+export interface OaViewOptions {
+  /**
+   * 允许展示调试能力的白名单地址列表。
+   */
+  whiteUrls?: string[];
+}
+
+/**
+ * OA 页面运行时配置对象。
+ */
+export interface OaViewConfig {
+  /**
+   * 当前生效的白名单地址列表。
+   */
+  whiteUrls: string[];
+}
+
+/**
+ * 默认白名单地址列表。
+ */
+export const defaultWhiteUrls = [
+  'http://192.168.11.231:6174',
+  'http://192.168.10.11:6174',
+  'http://dev-oa.ge.cn:6174',
+  'http://test-oa.ge.cn:6174',
+];
+
+/**
+ * OA 页面运行时配置注入 key。
+ * 使用字符串常量是为了兼容 dist 与源码组件并存时的 provide/inject 匹配。
+ */
+export const OA_VIEW_CONFIG_KEY = 'oa-view-config' as const;

package/src/index.ts

@@ -1,34 +1,24 @@
 import type { App, Plugin } from 'vue';
 
 import { sendLaunchAppParamsLog } from './utils';
+import { defaultWhiteUrls, OA_VIEW_CONFIG_KEY } from './configs/oa-view-config';
+import type { OaViewOptions } from './configs/oa-view-config';
 export * from './utils';
 export * from './composables';
+export * from './configs/oa-view-config';
 
-// SDK 配置接口
-export interface OaViewOptions {
-  whiteUrls?: string[];
-}
-
-// 默认白名单
-const defaultWhiteUrls = [
-  'http://192.168.11.231:6174',
-  'http://192.168.10.11:6174',
-  'http://dev-oa.ge.cn:6174',
-  'http://test-oa.ge.cn:6174',
-];
-
-// 配置注入 key
-export const OA_VIEW_CONFIG_KEY = Symbol('oa-view-config');
-
+/**
+ * 安装 OA 页面插件，并注入全局运行时配置。
+ * @param app Vue 应用实例。
+ * @param options 插件配置项。
+ */
 const install = (app: App, options: OaViewOptions = {}) => {
   // 合并配置
   const config = {
     whiteUrls: options.whiteUrls ?? defaultWhiteUrls,
   };
-
   // 全局 provide 配置
   app.provide(OA_VIEW_CONFIG_KEY, config);
-
   app.mixin({
     onLaunch(params: any) {
       sendLaunchAppParamsLog(params);
@@ -43,11 +33,11 @@ const plugin: Plugin = {
 export default plugin;
 
 /**
- * 向客户端获取数据
- * @param eventName  事件名称
- * @param params 客户端传递事件的参数
- * @param immediate 是否立即返回
- * @returns
+ * 根据原生事件名称向客户端请求数据。
+ * @param eventName 原生事件名称。
+ * @param params 发送给客户端的参数对象。
+ * @param immediate 是否启用超时保护。
+ * @returns 返回客户端回传的数据结果。
  */
 export function getDataByApp(eventName: string, params: Record<string, any>, immediate: boolean = false): Promise<any> {
   return new Promise((res, rej) => {

package/src/utils/send-log.ts

@@ -5,7 +5,7 @@ import { reportLog } from 'uniapp-log-sdk';
  * @param params
  */
 export function sendLaunchAppParamsLog(params: any) {
-  console.log('小程序启动入参：', params);
+  console.log('【OA View】小程序启动入参：', params);
   // #ifndef H5
   try {
     const outputData = JSON.parse(JSON.stringify(params?.referrerInfo?.extraData));