Page Assist侧边栏与Web UI设计解析-优快云博客

Page Assist侧边栏与Web UI设计解析

【免费下载链接】page-assist Use your locally running AI models to assist you in your web browsing 项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist

本文深入解析了Page Assist浏览器扩展的架构设计与用户体验优化方案。文章从侧边栏的React组件化架构、状态管理策略和交互模式入手，详细介绍了现代化的键盘快捷键系统、拖放交互支持和实时消息处理流程。接着探讨了Web UI控制中心的功能布局，包括导航菜单结构、通用设置模块和响应式设计。最后分析了多浏览器兼容性实现方案，展示了如何通过分层架构和条件编译技术实现对Chrome、Firefox等浏览器的完美支持。

侧边栏架构设计与交互模式

Page Assist的侧边栏架构采用了现代化的React组件化设计，结合了响应式状态管理和高效的键盘交互模式。整个侧边栏系统被设计为一个高度模块化的单页应用，能够在浏览器扩展环境中无缝运行。

组件化架构设计

侧边栏的核心架构基于React组件树结构，采用分层设计模式：

mermaid

每个组件都遵循单一职责原则，通过自定义Hook进行状态管理：

// 核心消息管理Hook
export const useMessage = () => {
  const {
    messages,          // 消息列表
    setMessages,       // 设置消息
    streaming,         // 流式传输状态
    setStreaming,      // 设置流式状态
    chatMode,          // 聊天模式
    setChatMode,       // 设置聊天模式
    webSearch,         // 网络搜索状态
    setWebSearch       // 设置搜索状态
  } = useStoreMessage()
  
  return {
    onSubmit,          // 提交消息处理
    regenerateLastMessage, // 重新生成消息
    editMessage,       // 编辑消息
    clearChat          // 清空聊天
  }
}

状态管理架构

侧边栏采用分层状态管理策略，结合了Plasmo扩展存储和React状态：

状态类型	存储位置	生命周期	用途
聊天消息	React状态	会话期间	实时消息显示
用户设置	扩展存储	持久化	用户偏好设置
模型配置	扩展存储	持久化	AI模型选择
聊天历史	IndexedDB	持久化	历史记录存储

mermaid

交互模式设计

键盘快捷键系统

Page Assist实现了高度可配置的键盘快捷键系统，支持用户自定义操作：

// 键盘快捷键配置架构
export interface KeyboardShortcut {
  key: string
  ctrlKey?: boolean
  altKey?: boolean
  shiftKey?: boolean
  metaKey?: boolean
  preventDefault?: boolean
  stopPropagation?: boolean
}

export interface KeyboardShortcutConfig {
  shortcut: KeyboardShortcut
  action: () => void
  enabled?: boolean
  description?: string
}

// 专用快捷键Hook
export const useSidebarShortcuts = (
  toggleSidebar: () => void,
  enabled: boolean = true
) => {
  const { shortcuts: configuredShortcuts } = useShortcutConfig()
  
  const toggleSidebarAction = useCallback(() => {
    toggleSidebar()
  }, [toggleSidebar])

  const shortcuts: KeyboardShortcutConfig[] = [
    {
      shortcut: configuredShortcuts.toggleSidebar,
      action: toggleSidebarAction,
      enabled,
      description: 'Toggle sidebar'
    }
  ]

  useKeyboardShortcuts(shortcuts)
  
  return { toggleSidebar: toggleSidebarAction, shortcuts }
}

拖放交互支持

侧边栏支持丰富的拖放交互功能：

// 文件拖放处理
const handleDrop = (e: DragEvent) => {
  e.preventDefault()
  e.stopPropagation()
  setDropState("idle")

  const files = Array.from(e.dataTransfer?.files || [])
  const isImage = files.every((file) => file.type.startsWith("image/"))

  if (!isImage) {
    setDropState("error")
    return
  }

  const newFiles = Array.from(e.dataTransfer?.files || []).slice(0, 1)
  if (newFiles.length > 0) {
    setDropedFile(newFiles[0])
  }
}

实时消息处理流程

消息处理采用了异步流式架构：

mermaid

响应式设计模式

侧边栏采用了自适应设计模式，确保在不同屏幕尺寸下的良好体验：

// 响应式布局示例
const SidepanelForm = ({ dropedFile }: Props) => {
  return (
    <div className="flex w-full flex-col items-center px-2">
      <div className="relative z-10 flex w-full flex-col items-center justify-center gap-2 text-base">
        <div className="relative flex w-full flex-row justify-center gap-2 lg:w-4/5">
          {/* 自适应输入容器 */}
          <div className="bg-neutral-50 dark:bg-[#262626] relative w-full max-w-[48rem] p-1 backdrop-blur-lg border border-gray-300 rounded-t-xl dark:border-gray-600">
            {/* 输入区域 */}
          </div>
        </div>
      </div>
    </div>
  )
}

错误处理与恢复机制

系统实现了完善的错误处理策略：

// 错误处理架构
const { mutateAsync: sendMessage, isPending: isSending } = useMutation({
  mutationFn: onSubmit,
  onSuccess: () => {
    textAreaFocus()  // 成功时聚焦输入框
  },
  onError: (error) => {
    textAreaFocus()  // 错误时恢复输入状态
    notification.error({
      message: t("formError.networkError"),
      description: error.message
    })
  }
})

这种架构设计确保了侧边栏在各种网络条件和用户操作下的稳定性和响应性，为用户提供了流畅的AI辅助浏览体验。

Web UI控制中心功能布局

Page Assist的Web UI控制中心采用了精心设计的布局架构，为用户提供了直观且功能丰富的配置界面。整个控制中心基于React技术栈构建，采用了现代化的组件化设计理念，确保用户体验的一致性和可扩展性。

导航菜单结构

控制中心的左侧导航菜单采用了分类清晰的层级结构，将各类设置按照功能模块进行组织：

mermaid

每个导航项都配备了直观的图标标识，帮助用户快速识别功能模块：

功能模块	图标	描述
通用设置	OrbitIcon	基础配置和全局选项
RAG设置	CombineIcon	检索增强生成相关配置
Ollama配置	OllamaIcon	本地AI模型设置
Chrome AI	ChromeIcon	浏览器AI功能（Beta）
OpenAI设置	CpuIcon	OpenAI API配置
模型管理	BrainCircuitIcon	AI模型选择和配置
知识库管理	BlocksIcon	知识库文件管理
提示词管理	BookIcon	自定义提示词模板
分享设置	ShareIcon	内容分享选项
关于页面	InfoIcon	版本信息和帮助

通用设置功能详解

通用设置模块包含了最常用的配置选项，采用分组式布局设计：

// 通用设置组件结构示例
export const GeneralSettings = () => {
  const [userChatBubble, setUserChatBubble] = useStorage("userChatBubble", true)
  const [copilotResumeLastChat, setCopilotResumeLastChat] = useStorage(
    "copilotResumeLastChat",
    false
  )
  // ... 更多状态管理
}

语言与界面设置

控制中心支持多语言切换，用户可以根据偏好选择界面语言：

<Select
  placeholder={t("generalSettings.settings.language.placeholder")}
  allowClear
  showSearch
  style={{ width: "200px" }}
  options={supportLanguage}
  value={locale}
  onChange={(value) => { changeLocale(value) }}
/>

聊天功能配置

系统提供了丰富的聊天相关设置选项：

配置项	类型	默认值	描述
Copilot恢复上次聊天	开关	false	是否自动恢复上次对话
默认开启网页聊天	开关	false	是否默认启用网页内容聊天
Web UI恢复上次聊天	开关	false	Web界面是否恢复上次会话
隐藏当前聊天模型设置	开关	false	简化聊天界面显示
恢复上次聊天模型	开关	false	自动选择上次使用的模型

高级功能选项

mermaid

每个功能开关都通过Ant Design的Switch组件实现，提供流畅的切换体验：

<Switch
  checked={generateTitle}
  onChange={(checked) => setGenerateTitle(checked)}
/>

响应式布局设计

控制中心采用了完全响应式的设计，能够适应不同屏幕尺寸：

/* 响应式布局示例 */
@media (max-width: 1024px) {
  .settings-layout {
    flex-direction: column;
  }
  .navigation-sidebar {
    position: sticky;
    top: 0;
    border-bottom: 1px solid #e5e7eb;
  }
}

在大屏幕设备上，导航菜单固定在左侧，内容区域在右侧；在小屏幕设备上，导航菜单转换为顶部横向滚动条，确保所有功能都可访问。

暗色模式支持

控制中心完整支持暗色模式，所有UI组件都经过精心设计，确保在明暗两种主题下都有良好的视觉效果：

const { mode, toggleDarkMode } = useDarkMode()
// 暗色模式切换组件
<button onClick={toggleDarkMode}>
  {mode === 'dark' ? <SunIcon /> : <MoonIcon />}
</button>

配置持久化机制

所有用户配置都通过@plasmohq/storage库进行本地存储，确保设置在不同会话间保持持久化：

const [userChatBubble, setUserChatBubble] = useStorage("userChatBubble", true)

这种设计使得用户无需重复配置，提升了使用体验。整个控制中心的布局和功能设计都体现了以用户为中心的设计理念，通过清晰的视觉层次和直观的操作流程，让用户能够轻松管理和定制他们的AI助手体验。

快捷键系统与操作效率优化

Page Assist 的快捷键系统是其提升用户体验和操作效率的核心功能之一。通过精心设计的键盘快捷键体系，用户可以快速访问核心功能，减少鼠标操作，显著提升与AI助手交互的效率。

快捷键架构设计

Page Assist 采用模块化的快捷键架构，通过 React Hook 模式实现高度可配置的键盘操作管理：

// 快捷键配置接口定义
export interface KeyboardShortcut {
  key: string
  ctrlKey?: boolean
  altKey?: boolean
  shiftKey?: boolean
  metaKey?: boolean
  preventDefault?: boolean
  stopPropagation?: boolean
}

export interface KeyboardShortcutConfig {
  shortcut: KeyboardShortcut
  action: () => void
  enabled?: boolean
  description?: string
}

这种设计允许开发者轻松添加新的快捷键，同时保持代码的可维护性和扩展性。

核心快捷键功能

Page Assist 提供了三类核心快捷键，覆盖了用户的主要操作场景：

1. 文本输入框聚焦快捷键

// 默认配置：Shift + Esc
focusTextarea: {
  key: 'Escape',
  shiftKey: true,
  preventDefault: true,
  stopPropagation: true
}

这个快捷键让用户能够快速将焦点切换到消息输入框，特别适合在浏览网页内容后立即进行对话的场景。

2. 新对话创建快捷键

// 默认配置：Ctrl + Shift + O  
newChat: {
  key: 'o',
  ctrlKey: true,
  shiftKey: true,
  preventDefault: true,
  stopPropagation: true
}

一键清除当前对话并开始新的聊天会话，提高多话题切换的效率。

3. 侧边栏切换快捷键

// 默认配置：Ctrl + B
toggleSidebar: {
  key: 'b',
  ctrlKey: true,
  preventDefault: true,
  stopPropagation: true
}

快速显示或隐藏聊天历史侧边栏，方便用户查看过往对话记录。

快捷键实现机制

Page Assist 使用 React Hook 模式实现快捷键管理，主要包含以下核心组件：

mermaid

事件处理流程

const handleKeyDown = useCallback((event: KeyboardEvent) => {
  shortcuts.forEach(({ shortcut, action, enabled = true }) => {
    if (!enabled) return
    
    // 检查按键组合匹配
    const keyMatches = event.key.toLowerCase() === key.toLowerCase()
    const ctrlMatches = event.ctrlKey === ctrlKey
    const altMatches = event.altKey === altKey
    const shiftMatches = event.shiftKey === shiftKey
    const metaMatches = event.metaKey === metaKey

    if (keyMatches && ctrlMatches && altMatches && shiftMatches && metaMatches) {
      event.preventDefault()
      event.stopPropagation()
      action()
    }
  })
}, [shortcuts])

配置管理与自定义

Page Assist 提供了完整的快捷键配置管理系统：

配置存储机制

const [shortcuts, setShortcuts] = useStorage<ShortcutConfig>(
  "keyboardShortcuts",
  defaultShortcuts
)

使用 @plasmohq/storage 进行配置的持久化存储，确保用户设置在不同会话间保持一致。

配置操作方法

// 更新单个快捷键
const updateShortcut = (shortcutName: keyof ShortcutConfig, newShortcut: KeyboardShortcut) => {
  setShortcuts(prev => ({ ...prev, [shortcutName]: newShortcut }))
}

// 重置所有快捷键
const resetShortcuts = () => {
  setShortcuts(defaultShortcuts)
}

// 重置单个快捷键
const resetShortcut = (shortcutName: keyof ShortcutConfig) => {
  setShortcuts(prev => ({ ...prev, [shortcutName]: defaultShortcuts[shortcutName] }))
}

快捷键使用场景分析

网页内容分析场景

mermaid

多话题对话管理

mermaid

性能优化考虑

Page Assist 在快捷键实现中考虑了多项性能优化措施：

事件委托优化：使用单个事件监听器处理所有快捷键，减少DOM事件监听器数量
条件执行：通过 enabled 参数控制快捷键是否生效，避免不必要的处理
内存管理：使用 useCallback 包装回调函数，避免不必要的重渲染
清理机制：组件卸载时自动移除事件监听器，防止内存泄漏

浏览器兼容性处理

针对不同浏览器的快捷键处理差异，Page Assist 实现了统一的处理逻辑：

// 统一处理修饰键，兼容不同操作系统
const ctrlKey = event.ctrlKey || event.metaKey // 兼容Mac的Command键

扩展快捷键配置示例

开发者可以轻松扩展新的快捷键功能：

// 添加截图快捷键示例
const useScreenshotShortcuts = (takeScreenshot: () => void, enabled: boolean = true) => {
  const { shortcuts: configuredShortcuts } = useShortcutConfig()

  const shortcuts: KeyboardShortcutConfig[] = [
    {
      shortcut: { key: 's', ctrlKey: true, shiftKey: true },
      action: takeScreenshot,
      enabled,
      description: 'Take screenshot'
    }
  ]

  useKeyboardShortcuts(shortcuts)
  return { takeScreenshot, shortcuts }
}

最佳实践建议

基于Page Assist的快捷键系统设计，推荐以下最佳实践：

遵循平台约定：使用常见的快捷键组合，如Ctrl+S保存、Ctrl+O打开等
避免冲突：检查快捷键是否与浏览器或网页现有功能冲突
提供可视化反馈：执行快捷键操作时给予用户视觉反馈
支持配置：允许用户自定义快捷键以适应个人习惯
文档完善：提供清晰的快捷键说明文档

通过这套完善的快捷键系统，Page Assist 显著提升了用户与AI助手交互的效率，使得网页内容分析、多话题对话管理等操作变得更加流畅和自然。

多浏览器兼容性实现方案

Page Assist作为一款跨浏览器扩展，其多浏览器兼容性实现方案展现了现代Web扩展开发的先进架构设计。通过深入分析其代码结构，我们可以发现该项目采用了分层架构、条件编译和运行时检测等多种技术手段来实现对Chrome、Firefox等主流浏览器的完美支持。

架构设计与入口分离

Page Assist采用了双入口架构设计，为不同浏览器提供独立的入口文件：

mermaid

这种设计允许针对不同浏览器的API差异进行专门优化。核心的差异处理体现在背景脚本中：

// Chrome版本使用chrome.sidePanel API
chrome.sidePanel.open({
  tabId: tab.id!
})

// Firefox版本使用browser.sidebarAction API  
browser.sidebarAction.toggle()

运行时环境检测机制

项目通过环境变量和运行时检测来确定当前浏览器环境：

// 环境变量检测
const isFirefox = import.meta.env.BROWSER === "firefox"
const isChrome = import.meta.env.BROWSER === "chrome"

// 运行时API特性检测
function supportsSidePanelAPI() {
  return typeof chrome !== 'undefined' && chrome.sidePanel
}

function supportsSidebarAction() {
  return typeof browser !== 'undefined' && browser.sidebarAction
}

路由系统的条件加载

路由系统采用懒加载和条件导入策略，确保不同浏览器加载最适合的组件：

// Firefox路由配置（使用懒加载减小包体积）
export const OptionRoutingFirefox = () => {
  return (
    <Routes>
      <Route path="/" element={<OptionIndex />} />
      <Route path="/settings" element={<OptionSettings />} />
      {/* 更多路由配置 */}
    </Routes>
  )
}

// Chrome路由配置
export const OptionRoutingChrome = () => {
  return (
    <Routes>
      <Route path="/" element={<OptionIndex />} />
      <Route path="/settings" element={<OptionSettings />} />
      <Route path="/settings/chrome" element={<OptionChrome />} />
    </Routes>
  )
}

API兼容层设计

项目构建了一个统一的API兼容层，封装浏览器特定的API调用：

// 统一的存储接口
class BrowserStorage {
  static async get(key: string): Promise<any> {
    if (typeof chrome !== 'undefined' && chrome.storage) {
      return new Promise((resolve) => {
        chrome.storage.local.get(key, (result) => resolve(result[key]))
      })
    } else if (typeof browser !== 'undefined' && browser.storage) {
      return browser.storage.local.get(key)
    }
  }
  
  static async set(key: string, value: any): Promise<void> {
    if (typeof chrome !== 'undefined' && chrome.storage) {
      return new Promise((resolve) => {
        chrome.storage.local.set({ [key]: value }, () => resolve())
      })
    } else if (typeof browser !== 'undefined' && browser.storage) {
      return browser.storage.local.set({ [key]: value })
    }
  }
}

功能特性的条件支持

不同浏览器对特定功能的支持程度不同，项目通过条件渲染来实现功能降级：

// TTS功能的条件支持
function useTTS() {
  const canUseBrowserTTS = () => {
    if (import.meta.env.BROWSER === "chrome") {
      return typeof chrome !== 'undefined' && chrome.tts
    }
    return false
  }
  
  const speak = (text: string) => {
    if (canUseBrowserTTS()) {
      chrome.tts.speak(text)
    } else {
      // 使用Web Speech API作为fallback
      const utterance = new SpeechSynthesisUtterance(text)
      speechSynthesis.speak(utterance)
    }
  }
}

构建系统的多目标配置

项目的构建系统支持同时为多个浏览器目标进行构建：

// wxt.config.ts 配置示例
export default defineConfig({
  browsers: ['chrome', 'firefox'],
  manifest: {
    // 通用配置
    name: 'Page Assist',
    version: '1.0.0',
    
    // 浏览器特定配置
    browser_specific_settings: {
      gecko: {
        id: '{uuid}',
        strict_min_version: '109.0'
      }
    },
    
    side_panel: {
      default_path: 'sidepanel.html'
    }
  }
})

测试与验证策略

为确保多浏览器兼容性，项目采用了分层测试策略：

测试类型	Chrome	Firefox	测试重点
单元测试	✅	✅	核心逻辑兼容性
集成测试	✅	✅	API调用验证
E2E测试	✅	✅	用户交互流程
性能测试	✅	✅	包体积和加载时间

错误处理与降级方案

完善的错误处理机制确保在特定浏览器中功能不可用时能够优雅降级：

function initializeSidePanel() {
  try {
    if (supportsSidePanelAPI()) {
      // Chrome的现代实现
      setupChromeSidePanel()
    } else if (supportsSidebarAction()) {
      // Firefox的实现
      setupFirefoxSidebar()
    } else {
      // 降级到弹出窗口模式
      setupPopupFallback()
    }
  } catch (error) {
    console.warn('Side panel initialization failed:', error)
    setupPopupFallback()
  }
}

通过这种多层次、多策略的兼容性实现方案，Page Assist能够在保持功能完整性的同时，为不同浏览器用户提供一致的使用体验。这种架构设计不仅解决了当前浏览器的兼容性问题，也为未来支持更多浏览器平台奠定了坚实的基础。

总结

Page Assist作为一款现代化的浏览器扩展，展现了出色的架构设计和用户体验优化。通过React组件化设计、分层状态管理和响应式布局，提供了流畅的AI辅助浏览体验。智能的快捷键系统和多浏览器兼容性方案进一步提升了操作效率和跨平台一致性。这种以用户为中心的设计理念，结合技术实现的精细考量，使得Page Assist成为浏览器扩展开发的优秀范例，为同类产品的开发提供了宝贵的参考价值。

【免费下载链接】page-assist Use your locally running AI models to assist you in your web browsing 项目地址: https://gitcode.com/GitHub_Trending/pa/page-assist

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考