浮动视图系统

相关源文件

• blocksuite/affine/blocks/attachment/src/attachment-block.ts
• blocksuite/affine/blocks/attachment/src/embed.ts
• blocksuite/affine/blocks/attachment/src/styles.ts
• blocksuite/affine/components/src/color-picker/utils.ts
• packages/frontend/component/src/lit-react/index.ts
• packages/frontend/component/src/lit-react/lit-portal/index.ts
• packages/frontend/component/src/lit-react/lit-portal/lit-portal.tsx
• packages/frontend/component/src/lit-react/to-react-node.ts
• packages/frontend/core/src/blocksuite/block-suite-editor/lit-adaper.tsx
• packages/frontend/core/src/desktop/dialogs/import/index.tsx
• packages/frontend/core/src/modules/peek-view/entities/peek-view.ts
• packages/frontend/core/src/modules/peek-view/view/doc-preview/doc-peek-view.css.ts
• packages/frontend/core/src/modules/peek-view/view/image-preview/index.css.ts
• packages/frontend/core/src/modules/peek-view/view/image-preview/index.tsx
• packages/frontend/core/src/modules/peek-view/view/modal-container.css.ts
• packages/frontend/core/src/modules/peek-view/view/modal-container.tsx
• packages/frontend/core/src/modules/peek-view/view/peek-view-controls.css.ts
• packages/frontend/core/src/modules/peek-view/view/peek-view-controls.tsx
• packages/frontend/core/src/modules/peek-view/view/peek-view-manager.tsx
• tests/affine-cloud/e2e/share-page.spec.ts
• tests/affine-local/e2e/attachment-preview.spec.ts
• tests/affine-local/e2e/blocksuite/color-picker.spec.ts
• tests/affine-local/e2e/blocksuite/paragraph.spec.ts
• tests/fixtures/v1-color-palettes-snapshot.zip
• tests/kit/src/utils/attachment.ts

Peek View System 提供了一个模态预览机制，允许用户在不离开当前上下文的情况下查看各种类型的内容（文档、图片、附件、AI 聊天）。它通过实现快速信息访问和预览功能，在 AFFiNE 中起到了关键的生产力提升作用。

有关在文档中嵌入内容的信息，请参阅编辑器系统文档 2.1。

架构概述

Peek View System 遵循实体-服务-视图架构，清晰地分离了状态管理和渲染逻辑。

来源: packages/frontend/core/src/modules/peek-view/entities/peek-view.ts230-310 packages/frontend/core/src/modules/peek-view/view/modal-container.tsx21-434 packages/frontend/core/src/modules/peek-view/view/peek-view-manager.tsx1-159

核心组件

PeekViewEntity

PeekViewEntity 是 Peek View 的中央状态管理器。

该实体通过两个关键的 LiveData 可观测对象维护状态

• active$: 跟踪当前活动的 Peek View
• show$: 控制可见性状态及动画配置

来源: packages/frontend/core/src/modules/peek-view/entities/peek-view.ts34-225

PeekViewModalContainer

PeekViewModalContainer 组件负责模态 UI 和动画。

主要动画方法包括：

• animateFade(): 简单的透明度过渡
• animateFadeBottom(): 带垂直移动的淡入效果
• animateZoomIn()/animateZoomOut(): 从目标元素缩放进入/退出

来源: packages/frontend/core/src/modules/peek-view/view/modal-container.tsx43-434 packages/frontend/core/src/modules/peek-view/view/modal-container.css.ts1-122

PeekViewManagerModal

PeekViewManagerModal 组件根据 Peek View 类型协调渲染。

来源: packages/frontend/core/src/modules/peek-view/view/peek-view-manager.tsx25-159

控制组件

该系统提供基于内容类型的专用控制组件。

来源: packages/frontend/core/src/modules/peek-view/view/peek-view-controls.tsx1-293 packages/frontend/core/src/modules/peek-view/view/peek-view-controls.css.ts1-33

Peek View 类型和解析

Peek View System 支持多种内容类型，每种类型从不同的目标解析。

来源: packages/frontend/core/src/modules/peek-view/entities/peek-view.ts127-225

Image Preview System

Image preview functionality provides a rich viewing experience with a comprehensive feature set

功能包括：

• Image navigation
• Zoom controls with mouse drag and keyboard support
• Download and copy functionality
• Support for image deletion when permitted

来源: packages/frontend/core/src/modules/peek-view/view/image-preview/index.tsx1-511 packages/frontend/core/src/modules/peek-view/view/image-preview/index.css.ts1-135

Attachment Preview

Attachment Preview system handles different file types with specialized viewers

Special handling exists for PDF files, including

• Page navigation
• Thumbnail view
• Zoom controls
• Embedded view option

来源: tests/affine-local/e2e/attachment-preview.spec.ts1-346 blocksuite/affine/blocks/attachment/src/embed.ts1-238 blocksuite/affine/blocks/attachment/src/attachment-block.ts1-225

Animation System Implementation

Peek View System uses Web Animations API (WAAPI) for smooth transitions.

来源: packages/frontend/core/src/modules/peek-view/view/modal-container.tsx100-345

与其他系统集成

Peek View System 与多个其他 AFFiNE 系统集成。

具体的集成包括：

• 使用 useInsidePeekView() hook 来检测组件是否位于 Peek View 中。
• 对共享/只读模式的特殊处理，这些模式会禁用某些交互。
• 与 Workbench 系统集成，用于在 Peek View 和完整文档视图之间进行导航。

来源: packages/frontend/core/src/blocksuite/block-suite-editor/lit-adaper.tsx22-149 packages/frontend/core/src/modules/peek-view/view/modal-container.tsx43-52

Opening and Closing Flow

The process of opening and closing a peek view follows a specific flow.

来源: packages/frontend/core/src/modules/peek-view/entities/peek-view.ts250-309 packages/frontend/core/src/modules/peek-view/view/modal-container.tsx70-369

可扩展性

The Peek View System is designed for extensibility through custom templates and renderers.

• CustomTemplatePeekViewInfo allows rendering custom Lit templates.
• toReactNode utility converts Lit templates to React nodes.
• Specialized controls can be added for new content types.

来源: packages/frontend/component/src/lit-react/to-react-node.ts1-37 packages/frontend/core/src/modules/peek-view/view/peek-view-manager.tsx25-60

Special Cases and Considerations

Shared Mode Handling

In shared mode, certain interactions are disabled.

• PDF embed previews are disabled in shared/readonly modes.
• Peek views for editing content like LaTeX are disabled.
• Copy functionality is still enabled to allow content sharing.

来源：tests/affine-cloud/e2e/share-page.spec.ts461-516 packages/frontend/core/src/blocksuite/block-suite-editor/lit-adaper.tsx158-160

移动端考虑

该系统为移动设备适配了其 UI

• 基于屏幕尺寸的不同布局规则
• 移动模式下控件的特殊样式
• 触控优化交互

来源：packages/frontend/core/src/modules/peek-view/view/modal-container.css.ts33-45 packages/frontend/core/src/modules/peek-view/view/peek-view-controls.css.ts9-31

结论

Peek View 系统为在 AFFiNE 中预览各种类型的内容提供了一个灵活、可扩展的框架。其结构良好的架构在状态管理、渲染逻辑和特定内容功能之间分离了关注点，从而易于维护并扩展新的预览类型。

来源：packages/frontend/core/src/modules/peek-view/entities/peek-view.ts packages/frontend/core/src/modules/peek-view/view/modal-container.tsx packages/frontend/core/src/modules/peek-view/view/peek-view-manager.tsx packages/frontend/core/src/modules/peek-view/view/peek-view-controls.tsx