Plait

https://github.com/worktile/plait
Admin
Plait is a modern drawing framework with a plugin mechanism for building all-in-one interactive...
Tokens:7,346
Snippets:106
Trust Score:9.3
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install and Build Plait Project

Source: https://github.com/worktile/plait/blob/develop/README.md

Standard npm commands to install dependencies, build the project, and start the development server.

```bash
npm i

npm run build

npm run start
```

--------------------------------

### Toolbar Component Implementation

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/island.html

Example of implementing a custom toolbar component by extending PlaitIslandBaseComponent and providing it to the Angular dependency injection system.

```typescript
    @Component({
        selector: 'app-toolbar',
        templateUrl: './toolbar.component.html',
        changeDetection: ChangeDetectionStrategy.OnPush,
        providers: [{ provide: PlaitIslandBaseComponent, useExisting: forwardRef(() => AppToolbarBaseComponent) }]
    })
    export class AppToolbarBaseComponent extends PlaitIslandBaseComponent {
        constructor(protected cdr: ChangeDetectorRef) {
            super(cdr);
        }
    }
```

--------------------------------

### PlaitBoardComponent Theme Binding

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Example of binding theme and options to the plait-board component.

```html
<plait-board
        [plaitTheme]="theme"
        [plaitOptions]="options"
        >

```

--------------------------------

### Override Plugin Configuration (withFlow)

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/plugin-options.md

Demonstrates how to override the default options for a plugin, for example, disabling multiple selections in `withFlow`. This allows for scenario-specific plugin behavior.

```typescript
export const withFlow: PlaitPlugin = (board: PlaitBoard) => {
    // ...
    (board as PlaitOptionsBoard).setPluginOptions<WithPluginOptions>(PlaitPluginKey.withSelection, { isMultipleSelection: false });
};
```

--------------------------------

### PlaitBoard Get Theme Colors

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Utility function to retrieve theme color configurations for a Plait board.

```typescript
PlaitBoard.getThemeColors<MindThemeColor>(board)
```

--------------------------------

### GeometryShapeGenerator Implementation

Source: https://github.com/worktile/plait/blob/develop/docs/guides/concepts/generator.md

An example of extending the Generator class. This concrete implementation provides the required `canDraw` and `draw` methods for specific geometry shapes.

```typescript
export class GeometryShapeGenerator extends Generator {
		//实现 candraw
    canDraw(): boolean {}
		//实现 draw 返回绘制完成的图形
    draw() {}
}
```

--------------------------------

### Get Embedded Island Components

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/island.md

The Plait board component uses ContentChildren to query for all embedded island components that inherit from PlaitIslandBaseComponent.

```typescript
@ContentChildren(PlaitIslandBaseComponent, { descendants: true }) islands?: QueryList<PlaitIslandBaseComponent>;

```

--------------------------------

### AbstractResizeState Enum for Outline Adjustment States

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/packages/mind.html

An enumeration defining the possible states during an outline resize operation: start, resizing, and end. This helps in managing and reacting to the different phases of the resize process.

```typescript
export enum AbstractResizeState {
    start = 'start',
    resizing = 'resizing',
    end = 'end'
}
```

--------------------------------

### WithOptions Plugin Implementation

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/plugin-options.md

The core implementation of the `withOptions` plugin, which adds `getPluginOptions` and `setPluginOptions` to the board. It uses a Map to store and manage plugin-specific configurations.

```typescript
export const withOptions = (board: PlaitBoard) => {
    const pluginOptions = new Map<string, any>();
    const newBoard = board as PlaitOptionsBoard;

    newBoard.getPluginOptions = key => {
        return pluginOptions.get(key);
    };

    newBoard.setPluginOptions = (key, options) => {
        const oldOptions = newBoard.getPluginOptions(key) || {};
        pluginOptions.set(key, { ...oldOptions, ...options });
    };
    
    return newBoard;
};
```

--------------------------------

### Basic Plait Board with Mind Map Plugin (HTML)

Source: https://github.com/worktile/plait/blob/develop/README.md

HTML template for integrating the Plait board component. It configures plugins and binds to value and event handlers.

```html
<plait-board [plaitPlugins]="plugins" [plaitValue]="value"
    (initialized)="initialized($event)" (change)="change($event)">
</plait-board>
```

--------------------------------

### Instantiating and Using Generator

Source: https://github.com/worktile/plait/blob/develop/docs/guides/concepts/generator.md

Demonstrates how to instantiate a concrete Generator (GeometryShapeGenerator) and call its `processDrawing` method to render graphics onto a parent SVG element.

```typescript
//实例化 generator
const generator = new GeometryShapeGenerator()
//调用绘制方法，generator 自动将绘制好的图形放到 g 中
generator.processDrawing(g)
```

--------------------------------

### Default Plugin Configuration (withSelection)

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/plugin-options.md

Defines the default options for a plugin, such as enabling multiple selections in `withSelection`. Use `setPluginOptions` to apply these defaults.

```typescript
export interface WithPluginOptions extends PlaitPluginOptions {
    isMultipleSelection: boolean;
}
export function withSelection(board: PlaitBoard) {
  	// ...
	(board as PlaitOptionsBoard).setPluginOptions<WithPluginOptions>(PlaitPluginKey.withSelection, { isMultipleSelection: true });
}
```

--------------------------------

### Basic Plait Board with Mind Map Plugin (TypeScript)

Source: https://github.com/worktile/plait/blob/develop/README.md

TypeScript component configuration for the Plait board. It sets up the mind map plugin and handles board events.

```typescript
// .ts
@Component({
  selector: 'board-basic',
  templateUrl: './board-basic.component.html',
  host: {
    class: 'board-basic-container',
  },
})
export class BasicBoardComponent {
  plugins = [withMind];

  value: PlaitElement[] = demoData;

  board!: PlaitBoard;

  change(event: OnChangeData) {
    // console.log(event.children);
  }

  initialized(value: PlaitBoard) {
    this.board = value;
  }
}
```

--------------------------------

### Handling Board Changes in Toolbar

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/island.html

Shows how to implement the OnBoardChange interface in a custom component to perform secondary data processing when the board data changes or the pointer type is updated.

```typescript
    export class AppToolbarBaseComponent extends PlaitIslandBaseComponent implements OnBoardChange {
        constructor(protected cdr: ChangeDetectorRef) {
            super(cdr);
        }
    
        onBoardChange() {
            //
        }
    }
```

--------------------------------

### Implement OnBoardChange for Data Handling

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/island.md

Implement the OnBoardChange interface in your custom component to perform secondary data processing when the board data changes.

```typescript
export class AppToolbarBaseComponent extends PlaitIslandBaseComponent implements OnBoardChange {
    constructor(protected cdr: ChangeDetectorRef) {
        super(cdr);
    }

    onBoardChange() {
        // 
    }
}
```

--------------------------------

### PlaitBoardComponent Theme Options

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Defines the options for PlaitBoardComponent, including themeColors.

```typescript
options: PlaitBoardOptions = {
             themeColors?: ThemeColor[];
        };

```

--------------------------------

### Define PlaitBoard with Theme Property

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Extends the PlaitBoard interface to include a theme property.

```typescript
export interface PlaitBoard {
      ... 
        theme: PlaitTheme;//board 主题
    }
    
    export interface PlaitTheme {
        themeColorMode: ThemeColorMode;
    }
```

--------------------------------

### Define a Custom Toolbar Component

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/island.md

Inherit from PlaitIslandBaseComponent and configure the provider to use the custom component as the PlaitIslandBaseComponent.

```typescript
@Component({
    selector: 'app-toolbar',
    templateUrl: './toolbar.component.html',
    changeDetection: ChangeDetectionStrategy.OnPush,
    providers: [{ provide: PlaitIslandBaseComponent, useExisting: forwardRef(() => AppToolbarBaseComponent) }]
})
export class AppToolbarBaseComponent extends PlaitIslandBaseComponent {
    constructor(protected cdr: ChangeDetectorRef) {
        super(cdr);
    }
}
```

--------------------------------

### Default Implementation for drawEmoji

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/packages/mind.html

Illustrates the default implementation for the drawEmoji method, which throws an error indicating that the method has not been implemented by the user.

```typescript
newBoard.drawEmoji = (emoji: EmojiItem, element: MindElement) => {
  throw new Error('Not implement drawEmoji method error.');
};
```

--------------------------------

### Plait Options Board Interface Definition

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/plugin-options.md

Defines the `PlaitOptionsBoard` interface, extending `PlaitBoard` with `getPluginOptions` and `setPluginOptions` methods for managing plugin configurations.

```typescript
export interface PlaitPluginOptions {
    disabled?: boolean;
}

export interface PlaitOptionsBoard extends PlaitBoard {
    getPluginOptions: <K = PlaitPluginOptions>(key: string) => K;
    setPluginOptions: <K = PlaitPluginOptions>(key: string, value: K) => void;
}
```

--------------------------------

### Use Custom Toolbar within Plait Board

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/island.md

Place your custom toolbar component inside the <plait-board> tags to associate it with the board.

```html
<plait-board>
    <app-toolbar></app-toolbar>
 </plait-board>
```

--------------------------------

### MindOptions Interface for Customization

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/packages/mind.html

Defines customizable options for the Mind plugin, such as emoji padding and spacing. This interface allows users to override default configurations for rendering and interaction styles.

```typescript
export interface MindOptions {
    emojiPadding: number;
    spaceBetweenEmojis: number;
}
```

--------------------------------

### ShapeEngine Interface Definition

Source: https://github.com/worktile/plait/blob/develop/docs/guides/concepts/engine.md

Defines the ShapeEngine interface, outlining methods for drawing, hit detection, point calculations, and connection logic for different shapes.

```typescript
export interface ShapeEngine {
    draw;	//绘制逻辑
    isHit; //是否击中
    getNearestPoint; // 获取最近距离
    getConnectorPoints; // 获取关联示意点
    getCornerPoints; // 获取拐角点
    getEdgeByConnectionPoint?;	// 根据关联点获取边
    getTangentVectorByConnectionPoint? ;	// 根据关联点获取切线
}
```

--------------------------------

### MindEmojiBaseComponent for Emoji Rendering

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/packages/mind.html

The base component class for rendering emojis within the Mind plugin. It handles basic initialization, including setting font size, and provides access to essential inputs like emoji item, board, and element.

```typescript
@Directive({
    host: {
        class: 'mind-node-emoji'
    }
})
export class MindEmojiBaseComponent implements OnInit {
    @Input()
    fontSize: number = 14;

    @Input()
    emojiItem!: EmojiItem;

    @Input()
    board!: PlaitBoard;

    @Input()
    element!: MindElement<EmojiData>;

    get nativeElement() {
        return this.elementRef.nativeElement;
    }

    constructor(protected elementRef: ElementRef<HTMLElement>) {}

    ngOnInit(): void {
        this.elementRef.nativeElement.style.fontSize = `${this.fontSize}px`;
    }
}
```

--------------------------------

### onAbstractResize Function Signature for Outline Adjustment

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/packages/mind.html

Defines an optional, overridable function signature for handling outline resizing events. This allows for custom business logic during the adjustment of outline drag ranges.

```typescript
export interface PlaitAbstractBoard extends PlaitBoard {
    onAbstractResize?: (state: AbstractResizeState) => void;
}
```

--------------------------------

### Iterate and Display Menus and Items

Source: https://github.com/worktile/plait/blob/develop/src/app/flow/flow.component.html

Uses Angular's @for directive to iterate over a 'menus' array and then over each menu's 'children' array to display hierarchical data. Suitable for rendering navigation or structured lists.

```html
@for (menu of menus; track $index) {

### {{ menu.name }}

@for (item of menu.children; track $index) {

{{ item.name }}

}

}
```

--------------------------------

### BoardTransforms Update Theme Color

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Static method to update the theme color of a Plait board.

```typescript
BoardTransforms.updateThemeColor(board: PlaitBoard, mode: ThemeColorMode)
```

--------------------------------

### Calculate ViewBox for Canvas

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/scrolling.md

Calculates the SVG viewBox based on board elements, zoom level, and container dimensions. Ensures all elements are visible with padding.

```typescript
export function getViewBox(board: PlaitBoard, zoom: number) {
    const viewportContainerRect = PlaitBoard.getBoardNativeElement(board).getBoundingClientRect();
    const elementHostBBox = getElementHostBBox(board, zoom);

    const horizontalPadding = viewportContainerRect.width / 2;
    const verticalPadding = viewportContainerRect.height / 2;
    const viewBox = [
        elementHostBBox.left - horizontalPadding / zoom,
        elementHostBBox.top - verticalPadding / zoom,
        elementHostBBox.right - elementHostBBox.left + (horizontalPadding * 2) / zoom,
        elementHostBBox.bottom - elementHostBBox.top + (verticalPadding * 2) / zoom
    ];
    return viewBox;
}
```

--------------------------------

### drawEmoji Function Signature for Custom Emoji Rendering

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/packages/mind.html

Provides the function signature for extending emoji functionality. Users must supply a component to render emojis, as the plugin only manages positioning and space allocation.

```typescript
drawEmoji: (emoji: EmojiItem, element: MindElement) => ComponentType<MindEmojiBaseComponent>;
```

--------------------------------

### Set SVG ViewBox and Element Dimensions

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/scrolling.md

Applies the calculated viewBox to the SVG element and sets its dimensions based on the viewBox and zoom level. Ensures the SVG element is displayed correctly.

```typescript
export function setSVGViewBox(board: PlaitBoard, viewBox: number[]) {
    const zoom = board.viewport.zoom;
    const hostElement = PlaitBoard.getHost(board);
    hostElement.style.display = 'block';
    hostElement.style.width = `${viewBox[2] * zoom}px`;
    hostElement.style.height = `${viewBox[3] * zoom}px`;

    if (viewBox && viewBox[2] > 0 && viewBox[3] > 0) {
        hostElement.setAttribute('viewBox', viewBox.join(' '));
    }
}
```

--------------------------------

### Define ThemeColorMode Enum

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Defines the available theme color modes for Plait.

```typescript
export enum ThemeColorMode {
        'default' = 'default',
        'colorful' = 'colorful',
        'soft' = 'soft',
        'retro' = 'retro',
        'dark' = 'dark',
        'starry' = 'starry'
    }
```

--------------------------------

### Update Theme Color Function

Source: https://github.com/worktile/plait/blob/develop/src/assets/content/docs/guides/solutions/theme.html

Function to update the theme color mode of a Plait board and apply it to all elements. It handles internal board processing and iterates through nodes to remove color-related properties.

```typescript
function updateThemeColor(board: PlaitBoard, mode: ThemeColorMode) {
        mode = mode ?? board.theme.themeColorMode;
        setTheme(board, { themeColorMode: mode }); //board 内部处理，添加 set_theme 的操作
    
        depthFirstRecursion((board as unknown) as PlaitElement, element => {
            board.applyTheme(element); //遍历处理节点，抹除与颜色相关的属性
        });
    }
```

--------------------------------

### Calculate Viewport Offset from Scroll Distance

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/scrolling.md

Calculates the mapping coordinates (viewport offset) based on the current scroll position and zoom level. This is the inverse of converting scroll distance to mapping coordinates.

```typescript
const zoom = this.board.viewport.zoom;
const viewBox = getViewBox(this.board, zoom);
const origination = [scrollLeft / zoom + viewBox[0], scrollTop / zoom + viewBox[1]] as Point;
```

--------------------------------

### Generator Abstract Class Definition

Source: https://github.com/worktile/plait/blob/develop/docs/guides/concepts/generator.md

Defines the abstract Generator class with methods for drawing, checking drawability, and destruction. Implementations must provide logic for `canDraw` and `draw`.

```typescript
//@plait/common
export abstract class Generator {
    g?: SVGGElement;

    constructor(protected board: PlaitBoard, options?: V) {}

  	//调用 draw 将图形添加到 g 里
    draw(element: T, parentG: SVGGElement, data?: K) {}

  	//用于判断是否可以绘制
    abstract canDraw(element: T, data?: K): boolean;

  	//绘制逻辑
    abstract draw(element: T, data?: K): SVGGElement | undefined;

    destroy() {}
}
```

--------------------------------

### Convert Mouse Event Coordinates to SVG Element Pixel Coordinates

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/scrolling.md

Converts coordinates from the browser viewport (event.x, event.y) to pixel coordinates relative to the Plait SVG container. This is useful when the SVG element does not fill the entire screen.

```typescript
export function toPoint(x: number, y: number, container: SVGElement): Point {
    const rect = container.getBoundingClientRect();
    return [x - rect.x, y - rect.y];
}
```

--------------------------------

### Convert SVG Element Pixel Coordinates to viewBox Coordinates

Source: https://github.com/worktile/plait/blob/develop/docs/guides/solutions/scrolling.md

Transforms pixel coordinates obtained from the SVG element into coordinates within the SVG's viewBox system. This accounts for the viewBox's origin and scaling factor.

```typescript
export function transformPoint(board: PlaitBoard, point: Point) {
    const { width, height } = Plait Board.getHost(board).getBoundingClientRect();
    const viewBox = PlaitBoard.getHost(board).viewBox.baseVal;
    const x = (point[0] / width) * viewBox.width + viewBox.x;
    const y = (point[1] / height) * viewBox.height + viewBox.y;
    const newPoint = [x, y] as Point;
    return newPoint;
}
```
Tokens:
Raw