\n {/* ... */}\n
\n \n );\n}\n```\n\n### 基础 UI 组件\n\n#### Brand 品牌组件\n\nBrand 组件用于显示应用品牌信息，支持 Logo 和名称的灵活配置。\n\n```typescript\nimport { Brand } from '@gulibs/vgrove-ui';\n\nfunction AppBrand() {\n return (\n \n \n }\n description=\"系统管理员\"\n >\n 张管理员\n \n }\n description=\"内容管理员\"\n >\n 李管理员\n \n \n\n \n }\n description=\"活跃用户\"\n >\n 王用户\n \n }\n description=\"新用户\"\n >\n 刘用户\n \n \n \n );\n}\n```\n\n### 响应式布局配置\n\n#### 布局设置\n\n```typescript\nimport { VGroveProvider } from '@gulibs/vgrove-ui';\n\nfunction App() {\n const layoutSettings = {\n // 侧边栏配置\n sidebar: {\n width: 280, // 展开宽度\n collapsedWidth: 72, // 折叠宽度\n collapsible: true, // 是否可折叠\n collapsed: false, // 默认折叠状态\n breakpoint: 'lg' // 响应式断点\n },\n\n // 导航栏配置\n navbar: {\n height: 64, // 导航栏高度\n fixed: true, // 是否固定\n transparent: false, // 是否透明\n blur: true // 是否启用模糊效果\n },\n\n // 页脚配置\n footer: {\n height: 60, // 页脚高度\n fixed: false, // 是否固定\n show: true // 是否显示\n },\n\n // 内容区域配置\n content: {\n padding: 24, // 内容区域内边距\n maxWidth: '100%', // 最大宽度\n centered: false // 是否居中\n }\n };\n\n return (\n \n \n \n \n \n );\n}\n```\n\n### 样式定制\n\n#### CSS 变量定制\n\n```css\n/* 自定义 CSS 变量 */\n:root {\n /* 布局尺寸 */\n --vgrove-sidebar-width: 280px;\n --vgrove-sidebar-collapsed-width: 72px;\n --vgrove-navbar-height: 64px;\n --vgrove-footer-height: 60px;\n\n /* 间距 */\n --vgrove-content-padding: 24px;\n --vgrove-page-max-width: 1200px;\n\n /* 过渡动画 */\n --vgrove-transition-duration: 200ms;\n --vgrove-transition-timing: ease-in-out;\n\n /* 阴影 */\n --vgrove-sidebar-shadow: 2px 0 8px rgba(0, 0, 0, 0.1);\n --vgrove-navbar-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);\n}\n\n/* 暗色主题定制 */\n.dark {\n --vgrove-sidebar-shadow: 2px 0 8px rgba(0, 0, 0, 0.3);\n --vgrove-navbar-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);\n}\n```\n\n#### Tailwind CSS 配置扩展\n\n```javascript\n// tailwind.config.js\nmodule.exports = {\n // ... 其他配置\n theme: {\n extend: {\n spacing: {\n 'sidebar': 'var(--vgrove-sidebar-width)',\n 'sidebar-collapsed': 'var(--vgrove-sidebar-collapsed-width)',\n 'navbar': 'var(--vgrove-navbar-height)',\n 'footer': 'var(--vgrove-footer-height)'\n },\n transitionDuration: {\n 'vgrove': 'var(--vgrove-transition-duration)'\n },\n boxShadow: {\n 'sidebar': 'var(--vgrove-sidebar-shadow)',\n 'navbar': 'var(--vgrove-navbar-shadow)'\n }\n }\n }\n}\n```\n\n## 🌐 国际化和主题系统\n\nVGrove UI 提供了完整的国际化 (i18n) 支持和灵活的主题系统，让您的应用能够轻松适配不同语言和视觉风格。\n\n### 国际化系统\n\n#### I18nMessage 国际化消息组件\n\nI18nMessage 组件用于显示多语言文本内容，支持变量插值和格式化。\n\n```typescript\nimport { I18nMessage } from '@gulibs/vgrove-ui';\n\nfunction WelcomeSection() {\n const user = { name: '张三', points: 1250 };\n\n return (\n \n {/* 基础消息 */}\n
\n\n {/* 带变量插值的消息 */}\n
\n\n {/* 复杂消息格式化 */}\n
\n\n {/* 带有HTML的富文本消息 */}\n
用户协议 和 隐私政策\"\n values={{\n termsLink: (text) => {text},\n privacyLink: (text) => {text}\n }}\n />\n\n {/* 带回退的消息 */}\n \n \n {/* 下拉菜单样式 */}\n {\n console.log('语言切换到:', language);\n }}\n />\n\n {/* 按钮组样式 */}\n \n
\n );\n}\n```\n\n### 主题系统\n\n#### useTheme Hook\n\n```typescript\nimport { useTheme } from '@gulibs/vgrove-ui';\n\nfunction ThemeControls() {\n const {\n theme, // 当前主题设置\n resolvedTheme, // 解析后的实际主题\n setTheme, // 设置主题函数\n toggleTheme, // 切换明暗主题\n isDark, // 是否为暗色主题\n isSystem // 是否跟随系统\n } = useTheme();\n\n return (\n \n
\n setTheme('light')}\n variant={theme === 'light' ? 'solid' : 'flat'}\n >\n 浅色\n \n\n setTheme('dark')}\n variant={theme === 'dark' ? 'solid' : 'flat'}\n >\n 深色\n \n\n setTheme('system')}\n variant={theme === 'system' ? 'solid' : 'flat'}\n >\n 跟随系统\n \n
\n\n
\n
\n {/* 开关样式 */}\n \n\n {/* 下拉菜单样式 */}\n \n\n {/* 圆形按钮样式 */}\n \n\n {/* 按钮组样式 */}\n \n
\n );\n}\n```\n\n## 🎣 Hooks 和高级功能\n\nVGrove UI 提供了丰富的自定义 Hooks 和高级功能，帮助您构建更强大和灵活的应用。\n\n### VGrove 核心 Hooks\n\n#### useVGrove - 核心上下文 Hook\n\nuseVGrove 提供对 VGrove 应用上下文的访问，包括布局设置和全局状态管理。\n\n```typescript\nimport { useVGrove } from '@gulibs/vgrove-ui';\n\nfunction LayoutController() {\n const {\n settings, // 当前布局设置\n updateSettings, // 更新设置函数\n resetSettings // 重置设置函数\n } = useVGrove();\n\n const toggleSidebar = () => {\n updateSettings({\n sidebar: {\n ...settings.sidebar,\n collapsed: !settings.sidebar?.collapsed\n }\n });\n };\n\n return (\n \n \n 侧边栏: {settings.sidebar?.collapsed ? '已折叠' : '已展开'}\n \n\n \n
\n );\n}\n```\n\n### 表单相关 Hooks\n\n#### useWatch / useFieldValue - 表单字段监听\n\n```typescript\nimport { useWatch, useFieldValue, useFieldsWatcher } from '@gulibs/vgrove-ui';\n\nfunction FormWatcher() {\n // 监听单个字段\n const username = useFieldValue('username');\n\n // 监听多个字段\n const [firstName, lastName] = useWatch(['firstName', 'lastName']);\n\n // 监听字段状态\n const { allFilled, anyFilled } = useFieldsWatcher(['name', 'email']);\n\n return (\n \n
用户名: {username || '未填写'}
\n
全名: {firstName && lastName ? `${firstName} ${lastName}` : '未完整'}
\n
状态: {allFilled ? '完成' : anyFilled ? '部分完成' : '未开始'}
\n
\n setSettings({\n ...settings,\n theme: e.target.value\n })}\n >\n \n \n \n\n \n
\n );\n}\n```\n\n## 📚 类型定义和 API 参考\n\n### 表单相关 API\n\n#### 函数和工具\n\n```typescript\n// 创建 FormInstance\nfunction createFormInstance(\n formReturn: UseFormReturn\n): FormInstance\n\n// 增强的 useForm Hook\nfunction useForm(\n options?: CustomUseFormProps\n): FormInstance\n\n// 注册全局 FormInstance\nfunction registerFormInstance(instance: FormInstance, key?: string): void\n\n// 注销全局 FormInstance\nfunction unregisterFormInstance(key?: string): void\n\n// 获取全局 FormInstance\nfunction getFormInstance(key?: string): FormInstance | null\n\n// 字段值监听\nfunction useFieldValue(\n name: FieldPath,\n control?: Control\n): any\n\n// 多字段监听\nfunction useFieldsWatcher(\n names: FieldPath[],\n control?: Control\n): FieldsWatcherResult\n\n// 字段更新工具\nfunction useFieldUpdate(name: string): FieldUpdateResult\n\n// 获取表单上下文 (返回 FormInstance)\nfunction useFormContext(): FormInstance\n\n// 可选获取表单上下文\nfunction useFormContextOptional(): FormInstance | null\n\n// 检测是否在 FormProvider 内部\nfunction useIsInsideFormProvider(): boolean\n\n// 获取可用的 FormInstance\nfunction useAvailableFormInstance(): FormInstance | null\n```\n\n### 核心类型\n\n#### 用户和认证相关\n\n```typescript\n// 基础用户类型\ninterface BaseUser {\n id: string | number;\n username?: string;\n email?: string;\n name?: string;\n avatar?: string;\n roles?: string[];\n permissions?: string[];\n [key: string]: any;\n}\n\n// 认证配置\ninterface AuthConfig {\n authCheck: () => Promise | BaseUser | null;\n roleCheck?: (user: BaseUser, roles: string[]) => boolean;\n permissionCheck?: (user: BaseUser, permissions: string[]) => boolean;\n loginPath?: string;\n forbiddenPath?: string;\n publicPaths?: string[];\n}\n```\n\n#### 表单相关类型\n\n```typescript\n// FormInstance 接口定义\ninterface FormInstance\n extends UseFormReturn {\n // 基础方法\n getFieldValue: (name: FieldPath) => any;\n getFieldsValue: () => TFieldValues;\n setFieldValue: (name: FieldPath, value: any) => void;\n setFieldsValue: (values: Partial) => void;\n resetFields: () => void;\n\n // 验证方法\n validateFields: () => Promise;\n setFieldError: (name: FieldPath, error: any) => void;\n clearFieldErrors: (names?: FieldPath[]) => void;\n}\n\n// 自定义 useForm 配置\ninterface CustomUseFormProps\n extends UseFormProps {\n // 是否注册为全局默认实例\n registerAsGlobal?: boolean;\n // 注册的键名（如果不提供则作为默认实例）\n globalKey?: string;\n}\n\n// 表单配置\ninterface FormProps {\n mode?: 'all' | 'onBlur' | 'onChange' | 'onSubmit';\n watchNames?: FieldPath | FieldPath[];\n footer?: false | FormFooterConfig;\n form?: FormInstance; // 支持传入 FormInstance\n onFinish?: SubmitHandler;\n onFinishError?: SubmitErrorHandler;\n}\n\n// 表单页脚配置\ninterface FormFooterConfig {\n resetProps?: Omit;\n resetText?: React.ReactNode;\n submitProps?: Omit;\n submitText?: React.ReactNode;\n hiddenReset?: boolean;\n onReset?: () => void;\n}\n\n// 表单项配置\ninterface FormItemProps {\n name: string;\n label?: React.ReactNode;\n required?: boolean;\n help?: React.ReactNode;\n tooltip?: TooltipProps;\n rules?: RegisterOptions;\n layout?: 'vertical' | 'horizontal';\n validateStatus?: 'error' | 'warning' | 'success';\n}\n\n// 表单字段监听器返回类型\ninterface FieldsWatcherResult {\n values: any[];\n allFilled: boolean;\n anyFilled: boolean;\n}\n\n// 表单字段更新工具返回类型\ninterface FieldUpdateResult {\n isInvalid: () => boolean;\n handle: (handler: EventHandler) => (event: FormEvent) => void;\n clear: () => void;\n}\n```\n\n#### 布局相关类型\n\n```typescript\n// 布局设置\ninterface LayoutSettings {\n sidebar?: {\n width?: number;\n collapsedWidth?: number;\n collapsible?: boolean;\n collapsed?: boolean;\n breakpoint?: 'sm' | 'md' | 'lg' | 'xl';\n };\n navbar?: {\n height?: number;\n fixed?: boolean;\n transparent?: boolean;\n blur?: boolean;\n };\n footer?: {\n height?: number;\n fixed?: boolean;\n show?: boolean;\n };\n}\n\n// 菜单项类型\ninterface SidebarMenuItem {\n key: string;\n label: React.ReactNode;\n href?: string;\n icon?: React.ReactNode;\n badge?: BadgeProps;\n children?: SidebarMenuItem[];\n requiredRoles?: string[];\n requiredPermissions?: string[];\n}\n```\n\n#### 主题相关类型\n\n```typescript\n// 主题模式\ntype ThemeMode = 'light' | 'dark' | 'system';\ntype ResolvedTheme = 'light' | 'dark';\n\n// 主题配置\ninterface ThemeConfig {\n defaultTheme?: ThemeMode;\n enableSystem?: boolean;\n attribute?: string;\n storageKey?: string;\n themes?: string[];\n}\n\n// 主题切换器配置\ninterface ThemeSwitchProps {\n variant?: 'switch' | 'dropdown' | 'circle' | 'buttons';\n size?: 'sm' | 'md' | 'lg';\n showLabel?: boolean;\n enableSystem?: boolean;\n onThemeChange?: (theme: ThemeMode, resolvedTheme: ResolvedTheme) => void;\n}\n```\n\n## 💡 最佳实践和示例\n\n### 项目结构建议\n\n```\nsrc/\n├── components/ # 通用组件\n│ ├── ui/ # UI 基础组件\n│ ├── forms/ # 表单组件\n│ └── layout/ # 布局组件\n├── pages/ # 页面组件\n├── hooks/ # 自定义 Hooks\n├── utils/ # 工具函数\n├── types/ # 类型定义\n├── constants/ # 常量定义\n├── locales/ # 国际化资源\n│ ├── zh-CN.json\n│ ├── en-US.json\n│ └── index.ts\n└── config/ # 配置文件\n ├── auth.ts # 认证配置\n ├── routes.ts # 路由配置\n └── theme.ts # 主题配置\n```\n\n### 完整应用示例\n\n```typescript\n// App.tsx\nimport React from 'react';\nimport {\n VGroveProvider,\n VGroveLayout,\n quickSetup,\n createBrowserRouter,\n RouterProvider\n} from '@gulibs/vgrove-ui';\nimport { authConfig } from './config/auth';\nimport { menuItems } from './config/menu';\n\n// 快速设置认证\nconst { authLoader, loginAction, logoutAction } = quickSetup(authConfig);\n\n// 创建路由\nconst router = createBrowserRouter([\n {\n path: '/login',\n element: ,\n action: loginAction\n },\n {\n path: '/',\n element: ,\n loader: authLoader\n },\n {\n path: '/dashboard',\n element: ,\n loader: authLoader\n }\n]);\n\nfunction App() {\n return (\n \n {\n localStorage.setItem('sidebar-collapsed', String(collapsed));\n }}\n >\n \n \n \n );\n}\n\nexport default App;\n```\n\n### 性能优化建议\n\n```typescript\n// 1. 使用 React.memo 优化组件渲染\nconst OptimizedComponent = React.memo(({ data }) => {\n return {data.title}
;\n});\n\n// 2. 使用 useMemo 优化计算\nconst ExpensiveComponent = ({ items }) => {\n const processedItems = useMemo(() => {\n return items.map(item => ({\n ...item,\n processed: heavyComputation(item)\n }));\n }, [items]);\n\n return ;\n};\n\n// 3. 使用 useCallback 优化事件处理\nconst FormComponent = ({ onSubmit }) => {\n const handleSubmit = useCallback((data) => {\n onSubmit(data);\n }, [onSubmit]);\n\n return ;\n};\n```\n\n## 🛠️ 开发和构建\n\n### 本地开发\n\n```bash\n# 克隆项目\ngit clone https://github.com/your-org/your-project.git\ncd your-project\n\n# 安装依赖\nnpm install\n\n# 启动开发服务器\nnpm run dev\n\n# 启动 Storybook (如果有)\nnpm run storybook\n```\n\n### 构建和部署\n\n```bash\n# 构建生产版本\nnpm run build\n\n# 预览构建结果\nnpm run preview\n\n# 运行测试\nnpm test\n\n# 运行类型检查\nnpm run type-check\n\n# 运行代码检查\nnpm run lint\n```\n\n## 🤝 贡献指南\n\n### 提交代码\n\n1. Fork 项目到您的 GitHub 账户\n2. 创建功能分支：`git checkout -b feature/amazing-feature`\n3. 提交更改：`git commit -m 'Add amazing feature'`\n4. 推送到分支：`git push origin feature/amazing-feature`\n5. 创建 Pull Request\n\n### 开发规范\n\n- 遵循现有的代码风格和命名约定\n- 为新功能添加适当的类型定义\n- 编写单元测试覆盖新功能\n- 更新相关文档和示例\n\n## 📄 许可证\n\n本项目基于 MIT 许可证开源。详见 [LICENSE](./LICENSE) 文件。\n\n---\n\n**让我们一起构建更好的 React 应用！** 🚀\n","readmeFilename":"README.md"}