更新

2026-03-11 14:33:49 +08:00
parent 38ad60f4bb
commit 08dd9cd307
57 changed files with 9547 additions and 379 deletions
@@ -0,0 +1,250 @@
+# 全局属性使用说明
+
+## 概述
+
+小程序通过 `main.js` 中的 `app.config.globalProperties` 定义全局属性，包括 `$url` 和 `apiUrl` 方法。
+
+## 全局属性定义
+
+### 在 main.js 中
+
+```javascript
+// Vue3 部分
+export function createApp() {
+  const app = createSSRApp(App)
+  
+  // 定义全局 baseUrl
+  app.config.globalProperties.$url = baseUrl
+  
+  // 定义全局 apiUrl 方法
+  app.config.globalProperties.apiUrl = apiUrl
+  
+  return {
+    app
+  }
+}
+```
+
+### 全局属性列表
+
+| 属性名 | 类型 | 说明 |
+|--------|------|------|
+| `$url` | string | API 基础 URL，默认值：`http://api.zzzhengyangtang.cn` |
+| `apiUrl` | function | API 请求方法 |
+
+## 在 API 服务中使用
+
+### 获取全局属性
+
+```javascript
+import { getCurrentInstance } from 'vue'
+
+const getGlobalProperties = () => {
+  try {
+    const instance = getCurrentInstance()
+    if (instance) {
+      return instance.appContext.config.globalProperties
+    }
+  } catch (e) {
+    console.warn('无法获取 getCurrentInstance')
+  }
+  return {}
+}
+
+// 使用
+const globalProps = getGlobalProperties()
+const baseUrl = globalProps.$url
+const apiUrl = globalProps.apiUrl
+```
+
+### 在 request 函数中使用
+
+```javascript
+export const request = (url, method = 'POST', data = {}, loading = true) => {
+  // 获取全局属性
+  const globalProps = getGlobalProperties()
+  const apiUrl = globalProps.apiUrl
+  const baseUrl = globalProps.$url || 'http://api.zzzhengyangtang.cn'
+  
+  if (!apiUrl) {
+    // 降级方案：直接使用 uni.request
+    return new Promise((resolve, reject) => {
+      uni.request({
+        url: `${baseUrl}${url}`,
+        method,
+        data,
+        // ...
+      })
+    })
+  }
+  
+  // 使用全局 apiUrl 方法
+  return apiUrl({
+    url,
+    method,
+    data,
+    header: {
+      'content-type': 'application/x-www-form-urlencoded'
+    }
+  }, loading)
+}
+```
+
+## 在组件中使用
+
+### 方式1：通过 getCurrentInstance
+
+```vue
+<script setup>
+import { getCurrentInstance } from 'vue'
+
+const instance = getCurrentInstance()
+const baseUrl = instance.appContext.config.globalProperties.$url
+const apiUrl = instance.appContext.config.globalProperties.apiUrl
+
+console.log('Base URL:', baseUrl)
+</script>
+```
+
+### 方式2：通过 this（Vue2 风格）
+
+```vue
+<script>
+export default {
+  methods: {
+    getBaseUrl() {
+      return this.$url
+    },
+    async fetchData() {
+      const response = await this.apiUrl({
+        url: '/api/data',
+        method: 'GET'
+      })
+      console.log(response)
+    }
+  }
+}
+</script>
+```
+
+### 方式3：通过 inject（推荐）
+
+```vue
+<script setup>
+import { inject } from 'vue'
+
+// 在 main.js 中提供
+// app.provide('$url', baseUrl)
+// app.provide('apiUrl', apiUrl)
+
+const baseUrl = inject('$url')
+const apiUrl = inject('apiUrl')
+</script>
+```
+
+## 修改全局属性
+
+### 修改 baseUrl
+
+编辑 `TUICallKit-Vue3/main.js`：
+
+```javascript
+var baseUrl = 'http://your-api-domain/api'
+```
+
+### 修改 apiUrl 方法
+
+编辑 `TUICallKit-Vue3/main.js` 中的 `apiUrl` 函数。
+
+## 全局属性的生命周期
+
+1. **初始化**：在 `main.js` 中通过 `app.config.globalProperties` 定义
+2. **可用**：应用创建后，所有组件都可以访问
+3. **销毁**：应用销毁时自动清理
+
+## 最佳实践
+
+### 1. 统一管理全局属性
+
+在 `main.js` 中集中定义所有全局属性：
+
+```javascript
+// 定义全局属性对象
+const globalConfig = {
+  $url: baseUrl,
+  apiUrl: apiUrl,
+  $appName: '医疗小程序',
+  $version: '1.0.0'
+}
+
+// 批量注册
+Object.keys(globalConfig).forEach(key => {
+  app.config.globalProperties[key] = globalConfig[key]
+})
+```
+
+### 2. 创建辅助函数
+
+```javascript
+// utils/global.js
+import { getCurrentInstance } from 'vue'
+
+export const useGlobal = () => {
+  const instance = getCurrentInstance()
+  const globalProps = instance.appContext.config.globalProperties
+  
+  return {
+    baseUrl: globalProps.$url,
+    apiUrl: globalProps.apiUrl,
+    appName: globalProps.$appName,
+    version: globalProps.$version
+  }
+}
+```
+
+### 3. 在组件中使用
+
+```vue
+<script setup>
+import { useGlobal } from '@/utils/global'
+
+const { baseUrl, apiUrl } = useGlobal()
+
+console.log('Base URL:', baseUrl)
+</script>
+```
+
+## 常见问题
+
+### Q: 如何在非组件中使用全局属性？
+
+A: 在 API 服务中使用 `getCurrentInstance()` 获取全局属性。
+
+### Q: 如何动态修改全局属性？
+
+A: 直接修改 `app.config.globalProperties` 中的值：
+
+```javascript
+const instance = getCurrentInstance()
+instance.appContext.config.globalProperties.$url = 'http://new-url'
+```
+
+### Q: 全局属性和 provide/inject 的区别？
+
+A: 
+- 全局属性：所有组件都可以访问，通过 `this.$property` 或 `getCurrentInstance()` 获取
+- provide/inject：父组件提供，子组件注入，更灵活但需要显式提供
+
+### Q: 如何在 Composition API 中使用全局属性？
+
+A: 使用 `getCurrentInstance()` 获取实例，然后访问 `appContext.config.globalProperties`。
+
+## 相关文件
+
+- 全局配置: `TUICallKit-Vue3/main.js`
+- API 服务: `TUICallKit-Vue3/utils/api.js`
+- 全局工具: `TUICallKit-Vue3/utils/global.js`（可选）
+
+## 总结
+
+通过 `app.config.globalProperties` 定义的全局属性可以在整个应用中访问，是管理全局配置和方法的最佳方式。