@linyjs/plugin-docs 0.0.13

package/docs/guides/ui-slots.md

@@ -0,0 +1,475 @@
+# UI 扩展插槽
+
+本指南介绍如何使用 linyjs 的 UI 扩展插槽(Slot)机制来注入自定义 UI 组件。
+
+## 什么是 Slot?
+
+Slot 是一种 UI 扩展机制,允许插件向预定义的位置注入自定义组件,而无需修改核心代码。
+
+### 使用场景
+
+- 🎯 在管理后台添加自定义菜单项
+- 📊 在仪表盘注入统计图表
+- 🔧 在设置页面添加配置选项
+- 🎨 自定义用户界面的任何部分
+
+## 可用的 Slot 位置
+
+### 管理后台
+
+| Slot 位置 | 说明 | 示例用途 |
+|-----------|------|----------|
+| `admin-sidebar` | 侧边栏菜单 | 添加新功能入口 |
+| `admin-header` | 顶部导航 | 添加通知、用户菜单 |
+| `admin-dashboard` | 仪表盘 | 添加统计卡片、图表 |
+| `admin-settings` | 设置页面 | 添加自定义配置项 |
+| `admin-user-list` | 用户列表操作列 | 添加自定义操作按钮 |
+
+### 个人后台
+
+| Slot 位置 | 说明 | 示例用途 |
+|-----------|------|----------|
+| `personal-dashboard` | 个人仪表盘 | 添加个人信息卡片 |
+| `personal-header` | 个人顶部导航 | 添加快捷操作 |
+
+### 插件市场
+
+| Slot 位置 | 说明 | 示例用途 |
+|-----------|------|----------|
+| `plugin-marketplace` | 插件市场页面 | 添加推荐插件 |
+
+## 注册 Slot 组件
+
+### 基本用法
+
+```typescript
+import type { ISlotComponent } from '@linyjs/ui-slots-interface';
+import { getSlotRegistry } from '@linyjs/admin';
+import React from 'react';
+
+// 1. 创建组件
+function AnalyticsMenu() {
+  return (
+    <a href="/admin/analytics" style={{ padding: '10px' }}>
+      📊 数据分析
+    </a>
+  );
+}
+
+// 2. 在插件初始化时注册
+export function initPlugin() {
+  const registry = getSlotRegistry();
+  
+  registry.register({
+    id: 'analytics-menu',
+    position: 'admin-sidebar',
+    component: AnalyticsMenu,
+    priority: 50,
+    packageName: 'analytics-plugin'
+  });
+}
+```
+
+### 条件渲染
+
+根据用户权限或状态决定是否显示:
+
+```typescript
+registry.register({
+  id: 'premium-feature',
+  position: 'admin-dashboard',
+  component: PremiumWidget,
+  priority: 100,
+  shouldRender: (context) => {
+    // 只有高级用户可见
+    return context.user?.isPremium === true;
+  }
+});
+```
+
+### 动态内容
+
+```typescript
+function NotificationBadge() {
+  const [count, setCount] = React.useState(0);
+  
+  React.useEffect(() => {
+    // 获取通知数量
+    fetch('/api/notifications/count')
+      .then(res => res.json())
+      .then(data => setCount(data.count));
+  }, []);
+  
+  return (
+    <div style={{ position: 'relative' }}>
+      🔔
+      {count > 0 && (
+        <span style={{
+          position: 'absolute',
+          top: '-5px',
+          right: '-5px',
+          backgroundColor: 'red',
+          color: 'white',
+          borderRadius: '50%',
+          padding: '2px 6px',
+          fontSize: '12px'
+        }}>
+          {count}
+        </span>
+      )}
+    </div>
+  );
+}
+
+registry.register({
+  id: 'notification-badge',
+  position: 'admin-header',
+  component: NotificationBadge,
+  priority: 90
+});
+```
+
+## Slot 优先级
+
+优先级决定组件的渲染顺序(数字越大越靠前):
+
+| 优先级范围 | 用途 | 示例 |
+|-----------|------|------|
+| 0-10 | 基础功能 | 默认菜单项 |
+| 10-50 | 常用扩展 | 普通功能入口 |
+| 50-100 | 重要扩展 | 核心功能入口 |
+| 100+ | 核心功能 | 系统级功能 |
+
+### 优先级示例
+
+```typescript
+// 低优先级 - 显示在后面
+registry.register({
+  id: 'help-link',
+  position: 'admin-sidebar',
+  component: HelpLink,
+  priority: 5
+});
+
+// 中优先级 - 显示在中间
+registry.register({
+  id: 'analytics-link',
+  position: 'admin-sidebar',
+  component: AnalyticsLink,
+  priority: 50
+});
+
+// 高优先级 - 显示在前面
+registry.register({
+  id: 'dashboard-link',
+  position: 'admin-sidebar',
+  component: DashboardLink,
+  priority: 100
+});
+```
+
+## Slot Context
+
+注册时可以访问上下文信息:
+
+```typescript
+interface SlotContext {
+  user?: {
+    id: number;
+    name: string;
+    roles: string[];
+    isPremium?: boolean;
+  };
+  location?: {
+    pathname: string;
+    search: string;
+  };
+  theme?: 'light' | 'dark';
+  // ... 其他上下文信息
+}
+
+registry.register({
+  id: 'user-specific-widget',
+  position: 'admin-dashboard',
+  component: UserWidget,
+  shouldRender: (context: SlotContext) => {
+    // 根据用户角色决定
+    return context.user?.roles?.includes('admin');
+  }
+});
+```
+
+## 移除 Slot
+
+如果需要动态移除已注册的 Slot:
+
+```typescript
+// 注册时保存引用
+const slotId = registry.register({
+  id: 'temp-widget',
+  position: 'admin-dashboard',
+  component: TempWidget
+});
+
+// 稍后移除
+registry.unregister(slotId);
+```
+
+## 完整示例
+
+### 示例 1: 添加侧边栏菜单
+
+```typescript
+import React from 'react';
+import { getSlotRegistry } from '@linyjs/admin';
+
+function BlogMenu() {
+  return (
+    <div style={{ 
+      padding: '12px 16px',
+      cursor: 'pointer',
+      '&:hover': { backgroundColor: '#f5f5f5' }
+    }}>
+      <span style={{ marginRight: '8px' }}>📝</span>
+      <span>博客管理</span>
+    </div>
+  );
+}
+
+export function initBlogPlugin() {
+  const registry = getSlotRegistry();
+  
+  registry.register({
+    id: 'blog-menu',
+    position: 'admin-sidebar',
+    component: BlogMenu,
+    priority: 60,
+    shouldRender: (context) => {
+      // 仅管理员和编辑可见
+      return context.user?.roles?.includes('admin') ||
+             context.user?.roles?.includes('editor');
+    }
+  });
+}
+```
+
+### 示例 2: 仪表盘统计卡片
+
+```typescript
+import React, { useState, useEffect } from 'react';
+
+function StatsCard({ title, value, icon }: { 
+  title: string; 
+  value: number; 
+  icon: string 
+}) {
+  return (
+    <div style={{
+      padding: '20px',
+      backgroundColor: 'white',
+      borderRadius: '8px',
+      boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
+      textAlign: 'center'
+    }}>
+      <div style={{ fontSize: '32px', marginBottom: '8px' }}>{icon}</div>
+      <div style={{ fontSize: '24px', fontWeight: 'bold', color: '#333' }}>
+        {value}
+      </div>
+      <div style={{ color: '#666', marginTop: '4px' }}>{title}</div>
+    </div>
+  );
+}
+
+function DashboardStats() {
+  const [stats, setStats] = useState({
+    users: 0,
+    articles: 0,
+    comments: 0
+  });
+  
+  useEffect(() => {
+    fetch('/api/stats')
+      .then(res => res.json())
+      .then(setStats);
+  }, []);
+  
+  return (
+    <div style={{
+      display: 'grid',
+      gridTemplateColumns: 'repeat(3, 1fr)',
+      gap: '16px',
+      padding: '20px'
+    }}>
+      <StatsCard title="用户数" value={stats.users} icon="👥" />
+      <StatsCard title="文章数" value={stats.articles} icon="📝" />
+      <StatsCard title="评论数" value={stats.comments} icon="💬" />
+    </div>
+  );
+}
+
+export function initStatsPlugin() {
+  const registry = getSlotRegistry();
+  
+  registry.register({
+    id: 'dashboard-stats',
+    position: 'admin-dashboard',
+    component: DashboardStats,
+    priority: 100
+  });
+}
+```
+
+### 示例 3: 用户列表操作按钮
+
+```typescript
+import React from 'react';
+
+function UserActionButtons({ userId }: { userId: number }) {
+  const handleBan = async () => {
+    if (confirm('确定要封禁此用户吗?')) {
+      await fetch(`/api/users/${userId}/ban`, { method: 'POST' });
+      alert('用户已封禁');
+    }
+  };
+  
+  return (
+    <div style={{ display: 'flex', gap: '8px' }}>
+      <button onClick={() => alert(`编辑用户 ${userId}`)}>
+        ✏️ 编辑
+      </button>
+      <button onClick={handleBan} style={{ color: 'red' }}>
+        🚫 封禁
+      </button>
+    </div>
+  );
+}
+
+export function initUserActionsPlugin() {
+  const registry = getSlotRegistry();
+  
+  registry.register({
+    id: 'user-actions',
+    position: 'admin-user-list',
+    component: UserActionButtons,
+    priority: 50
+  });
+}
+```
+
+## 最佳实践
+
+### 1. 组件轻量化
+
+Slot 组件应该轻量,避免复杂逻辑:
+
+```typescript
+// ✅ 好的做法 - 轻量组件
+function SimpleMenu() {
+  return <a href="/page">Page</a>;
+}
+
+// ❌ 避免 - 过重逻辑
+function ComplexMenu() {
+  // 大量状态管理、副作用等
+  const [state1, setState1] = useState(...);
+  const [state2, setState2] = useState(...);
+  // ...
+}
+```
+
+### 2. 错误边界
+
+为 Slot 组件添加错误处理:
+
+```typescript
+function SafeSlotComponent() {
+  const [error, setError] = useState<string | null>(null);
+  
+  try {
+    // 组件逻辑
+    return <div>Content</div>;
+  } catch (err) {
+    setError(err.message);
+    return <div>Error loading component</div>;
+  }
+}
+```
+
+### 3. 懒加载
+
+对于重型组件,使用懒加载:
+
+```typescript
+function LazySlotComponent() {
+  const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+  
+  return (
+    <React.Suspense fallback={<div>Loading...</div>}>
+      <HeavyComponent />
+    </React.Suspense>
+  );
+}
+
+registry.register({
+  id: 'heavy-widget',
+  position: 'admin-dashboard',
+  component: LazySlotComponent,
+  priority: 50
+});
+```
+
+### 4. 唯一 ID
+
+确保每个 Slot 的 ID 唯一:
+
+```typescript
+// ✅ 好的做法 - 使用包名作为前缀
+registry.register({
+  id: 'my-plugin.analytics-menu',
+  position: 'admin-sidebar',
+  component: AnalyticsMenu
+});
+
+// ❌ 避免 - ID 可能冲突
+registry.register({
+  id: 'analytics-menu',
+  position: 'admin-sidebar',
+  component: AnalyticsMenu
+});
+```
+
+## 调试技巧
+
+### 查看已注册的 Slots
+
+```typescript
+const registry = getSlotRegistry();
+const slots = registry.getAll();
+console.log('Registered slots:', slots);
+```
+
+### 测试条件渲染
+
+```typescript
+registry.register({
+  id: 'debug-widget',
+  position: 'admin-dashboard',
+  component: () => {
+    console.log('Rendering debug widget');
+    return <div>Debug</div>;
+  },
+  shouldRender: (context) => {
+    console.log('Context:', context);
+    return true;
+  }
+});
+```
+
+## 相关文档
+
+- 📖 [客户端模块开发](./client-module.md)
+- 🔒 [权限管理](./permissions.md)
+
+---
+
+**上一篇**: [客户端模块开发](./client-module.md) | **下一篇**: [权限管理](./permissions.md)