@linyjs/plugin-docs 0.0.15 → 0.0.17

package/docs/guides/client-hooks.md

@@ -0,0 +1,626 @@
+# 公共 Hooks 使用
+
+本指南详细介绍 linyjs 框架提供的公共 Hooks，用于在组件中消费跨模块注册的资源（组件、Hooks、服务）和路由功能。
+
+## 概述
+
+linyjs 通过 React Context 提供全局注册表，使模块间可以共享资源。框架提供以下 5 个公共 Hooks：
+
+| Hook | 用途 | 返回值 |
+|------|------|--------|
+| `useClientComponent` | 获取跨模块注册的组件 | `IComponent \| undefined` |
+| `useClientHook` | 获取跨模块注册的 Hook | `Function \| undefined` |
+| `useClientService` | 获取跨模块注册的服务实例 | `T \| undefined` |
+| `useClientRoute` | 获取路由功能（导航、参数等） | `any` |
+
+所有 Hooks 从 `@linyjs/client-module-interface` 导入：
+
+```typescript
+import {
+  useClientComponent,
+  useClientHook,
+  useClientService,
+  useClientRoute,
+} from '@linyjs/client-module-interface';
+```
+
+## 资源引用格式
+
+所有跨模块资源使用统一的引用格式：
+
+### RegistryKey 格式
+
+资源在全局注册表中的 key 采用 `moduleName.serviceTag.name` 三段式格式：
+
+```
+{moduleName}.{serviceTag}.{name}
+```
+
+### 两种引用方式
+
+| 引用方式 | 格式 | 示例 | 说明 |
+|----------|------|------|------|
+| 模块内引用 | `serviceTag.name` | `'userComponents.Avatar'` | 省略 moduleName，框架自动补全 |
+| 跨模块引用 | `moduleName.serviceTag.name` | `'userModule.userComponents.Avatar'` | 显式指定完整路径 |
+
+> 💡 **自动补全规则**：如果传入的引用路径只有 1 个点（即 `serviceTag.name`），框架会尝试补全当前模块名。如果传入 2 个及以上点（即 `moduleName.serviceTag.name`），框架视为完整路径直接使用。
+
+### 不同资源类型的引用格式
+
+| 资源类型 | 模块内引用 | 跨模块引用 |
+|----------|-----------|-----------|
+| 组件 | `'userComponents.Avatar'` | `'userModule.userComponents.Avatar'` |
+| Hook | `'authHooks.useAuth'` | `'authModule.authHooks.useAuth'` |
+| 服务 | `'userService'` | `'userModule.userService'` |
+
+> ⚠️ **服务的引用格式不同**：服务只有两段 `moduleName.serviceTag`，不含 `.name`，因为服务本身就是整个实例。
+
+---
+
+## useClientComponent
+
+获取跨模块注册的 React 组件。
+
+### 签名
+
+```typescript
+function useClientComponent<P = any>(refPath: string): IComponent<P> | undefined
+```
+
+### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `refPath` | `string` | 组件引用路径 |
+| `P`（泛型） | - | 组件 Props 类型，用于类型推断 |
+
+### 返回值
+
+返回对应的 React 组件。如果未找到，返回 `undefined` 并在控制台输出警告。
+
+### 使用示例
+
+#### 跨模块引用组件
+
+```typescript
+import { useClientComponent } from '@linyjs/client-module-interface';
+
+function MyPage() {
+  // 从 userModule 获取 Avatar 组件
+  const Avatar = useClientComponent<{ src: string; size?: number }>(
+    'userModule.userComponents.Avatar'
+  );
+
+  if (!Avatar) {
+    return <div>组件加载中...</div>;
+  }
+
+  return <Avatar src="/avatar.jpg" size={48} />;
+}
+```
+
+#### 模块内引用组件
+
+```typescript
+// 假设当前组件属于 userModule
+function UserCard() {
+  // 省略 moduleName，框架自动补全
+  const Avatar = useClientComponent('userComponents.Avatar');
+
+  return (
+    <div>
+      {Avatar && <Avatar src="/avatar.jpg" />}
+      <span>用户名</span>
+    </div>
+  );
+}
+```
+
+---
+
+## useClientHook
+
+获取跨模块注册的自定义 Hook。
+
+### 签名
+
+```typescript
+function useClientHook<T extends Function>(refPath: string): T | undefined
+```
+
+### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `refPath` | `string` | Hook 引用路径 |
+| `T`（泛型） | `extends Function` | Hook 的函数类型 |
+
+### 返回值
+
+返回对应的 Hook 函数。如果未找到，返回 `undefined` 并在控制台输出警告。
+
+### 使用示例
+
+#### 跨模块引用 Hook
+
+```typescript
+import { useClientHook } from '@linyjs/client-module-interface';
+
+function MyComponent() {
+  // 从 authModule 获取 useAuth Hook
+  const useAuth = useClientHook<() => { user: any; login: Function; logout: Function }>(
+    'authModule.authHooks.useAuth'
+  );
+
+  if (!useAuth) {
+    return <div>认证功能加载中...</div>;
+  }
+
+  // 调用获取到的 Hook
+  const { user, login, logout } = useAuth();
+
+  if (!user) {
+    return <button onClick={() => login()}>登录</button>;
+  }
+
+  return (
+    <div>
+      <span>欢迎, {user.name}</span>
+      <button onClick={() => logout()}>退出</button>
+    </div>
+  );
+}
+```
+
+#### 带参数的 Hook
+
+```typescript
+// 假设 dataModule 注册了一个 useFetchData Hook
+function Dashboard() {
+  type UseFetchData = (url: string) => {
+    data: any;
+    loading: boolean;
+    error: string | null;
+  };
+
+  const useFetchData = useClientHook<UseFetchData>(
+    'dataModule.dataHooks.useFetchData'
+  );
+
+  if (!useFetchData) return <div>Loading...</div>;
+
+  const { data, loading, error } = useFetchData('/api/stats');
+
+  if (loading) return <div>加载中...</div>;
+  if (error) return <div>错误: {error}</div>;
+
+  return <div>{JSON.stringify(data)}</div>;
+}
+```
+
+---
+
+## useClientService
+
+获取跨模块注册的服务实例。
+
+### 签名
+
+```typescript
+function useClientService<T = any>(refPath: string): T | undefined
+```
+
+### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `refPath` | `string` | 服务引用路径 |
+| `T`（泛型） | - | 服务实例类型 |
+
+### 返回值
+
+返回对应的服务实例。如果未找到，返回 `undefined` 并在控制台输出警告。
+
+> ⚠️ **注意**：服务的引用格式是 `moduleName.serviceTag`（两段），不是三段。服务实例是整个对象，不需要 `.name`。
+
+### 使用示例
+
+#### 跨模块引用服务
+
+```typescript
+import { useClientService } from '@linyjs/client-module-interface';
+
+interface IAnalyticsService {
+  track(event: string, data?: Record<string, any>): void;
+  pageView(path: string): void;
+}
+
+function MyPage() {
+  // 从 analyticsModule 获取分析服务
+  const analytics = useClientService<IAnalyticsService>(
+    'analyticsModule.analyticsService'
+  );
+
+  useEffect(() => {
+    // 记录页面访问
+    analytics?.pageView('/my-page');
+  }, []);
+
+  const handleClick = () => {
+    analytics?.track('button_click', { button: 'cta' });
+  };
+
+  return <button onClick={handleClick}>点击</button>;
+}
+```
+
+#### 模块内引用服务
+
+```typescript
+// 假设当前组件属于 userModule
+function UserList() {
+  // 省略 moduleName，框架自动补全为 userModule.userService
+  const userService = useClientService<{ getUsers: () => Promise<any[]> }>(
+    'userService'
+  );
+
+  const [users, setUsers] = useState([]);
+
+  useEffect(() => {
+    userService?.getUsers().then(setUsers);
+  }, []);
+
+  return (
+    <ul>
+      {users.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+```
+
+---
+
+## useClientRoute
+
+获取路由相关的组件和 Hooks。底层通过路由适配器（`IRouterAdapter`）实现，切换适配器后消费端代码不变。
+
+### 签名
+
+```typescript
+function useClientRoute(key: string): any
+```
+
+### 参数
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 路由功能标识 |
+
+### 可用的 Key
+
+| Key | 返回类型 | 说明 |
+|-----|----------|------|
+| `'NavLink'` | `React.ComponentType` | 导航链接组件，支持 active 状态样式 |
+| `'Link'` | `React.ComponentType` | 普通链接组件 |
+| `'useNavigate'` | `() => NavigateFunction` | 编程式导航 Hook |
+| `'useParams'` | `() => Record<string, string>` | 获取路由参数 Hook |
+| `'useLocation'` | `() => Location` | 获取当前位置 Hook |
+| `'useSearchParams'` | `() => [URLSearchParams, Function]` | 获取/设置查询参数 Hook |
+
+### 使用示例
+
+#### 导航链接
+
+```typescript
+import { useClientRoute } from '@linyjs/client-module-interface';
+
+function NavBar() {
+  const NavLink = useClientRoute('NavLink');
+  const Link = useClientRoute('Link');
+
+  if (!NavLink) return null;
+
+  return (
+    <nav>
+      {/* NavLink 支持 active 状态 */}
+      <NavLink to="/" end className="nav-link">
+        首页
+      </NavLink>
+      <NavLink to="/articles" className="nav-link">
+        文章
+      </NavLink>
+      <NavLink to="/kanban" className="nav-link">
+        看板
+      </NavLink>
+    </nav>
+  );
+}
+```
+
+#### 编程式导航
+
+```typescript
+function LoginForm() {
+  const useNavigate = useClientRoute('useNavigate');
+  const navigate = useNavigate();
+
+  const handleLogin = async (credentials) => {
+    const result = await login(credentials);
+    if (result.success) {
+      navigate('/dashboard');                    // 导航到仪表盘
+      // navigate('/dashboard', { replace: true }); // 替换历史记录
+    } else {
+      navigate('/login?error=invalid');
+    }
+  };
+
+  return <button onClick={() => handleLogin({ ... })}>登录</button>;
+}
+```
+
+#### 获取路由参数
+
+```typescript
+function TaskDetail() {
+  const useParams = useClientRoute('useParams');
+  const params = useParams();
+
+  return <div>任务 ID: {params.id}</div>;
+}
+
+// 多参数路由 /groups/:groupId/tasks/:taskId
+function GroupTaskDetail() {
+  const useParams = useClientRoute('useParams');
+  const { groupId, taskId } = useParams();
+
+  return (
+    <div>
+      分组: {groupId}, 任务: {taskId}
+    </div>
+  );
+}
+```
+
+#### 获取当前位置
+
+```typescript
+function Breadcrumb() {
+  const useLocation = useClientRoute('useLocation');
+  const location = useLocation();
+
+  const paths = location.pathname.split('/').filter(Boolean);
+
+  return (
+    <nav>
+      {paths.map((path, index) => (
+        <span key={index}>
+          {index > 0 && ' / '}
+          {path}
+        </span>
+      ))}
+    </nav>
+  );
+}
+```
+
+#### 获取和设置查询参数
+
+```typescript
+function ArticleList() {
+  const useSearchParams = useClientRoute('useSearchParams');
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const page = Number(searchParams.get('page') || '1');
+  const limit = Number(searchParams.get('limit') || '10');
+
+  const handlePageChange = (newPage: number) => {
+    setSearchParams({ page: String(newPage), limit: String(limit) });
+  };
+
+  return (
+    <div>
+      <p>第 {page} 页，每页 {limit} 条</p>
+      <button onClick={() => handlePageChange(page + 1)}>下一页</button>
+    </div>
+  );
+}
+```
+
+> 📖 **路由功能的详细说明**：`useClientRoute` 的更多用法请阅读 [前端页面路由](./client-routes.md)。
+
+---
+
+## 资源注册
+
+以上 Hooks 消费的资源由各模块通过 ServiceDef 声明注册。以下是注册方式的简要说明，详见 [客户端模块开发](./client-module.md)。
+
+### 注册组件
+
+```typescript
+import type { IComponentListService, IComponentListDef } from '@linyjs/client-module-interface';
+
+class MyComponentService implements IComponentListService {
+  components = {
+    MyButton,
+    MyCard
+  };
+}
+
+const componentDef: IComponentListDef = {
+  serviceTag: 'myComponents',
+  serviceImpl: MyComponentService,
+  meta: { usageType: 'component' }
+};
+
+// 注册后可通过 useClientComponent('moduleName.myComponents.MyButton') 获取
+```
+
+### 注册 Hook
+
+```typescript
+import type { IHooksService, IHooksDef } from '@linyjs/client-module-interface';
+
+class MyHooksService implements IHooksService {
+  hooks = {
+    useFetchData,
+    useLocalStorage
+  };
+}
+
+const hookDef: IHooksDef = {
+  serviceTag: 'myHooks',
+  serviceImpl: MyHooksService,
+  meta: { usageType: 'hook' }
+};
+
+// 注册后可通过 useClientHook('moduleName.myHooks.useFetchData') 获取
+```
+
+### 注册服务
+
+```typescript
+import type { INormalServiceDef } from '@linyjs/client-module-interface';
+
+class MyService {
+  doSomething() { /* ... */ }
+}
+
+const serviceDef: INormalServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  meta: { usageType: 'normal_service' }
+};
+
+// 注册后可通过 useClientService('moduleName.myService') 获取
+```
+
+---
+
+## React Context 提供者
+
+所有 Hooks 依赖以下 React Context。框架在根组件中提供这些 Context，确保所有子组件都能访问注册表：
+
+| Context | 类型 | 说明 |
+|---------|------|------|
+| `ClientComponentsContext` | `Record<string, IComponent>` | 组件注册表 |
+| `ClientHooksContext` | `Record<string, Function>` | Hook 注册表 |
+| `ClientServicesContext` | `Record<string, any>` | 服务注册表 |
+| `ClientRouterContext` | `any` | 路由适配器实例 |
+
+> ⚠️ **SSR 注意**：在 SSR 模式下，这些 Context 由 SSR 中间件自动提供。在 CSR 模式下，需要确保根组件包裹了所有 Provider。
+
+---
+
+## 最佳实践
+
+### 1. 使用 TypeScript 泛型获取类型安全
+
+```typescript
+// ✅ 好的做法：使用泛型参数
+const Avatar = useClientComponent<{ src: string; size?: number }>(
+  'userModule.userComponents.Avatar'
+);
+
+const useAuth = useClientHook<() => { user: User | null }>(
+  'authModule.authHooks.useAuth'
+);
+
+const analytics = useClientService<IAnalyticsService>(
+  'analyticsModule.analyticsService'
+);
+
+// ❌ 避免：使用 any 类型，丢失类型检查
+const Avatar = useClientComponent('userModule.userComponents.Avatar');  // 类型为 any
+```
+
+### 2. 处理资源未找到的情况
+
+```typescript
+function MyPage() {
+  const Avatar = useClientComponent('userModule.userComponents.Avatar');
+
+  // 始终检查 undefined
+  if (!Avatar) {
+    return <div>组件加载中...</div>;
+  }
+
+  return <Avatar src="/avatar.jpg" />;
+}
+```
+
+### 3. 避免在渲染期间调用获取到的 Hook
+
+```typescript
+function MyComponent() {
+  const useAuth = useClientHook('authModule.authHooks.useAuth');
+
+  // ✅ 正确：先获取 Hook，再在组件顶层调用
+  const { user } = useAuth ? useAuth() : { user: null };
+
+  return <div>{user?.name}</div>;
+}
+```
+
+### 4. 使用完整的跨模块引用路径
+
+```typescript
+// ✅ 推荐：使用完整路径，明确来源
+const Avatar = useClientComponent('userModule.userComponents.Avatar');
+
+// ⚠️ 谨慎：模块内引用依赖自动补全，可能在跨模块场景下失效
+const Avatar = useClientComponent('userComponents.Avatar');
+```
+
+---
+
+## 常见问题
+
+### 1. Hook 返回 undefined
+
+**原因**：资源未注册或引用路径错误。
+
+**排查步骤**：
+1. 检查控制台是否有 `[useClientComponent] Component not found` 等警告
+2. 确认模块已正确加载（检查模块加载日志）
+3. 确认引用路径格式正确（三段式 `moduleName.serviceTag.name`）
+4. 确认 ServiceDef 的 `meta.usageType` 正确
+
+### 2. 服务引用格式错误
+
+```typescript
+// ❌ 错误：服务引用使用了三段式
+const service = useClientService('moduleName.serviceTag.someMethod');
+
+// ✅ 正确：服务引用使用两段式
+const service = useClientService('moduleName.serviceTag');
+// 然后通过 service.someMethod() 调用方法
+```
+
+### 3. 路由功能返回 undefined
+
+```typescript
+const useNavigate = useClientRoute('useNavigate');
+
+if (!useNavigate) {
+  // RouterProvider 未设置或路由适配器未初始化
+  // 检查是否在 RouterProvider 内部使用此 Hook
+  console.warn('路由功能不可用');
+  return;
+}
+
+const navigate = useNavigate();
+```
+
+---
+
+## 相关文档
+
+- 💻 [客户端模块开发](./client-module.md) — 资源注册方式
+- 🛤️ [前端页面路由](./client-routes.md) — `useClientRoute` 详细用法
+- 📊 [前端状态管理](./state-management.md) — Jotai 全局状态管理
+- 🔧 [API 参考](../api-reference/index.md) — Hooks 接口定义
+- 🎨 [UI 扩展插槽](./ui-slots.md) — UI 组件注入机制
+
+---
+
+**上一篇**: [前端页面路由](./client-routes.md) | **下一篇**: [前端状态管理](./state-management.md)

package/docs/guides/client-module.md

@@ -164,7 +164,7 @@ class BlogRouteService implements IRouteService {
 
 ## 全局状态(Global State)
 
-使用 Jotai 进行状态管理。
+使用 Jotai 进行状态管理。关于状态管理的完整说明（包括派生状态、跨模块共享、SSR 注意事项等），请阅读 [前端状态管理](./state-management.md)。
 
 ### 定义状态
 
@@ -595,10 +595,13 @@ function SafeComponent() {
 
 ## 下一步
 
+- 🛤️ 阅读 [前端页面路由](./client-routes.md) — 路由定义、参数、守卫、Loader、useClientRoute
+- 🪝 阅读 [公共 Hooks 使用](./client-hooks.md) — useClientComponent、useClientHook、useClientService、useClientRoute
+- 📊 阅读 [前端状态管理](./state-management.md) — Jotai 全局状态管理
 - 🎨 阅读 [UI 扩展插槽](./ui-slots.md)
 - 🔒 阅读 [权限管理](./permissions.md)
 - 💾 阅读 [数据持久化](./data-persistence.md)
 
 ---
 
-**上一篇**: [服务端模块开发](./server-module.md) | **下一篇**: [UI 扩展插槽](./ui-slots.md)
+**上一篇**: [服务端模块开发](./server-module.md) | **下一篇**: [前端页面路由](./client-routes.md)