mirror of
https://github.com/toeverything/AFFiNE.git
synced 2026-07-26 14:58:55 +08:00
feat(docs): migrate bs docs
This commit is contained in:
DarkSky
@@ -0,0 +1,119 @@
|
||||
# Edgeless Data Structure
|
||||
|
||||
## Fundamentals
|
||||
|
||||
In BlockSuite, documents in edgeless mode are isomorphic to those in page mode. Edgeless documents are also composed of blocks, with no data conversion occurring during mode switching.
|
||||
|
||||
By default, the root block of a rich text document contains a single note block child, with a block tree structure like this:
|
||||
|
||||
```
|
||||
Root Block
|
||||
Note Block
|
||||
Paragraph Block 1
|
||||
Paragraph Block 2
|
||||
Paragraph Block 3
|
||||
```
|
||||
|
||||
In the edgeless editor, you can easily split the document into multiple note cards, which can be positioned separately on the edgeless canvas, resulting in this block tree structure:
|
||||
|
||||
```
|
||||
Root Block
|
||||
Note Block
|
||||
Paragraph Block 1
|
||||
Note Block
|
||||
Paragraph Block 2
|
||||
Paragraph Block 3
|
||||
```
|
||||
|
||||
## Surface Block and Surface Element
|
||||
|
||||
Edgeless mode introduces additional editable content such as brushes, connectors, and geometric shapes. To accommodate this, the edgeless editor implements a **surface block** as a container for whiteboard graphical content. Documents compatible with both edgeless and page modes have a default surface block as the first child of the root block:
|
||||
|
||||
```
|
||||
Root Block
|
||||
Surface Block
|
||||
Note Block
|
||||
Paragraph Block 1
|
||||
Note Block
|
||||
Paragraph Block 2
|
||||
Paragraph Block 3
|
||||
```
|
||||
|
||||
The surface block can store two types of content:
|
||||
|
||||
- The `block.children` field can contain edgeless-specific card blocks, such as embed-style links to YouTube, Figma, or other BlockSuite documents.
|
||||
- Graphical content like brushstrokes and polygons are modeled as `SurfaceElement`s and stored in the `block.elements` field. Common element types include `BrushElement`, `ShapeElement`, and `ConnectorElement`.
|
||||
|
||||
A typical edgeless document structure with a surface block might look like this:
|
||||
|
||||
```
|
||||
Root Block
|
||||
Surface Block
|
||||
Embed Block
|
||||
Shape Element
|
||||
Brush Element
|
||||
Note Block
|
||||
Paragraph Block 1
|
||||
Note Block
|
||||
Paragraph Block 2
|
||||
Paragraph Block 3
|
||||
```
|
||||
|
||||
## Surface Block as Parent Block
|
||||
|
||||
With the introduction of the surface block, blocks can have two potential storage locations:
|
||||
|
||||
- Blocks used exclusively in the edgeless editor without nesting can be stored as direct children of the surface block.
|
||||
- Other blocks are stored outside the surface block, as in rich text mode. These blocks can be reused between rich text and edgeless editor modes and allow complex nesting structures.
|
||||
|
||||
BlockSuite allows specific block types to appear in both locations. For example:
|
||||
|
||||
```
|
||||
Root Block
|
||||
Surface Block
|
||||
Image Block 1
|
||||
Note Block
|
||||
Image Block 2
|
||||
Image Block 3
|
||||
```
|
||||
|
||||
In the example above, the image blocks appear under both the note block and the surface block. The edgeless editor can display all three image blocks simultaneously. The key difference is that the image with the surface block as its parent can be placed anywhere on the whiteboard, while the images within the note block must be arranged from top to bottom according to the note's internal layout.
|
||||
|
||||
## Block and Element Hierarchy
|
||||
|
||||
Although the block tree shows node adjacency, this relationship doesn't determine the content hierarchy in the whiteboard, which needs to render both blocks and surface elements.
|
||||
|
||||
Instead, BlockSuite allows specific block types to determine hierarchy order along with surface elements, including:
|
||||
|
||||
- Note blocks
|
||||
- All children of the surface block
|
||||
|
||||
Blocks with adjustable hierarchy dynamically receive an `index` field. Since all surface elements also have this field, comparing the `index` values of these indexable blocks and elements uniquely determines the edgeless content hierarchy.
|
||||
|
||||
In this example:
|
||||
|
||||
```
|
||||
Root Block
|
||||
Surface Block
|
||||
Brush Element
|
||||
Image Block 1
|
||||
Note Block
|
||||
Paragraph Block 1
|
||||
Paragraph Block 2
|
||||
Image Block 2
|
||||
```
|
||||
|
||||
The note block and image block 1 have `index` fields and can adjust their hierarchy order along with the brush element. The paragraph blocks and image block 2 within the note block are rendered as children of the note block and don't intersect with surface elements hierarchically.
|
||||
|
||||
All indexable blocks and surface elements have an `xywh` field, determining their absolute position on the edgeless canvas.
|
||||
|
||||
> This hierarchy determination technique is called fractional indexing, [also used by Figma](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/).
|
||||
|
||||
## Frames and Groups
|
||||
|
||||
There are two ways to associate blocks and/or elements in the edgeless editor: **frames** and **groups**.
|
||||
|
||||
- Frame blocks are surface-only blocks with specific `xywh` dimensions. Dragging a frame moves all blocks and elements within its `xywh` area, establishing a dynamic association based on geometric region. Multiple frames can overlap positionally but cannot nest in the block tree.
|
||||
- Group elements are special surface elements without inherent dimensions, determined by their children. Groups store the IDs of all child nodes. All indexable blocks and elements can be group children, and groups can nest multiple levels.
|
||||
|
||||
Developers can extend these association mechanisms to create more dynamic nesting relationships, implementing element types like `MindmapElement` with more dynamic linking effects.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Edgeless Editor
|
||||
|
||||
This editor component offers a canvas with infinite logical dimensions, suitable for whiteboard and graphic editing.
|
||||
|
||||
<iframe src="https://try-blocksuite.vercel.app/?init&mode=edgeless" frameborder="no" width="100%" height="500"></iframe>
|
||||
|
||||
## Features
|
||||
|
||||
- All the rich text editing capabilities in the [page editor](./page-editor).
|
||||
- `CanvasElement` rendered to HTML5 canvas, including shapes, brushes, connectors, and text.
|
||||
- Use of [frames](../blocks/frame-block) to denote canvas areas of any size.
|
||||
- Presentation mode achieved by switching between multiple frames in sequence.
|
||||
- Nestable group elements.
|
||||
- Various [link cards](../blocks/link-blocks) that can be inserted on top of the canvas.
|
||||
- Customizable toolbars and other widgets.
|
||||
|
||||
Moreover, this editor inherits capabilities built into the BlockSuite framework, including:
|
||||
|
||||
- Per-user undo/redo stack
|
||||
- Real-time collaboration
|
||||
- [Document streaming](../../guide/data-synchronization#document-streaming)
|
||||
|
||||
Notably, the BlockSuite framework allows runtime compatibility between the page editor and the edgeless editor, beyond mere static file format compatibility. This means you can dynamically attach the same doc object to different instances of the page editor and edgeless editor.
|
||||
|
||||
## Usage
|
||||
|
||||
```ts
|
||||
import { EdgelessEditor } from '@blocksuite/presets';
|
||||
|
||||
const editor = new EdgelessEditor();
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
Like all BlockSuite editors, the editor UI is entirely composed of the combination of [block specs](../../guide/block-spec). A specialized [root block](../blocks/root-block) spec serves as the root node of the document and implements all top-level document UI, with main widgets also mounted on the root block. Accordingly, commonly used editing APIs are provided in the root service.
|
||||
|
||||
Specifically, the canvas element and some blocks that appear on the top layer of the canvas are located on the [surface block](../blocks/surface-block). Therefore, operating the edgeless editor also requires accessing the model and service mounted on this block.
|
||||
|
||||
To integrate and customize this editor, you can:
|
||||
|
||||
- [Customize new block specs](../../guide/working-with-block-tree#defining-new-blocks)
|
||||
- 🚧 Configure widgets and customize new widgets
|
||||
- 🚧 Use UI components from any framework
|
||||
|
||||
🚧 We are planning support for more frameworks.
|
||||
|
||||
## Reference
|
||||
|
||||
- [`EdgelessEditor`](/api/@blocksuite/presets/classes/EdgelessEditor.html)
|
||||
- [`EdgelessRootService`](/api/@blocksuite/blocks/classes/EdgelessRootService.html)
|
||||
- [`SurfaceBlockModel`](/api/@blocksuite/blocks/classes/SurfaceBlockModel.html)
|
||||
- [`SurfaceBlockService`](/api/@blocksuite/blocks/classes/SurfaceBlockService.html)
|
||||
|
||||
Since `EdgelessEditor` is a native web component, all DOM-related properties are inherited.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Doc Editor
|
||||
|
||||
This editor component is designed for conventional flow content editing, offering functionalities aligned with rich text editors based on the frameworks like ProseMirror or Slate.
|
||||
|
||||
<iframe src="https://try-blocksuite.vercel.app/?init" frameborder="no" width="100%" height="500"></iframe>
|
||||
|
||||
## Features
|
||||
|
||||
- [Text](../blocks/paragraph-block), [lists](../blocks/list-block), and [code](../blocks/code-block) blocks, along with customizable inline elements.
|
||||
- [Images](../blocks/image-block), [attachments](../blocks/attachment-block), and customizable [embed](../blocks/embed-blocks) blocks.
|
||||
- [Database](../blocks/database-block) block that provides tables with kanban view support.
|
||||
- Bidirectional [links](../blocks/link-blocks) between documents and transclusion similar to Notion synced blocks.
|
||||
- Two types of selections, including native text selection and block-level selection.
|
||||
- Cross-block dragging and multiple widget toolbars.
|
||||
|
||||
Moreover, this editor inherits capabilities built into the BlockSuite framework, including:
|
||||
|
||||
- Per-user undo/redo stack
|
||||
- Real-time collaboration
|
||||
- [Document streaming](../../guide/data-synchronization#document-streaming)
|
||||
|
||||
Notably, the BlockSuite framework allows runtime compatibility between the page editor and the edgeless editor, beyond mere static file format compatibility. This means you can dynamically attach the same doc object to different instances of the page editor and edgeless editor.
|
||||
|
||||
## Usage
|
||||
|
||||
```ts
|
||||
import { PageEditor } from '@blocksuite/presets';
|
||||
|
||||
const editor = new PageEditor();
|
||||
```
|
||||
|
||||
Assigning a [`doc`](../../guide/working-with-block-tree#block-tree-basics) object to `editor.doc` will attach a block tree to the editor, and [`editor.host`](../../guide/working-with-block-tree#block-tree-in-editor) contains the API surface for editing. The [quick start](../../guide/quick-start) guide also serves as an online playground.
|
||||
|
||||
## Integration
|
||||
|
||||
Like all BlockSuite editors, the editor UI is entirely composed of the combination of [block specs](../../guide/block-spec). A specialized [root block](../blocks/root-block) spec serves as the root node of the document and implements all top-level document UI, with main widgets also mounted on the Accordingly, commonly used editing APIs are provided in the page service.
|
||||
|
||||
To integrate and customize this editor, you can:
|
||||
|
||||
- [Customize new block specs](../../guide/working-with-block-tree#defining-new-blocks)
|
||||
- 🚧 Configure widgets and customize new widgets
|
||||
- 🚧 Use UI components from any framework
|
||||
|
||||
🚧 We are planning support for more frameworks.
|
||||
|
||||
## Reference
|
||||
|
||||
- [`PageEditor`](/api/@blocksuite/presets/classes/PageEditor.html)
|
||||
- [`PageRootService`](/api/@blocksuite/blocks/classes/PageRootService.html)
|
||||
|
||||
Since `PageEditor` is a native web component, all DOM-related properties are inherited.
|
||||
Reference in New Issue
Block a user