#Workspace - 工作空间

Workspace 是一个功能强大的工作空间组件，提供了标签页式的内容管理界面。支持多种内容类型的展示，包括实时跟随、任务管理、文件预览、浏览器内容等，为用户提供统一的工作环境。

#✨ 功能特点

• 🔄 实时跟随: 支持 shell、markdown、html 等内容的实时更新显示，也支持完全自定义渲染
• 📋 任务管理: 内置任务列表和任务状态管理功能
• 📁 文件预览: 支持多种文件格式的预览和下载（含可选的 docx / xlsx / pptx Office 三件套，见 OfficeViewer）
• 🌐 浏览器集成: 可嵌入浏览器内容和网页预览
• 🎛️ 自定义内容: 支持自定义组件和内容渲染（通过 customContent 或 Workspace.Custom）
• 📱 响应式设计: 适配不同屏幕尺寸，提供良好的用户体验

#性能与布局

实时内容、HTML 代码视图和文本文件预览默认使用轻量只读 Markdown，不创建 Slate 编辑器。需要 Slate 文档行为时，可设置对应的 markdownEditorProps={{ renderMode: 'slate' }}；实时面板显式设置 readonly: false 仍使用可编辑视图。

Workspace 按实际标题和标签栏高度分配内容空间。嵌入固定高度面板时，为父容器设置高度；窄屏标签在标签栏内横向滚动。流式内容仅在用户处于跟随状态时自动滚动，向上浏览历史内容会暂停跟随。

文件列表默认渐进展示 50 项，查看更多时追加 100 项。更新文件数据时尽量复用未变节点引用；使用 id 标识文件，更新远程文件版本时同步更新 lastModified。切换文件会取消旧预览请求并释放其临时资源。

#代码演示

已废弃事件保留向下兼容：onToggleGroup → onGroupToggle、loading → isLoading，详见各 API 表里带删除线 + version 标记的行。

#基础用法

#文件管理

#实时跟随

#浏览器

#任务管理

#空状态

#自定义内容

#高级用法

#Header 右侧自定义

#API

#Workspace

#子面板识别

内置子组件带有面板类型标记，支持 React.memo(Workspace.File) 等常见包裹（通过 type 链解析）。自定义 HOC 若无法识别，可在子组件上传入 panelType（如 panelType="file"），或使用 markWorkspacePanel(YourPanel, 'file') 标记组件。

各子面板的 tab 配置见 TabConfiguration；BaseChildProps.panelType 仅用于无法自动识别时显式声明类型。

#受控标签与文件预览

• 受控：传入 activeTabKey 时，在 onTabChange 中更新 state。非法 key 时界面回退到有效项；notifyOnInvalidActiveTabKey={false} 可仅静默回退、不触发回调。
• 非受控：使用 defaultActiveTabKey 指定初始标签，未传则激活第一项。
• 预览：默认在离开文件类标签（file / fileTree）时重置预览；设置 preserveFilePreviewOnTabChange 可在切 Tab 后保留预览态。

#Workspace.Realtime

实时跟随组件，用于展示实时更新的内容（支持 shell、markdown/md、html，也支持通过 customContent 完全自定义渲染）。

#RealtimeFollowData

#DiffContent

#Workspace.Task

任务组件，用于展示任务列表。

#TaskItemInput

#TaskItem

#Workspace.File

文件组件，用于展示文件列表和文件操作。

#DOM id 绑定策略

• 当 bindDomId 为 false（默认）：不会在文件项根元素写入 id 属性，更推荐通过选择器如 [data-testid] 或 className 进行自动化选择。
• 当 bindDomId 为 true：组件会在文件项根元素绑定 id。来源遵循：
  • 若传入的 FileNode.id 存在，则使用该值；
  • 否则使用组件内部生成的稳定 id（基于节点内容生成并缓存）。

#FileTreeSwitchConfig

Workspace.File.fileTreeSwitch 的配置；传入后在搜索框旁展示「平铺 / 文件树」段控件。treeProps 与独立使用 Workspace.FileTree 时一致——tab / resetKey / filterKeyword 以及预览/下载/分享/定位/点击等回调由 Workspace.File 注入，不需在此重复传。

#Workspace.FileTree

树形文件列表，目录节点在首次展开时通过 onLoadChildren 拉取子节点（懒加载）。叶子节点可挂 file 字段以展示预览/下载等操作（与 onPreview / onDownload 等配合）；与 Workspace.File 的 fileTreeSwitch 联用时由 Workspace.File 注入关键字与预览/下载回调。filterKeyword 仅匹配已展开目录下的已加载子树；无匹配时按是否已展开展示不同文案（workspace.treeFilterNoMatchVisibleRoots / workspace.treeFilterNoMatchInExpanded）。

#FileTreeNode

#FileActionRef

#FileNode

预览内容来源优先级：Workspace.File / Workspace.FileTree 的 onPreview 自定义返回值 → customContent（PreviewComponent） → loading 占位 → content（文本/Markdown/HTML 内联） → previewUrl（图片优先） → url（其他文件）。canPreview === false 会跳过以上分支并直接展示 UnsupportedFileCard。

#FileRenderContext

自定义渲染函数的参数类型：

#FileBuiltinActions

内置操作按钮类型，用于在 renderActions 中复用：

#GroupNode

#FileType

文件类型键值，内置常见文本/图片/视频/音频/办公文档/压缩包/代码等类型（如 plainText、markdown、image、video、audio、pdf、word、excel、csv、powerpoint、archive、javascript、typescript、react、python、java、cpp、c、csharp、go、rust、php、ruby、shell、powershell、sql、lua、perl、scala、config)。

#FileCategory

文件分类枚举，用于对文件类型进行分组：

#Workspace.Browser

浏览器组件，用于展示浏览器搜索建议和搜索结果列表，适合承接「联网搜索 / WebSearch」等智能体工具输出。

#BrowserSuggestion

#BrowserItem

#Workspace.Custom

自定义组件，用于展示自定义内容。与 Workspace.Realtime/Workspace.Task 等通过 data prop 传内容的子组件不同，Workspace.Custom 直接以 children 接收 React 节点；适合内容形态完全无法被内置子面板覆盖的场景。

#TabItem（内部结构）

Workspace 解析子组件后得到的标签项，供内部分栏与内容渲染使用；其中 componentType 为内置子面板类型（realtime | browser | task | file | fileTree | custom），用于在首个「实时跟随」后插入视觉分割线。

#TabConfiguration

标签页配置项，适用于所有子组件（不传则使用组件内置默认：图标与标题）。

所有 Workspace.* 子组件另支持 BaseChildProps.panelType（WorkspacePanelType），用于 HOC 无法自动识别时显式声明面板类型。

#使用场景

#1. 开发工作空间

适用于开发环境中的多标签页工作空间，可以同时查看代码、日志、文档等。

#2. 数据分析工作台

用于数据分析场景，可以同时展示数据文件、分析结果、可视化图表等。

#3. 文档管理系统

用于文档的预览、编辑、版本对比等功能。

#4. 实时监控面板

用于展示实时数据、日志流、系统状态等信息。

#5. 任务管理界面

用于展示任务进度、执行状态、结果输出等。

#最佳实践

1. 合理使用标签页数量：建议单个工作空间内的标签页数量不超过 8 个，避免界面过于拥挤。

2. 标签页命名：使用简洁明了的标签页标题，便于用户快速识别。

3. 文件类型支持：充分利用内置的文件类型支持，为不同类型的文件提供合适的预览方式。

4. 自定义预览：对于特殊文件类型，可以通过 onPreview 回调实现自定义预览逻辑。

5. 自定义内容渲染：

   • 对于需要完全自定义的内容，优先使用 Workspace.Realtime 的 customContent 属性
   • customContent 优先级最高，传入后会忽略其他渲染逻辑
   • 也可以使用 Workspace.Custom 实现独立的自定义标签页，区别是前者会自带分割线

6. 响应式设计：考虑在不同屏幕尺寸下的显示效果，合理设置工作空间的高度和宽度。

7. 性能优化：对于大量文件或复杂内容，考虑使用虚拟滚动或分页加载。

8. 错误处理：为文件预览、下载等操作添加适当的错误处理和用户提示。

9. 无障碍支持：确保工作空间组件具有良好的键盘导航和屏幕阅读器支持。

10. 子组件识别：优先使用 Workspace.* 内置子组件；memo 一般可直接使用，自定义 HOC 用 panelType 或 markWorkspacePanel（见 子面板识别）。

11. 受控标签：activeTabKey + onTabChange 成对使用；非法 key 可用 notifyOnInvalidActiveTabKey={false} 避免多余回调。

12. 文件预览：需要跨 Tab 保留预览时设置 preserveFilePreviewOnTabChange。

#扩展 API

#HtmlPreviewProps

HTML 预览组件的属性接口，用于 HTML 内容的预览和代码查看。

#PreviewComponentProps

文件预览组件的属性接口，用于文件内容的预览显示。

#工具函数

#getFileType

根据文件名推断文件类型。

getFileType(filename: string): FileType

参数：

• filename - 文件名（包含扩展名）

返回值：

• 推断出的文件类型，如果无法识别则返回 'plainText'

#getMimeType

根据文件类型获取对应的 MIME 类型。

getMimeType(fileType: FileType): string

参数：

• fileType - 文件类型

返回值：

• 对应的 MIME 类型字符串

#getFileCategory

根据文件类型获取文件分类。

getFileCategory(fileType: FileType): FileCategory

参数：

• fileType - 文件类型

返回值：

• 对应的文件分类枚举值