验证中...}
component={}
/>
);
}
```
### 2. 用户状态管理
```tsx
import { useUser } from '@gulibs/vgrove-client';
function AuthComponent() {
const {
user,
isAuthenticated,
isLoading,
login,
logout,
error
} = useUser({
loginApi: async (credentials) => {
const response = await fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credentials)
});
return response.json();
},
fetchUser: async (token) => {
const response = await fetch('/api/user', {
headers: { Authorization: `Bearer ${token}` }
});
return response.json();
}
});
if (isLoading) return 加载中...
;
if (error) return 错误: {error}
;
return (
{isAuthenticated ? (
) : (
)}
组件内容
;
}
```
#### 3.5 验证修复效果
```tsx
// 验证工具：检查页面是否使用了快速通道
function usePerformanceVerification() {
const [hasLayoutShift, setHasLayoutShift] = useState(false);
const [renderTime, setRenderTime] = useState(0);
useEffect(() => {
const startTime = performance.now();
// 检测布局抖动
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.entryType === 'layout-shift' && entry.value > 0) {
setHasLayoutShift(true);
}
}
});
observer.observe({ entryTypes: ['layout-shift'] });
// 测量渲染时间
requestAnimationFrame(() => {
setRenderTime(performance.now() - startTime);
});
return () => observer.disconnect();
}, []);
return { hasLayoutShift, renderTime };
}
// 使用验证工具
function VerifiedPage() {
const { hasLayoutShift, renderTime } = usePerformanceVerification();
return (
} />
{process.env.NODE_ENV === 'development' && (
布局抖动: {hasLayoutShift ? '❌ 检测到' : '✅ 无'}
渲染时间: {renderTime.toFixed(2)}ms
)}
);
}
```
### 4. 国际化支持
```tsx
import { I18nProvider, useI18n, createI18nClient } from '@gulibs/vgrove-client';
// 创建国际化客户端
const i18nClient = createI18nClient({
defaultLocale: 'zh',
supportedLocales: ['zh', 'en'],
resources: {
zh: {
welcome: '欢迎',
hello: '你好, {name}!'
},
en: {
welcome: 'Welcome',
hello: 'Hello, {name}!'
}
}
});
function App() {
return (
);
}
function MyComponent() {
const { t, locale, setLocale } = useI18n();
return (
{t('welcome')}
{t('hello', { name: '张三' })}
);
}
```
### 5. 存储管理
```tsx
import { useStorage } from '@gulibs/vgrove-client';
function StorageExample() {
// 基础存储使用
const [userPrefs, setUserPrefs, removeUserPrefs] = useStorage('user_preferences', {
theme: 'light',
language: 'zh'
});
// 使用 sessionStorage
const [tempData, setTempData] = useStorage('temp_data', null, {
storage: 'session'
});
// 带过期时间的存储（1小时后过期）
const [cacheData, setCacheData, removeCacheData, setCacheWithExpiry, isCacheExpired, cleanupCache] = useStorage(
'api_cache',
{},
{
storage: 'local',
maxAge: 60 * 60 * 1000, // 1小时
autoCleanup: true, // 自动清理过期数据
cleanupInterval: 5 * 60 * 1000 // 每5分钟清理一次
}
);
// 临时令牌存储（30分钟后过期）
const [tempToken, setTempToken, removeTempToken, setTokenWithExpiry, isTokenExpired] = useStorage(
'temp_token',
null,
{
storage: 'session',
maxAge: 30 * 60 * 1000, // 30分钟
autoCleanup: true
}
);
return (
当前主题: {userPrefs.theme}
{/* 缓存数据管理 */}
缓存状态: {isCacheExpired() ? '已过期' : '有效'}
{/* 临时令牌管理 */}
令牌状态: {isTokenExpired() ? '已过期' : '有效'}
);
}
```
### 6. 认证状态管理 Hooks
```tsx
import { useUser, useUserState, useAuthToken } from '@gulibs/vgrove-client';
// 只读用户状态
function ReadOnlyUserInfo() {
const { user, isAuthenticated, token } = useUserState('auth', false);
if (!isAuthenticated) return 未登录
;
return (
用户: {user?.name}
Token: {token?.substring(0, 20)}...
);
}
// Token 管理
function TokenManager() {
const {
token,
refreshToken,
setToken,
setRefreshToken,
clearAllTokens,
hasToken,
hasRefreshToken
} = useAuthToken('auth');
return (
有 Token: {hasToken ? '是' : '否'}
有 Refresh Token: {hasRefreshToken ? '是' : '否'}
);
}
```
### 7. 路由保护的不同形式
```tsx
import {
RouteProtectionWrapper,
withRouteProtection,
useRouteProtection
} from '@gulibs/vgrove-client';
// 1. 组件包装器形式（已展示）
function ComponentWrapper() {
return (
}
/>
);
}
// 2. 高阶组件形式
const ProtectedComponent = withRouteProtection(MyComponent, {
guards: [authGuard, adminGuard],
loadingElement: 验证中...
});
function App() {
return ;
}
// 3. Hook 形式
function HookBasedProtection() {
const { isLoading, error, hasAccess, user } = useRouteProtection([authGuard]);
if (isLoading) return 检查访问权限...
;
if (error) return 错误: {error}
;
if (!hasAccess) return 访问被拒绝
;
return (
);
}
```
## 🛡️ 认证与守卫系统完全指南
### 认证 vs 守卫的区别
| 特性 | Auth （认证） | Guard （守卫） |
|------|-------------|--------------|
| **主要用途** | 身份验证 | 权限控制 |
| **检查内容** | 用户是否已登录 | 用户是否有权限访问 |
| **失败后果** | 重定向到登录页 | 重定向到错误页 / 拒绝页 |
| **适用场景** | 保护需要登录的页面 | 保护需要特定权限的页面 |
| **执行顺序** | 优先执行 | 在认证通过后执行 |
### 🔐 认证系统详解
#### 1. 基础认证 - defineAuth
**最简单的认证方式，适合基础的登录检查**
```tsx
import { defineAuth } from '@gulibs/vgrove-client';
// 页面级认证文件：pages/dashboard/auth.ts
export default defineAuth({
name: 'dashboard-auth', // 认证名称（可选）
redirectTo: '/login', // 失败时重定向路径
errorMessage: '请先登录访问仪表板', // 错误消息
check: (context) => { // 认证检查函数
// context 包含：path, params, query, user, roles, permissions, data
const token = localStorage.getItem('auth_token');
// ⚠️ 关键：必须返回 boolean 值
return !!token;
}
});
```
**❌ 常见错误：**
```tsx
// 错误1：没有返回值
check: (context) => {
const token = localStorage.getItem('auth_token');
// ❌ 缺少 return 语句
}
// 错误2：返回非布尔值
check: (context) => {
return localStorage.getItem('auth_token'); // ❌ 返回 string | null
}
// 错误3：异步函数但没有正确处理
check: (context) => {
return fetch('/api/verify').then(res => res.ok); // ❌ 返回 Promise
}
```
**✅ 正确用法：**
```tsx
// 同步检查
check: (context) => {
const token = localStorage.getItem('auth_token');
return !!token; // ✅ 返回 boolean
}
// 异步检查
check: async (context) => {
try {
const response = await fetch('/api/verify', {
headers: { Authorization: `Bearer ${context.user?.token}` }
});
return response.ok; // ✅ 返回 boolean
} catch (error) {
console.error('Auth check failed:', error);
return false; // ✅ 异常时返回 false
}
}
```
#### 2. 智能认证 - defineSmartAuth ⭐
**推荐使用！自动处理循环重定向，防止常见错误**
```tsx
import { defineSmartAuth } from '@gulibs/vgrove-client';
// 页面级认证文件：pages/auth.ts (根目录)
export default defineSmartAuth({
name: 'root-smart-auth',
redirectTo: '/login',
errorMessage: '请先登录后访问应用',
// 🚀 智能特性配置
enableLoopDetection: true, // 启用循环重定向检测
excludeCommonPublicPaths: true, // 自动排除常见公共路径
publicPaths: [ // 自定义公共路径
'/about',
'/help',
'/docs/*', // 支持通配符
'/api/*'
],
check: (context) => {
// 智能认证会自动处理：
// 1. 如果是公共路径，直接允许访问
// 2. 如果检测到循环重定向，自动阻止
// 3. 然后才执行这里的检查逻辑
const token = localStorage.getItem('auth_token');
console.log('🔐 Smart Auth Check:', {
path: context.path,
hasToken: !!token,
user: context.user
});
return !!token;
}
});
```
**内置公共路径列表：**
```tsx
// defineSmartAuth 自动排除这些路径：
const DEFAULT_PUBLIC_PATHS = [
'/login', '/signin', '/sign-in',
'/register', '/signup', '/sign-up',
'/auth/login', '/auth/signin',
'/auth/register', '/auth/signup',
'/reset-password', '/forgot-password',
'/verify-email', '/verify',
'/public', '/'
];
```
#### 3. 根目录认证 - defineRootAuth
**专用于整个应用的登录保护**
```tsx
import { defineRootAuth } from '@gulibs/vgrove-client';
// 页面级认证文件：pages/auth.ts
export default defineRootAuth({
redirectTo: '/login',
errorMessage: '请先登录后访问应用',
publicPaths: ['/help', '/about'], // 自定义公共路径
check: (context) => {
const token = localStorage.getItem('auth_token');
return !!token;
}
});
```
### 🛡️ 守卫系统详解
#### 1. 自定义守卫 - defineGuard
**适用于复杂的业务逻辑判断**
```tsx
import { defineGuard } from '@gulibs/vgrove-client';
// 页面级守卫文件：pages/admin/guard.ts
export default defineGuard({
name: 'admin-access', // 守卫名称
type: 'custom', // 守卫类型
redirectTo: '/forbidden', // 失败时重定向
errorMessage: '需要管理员权限访问此页面', // 错误消息
condition: (context) => { // 守卫条件函数
// context 包含：path, params, query, user, permissions, roles, data
// 检查用户角色
if (!context.user?.role) return false;
// 检查是否是管理员
const isAdmin = context.user.role === 'admin';
// 检查时间限制（示例：只允许工作时间访问）
const now = new Date();
const workingHours = now.getHours() >= 9 && now.getHours() <= 18;
return isAdmin && workingHours;
}
});
```
#### 2. 角色守卫 - defineRoleGuard
**基于用户角色的访问控制**
```tsx
import { defineRoleGuard } from '@gulibs/vgrove-client';
// 在 _configs.tsx 中使用
export default defineConfigs({
guard: defineRoleGuard(
['admin', 'manager'], // 允许的角色列表
'/forbidden', // 可选：重定向路径
{ // 可选：额外选项
publicPaths: ['/help'],
enableLoopDetection: true
}
)
});
```
#### 3. 权限守卫 - definePermissionGuard
**基于具体权限的访问控制**
```tsx
import { definePermissionGuard } from '@gulibs/vgrove-client';
// 在 _configs.tsx 中使用
export default defineConfigs({
guard: definePermissionGuard(
['user.write', 'user.update'], // 所需权限列表
'/no-permission', // 可选：重定向路径
{ // 可选：额外选项
enableLoopDetection: true
}
)
});
```
#### 4. 守卫工厂函数
**快速创建常用的守卫**
```tsx
import { defineCustomGuard } from '@gulibs/vgrove-client';
// VIP 用户守卫
export const vipGuard = defineCustomGuard(
'vip-only',
(context) => context.user?.membership === 'VIP',
'/upgrade'
);
// 时间限制守卫
export const workingHoursGuard = defineCustomGuard(
'working-hours',
(context) => {
const hour = new Date().getHours();
return hour >= 9 && hour <= 18;
},
'/not-available'
);
// 地理位置守卫
export const regionGuard = defineCustomGuard(
'region-check',
async (context) => {
const region = await getUserRegion();
return ['US', 'CA', 'EU'].includes(region);
},
'/region-blocked'
);
```
### 📁 使用方式对比
#### 方式 1：单文件方式
```
src/pages/
├── dashboard/
│ ├── auth.ts # 认证配置
│ ├── guard.ts # 守卫配置
│ └── page.tsx # 页面组件
└── admin/
├── auth.ts
├── guard.ts
└── page.tsx
```
**优点：** 功能分离清晰，易于理解
**缺点：** 文件较多，配置分散
#### 方式 2：配置文件方式 （推荐）
```
src/pages/
├── dashboard/
│ ├── _configs.tsx # 集中配置
│ └── page.tsx # 页面组件
└── admin/
├── _configs.tsx
└── page.tsx
```
**优点：** 配置集中，支持自定义组件，功能完整
**缺点：** 单文件可能较大
**完整示例：**
```tsx
// pages/dashboard/_configs.tsx
import { defineConfigs, defineSmartAuth, defineGuard } from '@gulibs/vgrove-client';
import React from 'react';
// 自定义错误组件
const AccessDeniedError = ({ error, retry }: { error?: Error; retry?: () => void }) => (
访问被拒绝
{error?.message}
);
// 自定义加载组件
const AuthLoading = ({ progress }: { progress?: number }) => (
验证身份中...
{progress &&
进度: {Math.round(progress * 100)}%
}
);
export default defineConfigs({
// 智能认证配置
auth: defineSmartAuth({
name: 'dashboard-smart-auth',
redirectTo: '/login',
errorMessage: '请先登录访问仪表板',
enableLoopDetection: true,
excludeCommonPublicPaths: true,
check: (context) => {
const token = localStorage.getItem('auth_token');
console.log('Dashboard auth check:', {
path: context.path,
hasToken: !!token
});
return !!token;
}
}),
// 守卫配置
guard: defineGuard({
name: 'dashboard-access',
type: 'custom',
redirectTo: '/upgrade',
errorMessage: '需要升级账户以访问仪表板',
condition: (context) => {
// 检查用户类型
if (!context.user) return false;
// 免费用户不能访问仪表板
return context.user.plan !== 'free';
}
}),
// 自定义错误组件
error: AccessDeniedError,
// 自定义加载组件
loading: AuthLoading
});
```
### 🚨 常见错误和解决方案
#### 错误 1：循环重定向死循环
**症状：** 页面不断重定向，浏览器显示"重定向次数过多"
**原因：** 登录页面设置了认证保护
```tsx
// ❌ 错误示例
// pages/login/auth.ts
export default defineAuth({
redirectTo: '/login', // 重定向到自己
check: () => false // 总是返回false
});
```
**解决方案：**
```tsx
// ✅ 方案1：删除登录页面的认证文件
// 直接删除 pages/login/auth.ts
// ✅ 方案2：使用智能认证自动处理
export default defineSmartAuth({
redirectTo: '/login',
enableLoopDetection: true, // 自动检测并阻止循环
excludeCommonPublicPaths: true, // 自动排除登录页面
check: (context) => !!context.user
});
```
#### 错误 2：守卫执行顺序混乱
**症状：** 权限检查在认证检查之前执行
```tsx
// ❌ 错误：在需要认证的页面只设置守卫
export default defineConfigs({
// 缺少 auth 配置
guard: defineGuard({
condition: (context) => context.user?.role === 'admin' // 用户可能为 null
})
});
// ✅ 正确：先认证，再守卫
export default defineConfigs({
// 先进行身份认证
auth: defineSmartAuth({
redirectTo: '/login',
check: (context) => !!context.user
}),
// 认证通过后检查权限
guard: defineGuard({
condition: (context) => {
// 此时 context.user 已经确保存在
return context.user?.role === 'admin';
},
redirectTo: '/forbidden'
})
});
```
### 🎯 最佳实践
#### 1. 分层认证架构
```
src/pages/
├── auth.ts # 根目录：基础身份认证
├── public/ # 公开页面（无需认证）
│ ├── login/
│ ├── register/
│ └── about/
├── user/ # 用户区域
│ ├── _configs.tsx # 用户认证 + 基础权限
│ ├── dashboard/
│ └── profile/
├── admin/ # 管理员区域
│ ├── _configs.tsx # 管理员认证 + 管理权限
│ ├── users/
│ └── settings/
└── premium/ # 高级功能区域
├── _configs.tsx # 会员认证 + 会员权限
└── analytics/
```
#### 2. 认证状态管理
```tsx
// utils/auth.ts - 集中的认证工具
export class AuthManager {
private static instance: AuthManager;
static getInstance(): AuthManager {
if (!AuthManager.instance) {
AuthManager.instance = new AuthManager();
}
return AuthManager.instance;
}
// 获取当前用户
getCurrentUser(): User | null {
try {
const userData = localStorage.getItem('user_data');
return userData ? JSON.parse(userData) : null;
} catch {
return null;
}
}
// 检查认证状态
isAuthenticated(): boolean {
const token = localStorage.getItem('auth_token');
const user = this.getCurrentUser();
return !!(token && user && user.status === 'active');
}
// 检查角色
hasRole(roles: string[]): boolean {
const user = this.getCurrentUser();
return user?.roles?.some(role => roles.includes(role)) || false;
}
// 检查权限
hasPermission(permissions: string[]): boolean {
const user = this.getCurrentUser();
return permissions.every(permission =>
user?.permissions?.includes(permission)
);
}
// 登出
logout(): void {
localStorage.removeItem('auth_token');
localStorage.removeItem('user_data');
localStorage.removeItem('refresh_token');
// 触发自定义事件通知其他组件
window.dispatchEvent(new CustomEvent('authStateChange'));
// 重定向到登录页
window.location.href = '/public/login';
}
}
// 在认证配置中使用
export default defineSmartAuth({
check: (context) => {
const authManager = AuthManager.getInstance();
return authManager.isAuthenticated();
}
});
```
#### 3. 调试和开发工具
```tsx
// utils/authDebug.ts - 认证调试工具
export class AuthDebugger {
private static enabled = process.env.NODE_ENV === 'development';
static log(message: string, data?: any): void {
if (!this.enabled) return;
console.group(`🔐 Auth Debug: ${message}`);
if (data) {
console.log('Data:', data);
}
console.log('Timestamp:', new Date().toISOString());
console.groupEnd();
}
static logAuthCheck(
checkName: string,
result: boolean,
context: any,
reason?: string
): void {
if (!this.enabled) return;
const emoji = result ? '✅' : '❌';
console.group(`${emoji} Auth Check: ${checkName}`);
console.log('Result:', result);
console.log('Context:', {
path: context.path,
user: context.user ? 'Present' : 'Missing',
roles: context.roles,
permissions: context.permissions
});
if (reason) console.log('Reason:', reason);
console.groupEnd();
}
}
// 在认证配置中使用
export default defineSmartAuth({
name: 'debug-auth',
redirectTo: '/login',
check: (context) => {
const token = localStorage.getItem('auth_token');
const result = !!token;
AuthDebugger.logAuthCheck(
'Token Check',
result,
context,
result ? 'Token found' : 'Token missing'
);
return result;
}
});
```
### 🔧 调试指南
#### 浏览器控制台调试命令
```javascript
// 1. 检查当前认证状态
console.log('Auth Token:', localStorage.getItem('auth_token'));
console.log('User Data:', JSON.parse(localStorage.getItem('user_data') || 'null'));
// 2. 模拟登录状态
localStorage.setItem('auth_token', 'debug-token-123');
localStorage.setItem('user_data', JSON.stringify({
id: 'debug-user',
name: 'Debug User',
role: 'admin',
status: 'active',
permissions: ['read', 'write', 'admin']
}));
// 3. 清除认证状态
localStorage.removeItem('auth_token');
localStorage.removeItem('user_data');
localStorage.removeItem('refresh_token');
// 4. 检查页面保护状态
console.log('Current Path:', window.location.pathname);
console.log('Should be protected:', !window.location.pathname.includes('/public/'));
```
### 📝 快速参考
#### 认证类型对比表
| 场景 | 推荐方案 | 配置示例 |
|------|----------|----------|
| 简单登录检查 | `defineAuth` | `check: (ctx) => !!ctx.user` |
| 复杂认证逻辑 | `defineSmartAuth` | `enableLoopDetection: true` |
| 根目录保护 | `defineRootAuth` | `publicPaths: ['/public/*']` |
| 角色权限 | `defineRoleGuard` | `['admin', 'manager']` |
| 具体权限 | `definePermissionGuard` | `['user.read', 'user.write']` |
| 自定义业务逻辑 | `defineGuard` | `condition: (ctx) => {...}` |
#### 记住这些关键点
- ✅ 认证函数必须返回 `boolean`
- ✅ 登录页面不要设置认证保护
- ✅ 使用 `defineSmartAuth` 避免循环重定向
- ✅ 先设置 `auth` 再设置 `guard`
- ✅ 异步认证要用 `async/await`
- ✅ 错误处理要提供用户友好的提示
---
> **💡 提示：** 对于初学者，建议先使用 `defineSmartAuth` 和 `defineRoleGuard`，它们内置了大部分常见错误的处理逻辑。
### 7. 高级国际化 Hooks
```tsx
import {
useI18nKeyValidator,
useI18nNamespace,
usePlural,
useTranslateLocalized
} from '@gulibs/vgrove-client';
// 键验证 Hook
function I18nKeyValidator() {
const { hasKey, validateKey, getAvailableKeys } = useI18nKeyValidator();
const checkKey = (key: string) => {
if (hasKey(key)) {
console.log('键存在:', key);
} else {
const { suggestions } = validateKey(key);
console.log('键不存在，建议:', suggestions);
}
};
return (
可用键数量: {getAvailableKeys().length}
);
}
// 命名空间 Hook
function NamespaceExample() {
const { t, resources, exists } = useI18nNamespace('user');
if (!exists) return 命名空间不存在
;
return (
{t('profile.title')}
{/* 相当于 user.profile.title */}
{t('profile.description')}
);
}
// 复数形式 Hook
function PluralExample() {
const plural = usePlural();
const [count, setCount] = useState(1);
return (
{plural('message.count', count, { count })}
);
}
// 本地化对象翻译 Hook
function LocalizedTranslation() {
const translateLocalized = useTranslateLocalized();
const localizedTitle = { localizedId: 'page.title' };
return (
{translateLocalized(localizedTitle)}
);
}
```
### 8. I18nMessage 组件
```tsx
import { I18nMessage, I18nTitle, I18nText, I18nSwitch } from '@gulibs/vgrove-client';
// 基础用法
function MyComponent() {
return (
);
}
// 使用便捷组件
function PageContent() {
return (
{/* 支持不同格式 */}
{/* 组件标记格式 */}
);
}
// 语言切换器
function LanguageSwitcher() {
return (
console.log('语言切换到:', locale)}
/>
);
}
```
### 9. 性能优化工具详细示例
```tsx
import {
PerformanceCache,
BatchProcessor,
PerformanceTracker,
MemoryOptimizer,
Debouncer,
measureAsync
} from '@gulibs/vgrove-client';
// 缓存管理
function CacheExample() {
const cache = useMemo(() => new PerformanceCache(100), []);
const fetchWithCache = useCallback(async (key: string) => {
if (cache.has(key)) {
return cache.get(key);
}
const data = await fetch(`/api/data/${key}`).then(res => res.json());
cache.set(key, data);
return data;
}, [cache]);
return (
缓存大小: {cache.size()}
);
}
// 批处理示例
function BatchProcessingExample() {
const batchProcessor = useMemo(() => new BatchProcessor(5, 100), []);
const processBatchData = useCallback(async () => {
const userIds = ['1', '2', '3', '4', '5', '6', '7', '8'];
const users = await batchProcessor.processBatch(
userIds,
async (id) => {
const response = await fetch(`/api/users/${id}`);
return response.json();
}
);
console.log('批处理完成:', users);
}, [batchProcessor]);
return (
);
}
// 性能追踪示例
function PerformanceExample() {
const tracker = useMemo(() => new PerformanceTracker(), []);
const expensiveOperation = useCallback(async () => {
tracker.startTimer('expensive-operation');
// 模拟耗时操作
await new Promise(resolve => setTimeout(resolve, 1000));
const duration = tracker.endTimer('expensive-operation');
console.log(`操作耗时: ${duration}ms`);
tracker.increment('operation-count');
console.log(`操作次数: ${tracker.getCounter('operation-count')}`);
}, [tracker]);
return (
);
}
// 防抖示例
function DebounceExample() {
const debouncer = useMemo(() => new Debouncer(), []);
const [searchTerm, setSearchTerm] = useState('');
const handleSearch = useCallback((term: string) => {
debouncer.debounce('search', () => {
console.log('搜索:', term);
// 执行实际搜索
}, 500);
}, [debouncer]);
return (
{
setSearchTerm(e.target.value);
handleSearch(e.target.value);
}}
placeholder="搜索（防抖 500ms）"
/>
);
}
// 内存优化示例
function MemoryOptimizationExample() {
useEffect(() => {
const memoryOptimizer = MemoryOptimizer.getInstance();
// 添加清理任务
memoryOptimizer.addCleanupTask(() => {
console.log('清理缓存数据');
// 清理各种缓存
});
// 启动定期清理（5分钟）
memoryOptimizer.startPeriodicCleanup(5 * 60 * 1000);
return () => {
// 组件卸载时进行清理
memoryOptimizer.runCleanup();
};
}, []);
return 内存优化已启用
;
}
// 异步性能测量
function AsyncMeasurementExample() {
const measureApiCall = useCallback(async () => {
const result = await measureAsync('api-call', async () => {
const response = await fetch('/api/data');
return response.json();
});
console.log('API 调用结果:', result);
console.log('耗时:', result.duration, 'ms');
}, []);
return (
);
}
```
### 10. 工具函数详细示例
```tsx
import {
normalizePath,
parseQuery,
buildQuery,
updateQuery,
debounce,
throttle,
deepMerge,
deepClone,
unique,
groupBy,
isEmpty,
safeParseInt,
toCamelCase,
toKebabCase,
capitalize,
truncate,
safely,
safelyAsync
} from '@gulibs/vgrove-client';
function UtilityFunctionsExample() {
// 路径处理
const normalizedPath = normalizePath('//api//users//profile//');
console.log(normalizedPath); // '/api/users/profile'
// 查询参数处理
const queryParams = parseQuery('?name=john&age=25&active=true');
console.log(queryParams); // { name: 'john', age: '25', active: 'true' }
const queryString = buildQuery({ name: 'jane', age: 30, active: false });
console.log(queryString); // 'name=jane&age=30&active=false'
const updatedUrl = updateQuery('/users', { page: 2, size: 10 });
console.log(updatedUrl); // '/users?page=2&size=10'
// 防抖和节流
const debouncedSearch = debounce((term: string) => {
console.log('搜索:', term);
}, 500);
const throttledScroll = throttle(() => {
console.log('滚动事件');
}, 100);
// 对象操作
const original = { a: 1, b: { c: 2 } };
const cloned = deepClone(original);
const merged = deepMerge({ x: 1 }, { y: 2, z: { a: 3 } });
// 数组操作
const items = [1, 2, 2, 3, 4, 4, 5];
const uniqueItems = unique(items);
console.log(uniqueItems); // [1, 2, 3, 4, 5]
const users = [
{ name: 'Alice', role: 'admin' },
{ name: 'Bob', role: 'user' },
{ name: 'Charlie', role: 'admin' }
];
const groupedUsers = groupBy(users, user => user.role);
console.log(groupedUsers);
// { admin: [Alice, Charlie], user: [Bob] }
// 字符串操作
const camelCase = toCamelCase('hello-world-example');
console.log(camelCase); // 'helloWorldExample'
const kebabCase = toKebabCase('HelloWorldExample');
console.log(kebabCase); // 'hello-world-example'
const capitalized = capitalize('hello world');
console.log(capitalized); // 'Hello world'
const truncated = truncate('This is a very long text', 10);
console.log(truncated); // 'This is a...'
// 安全操作
const safeValue = safely(() => JSON.parse('invalid json'), null);
console.log(safeValue); // null
const safeAsyncValue = safelyAsync(
async () => {
const response = await fetch('/api/data');
return response.json();
},
{ error: 'Failed to load' }
);
// 类型检查和转换
const emptyCheck = isEmpty(''); // true
const numberValue = safeParseInt('123abc', 0); // 123
return (
工具函数示例
标准化路径: {normalizedPath}
解析查询: {JSON.stringify(queryParams)}
构建查询: {queryString}
唯一数组: {JSON.stringify(uniqueItems)}
debouncedSearch(e.target.value)}
placeholder="防抖搜索"
/>
滚动内容...
);
}
```
### 11. 国际化路由集成
```tsx
import {
createI18nClient,
createI18nRouteLoader,
createI18nHandle,
useRouteI18n
} from '@gulibs/vgrove-client';
// 创建国际化客户端
const i18nClient = createI18nClient({
defaultLocale: 'zh',
supportedLocales: ['zh', 'en'],
basePath: '/api/locales'
});
// 创建路由加载器
const i18nLoader = createI18nRouteLoader(i18nClient, {
preloadAll: false,
delay: 0
});
// 路由配置
export const route = {
path: '/products/:id',
loader: i18nLoader,
handle: createI18nHandle({
meta: {
title: 'products.detail.title',
description: 'products.detail.description'
},
pageExtras: (context) => {
const { params, query } = context;
return (
);
}
})
};
// 组件使用
function ProductDetailPage() {
const {
locale,
isLoaded,
getLocalizedUrl,
waitForI18n
} = useRouteI18n();
const { t } = useI18n();
const { meta, pageExtras } = useHandle();
// 等待国际化资源加载
useEffect(() => {
waitForI18n().then(() => {
console.log('国际化资源加载完成');
});
}, [waitForI18n]);
if (!isLoaded) {
return Loading translations...
;
}
return (
{t('products.detail.title')}
{/* 动态生成的页面额外内容 */}
{pageExtras}
{/* 语言切换按钮 */}
);
}
```
### 12. 页面配置和 Hooks
```tsx
import {
useHandle,
defineHandle,
usePageMeta,
useBreadcrumbs,
useDocumentTitle
} from '@gulibs/vgrove-client';
// 定义页面处理配置
export const handle = defineHandle({
meta: {
title: 'page.title',
description: '页面描述'
},
breadcrumbs: {
href: '/current-page',
children: '当前页面'
},
// pageExtras 可以是静态内容或函数
pageExtras: (context) => {
// 可以访问路由上下文信息
const { path, params, query, matches, handle } = context;
return (
当前路径: {path}
路由参数: {JSON.stringify(params)}
查询参数: {JSON.stringify(query)}
匹配的路由数量: {matches.length}
{params.id &&
商品ID: {params.id}
}
{query.tab &&
当前标签: {query.tab}
}
);
}
});
function MyPage() {
// 获取页面配置
const { meta, breadcrumbs, pageExtras } = useHandle();
return (
{meta?.title}
{/* 渲染动态生成的额外内容 */}
{pageExtras}
{/* 页面内容 */}
);
}
// 使用页面元数据 Hook
function PageWithMeta() {
const meta = usePageMeta(handle, { enableI18n: true });
const updateTitle = useDocumentTitle(handle, 'My App', { enableI18n: true });
useEffect(() => {
updateTitle(); // 设置文档标题
}, [updateTitle]);
return (
{meta?.title}
{meta?.description}
);
}
// 使用面包屑 Hook
function PageWithBreadcrumbs() {
const breadcrumbs = useBreadcrumbs(handle, {
enableI18n: true,
includeMatches: true
});
return (
);
}
```
### 13. 综合应用示例
```tsx
import {
RouteProtectionWrapper,
I18nProvider,
useUser,
useI18n,
I18nMessage,
createI18nClient,
defineAuth,
defineGuard,
PerformanceCache,
useStorage
} from '@gulibs/vgrove-client';
// 创建国际化客户端
const i18nClient = createI18nClient({
defaultLocale: 'zh',
supportedLocales: ['zh', 'en'],
persistence: { enabled: true },
detectBrowserLanguage: true
});
// 创建缓存
const appCache = new PerformanceCache(200);
// 定义认证守卫
const authGuard = defineAuth({
redirectTo: '/login',
errorMessage: 'auth.required'
});
// 定义VIP守卫
const vipGuard = defineGuard({
name: 'vip-only',
condition: (context) => context.user?.membership === 'VIP',
redirectTo: '/upgrade',
errorMessage: 'vip.required'
});
// 主应用组件
function App() {
return (
);
}
function AppContent() {
const { isAuthenticated, user } = useUser({
storagePrefix: 'myapp',
autoRefreshInterval: 15 * 60 * 1000,
loginApi: async (credentials) => {
const response = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credentials)
});
return response.json();
}
});
const { locale, setLocale } = useI18n();
const [userPreferences, setUserPreferences] = useStorage('user_prefs', {
theme: 'light',
notifications: true
});
return (
{/* 顶部导航 */}
{isAuthenticated && (
)}
{/* 主内容区 */}
{/* 公开页面 */}
{/* 需要认证的页面 */}
}
component={}
/>
{/* 需要VIP权限的页面 */}
}
component={}
/>
{/* 用户偏好设置 */}
);
}
// 受保护页面
function ProtectedPage() {
const { user } = useUser();
return (
);
}
// VIP页面
function VIPPage() {
const { user } = useUser();
return (
);
}
```
## 🎯 高级用法
### 中间件系统
```tsx
import { defineMiddleware } from '@gulibs/vgrove-client';
const loggingMiddleware = defineMiddleware({
name: 'logging',
priority: 10,
handler: async (context, next) => {
console.log(`访问页面: ${context.path}`);
const start = Date.now();
await next();
const duration = Date.now() - start;
console.log(`页面处理耗时: ${duration}ms`);
}
});
// 全局性能监控中间件
const performanceMiddleware = defineMiddleware({
name: 'performance',
priority: 1,
handler: async (context, next) => {
if (window.performance) {
const mark = `route-${context.path}-start`;
performance.mark(mark);
}
await next();
if (window.performance) {
const endMark = `route-${context.path}-end`;
performance.mark(endMark);
performance.measure(`route-${context.path}`, `route-${context.path}-start`, endMark);
}
}
});
}
/>
```
### 国际化资源加载器
```tsx
import { createI18nLoader, ViteI18nLoader, createI18nClient } from '@gulibs/vgrove-client';
// 1. 基础资源加载器
const loader = createI18nLoader({
basePath: '/api/locales',
extensions: ['.json'],
cache: true,
debug: true
});
// 2. 自定义获取函数
const customLoader = createI18nLoader({
fetchResources: async (locale, path) => {
const response = await fetch(`/api/i18n/${locale}`);
if (!response.ok) {
throw new Error(`Failed to load locale: ${response.statusText}`);
}
return response.json();
},
onLoad: (locale, data) => {
console.log(`✅ Loaded ${locale}:`, Object.keys(data));
},
onError: (locale, error) => {
console.error(`❌ Failed to load ${locale}:`, error);
}
});
// 3. 高级加载器实例
const advancedLoader = new ViteI18nLoader({
basePath: '/locales',
cache: true,
cacheTime: 30 * 60 * 1000, // 30分钟
debug: process.env.NODE_ENV === 'development'
});
// 4. 与国际化客户端集成
const i18nClient = createI18nClient({
defaultLocale: 'zh',
supportedLocales: ['zh', 'en'],
basePath: '/api/locales',
cache: true,
detectBrowserLanguage: true,
persistence: {
enabled: true,
key: 'user_locale',
storage: 'localStorage'
}
});
// 5. 手动预加载资源
await loader.preloadResources(['zh', 'en']);
// 6. 检查加载器状态
console.log('Available keys:', loader.getAvailableKeys?.());
console.log('Has key "welcome":', loader.hasKey?.('welcome'));
console.log('Using virtual module:', advancedLoader.isUsingVirtualModule?.());
```
### 复杂路由守卫
```tsx
// 角色守卫
const roleGuard = defineAuth({
roles: ['admin', 'moderator'],
redirectTo: '/login',
errorMessage: '需要以下角色之一: admin, moderator'
});
// 权限守卫
const permissionGuard = defineGuard({
name: 'permission-user:read,user:write',
condition: (context) => {
return context.user?.permissions?.includes('user:read') &&
context.user?.permissions?.includes('user:write');
},
redirectTo: '/forbidden',
errorMessage: '需要以下权限: user:read, user:write'
});
// 自定义复合守卫
const complexGuard = defineGuard({
name: 'complex-auth',
condition: async (context) => {
// 检查用户是否已认证
if (!context.user) return false;
// 检查时间限制
const now = new Date();
const workingHours = now.getHours() >= 9 && now.getHours() <= 18;
// 检查用户类型和时间
return context.user.type === 'employee' ? workingHours : true;
},
redirectTo: '/access-denied',
errorMessage: '当前时间段无法访问'
});
// 环境守卫
const environmentGuard = defineGuard({
name: 'environment',
condition: () => {
return process.env.NODE_ENV === 'development' ||
localStorage.getItem('feature_flag_enabled') === 'true';
},
redirectTo: '/not-available'
});
```
### 性能优化工具
```tsx
import {
PerformanceCache,
BatchProcessor,
PerformanceTracker,
MemoryOptimizer
} from '@gulibs/vgrove-client';
// 创建缓存实例
const cache = new PerformanceCache(100);
// 批处理器
const processor = new BatchProcessor(5, 100);
// 性能追踪
const tracker = new PerformanceTracker();
// 内存优化器
const memoryOptimizer = MemoryOptimizer.getInstance();
function useOptimizedData() {
useEffect(() => {
// 启动性能追踪
tracker.startTimer('data-loading');
// 批处理数据加载
const loadData = async () => {
const items = ['user', 'settings', 'permissions'];
const results = await processor.processBatch(
items,
async (item) => {
const cached = cache.get(item);
if (cached) return cached;
const data = await fetchData(item);
cache.set(item, data);
return data;
}
);
return results;
};
loadData().finally(() => {
const duration = tracker.endTimer('data-loading');
console.log(`数据加载耗时: ${duration}ms`);
});
// 注册清理任务
memoryOptimizer.addCleanupTask(() => {
cache.clear();
});
return () => {
memoryOptimizer.runCleanup();
};
}, []);
}
```
### 工具函数和实用程序
```tsx
import {
normalizePath,
parseQuery,
buildQuery,
debounce,
throttle,
deepMerge,
safeParseInt,
isEmpty,
measureTime
} from '@gulibs/vgrove-client';
// 路径处理
const normalizedPath = normalizePath('//path//to//page//');
// => '/path/to/page'
// 查询参数处理
const params = parseQuery('?name=john&age=25&active=true');
// => { name: 'john', age: '25', active: 'true' }
const query = buildQuery({ name: 'jane', age: 30 });
// => 'name=jane&age=30'
// 防抖和节流
const debouncedSearch = debounce((query: string) => {
searchAPI(query);
}, 500);
const throttledScroll = throttle(() => {
updateScrollPosition();
}, 100);
// 性能测量
const timedFunction = measureTime(expensiveFunction, 'expensive-operation');
// 数据处理
const config = deepMerge(defaultConfig, userConfig);
const count = safeParseInt(userInput, 0);
const hasData = !isEmpty(responseData);
```
## 📖 API 参考
### 路由保护
#### `RouteProtectionWrapper`
路由保护包装器组件。
**Props:**
```typescript
interface RouteProtectionWrapperProps {
guards?: (AuthOptions | GuardOptions | Function)[];
middlewares?: (MiddlewareOptions | Function)[];
loadingElement?: React.ReactNode;
component: React.ReactNode;
children?: React.ReactNode;
}
```
#### `defineAuth(options: AuthOptions)`
定义认证守卫。
```typescript
interface AuthOptions {
name?: string;
redirectTo?: string;
errorMessage?: string;
check?: (context: AuthContext) => boolean | Promise;
roles?: string[];
permissions?: string[];
}
```
#### `defineGuard(options: GuardOptions)`
定义自定义守卫。
```typescript
interface GuardOptions {
name?: string;
type?: 'auth' | 'role' | 'permission' | 'custom';
redirectTo?: string;
errorMessage?: string;
condition: (context: GuardContext) => boolean | Promise;
}
```
#### `defineMiddleware(options: MiddlewareOptions)`
定义中间件。
```typescript
interface MiddlewareOptions {
name?: string;
priority?: number;
devOnly?: boolean;
handler: (context: MiddlewareContext, next: () => Promise | void) => Promise | void;
}
```
### 状态管理
#### `useUser(options: UseUserOptions)`
用户状态管理 Hook。
**返回值：**
```typescript
interface AuthState & AuthActions {
user: TUser | null;
token: string | null;
refreshToken: string | null;
isAuthenticated: boolean;
isLoading: boolean;
error: string | null;
login: (credentials: TCredentials) => Promise;
logout: () => void;
refreshUser: () => Promise;
refreshTokenAction: () => Promise;
updateUser: (userData: Partial) => void;
setToken: (token: string) => void;
setRefreshToken: (refreshToken: string) => void;
clearError: () => void;
}
```
#### `useStorage(key: string, defaultValue: T, options?)`
基于 @gulibs/react-storage 的通用存储 Hook，支持过期时间。
```typescript
interface UseStorageOptions {
/** 存储类型 */
storage?: 'local' | 'session';
/** 过期时间（毫秒），0 表示永不过期 */
maxAge?: number;
/** 是否自动清理过期数据 */
autoCleanup?: boolean;
/** 清理间隔（毫秒），默认 5 分钟 */
cleanupInterval?: number;
}
function useStorage(
key: string,
defaultValue: T,
options?: UseStorageOptions
): [
T, // 当前值
(value: T) => void, // 设置值函数
() => void, // 移除值函数
(value: T, maxAge?: number) => void, // 设置值并指定过期时间
() => boolean, // 检查是否过期
() => void // 清理过期数据
]
```
**返回值：**
- `[0]` - 当前值
- `[1]` - 设置值函数（使用默认过期时间）
- `[2]` - 移除值函数
- `[3]` - 设置值并指定过期时间函数
- `[4]` - 检查是否过期函数
- `[5]` - 手动清理过期数据函数
**示例：**
```typescript
// 基础使用
const [userPrefs, setUserPrefs, removeUserPrefs] = useStorage('user_prefs', {
theme: 'light'
}, { storage: 'local' });
// 带过期时间（1小时）
const [cache, setCache, removeCache, setCacheWithExpiry, isCacheExpired, cleanupCache] = useStorage(
'api_cache',
{},
{
storage: 'local',
maxAge: 60 * 60 * 1000, // 1小时过期
autoCleanup: true // 自动清理
}
);
// 使用指定过期时间设置数据
setCacheWithExpiry({ data: 'temp' }, 5 * 60 * 1000); // 5分钟后过期
// 检查数据是否过期
if (isCacheExpired()) {
console.log('数据已过期');
}
// 手动清理过期数据
cleanupCache();
```
#### `useUserState(storagePrefix?, useSessionStorage?)`
只读用户状态 Hook。
```typescript
function useUserState(
storagePrefix?: string,
useSessionStorage?: boolean
): {
user: TUser | null;
token: string | null;
refreshToken: string | null;
isAuthenticated: boolean;
}
```
#### `useAuthToken(storagePrefix?, useSessionStorage?)`
Token 管理 Hook。
```typescript
function useAuthToken(
storagePrefix?: string,
useSessionStorage?: boolean
): {
token: string | null;
refreshToken: string | null;
setToken: (token: string) => void;
setRefreshToken: (refreshToken: string) => void;
clearToken: () => void;
clearRefreshToken: () => void;
clearAllTokens: () => void;
hasToken: boolean;
hasRefreshToken: boolean;
}
```
### 国际化
#### `I18nProvider`
国际化提供者组件。
```typescript
interface I18nProviderProps {
children: ReactNode;
client?: I18nClient | I18nClientConfig;
defaultLocale?: string;
locales?: string[];
loadResources?: (locale: string) => Promise>;
resources?: Record>;
}
```
#### `I18nMessage`
国际化消息组件，修复了刷新时找不到翻译内容的问题。
```typescript
interface I18nMessageProps {
/** 翻译键 - 类型安全，与 @gulibs/vgrove-i18n 生成的类型兼容 */
id: LocalizedType;
/** 插值参数 */
params?: Record;
/** 默认值（当翻译不存在时使用） */
defaultValue?: string;
/** 渲染格式 */
format?: 'text' | 'html' | 'markdown' | 'component';
/** 自定义渲染函数 */
render?: (text: string) => ReactNode;
/** 包装元素 */
as?: keyof React.JSX.IntrinsicElements | React.ComponentType>;
/** 自定义类名 */
className?: string;
}
```
#### `I18nSwitch`
语言切换组件。
```typescript
interface I18nSwitchProps {
/** 自定义类名 */
className?: string;
/** 语言选项，如果不提供则使用可用语言列表 */
locales?: { code: string; label: string }[];
/** 是否显示语言标签 */
showLabels?: boolean;
/** 切换按钮样式 */
variant?: 'select' | 'button' | 'tabs';
/** 语言切换回调 */
onLocaleChange?: (locale: string) => void;
}
```
#### 便捷组件
```typescript
// 国际化标题
function I18nTitle(
props: Omit, 'as' | 'format'> & { level?: 1 | 2 | 3 | 4 | 5 | 6 }
): JSX.Element
// 国际化段落
function I18nParagraph(
props: Omit, 'as' | 'format'>
): JSX.Element
// 国际化文本
function I18nText(
props: Omit, 'as' | 'format'>
): JSX.Element
```
#### 调试和优化 Hooks
```typescript
// I18nMessage 调试 Hook
function useI18nMessageDebug(): {
isReady: boolean;
locale: string;
debugInfo: {
totalKeys: number;
isUsingVirtualModule: boolean;
hasKeys: boolean;
};
validateKey: (key: string) => {
exists: boolean;
ready: boolean;
locale: string;
};
}
// I18nMessage 性能优化 Hook
function useI18nMessageMemo(
id: LocalizedType,
params?: Record,
defaultValue?: string
): string
```
#### `useI18n()`
国际化 Hook。
```typescript
interface I18nContextType {
locale: string;
setLocale: (locale: string) => Promise;
t: (key: string, params?: Record) => string;
isReady: boolean;
availableLocales: string[];
availableKeys: string[];
hasKey: (key: string) => boolean;
getNamespaceResources: (namespace: string) => Record | undefined;
isUsingVirtualModule: boolean;
}
```
#### `createI18nClient(config: I18nClientConfig)`
创建国际化客户端。
```typescript
interface I18nClientConfig extends I18nLoaderConfig {
defaultLocale: string;
supportedLocales?: string[];
resources?: Record>;
fallbackToDefault?: boolean;
detectBrowserLanguage?: boolean;
persistence?: {
enabled?: boolean;
key?: string;
storage?: 'localStorage' | 'sessionStorage';
};
interpolation?: {
prefix?: string;
suffix?: string;
escape?: (value: any) => string;
};
}
```
#### `createI18nLoader(config: I18nLoaderConfig)`
创建资源加载器。
```typescript
interface I18nLoaderConfig {
basePath?: string;
extensions?: string[];
localePattern?: 'directory' | 'filename';
defaultLocale?: string;
cacheTime?: number;
cache?: boolean;
debug?: boolean;
onLoad?: (locale: string, data: Record) => void;
onError?: (locale: string, error: Error) => void;
fetchResources?: (locale: string, path: string) => Promise>;
}
```
### 页面配置
#### `usePageConfig(handle?, options?)`
获取页面配置。
#### `useI18nPageConfig(handle?)`
获取国际化页面配置。
#### `useHandle()`
获取当前页面的 handle。
#### `PageExtrasContext` 接口
pageExtras 函数的上下文参数接口。
```typescript
interface PageExtrasContext {
/** 当前路由路径 */
path: string;
/** 路由参数 */
params: Record;
/** 查询参数 */
query: Record;
/** 当前路由匹配信息 */
matches: UIMatch[];
/** 当前页面的 handle */
handle: PageHandle;
}
```
**使用示例：**
```typescript
export const handle = defineHandle({
meta: {
title: 'products.title'
},
pageExtras: (context: PageExtrasContext) => {
const { path, params, query, matches, handle } = context;
// 根据路由参数动态生成内容
if (params.productId) {
return ;
}
// 根据查询参数显示不同内容
if (query.mode === 'debug') {
return (
);
}
return null;
}
});
```
#### `useBreadcrumbs(handle?, options?)`
获取面包屑配置。
#### `useDocumentTitle(handle?, suffix?, options?)`
设置文档标题。
### 国际化路由集成
#### `createI18nRouteLoader(i18nClient, options?)`
创建国际化路由加载器，用于在路由加载时预加载所需的翻译资源。
```typescript
function createI18nRouteLoader(
i18nClient: I18nClient,
options?: I18nRouteLoaderOptions
): (args: LoaderFunctionArgs) => Promise
interface I18nRouteLoaderOptions {
/** 要预加载的语言列表，默认使用当前语言 */
locales?: string[];
/** 是否预加载所有支持的语言 */
preloadAll?: boolean;
/** 延迟加载时间（毫秒），用于演示加载状态 */
delay?: number;
}
```
#### `useRouteI18n()`
在组件中使用路由国际化数据的 Hook。
```typescript
function useRouteI18n(): {
/** 当前语言 */
locale: string;
/** 国际化资源是否已加载 */
isLoaded: boolean;
/** 获取当前路径的语言参数 */
getLocaleFromPath: () => string | null;
/** 切换语言的 URL 生成器 */
getLocalizedUrl: (newLocale: string) => string;
/** 等待国际化资源加载完成 */
waitForI18n: () => Promise;
}
```
#### `createI18nHandle(baseHandle?)`
创建支持国际化的页面处理配置。
```typescript
function createI18nHandle(
baseHandle?: Partial>
): I18nHandle
interface I18nHandle extends PageHandle {
/** 标记为需要国际化处理 */
i18n: boolean;
/** 国际化元数据处理器 */
getI18nMeta?: (t: (key: string) => string) => {
title?: string;
description?: string;
[key: string]: any;
};
}
```
#### `enhanceRoutesWithI18n(routes, i18nClient, options?)`
为现有路由配置添加国际化支持。
```typescript
function enhanceRoutesWithI18n(
routes: any[],
i18nClient: I18nClient,
options?: EnhanceRoutesI18nOptions
): any[]
interface EnhanceRoutesI18nOptions {
/** 是否为所有路由添加国际化 loader */
autoAddLoader?: boolean;
}
```
### 性能优化
#### `PerformanceCache`
高性能 LRU 缓存。
```typescript
class PerformanceCache {
constructor(maxSize: number = 100);
get(key: K): V | undefined;
set(key: K, value: V): void;
has(key: K): boolean;
delete(key: K): boolean;
clear(): void;
size(): number;
}
```
#### `BatchProcessor`
批处理器。
```typescript
class BatchProcessor {
constructor(batchSize: number = 10, delay: number = 50);
async processBatch(
items: T[],
processor: (item: T) => Promise
): Promise;
}
```
#### `PerformanceTracker`
性能追踪器。
```typescript
class PerformanceTracker {
startTimer(name: string): void;
endTimer(name: string): number;
increment(name: string): void;
getCounter(name: string): number;
reset(): void;
getStats(): Record;
}
```
#### `MemoryOptimizer`
内存优化器（单例模式）。
```typescript
class MemoryOptimizer {
static getInstance(): MemoryOptimizer;
addCleanupTask(task: () => void): void;
startPeriodicCleanup(intervalMs?: number): void;
runCleanup(): void;
dispose(): void;
}
```
#### `Debouncer`
防抖器。
```typescript
class Debouncer {
debounce(key: string, fn: () => void, delay: number): void;
cancel(key: string): void;
cancelAll(): void;
}
```
### 工具函数 API
#### 路径和 URL 工具
```typescript
// 路径标准化
function normalizePath(path: string): string;
// 路径连接
function joinPath(...segments: string[]): string;
// 路径匹配
function matchPath(pattern: string, path: string): boolean;
// 参数提取
function extractParams(pattern: string, path: string): Record;
// 查询参数解析
function parseQuery(search: string): Record;
// 查询参数构建
function buildQuery(params: Record): string;
// URL 查询参数更新
function updateQuery(url: string, params: Record): string;
```
#### 数据处理工具
```typescript
// 深拷贝
function deepClone(obj: T): T;
// 深度合并
function deepMerge>(target: T, source: Partial): T;
// 数组去重
function unique(array: T[], keyFn?: (item: T) => any): T[];
// 数组分组
function groupBy(array: T[], keyFn: (item: T) => string): Record;
// 数组映射为数组
function mapToArray(map: Map): V[];
```
#### 字符串工具
```typescript
// 转换为驼峰命名
function toCamelCase(str: string): string;
// 转换为短横线命名
function toKebabCase(str: string): string;
// 首字母大写
function capitalize(str: string): string;
// 字符串截断
function truncate(str: string, length: number, suffix?: string): string;
```
#### 类型检查和安全工具
```typescript
// 空值检查
function isEmpty(value: any): boolean;
// 函数检查
function isFunction(value: any): value is Function;
// Promise 检查
function isPromise(value: any): value is Promise;
// 记录对象检查
function isRecord(obj: any): obj is Record;
// 安全整数解析
function safeParseInt(value: any, defaultValue?: number): number;
// 安全执行
function safely(fn: () => T, fallback: T): T;
// 安全异步执行
function safelyAsync(fn: () => Promise, fallback: T): Promise;
```
#### 性能和缓存工具
```typescript
// 防抖函数
function debounce void>(
fn: T,
delay: number
): T;
// 节流函数
function throttle void>(
fn: T,
delay: number
): T;
// 性能测量
function measureTime any>(
fn: T,
name?: string
): T;
// 异步性能测量
function measureAsync(
name: string,
fn: () => Promise
): Promise;
// 简单缓存类
class SimpleCache {
constructor(maxAge?: number, maxSize?: number);
set(key: K, value: V): void;
get(key: K): V | undefined;
has(key: K): boolean;
delete(key: K): boolean;
clear(): void;
}
```
## 🏆 最佳实践
### 1. I18nMessage 组件最佳实践
```tsx
// ✅ 推荐：总是提供默认值
function GoodExample() {
return (
);
}
// ❌ 避免：不提供默认值
function BadExample() {
return ;
}
// ✅ 推荐：使用调试工具进行开发
function DebugExample() {
const { validateKey, debugInfo } = useI18nMessageDebug();
useEffect(() => {
// 开发环境下验证翻译键
if (process.env.NODE_ENV === 'development') {
const validation = validateKey('welcome.title');
if (!validation.exists) {
console.warn('翻译键不存在：', 'welcome.title');
}
}
}, [validateKey]);
return (
{process.env.NODE_ENV === 'development' && (
{JSON.stringify(debugInfo, null, 2)}
)}
);
}
// ✅ 推荐：使用性能优化 Hook 处理复杂逻辑
function OptimizedExample() {
const translatedText = useI18nMessageMemo(
'complex.message',
{ count: 100, type: 'items' },
'默认消息'
);
return (
{translatedText}
{/* 避免在渲染中直接使用 t 函数进行复杂计算 */}
);
}
// ✅ 推荐：组合使用便捷组件
function PageLayout() {
return (
{
// 可选：语言切换时的额外逻辑
console.log(`语言切换到: ${locale}`);
}}
/>
);
}
```
### 2. 国际化路由集成最佳实践
```tsx
// i18n/routes.ts
import { createI18nClient, createI18nRouteLoader, createI18nHandle } from '@gulibs/vgrove-client';
// 创建国际化客户端
const i18nClient = createI18nClient({
defaultLocale: 'zh',
supportedLocales: ['zh', 'en'],
basePath: '/api/locales',
cache: true
});
// 创建国际化路由加载器
export const i18nLoader = createI18nRouteLoader(i18nClient, {
preloadAll: false,
delay: 0 // 生产环境不需要延迟
});
// 路由配置
export const routes = [
{
path: '/dashboard',
loader: i18nLoader,
handle: createI18nHandle({
meta: {
title: 'dashboard.title',
description: 'dashboard.description'
},
pageExtras: (context) => {
return ;
}
})
}
];
// 组件中使用
function DashboardPage() {
const { locale, isLoaded, getLocalizedUrl } = useRouteI18n();
const { t } = useI18n();
if (!isLoaded) {
return 加载中。..
;
}
return (
{t('dashboard.title')}
);
}
```
### 3. 路由守卫组织
```tsx
// guards/index.ts
export const authGuard = defineAuth({
redirectTo: '/login',
errorMessage: '请先登录'
});
export const adminGuard = defineAuth({
roles: ['admin'],
redirectTo: '/forbidden',
errorMessage: '需要管理员权限'
});
export const premiumGuard = defineGuard({
name: 'premium',
condition: (context) => context.user?.isPremium,
redirectTo: '/upgrade',
errorMessage: '需要升级到高级版'
});
// guards/factory.ts
export function createRoleGuard(roles: string[], redirectTo = '/forbidden') {
return defineAuth({
roles,
redirectTo,
errorMessage: `需要以下角色之一: ${roles.join(', ')}`
});
}
export function createPermissionGuard(permissions: string[], redirectTo = '/forbidden') {
return defineGuard({
name: `permission-${permissions.join('-')}`,
condition: (context) => {
return permissions.every(permission =>
context.user?.permissions?.includes(permission)
);
},
redirectTo,
errorMessage: `需要以下权限: ${permissions.join(', ')}`
});
}
```
### 4. 增强的国际化和路由集成
```tsx
// i18n/setup.ts
import {
createI18nClient,
createI18nRouteLoader,
enhanceRoutesWithI18n
} from '@gulibs/vgrove-client';
export const i18nClient = createI18nClient({
defaultLocale: 'zh',
supportedLocales: ['zh', 'en'],
fallbackToDefault: true,
detectBrowserLanguage: true,
persistence: {
enabled: true,
key: 'app_locale',
storage: 'localStorage'
},
interpolation: {
prefix: '{',
suffix: '}',
escape: (value) => String(value).replace(/[<>]/g, '')
},
debug: process.env.NODE_ENV === 'development',
// 开发环境短缓存，生产环境长缓存
cacheTime: process.env.NODE_ENV === 'production'
? 24 * 60 * 60 * 1000
: 5 * 60 * 1000,
onError: (locale, error) => {
// 发送错误到监控系统
console.error(`Failed to load locale ${locale}:`, error);
},
onLoad: (locale, data) => {
console.log(`✅ Loaded ${locale} with ${Object.keys(data).length} keys`);
}
});
// routes/config.ts
import { routes as baseRoutes } from './base-routes';
// 自动增强所有路由以支持国际化
export const routes = enhanceRoutesWithI18n(baseRoutes, i18nClient, {
autoAddLoader: true
});
// hooks/useI18nRouteHelpers.ts
export function useI18nRouteHelpers() {
const {
locale,
isLoaded,
getLocaleFromPath,
getLocalizedUrl,
waitForI18n
} = useRouteI18n();
const { t } = useI18n();
// 切换语言并导航
const switchLanguage = useCallback(async (newLocale: string) => {
const url = getLocalizedUrl(newLocale);
await waitForI18n(); // 等待资源加载
window.location.href = url;
}, [getLocalizedUrl, waitForI18n]);
// 获取当前页面的本地化路径
const getLocalizedPath = useCallback((path: string, targetLocale?: string) => {
const url = new URL(path, window.location.origin);
url.searchParams.set('locale', targetLocale || locale);
return url.pathname + url.search;
}, [locale]);
return {
locale,
isLoaded,
switchLanguage,
getLocalizedPath,
getLocaleFromPath,
t
};
}
```
### 5. 性能优化策略
```tsx
// utils/performance.ts
import {
PerformanceCache,
BatchProcessor,
MemoryOptimizer
} from '@gulibs/vgrove-client';
// 全局缓存实例
export const globalCache = new PerformanceCache(200);
export const batchProcessor = new BatchProcessor(10, 100);
export const memoryOptimizer = MemoryOptimizer.getInstance();
// 启动内存优化
memoryOptimizer.startPeriodicCleanup(5 * 60 * 1000); // 5 分钟清理一次
// hooks/useOptimizedApi.ts
export function useOptimizedApi() {
const cache = useMemo(() => new PerformanceCache(50), []);
const fetchWithCache = useCallback(async (url: string) => {
const cached = cache.get(url);
if (cached) return cached;
const response = await fetch(url);
const data = await response.json();
cache.set(url, data);
return data;
}, [cache]);
const batchFetch = useCallback(async (urls: string[]) => {
return batchProcessor.processBatch(urls, fetchWithCache);
}, [fetchWithCache]);
useEffect(() => {
// 注册清理任务
memoryOptimizer.addCleanupTask(() => {
cache.clear();
});
}, [cache]);
return { fetchWithCache, batchFetch };
}
```
### 6. 错误处理
```tsx
// utils/errorBoundary.tsx
import { defineGuard } from '@gulibs/vgrove-client';
export const errorHandlingGuard = defineGuard({
name: 'error-handling',
condition: async (context) => {
try {
// 检查用户权限
if (!context.user) return false;
// 检查网络状态
if (!navigator.onLine) {
throw new Error('网络连接已断开');
}
return true;
} catch (error) {
// 发送错误到监控系统
console.error('Guard error:', error);
return false;
}
},
redirectTo: '/error'
});
// components/ErrorBoundary.tsx
class ErrorBoundary extends React.Component<
{ children: React.ReactNode },
{ hasError: boolean; error?: Error }
> {
constructor(props: any) {
super(props);
this.state = { hasError: false };
}
static getDerivedStateFromError(error: Error) {
return { hasError: true, error };
}
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
console.error('ErrorBoundary caught an error:', error, errorInfo);
// 发送错误到监控系统
}
render() {
if (this.state.hasError) {
return (
出现了一些问题
{this.state.error?.message}
);
}
return this.props.children;
}
}
```
### 7. 存储管理最佳实践
```tsx
// hooks/useAppStorage.ts
import { useStorage } from '@gulibs/vgrove-client';
// ✅ 推荐：为不同类型的数据创建专门的 Hook
export function useUserPreferences() {
return useStorage('user_preferences', {
theme: 'light' as 'light' | 'dark',
language: 'zh' as string,
notifications: true,
autoSave: true
});
}
export function useAppSettings() {
return useStorage('app_settings', {
sidebar: { collapsed: false, width: 280 },
editor: { fontSize: 14, tabSize: 2 },
debug: false
}, { storage: 'local' });
}
export function useSessionData() {
return useStorage('session_data', {
lastActivity: Date.now(),
activeTab: 'dashboard'
}, { storage: 'session' });
}
// ✅ 推荐：类型安全的存储 Hook
interface UserPreferences {
theme: 'light' | 'dark';
language: string;
notifications: boolean;
}
export function useTypedUserPrefs() {
const [prefs, setPrefs, removePrefs] = useStorage(
'typed_user_prefs',
{ theme: 'light', language: 'zh', notifications: true }
);
// 提供类型安全的更新方法
const updateTheme = (theme: UserPreferences['theme']) => {
setPrefs({ ...prefs, theme });
};
const toggleNotifications = () => {
setPrefs({ ...prefs, notifications: !prefs.notifications });
};
return { prefs, setPrefs, updateTheme, toggleNotifications, removePrefs };
}
// ✅ 推荐：带过期时间的缓存管理
export function useApiCache() {
const [cache, setCache, removeCache, setCacheWithExpiry, isCacheExpired, cleanupCache] = useStorage(
'api_cache',
{},
{
storage: 'local',
maxAge: 30 * 60 * 1000, // 30分钟过期
autoCleanup: true, // 自动清理过期数据
cleanupInterval: 5 * 60 * 1000 // 每5分钟清理一次
}
);
// 提供缓存相关的便捷方法
const cacheApiResult = useCallback((key: string, data: any, customExpiry?: number) => {
if (customExpiry) {
setCacheWithExpiry({ ...cache, [key]: data }, customExpiry);
} else {
setCache({ ...cache, [key]: data });
}
}, [cache, setCache, setCacheWithExpiry]);
const getCachedResult = useCallback((key: string) => {
if (isCacheExpired()) {
return null;
}
return cache[key] || null;
}, [cache, isCacheExpired]);
const clearExpiredCache = useCallback(() => {
cleanupCache();
}, [cleanupCache]);
return {
cache,
cacheApiResult,
getCachedResult,
clearExpiredCache,
removeCache,
isCacheExpired
};
}
// ✅ 推荐：临时数据管理（短期过期）
export function useTempData(key: string, defaultValue: T, maxAge: number = 10 * 60 * 1000) {
const [data, setData, removeData, setWithExpiry, isExpired, cleanup] = useStorage(
`temp_${key}`,
defaultValue,
{
storage: 'session',
maxAge,
autoCleanup: true,
cleanupInterval: 60 * 1000 // 每分钟清理一次
}
);
// 自动设置过期时间的便捷方法
const setTempData = useCallback((value: T, customExpiry?: number) => {
setWithExpiry(value, customExpiry || maxAge);
}, [setWithExpiry, maxAge]);
return {
data,
setTempData,
removeData,
isExpired,
cleanup
};
}
// ✅ 推荐：令牌管理（支持自动过期）
export function useTokenStorage() {
const [accessToken, setAccessToken, removeAccessToken, setTokenWithExpiry, isTokenExpired, cleanupTokens] = useStorage(
'access_token',
null,
{
storage: 'local',
maxAge: 15 * 60 * 1000, // 15分钟过期
autoCleanup: true
}
);
const [refreshToken, setRefreshToken, removeRefreshToken] = useStorage(
'refresh_token',
null,
{
storage: 'local',
maxAge: 7 * 24 * 60 * 60 * 1000, // 7天过期
autoCleanup: true
}
);
// 设置带过期时间的访问令牌
const setTokenWithExpiresIn = useCallback((token: string, expiresIn: number) => {
setTokenWithExpiry(token, expiresIn * 1000); // 转换为毫秒
}, [setTokenWithExpiry]);
// 检查令牌是否有效
const isTokenValid = useCallback(() => {
return accessToken && !isTokenExpired();
}, [accessToken, isTokenExpired]);
// 清理所有令牌
const clearAllTokens = useCallback(() => {
removeAccessToken();
removeRefreshToken();
cleanupTokens();
}, [removeAccessToken, removeRefreshToken, cleanupTokens]);
return {
accessToken,
refreshToken,
setAccessToken,
setRefreshToken,
setTokenWithExpiresIn,
isTokenValid,
isTokenExpired,
clearAllTokens
};
}
// ✅ 推荐：智能缓存策略
export function useSmartCache(
key: string,
fetcher: () => Promise,
options: {
maxAge?: number;
staleWhileRevalidate?: boolean;
retryCount?: number;
} = {}
) {
const {
maxAge = 10 * 60 * 1000, // 默认10分钟
staleWhileRevalidate = true,
retryCount = 3
} = options;
const [cache, setCache, , setCacheWithExpiry, isCacheExpired, cleanup] = useStorage(
`smart_cache_${key}`,
null as T | null,
{
storage: 'local',
maxAge,
autoCleanup: true
}
);
const [isLoading, setIsLoading] = useState(false);
const [error, setError] = useState(null);
const fetchData = useCallback(async (forceRefresh = false) => {
// 如果有缓存且未过期，直接返回
if (!forceRefresh && cache && !isCacheExpired()) {
return cache;
}
setIsLoading(true);
setError(null);
let attempts = 0;
while (attempts < retryCount) {
try {
const data = await fetcher();
setCacheWithExpiry(data, maxAge);
setIsLoading(false);
return data;
} catch (err) {
attempts++;
if (attempts >= retryCount) {
setError(err instanceof Error ? err : new Error('Failed to fetch data'));
setIsLoading(false);
// 如果允许返回过期数据，则返回缓存中的数据
if (staleWhileRevalidate && cache) {
return cache;
}
throw err;
}
// 重试前等待
await new Promise(resolve => setTimeout(resolve, 1000 * attempts));
}
}
}, [cache, isCacheExpired, fetcher, setCacheWithExpiry, maxAge, retryCount, staleWhileRevalidate]);
return {
data: cache,
isLoading,
error,
fetchData,
cleanup,
isExpired: isCacheExpired
};
}
```
### 8. 性能优化最佳实践
```tsx
// hooks/useOptimizedData.ts
import {
PerformanceCache,
BatchProcessor,
MemoryOptimizer,
measureAsync
} from '@gulibs/vgrove-client';
// ✅ 推荐：创建全局缓存实例
const apiCache = new PerformanceCache(100);
const batchProcessor = new BatchProcessor(10, 100);
export function useOptimizedAPI() {
// ✅ 推荐：带缓存的 API 调用
const fetchWithCache = useCallback(async (endpoint: string) => {
if (apiCache.has(endpoint)) {
return apiCache.get(endpoint);
}
const result = await measureAsync(`api-${endpoint}`, async () => {
const response = await fetch(`/api/${endpoint}`);
return response.json();
});
apiCache.set(endpoint, result);
console.log(`API ${endpoint} 耗时: ${result.duration}ms`);
return result;
}, []);
// ✅ 推荐：批量处理
const batchFetch = useCallback(async (endpoints: string[]) => {
return batchProcessor.processBatch(endpoints, fetchWithCache);
}, [fetchWithCache]);
return { fetchWithCache, batchFetch };
}
// ✅ 推荐：组件级内存优化
export function useMemoryOptimizedComponent() {
useEffect(() => {
const memoryOptimizer = MemoryOptimizer.getInstance();
// 注册清理任务
const cleanupId = Date.now().toString();
memoryOptimizer.addCleanupTask(() => {
console.log(`清理组件 ${cleanupId} 的资源`);
// 清理组件相关资源
});
return () => {
// 组件卸载时立即清理
memoryOptimizer.runCleanup();
};
}, []);
}
```
### 9. 工具函数最佳实践
```tsx
// utils/helpers.ts
import {
debounce,
throttle,
deepMerge,
safely,
safelyAsync,
parseQuery,
buildQuery
} from '@gulibs/vgrove-client';
// ✅ 推荐：创建专门的防抖/节流 Hook
export function useDebouncedCallback void>(
callback: T,
delay: number
) {
const debouncedFn = useMemo(() => debounce(callback, delay), [callback, delay]);
useEffect(() => {
return () => {
// 组件卸载时取消防抖
debouncedFn.cancel?.();
};
}, [debouncedFn]);
return debouncedFn;
}
export function useThrottledCallback void>(
callback: T,
delay: number
) {
return useMemo(() => throttle(callback, delay), [callback, delay]);
}
// ✅ 推荐：安全的配置合并
export function useSafeConfig>(
defaultConfig: T,
userConfig?: Partial
): T {
return useMemo(() => {
return safely(
() => deepMerge(defaultConfig, userConfig || {}),
defaultConfig
);
}, [defaultConfig, userConfig]);
}
// ✅ 推荐：URL 状态管理
export function useURLState>(
defaultState: T
) {
const location = useLocation();
const navigate = useNavigate();
const urlState = useMemo(() => {
const params = parseQuery(location.search);
return safely(() => ({ ...defaultState, ...params }), defaultState);
}, [location.search, defaultState]);
const setURLState = useCallback((newState: Partial) => {
const mergedState = { ...urlState, ...newState };
const queryString = buildQuery(mergedState);
navigate(`${location.pathname}?${queryString}`, { replace: true });
}, [urlState, location.pathname, navigate]);
return [urlState, setURLState] as const;
}
// ✅ 推荐：安全的异步操作
export function useSafeAsync(
asyncFn: () => Promise,
deps: React.DependencyList,
fallback: T
) {
const [data, setData] = useState(fallback);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
useEffect(() => {
let cancelled = false;
const execute = async () => {
setLoading(true);
setError(null);
const result = await safelyAsync(asyncFn, fallback);
if (!cancelled) {
setData(result);
setLoading(false);
}
};
execute();
return () => {
cancelled = true;
};
}, deps);
return { data, loading, error };
}
```
## 🚨 故障排除
### 常见问题
#### 1. I18nMessage 组件刷新后找不到翻译内容
**症状：** 页面刷新后 `I18nMessage` 组件显示键名或默认值，而非实际翻译内容
**原因分析：**
- `I18nProvider` 初始化时资源加载是异步的
- `I18nMessage` 在初始渲染时资源可能尚未加载完成
- `useMemo` 缓存问题导致资源加载完成后不会重新计算
**解决方案：**
```tsx
// ✅ 正确用法 - vgrove-client 已修复此问题
import { I18nMessage } from '@gulibs/vgrove-client';
function MyComponent() {
return (
);
}
// ✅ 调试信息
import { useI18nMessageDebug } from '@gulibs/vgrove-client';
function DebugComponent() {
const { isReady, debugInfo, validateKey } = useI18nMessageDebug();
console.log('I18n Debug:', debugInfo);
console.log('Key validation:', validateKey('welcome.message'));
return null;
}
```
**修复内容：**
1. 添加 `isReady` 状态依赖，确保资源加载完成后重新渲染
2. 分离翻译计算和显示逻辑
3. 添加开发环境下的调试信息和警告
4. 优化资源加载监听机制
#### 2. 虚拟模块加载失败
**症状：** 错误信息 `Failed to resolve import "~i18n-locales-loader"`
**解决方案：**
```bash
# 检查插件配置
# vite.config.ts 中确保有：
import i18nPlugin from '@gulibs/vgrove-i18n';
export default defineConfig({
plugins: [
i18nPlugin({
basePath: 'src/locales',
keysOutput: 'src/i18n-keys.ts'
})
]
});
# 重启开发服务器
npm run dev
```
#### 3. 认证状态不同步
**症状：** 页面刷新后用户状态丢失
**解决方案：**
```tsx
// 确保正确配置 useUser
const { user, isAuthenticated } = useUser({
storagePrefix: 'myapp', // 使用唯一前缀
useSessionStorage: false, // 使用 localStorage 持久化
autoRefreshInterval: 15 * 60 * 1000, // 15 分钟自动刷新
});
// 检查 localStorage
console.log('Stored token:', localStorage.getItem('myapp_token'));
console.log('Stored user:', localStorage.getItem('myapp_user'));
```
#### 4. 路由保护不生效
**症状：** 守卫没有阻止未授权访问
**解决方案：**
```tsx
// 检查 RouteProtectionWrapper 的使用
}
component={}
>
{/* 不要在这里放置组件 */}
// 确保守卫返回布尔值
const authGuard = defineAuth({
check: (context) => {
console.log('Auth check:', context.user); // 调试日志
return !!context.user; // 明确返回布尔值
}
});
```
#### 5. 资源加载失败
**症状：** 国际化资源无法加载
**解决方案：**
```tsx
// 启用调试模式
const loader = createI18nLoader({
debug: true, // 查看详细加载日志
onError: (locale, error) => {
console.error(`Loading ${locale} failed:`, error);
// 检查网络请求是否成功
}
});
// 检查资源路径
// 确保服务器上存在对应文件
fetch('/locales/zh.json')
.then(res => res.json())
.then(data => console.log('Resource loaded:', data))
.catch(err => console.error('Resource load failed:', err));
// 检查 CORS 设置（如果是跨域请求）
```
#### 6. 性能问题
**症状：** 页面加载缓慢
**解决方案：**
```tsx
// 启用缓存
const cache = new PerformanceCache