wip: 临时提交
This commit is contained in:
ray
361
docs/theme-guide.md
Normal file
361
docs/theme-guide.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# 主题设置功能指南
|
||||
|
||||
## 功能概述
|
||||
|
||||
本项目提供了完整的主题设置功能，支持暗黑模式切换和主题色自定义，让用户可以个性化应用的外观。
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. 暗黑模式
|
||||
|
||||
- 支持浅色/暗黑模式切换
|
||||
- 自动保存用户偏好设置
|
||||
- 平滑的过渡动画效果
|
||||
- 导航栏颜色自动适配
|
||||
|
||||
### 2. 主题色设置
|
||||
|
||||
- 12种预设主题色可选
|
||||
- 支持自定义十六进制颜色值
|
||||
- 实时预览效果
|
||||
- 主题色持久化存储
|
||||
|
||||
### 3. 效果预览
|
||||
|
||||
- 按钮样式预览
|
||||
- 文本颜色预览
|
||||
- 标签组件预览
|
||||
- 实时更新显示
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── composables/
|
||||
│ └── theme/
|
||||
│ ├── theme.ts # 主题管理核心逻辑
|
||||
│ └── rootTheme.ts # 主题配置和默认值
|
||||
├── store/
|
||||
│ └── modules/
|
||||
│ └── theme.ts # 主题状态管理
|
||||
├── pages/
|
||||
│ └── setting.vue # 主题设置页面
|
||||
├── utils/
|
||||
│ ├── theme.ts # 主题工具函数
|
||||
│ └── colorUtils.ts # 颜色处理工具
|
||||
└── styles/
|
||||
└── global.scss # 全局主题样式
|
||||
```
|
||||
|
||||
## 核心组件说明
|
||||
|
||||
### 1. useTheme Composable
|
||||
|
||||
位置：`src/composables/theme/theme.ts`
|
||||
|
||||
主要功能：
|
||||
|
||||
- 主题模式切换（浅色/暗黑）
|
||||
- 主题色设置和保存
|
||||
- 导航栏颜色适配
|
||||
- 本地存储管理
|
||||
|
||||
```typescript
|
||||
const {
|
||||
theme, // 当前主题模式
|
||||
themeVars, // 主题变量
|
||||
toggleTheme, // 切换主题模式
|
||||
setThemeColor, // 设置主题色
|
||||
initTheme, // 初始化主题
|
||||
} = useTheme();
|
||||
```
|
||||
|
||||
### 2. useThemeStore
|
||||
|
||||
位置：`src/store/modules/theme.ts`
|
||||
|
||||
主要功能：
|
||||
|
||||
- 主题色状态管理
|
||||
- CSS变量动态设置
|
||||
- 多平台兼容处理
|
||||
|
||||
```typescript
|
||||
const themeStore = useThemeStore();
|
||||
|
||||
// 设置主题色
|
||||
themeStore.setPrimaryColor("#165DFF");
|
||||
|
||||
// 初始化主题
|
||||
themeStore.initTheme();
|
||||
```
|
||||
|
||||
### 3. 主题设置页面
|
||||
|
||||
位置：`src/pages/setting.vue`
|
||||
|
||||
功能模块：
|
||||
|
||||
- 暗黑模式开关
|
||||
- 预设主题色选择
|
||||
- 自定义颜色输入
|
||||
- 效果实时预览
|
||||
- 重置默认主题
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 基础使用
|
||||
|
||||
在页面中引入主题功能：
|
||||
|
||||
```vue
|
||||
<script setup>
|
||||
import { useTheme } from "@/composables/theme/theme";
|
||||
import { useThemeStore } from "@/store/modules/theme";
|
||||
|
||||
const { theme, themeVars, toggleTheme } = useTheme();
|
||||
const themeStore = useThemeStore();
|
||||
|
||||
// 切换暗黑模式
|
||||
function switchTheme() {
|
||||
toggleTheme();
|
||||
}
|
||||
|
||||
// 设置主题色
|
||||
function changeThemeColor(color) {
|
||||
themeStore.setPrimaryColor(color);
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<wd-config-provider :theme-vars="themeVars" :theme="theme">
|
||||
<!-- 你的页面内容 -->
|
||||
</wd-config-provider>
|
||||
</template>
|
||||
```
|
||||
|
||||
### 2. 在布局中使用
|
||||
|
||||
在 `src/layouts/tabbar.vue` 中已经集成了主题功能：
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<wd-config-provider :theme-vars="themeVars" :theme="theme">
|
||||
<!-- 布局内容 -->
|
||||
</wd-config-provider>
|
||||
</template>
|
||||
```
|
||||
|
||||
### 3. 自定义主题色
|
||||
|
||||
支持的颜色格式：
|
||||
|
||||
- 6位十六进制：`#165DFF`
|
||||
- 3位十六进制：`#16F`（会自动转换为6位）
|
||||
|
||||
```javascript
|
||||
// 设置自定义主题色
|
||||
const customColor = "#FF6B6B";
|
||||
themeStore.setPrimaryColor(customColor);
|
||||
```
|
||||
|
||||
## 预设主题色
|
||||
|
||||
项目提供了12种预设主题色：
|
||||
|
||||
| 颜色名称 | 颜色值 | 说明 |
|
||||
| -------- | ------- | ---------- |
|
||||
| 蓝色 | #0055FE | 默认主题色 |
|
||||
| 红色 | #CD5C5C | 经典红色 |
|
||||
| 绿色 | #228B22 | 自然绿色 |
|
||||
| 紫色 | #722ED1 | 优雅紫色 |
|
||||
| 橙色 | #FA8C16 | 活力橙色 |
|
||||
| 黄色 | #FADB14 | 明亮黄色 |
|
||||
| 青色 | #13C2C2 | 清新青色 |
|
||||
| 粉色 | #EB2F96 | 温馨粉色 |
|
||||
| 天蓝色 | #1890FF | 科技蓝色 |
|
||||
| 深红色 | #F5222D | 警示红色 |
|
||||
|
||||
## 样式变量
|
||||
|
||||
主题系统使用CSS变量来实现动态主题切换：
|
||||
|
||||
```scss
|
||||
:root {
|
||||
/* 主色调 */
|
||||
--primary-color: #165dff;
|
||||
--primary-color-light: #94bfff;
|
||||
--primary-color-dark: #0e3c9b;
|
||||
|
||||
/* 功能色 */
|
||||
--success-color: #0fc6c2;
|
||||
--warning-color: #ff7d00;
|
||||
--danger-color: #f5222d;
|
||||
--info-color: #86909c;
|
||||
}
|
||||
```
|
||||
|
||||
在组件中使用：
|
||||
|
||||
```scss
|
||||
.my-button {
|
||||
background-color: var(--primary-color);
|
||||
color: #fff;
|
||||
|
||||
&:hover {
|
||||
background-color: var(--primary-color-dark);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 平台兼容性
|
||||
|
||||
### H5平台
|
||||
|
||||
- 使用CSS变量动态设置主题
|
||||
- 支持所有现代浏览器
|
||||
- 平滑的过渡动画
|
||||
|
||||
### 小程序平台
|
||||
|
||||
- 使用原生API设置TabBar样式
|
||||
- 通过工具函数处理样式应用
|
||||
- 兼容微信、支付宝等小程序
|
||||
|
||||
### APP平台
|
||||
|
||||
- 支持原生导航栏颜色设置
|
||||
- 状态栏颜色自动适配
|
||||
- 性能优化处理
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 主题初始化
|
||||
|
||||
在应用启动时初始化主题：
|
||||
|
||||
```typescript
|
||||
// src/App.vue
|
||||
import { useThemeStore } from "@/store/modules/theme";
|
||||
|
||||
const themeStore = useThemeStore();
|
||||
|
||||
onLaunch(() => {
|
||||
// 初始化主题
|
||||
themeStore.initTheme();
|
||||
});
|
||||
```
|
||||
|
||||
### 2. 组件中使用主题
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<view class="my-component">
|
||||
<text class="title">标题</text>
|
||||
<button class="primary-btn">按钮</button>
|
||||
</view>
|
||||
</template>
|
||||
|
||||
<style lang="scss" scoped>
|
||||
.my-component {
|
||||
.title {
|
||||
color: var(--primary-color);
|
||||
}
|
||||
|
||||
.primary-btn {
|
||||
background: var(--primary-color);
|
||||
color: #fff;
|
||||
border: none;
|
||||
border-radius: 8rpx;
|
||||
|
||||
&:active {
|
||||
background: var(--primary-color-dark);
|
||||
}
|
||||
}
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
### 3. 暗黑模式适配
|
||||
|
||||
```scss
|
||||
// 暗黑模式样式
|
||||
:deep(.wd-config-provider[data-theme="dark"]) {
|
||||
.my-component {
|
||||
background: #2a2a2a;
|
||||
color: #fff;
|
||||
|
||||
.title {
|
||||
color: var(--primary-color);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **性能优化**：主题切换时避免频繁的DOM操作
|
||||
2. **兼容性**：小程序环境下某些CSS特性可能不支持
|
||||
3. **用户体验**：提供平滑的过渡动画效果
|
||||
4. **持久化**：确保用户设置能够正确保存和恢复
|
||||
5. **响应式**：在不同屏幕尺寸下保持良好的显示效果
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 1. 主题色不生效
|
||||
|
||||
- 检查CSS变量是否正确设置
|
||||
- 确认组件是否在 `wd-config-provider` 包裹内
|
||||
- 验证颜色值格式是否正确
|
||||
|
||||
### 2. 暗黑模式切换异常
|
||||
|
||||
- 检查 `theme` 状态是否正确更新
|
||||
- 确认暗黑模式样式是否正确编写
|
||||
- 验证导航栏颜色设置是否生效
|
||||
|
||||
### 3. 设置不持久化
|
||||
|
||||
- 检查本地存储权限
|
||||
- 确认存储key是否正确
|
||||
- 验证初始化逻辑是否执行
|
||||
|
||||
## 扩展开发
|
||||
|
||||
### 1. 添加新的预设主题色
|
||||
|
||||
在 `src/composables/theme/rootTheme.ts` 中添加：
|
||||
|
||||
```typescript
|
||||
export const colorColumns = [
|
||||
// 现有颜色...
|
||||
{
|
||||
value: "#YOUR_COLOR",
|
||||
label: "你的颜色名称",
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
### 2. 自定义主题变量
|
||||
|
||||
在 `src/composables/theme/rootTheme.ts` 中扩展：
|
||||
|
||||
```typescript
|
||||
export const initThemeVars: ConfigProviderThemeVars = {
|
||||
colorTheme: colorColumns[0].value,
|
||||
// 添加更多主题变量
|
||||
colorSuccess: "#52c41a",
|
||||
colorWarning: "#faad14",
|
||||
colorDanger: "#ff4d4f",
|
||||
};
|
||||
```
|
||||
|
||||
### 3. 添加主题切换动画
|
||||
|
||||
```scss
|
||||
.theme-transition {
|
||||
transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
|
||||
}
|
||||
```
|
||||
|
||||
通过以上指南，你可以充分利用项目的主题设置功能，为用户提供个性化的应用体验。
|
||||
342
docs/wechat-login-guide.md
Normal file
342
docs/wechat-login-guide.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# 微信小程序手机授权登录功能指南
|
||||
|
||||
## 功能概述
|
||||
|
||||
本项目实现了完整的微信小程序手机授权登录功能，包括：
|
||||
|
||||
- 微信登录授权
|
||||
- 手机号获取授权
|
||||
- 头像昵称填写（使用微信小程序新能力）
|
||||
- 用户信息完善流程
|
||||
- 登录状态管理
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. 微信登录流程
|
||||
|
||||
- **基础微信登录**：使用 `uni.login()` 获取 code，调用后端接口完成登录
|
||||
- **增强微信登录**：支持更多用户信息和手机号一次性授权
|
||||
- **登录状态检查**：自动检查用户信息完整性，引导用户完善信息
|
||||
|
||||
### 2. 手机号授权
|
||||
|
||||
- **一键授权**：使用微信小程序 `getPhoneNumber` 能力
|
||||
- **安全获取**：通过后端接口解密获取真实手机号
|
||||
- **状态显示**：显示脱敏手机号，支持重新授权
|
||||
|
||||
### 3. 头像昵称填写
|
||||
|
||||
- **微信新能力**：使用 `chooseAvatar` 和 `type="nickname"` 输入框
|
||||
- **自动上传**：头像选择后自动上传到服务器
|
||||
- **实时预览**：支持头像实时预览和昵称输入
|
||||
|
||||
### 4. 用户信息完善
|
||||
|
||||
- **智能引导**：登录后自动检查信息完整性
|
||||
- **分步填写**：头像、昵称、性别、手机号分步骤完善
|
||||
- **跳过机制**：允许用户暂时跳过，但会提示影响功能使用
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
src/
|
||||
├── pages/
|
||||
│ └── login/
|
||||
│ ├── index.vue # 登录页面
|
||||
│ └── complete-profile.vue # 完善信息页面
|
||||
├── components/
|
||||
│ └── WechatProfile.vue # 微信头像昵称组件
|
||||
├── api/
|
||||
│ ├── auth.ts # 认证API
|
||||
│ ├── user.ts # 用户API
|
||||
│ └── file.ts # 文件上传API
|
||||
├── store/
|
||||
│ └── modules/
|
||||
│ └── user.ts # 用户状态管理
|
||||
└── utils/
|
||||
├── auth.ts # 认证工具函数
|
||||
└── storage.ts # 存储工具函数
|
||||
```
|
||||
|
||||
## 核心组件说明
|
||||
|
||||
### 1. 登录页面 (`pages/login/index.vue`)
|
||||
|
||||
**主要功能：**
|
||||
|
||||
- 用户名密码登录
|
||||
- 微信一键登录
|
||||
- 登录状态检查和跳转
|
||||
|
||||
**关键代码：**
|
||||
|
||||
```typescript
|
||||
// 微信登录处理
|
||||
const handleWechatLogin = async () => {
|
||||
const { code } = await uni.login({ provider: "weixin" });
|
||||
|
||||
// 尝试增强登录
|
||||
try {
|
||||
const result = await userStore.loginByWechatMini({ code });
|
||||
// 检查信息完整性
|
||||
if (result.isNewUser || !result.isProfileComplete) {
|
||||
// 跳转到完善信息页面
|
||||
uni.navigateTo({
|
||||
url: `/pages/login/complete-profile?redirect=${redirect}`,
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
// 回退到基础登录
|
||||
await userStore.loginByWechat(code);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 2. 完善信息页面 (`pages/login/complete-profile.vue`)
|
||||
|
||||
**主要功能：**
|
||||
|
||||
- 头像上传（支持微信新能力）
|
||||
- 昵称输入
|
||||
- 性别选择
|
||||
- 手机号授权
|
||||
- 信息提交和验证
|
||||
|
||||
**关键代码：**
|
||||
|
||||
```typescript
|
||||
// 手机号授权
|
||||
const onGetPhoneNumber = async (e: any) => {
|
||||
if (e.detail.errMsg === "getPhoneNumber:ok") {
|
||||
const phoneData = await UserAPI.getPhoneNumber({
|
||||
code: e.detail.code,
|
||||
encryptedData: e.detail.encryptedData,
|
||||
iv: e.detail.iv,
|
||||
});
|
||||
profileForm.mobile = phoneData.phoneNumber;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### 3. 微信头像昵称组件 (`components/WechatProfile.vue`)
|
||||
|
||||
**主要功能：**
|
||||
|
||||
- 使用微信小程序头像选择能力
|
||||
- 昵称输入框（type="nickname"）
|
||||
- 性别选择
|
||||
- 数据双向绑定
|
||||
|
||||
**关键代码：**
|
||||
|
||||
```vue
|
||||
<!-- 头像选择 -->
|
||||
<button open-type="chooseAvatar" @chooseavatar="onChooseAvatar">
|
||||
<image v-if="avatar" :src="avatar" />
|
||||
</button>
|
||||
|
||||
<!-- 昵称输入 -->
|
||||
<input v-model="nickname" type="nickname" placeholder="请输入昵称" />
|
||||
```
|
||||
|
||||
## API 接口说明
|
||||
|
||||
### 1. 认证相关接口
|
||||
|
||||
```typescript
|
||||
// 基础微信登录
|
||||
AuthAPI.wechatLogin(code: string): Promise<LoginResult>
|
||||
|
||||
// 增强微信登录
|
||||
AuthAPI.wechatMiniLogin(data: WechatMiniLoginData): Promise<WechatLoginResult>
|
||||
```
|
||||
|
||||
### 2. 用户相关接口
|
||||
|
||||
```typescript
|
||||
// 获取微信手机号
|
||||
UserAPI.getPhoneNumber(data: WechatPhoneData): Promise<PhoneNumberResult>
|
||||
|
||||
// 绑定手机号
|
||||
UserAPI.bindMobile(data: MobileBindingForm): Promise<void>
|
||||
|
||||
// 更新用户信息
|
||||
UserAPI.updateProfile(data: UserProfileForm): Promise<void>
|
||||
```
|
||||
|
||||
### 3. 文件上传接口
|
||||
|
||||
```typescript
|
||||
// 上传文件
|
||||
FileAPI.upload(filePath: string): Promise<FileInfo>
|
||||
```
|
||||
|
||||
## 类型定义
|
||||
|
||||
### 微信登录相关
|
||||
|
||||
```typescript
|
||||
interface WechatMiniLoginData {
|
||||
code: string;
|
||||
userInfo?: {
|
||||
nickName?: string;
|
||||
avatarUrl?: string;
|
||||
gender?: number;
|
||||
};
|
||||
phoneData?: {
|
||||
code: string;
|
||||
encryptedData?: string;
|
||||
iv?: string;
|
||||
};
|
||||
}
|
||||
|
||||
interface WechatLoginResult extends LoginResult {
|
||||
isNewUser?: boolean;
|
||||
isProfileComplete?: boolean;
|
||||
userInfo?: {
|
||||
userId?: number;
|
||||
username?: string;
|
||||
nickname?: string;
|
||||
avatar?: string;
|
||||
mobile?: string;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 手机号授权相关
|
||||
|
||||
```typescript
|
||||
interface WechatPhoneData {
|
||||
code: string;
|
||||
encryptedData?: string;
|
||||
iv?: string;
|
||||
}
|
||||
|
||||
interface PhoneNumberResult {
|
||||
phoneNumber: string;
|
||||
purePhoneNumber?: string;
|
||||
countryCode?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 1. 用户首次登录
|
||||
|
||||
1. 用户点击微信登录按钮
|
||||
2. 调用 `uni.login()` 获取微信 code
|
||||
3. 调用后端登录接口，获取 token
|
||||
4. 检查用户信息完整性
|
||||
5. 如果信息不完整，跳转到完善信息页面
|
||||
|
||||
### 2. 完善用户信息
|
||||
|
||||
1. 用户进入完善信息页面
|
||||
2. 选择头像（使用微信新能力或传统上传）
|
||||
3. 输入昵称（使用 type="nickname" 输入框）
|
||||
4. 选择性别
|
||||
5. 授权获取手机号
|
||||
6. 提交信息，更新用户资料
|
||||
|
||||
### 3. 后续登录
|
||||
|
||||
1. 用户再次登录时，检查信息完整性
|
||||
2. 如果信息完整，直接跳转到主页
|
||||
3. 如果信息不完整，引导用户完善
|
||||
|
||||
## 配置要求
|
||||
|
||||
### 1. 微信小程序配置
|
||||
|
||||
在 `manifest.json` 中配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"mp-weixin": {
|
||||
"appid": "your-appid",
|
||||
"setting": {
|
||||
"urlCheck": false
|
||||
},
|
||||
"permission": {
|
||||
"scope.userInfo": {
|
||||
"desc": "用于完善用户资料"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 后端接口要求
|
||||
|
||||
- 支持微信登录 code 解析
|
||||
- 支持微信手机号解密
|
||||
- 支持文件上传
|
||||
- 支持用户信息更新
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 1. 微信小程序新能力
|
||||
|
||||
- `chooseAvatar` 和 `type="nickname"` 需要微信基础库 2.21.2+
|
||||
- 需要在微信开发者工具中测试
|
||||
- 真机调试时需要注意兼容性
|
||||
|
||||
### 2. 手机号授权
|
||||
|
||||
- 需要微信小程序认证
|
||||
- 需要在微信公众平台配置服务器域名
|
||||
- 手机号解密需要在后端完成
|
||||
|
||||
### 3. 用户体验
|
||||
|
||||
- 提供跳过机制，避免强制完善信息
|
||||
- 显示脱敏手机号，保护用户隐私
|
||||
- 支持重新授权和修改信息
|
||||
|
||||
## 扩展功能
|
||||
|
||||
### 1. 社交登录
|
||||
|
||||
可以扩展支持其他社交平台登录：
|
||||
|
||||
- QQ 登录
|
||||
- 支付宝登录
|
||||
- 苹果登录
|
||||
|
||||
### 2. 实名认证
|
||||
|
||||
可以添加实名认证功能：
|
||||
|
||||
- 身份证验证
|
||||
- 人脸识别
|
||||
- 银行卡验证
|
||||
|
||||
### 3. 多端同步
|
||||
|
||||
可以实现多端登录状态同步：
|
||||
|
||||
- H5 端登录
|
||||
- APP 端登录
|
||||
- 小程序端登录
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 1. 微信登录失败
|
||||
|
||||
- 检查 appid 配置
|
||||
- 检查服务器域名配置
|
||||
- 检查网络连接
|
||||
|
||||
### 2. 手机号授权失败
|
||||
|
||||
- 检查小程序是否已认证
|
||||
- 检查后端解密接口
|
||||
- 检查用户授权状态
|
||||
|
||||
### 3. 头像上传失败
|
||||
|
||||
- 检查文件上传接口
|
||||
- 检查文件大小限制
|
||||
- 检查网络状态
|
||||
|
||||
## 总结
|
||||
Reference in New Issue
Block a user