DOCSEARCHbyAlgolia
Submit Docs

Canvas Editor Documentation

repository·main·Indexed 26 days ago

https://github.com/hufe921/canvas-editor

A feature-rich, WYSIWYG rich text editor built on the HTML <canvas> API, designed for pixel-perfect rendering and complex document layouts such as EMRs, legal contracts, and reports. It provides comprehensive commands for text formatting, table management, image and hyperlink insertion, and document utilities like watermarking and page breaks.

Tokens
48.2K
Snippets
135
Records
284
Agent score
88%

What's inside @hufe921/canvas-editor

  1. Overview of Canvas Editor features

    main

    Canvas Editor is a WYSIWYG rich text editor that implements its own cursor and typography logic. Key features include:

    • Rich Text Operations: Undo/redo, font styling (size, color, bold, italic, etc.), alignment, line height, and spacing.
    • Element Insertion: Tables, images, hyperlinks, LaTeX formulas, dividers, and content blocks.
    • Advanced Table Support: Row/column manipulation, cell merging/splitting, and cross-page pagination.
    • Controls & Forms: Text, number, dropdown, radio, checkbox, and date controls with support for cascading expressions (logic-based visibility/editability).
    • Document Management: Page modes (paginated or continuous), headers, footers, page numbers, and automatic Table of Contents (TOC).
    • Collaboration & Review: Track changes (insertions/deletions) and text annotations.
    • Macros: Record and playback command sequences.
    • Output: Print support via canvas-to-image or PDF drawing.
    • Customization: Built-in right-click menus, keyboard shortcuts, and i18n (Chinese/English) support.

    Note: The official npm package provides only the editor core. UI components like the menu bar or external toolbars must be implemented by the user or extended via plugins.

  2. Overview of Canvas Editor

    main
    Canvas Editor is a Canvas/SVG-based rich text editor designed for a Word-like experience. It features a WYSIWYG (What You See Is What You Get) interface with pagination, uses a lightweight JSON-based data structure for complex styling, and supports common rich text operations including tables, watermarks, controls, and formulas. The core package is available via npm, allowing developers to maintain their own menu bars and toolbars. It provides a flexible development mechanism through lifecycle hooks, event callbacks, custom right-click menus, and keyboard shortcuts, all with complete TypeScript type support.

  4. Understand Macro types in Canvas Editor

    main

    Canvas Editor supports two types of macros:

    1. Recorded macro (RECORDED): Created using startRecording and stopRecording. It captures every command.execute* call as a step and can be serialized to JSON for persistence.
    2. Script macro (SCRIPT): Created via register. These are JavaScript functions that can execute arbitrary logic, including loops, conditions, asynchronous operations, and data reading.

    Note: Non-serializable arguments (like DOM nodes or functions) are silently dropped during recording.

  5. Features of Canvas Editor DevTools

    main

    The Canvas Editor DevTools extension provides three main debugging capabilities:

    Element Tree Inspector

    • View the real-time document structure of the Canvas Editor.
    • Supports partitioned views for the main content area, header, and footer.
    • Click elements to view detailed style and property information.
    • Quickly locate specific elements within the document.

    Event Monitor

    • Monitor real-time events including:
      • Content change events
      • Selection style change events
      • Page events
      • Control events
      • Image events
      • Mouse events
    • Filter events by category and view logs with automatic scrolling.

    Configuration Panel

    • View current editor configurations.
    • Modify settings for appearance, watermarks, and page numbers.
    • Adjust styles for tables and controls.
    • Configure cursor-related options.

  6. Execute commands in Canvas Editor

    main

    To execute commands, access the command property on your editor instance. The general pattern is instance.command.commandName(payload).

    Handling External UI Components If you are building a custom toolbar outside of the editor container (e.g., a React/Vue component), commands might cause the cursor to move out of the document. To prevent this, assign the EDITOR_COMPONENT identifier to your external component so the editor recognizes it as internal.

    Example for Vue/React-like environments:

    import { EDITOR_COMPONENT, EditorComponent } from '@hufe921/canvas-editor'

// Assign EDITOR_COMPONENT to the external menu container
<div class="menu" :[EDITOR_COMPONENT]="EditorComponent.MENU">
  <button class="bold"></button>
</div>
    import Editor from "@hufe921/canvas-editor"

const instance = new Editor(container, <IElement[]>data, options)
instance.command.commandName()

  7. Configure Cascade Expressions for Control Logic

    main

    Cascade expressions allow you to automatically control the visibility, requirement, editability, or deletability of other controls or titles based on changes to a trigger control's value. Rules are configured on the control.cascade property of the triggering control.

    Data Structure

    An IControlCascadeRule consists of an expression (DSL string) and actions. If the expression evaluates to true, the actions are applied. If it evaluates to false, the engine either applies elseActions or reverts the target to its original baseline state.

    Cascade Action Effects

    When defining an ICascadeAction, you can target specific controls via controlId or groups of controls/titles via conceptId. Use targetType ('control' | 'title') to disambiguate if necessary.

    Supported effects:

    • hide: Controls visibility (applies to both controls and titles).
    • required: Makes a control mandatory (controls only).
    • disabled: Makes a control read-only (controls only).
    • deletable: Controls if a control can be deleted (controls only).

  8. Configure Cascade Expressions for control visibility and state

    main

    Cascade expressions allow a trigger control to automatically manage the visibility, required state, editability, and deletability of other controls or titles based on its own value.

    Rules are defined in the control.cascade property. When the expression evaluates to true, the actions are applied. If the expression evaluates to false, the engine either restores the target's original baseline state (if elseActions is omitted) or applies the elseActions provided.

    Data Structure

    An IControlCascadeRule consists of:

    • expression: A DSL string (e.g., getValue(@self) == '1').
    • actions: An array of ICascadeAction to apply when true.
    • elseActions (optional): An array of ICascadeAction to apply when false.

    An ICascadeAction defines the target and the effects:

    • controlId: A unique target control ID.
    • conceptId: A batch target (matches all controls or titles with this conceptId).
    • targetType: 'control' | 'title' (defaults to auto-detection: control first, then title).
    • effects: An object containing:
      • hide: Boolean for visibility (hides control/title and subsequent titles if targeting a title).
      • required: Boolean for the control's required state.
      • disabled: Boolean for editability.
      • deletable: Boolean for deletability.
    interface IControlCascadeRule {
  expression: string
  actions: ICascadeAction[]
  elseActions?: ICascadeAction[]
}

interface ICascadeAction {
  controlId?: string
  conceptId?: string
  targetType?: 'control' | 'title'
  effects: {
    hide?: boolean
    required?: boolean
    disabled?: boolean
    deletable?: boolean
  }
}

  10. Execute commands via the Editor instance

    main

    To execute commands in the Canvas Editor, access the command property on your editor instance.

    import Editor from "@hufe921/canvas-editor"

const instance = new Editor(container, <IElement[]>data, options)
instance.command.commandName()
    import Editor from "@hufe921/canvas-editor"

const instance = new Editor(container, <IElement[]>data, options)
instance.command.commandName()

  11. Quick Start with Canvas Editor

    main

    To use Canvas Editor, create a container element in your HTML and initialize the Editor class by passing the container and an options object. The main option accepts an array of objects containing the initial document content.

    <div class="canvas-editor"></div>
    import Editor from '@hufe921/canvas-editor'

const container = document.querySelector('.canvas-editor')

const editor = new Editor(container, {
  main: [
    {
      value: 'Hello, Canvas Editor!'
    }
  ]
})

  12. Use internal editor keyboard shortcuts

    main

    The Canvas Editor supports a variety of internal keyboard shortcuts for text manipulation, formatting, navigation, and selection. These shortcuts allow for efficient editing within the canvas environment.

    Text Editing & Deletion

    • Backspace: Delete backward
    • Delete: Delete forward
    • Enter: New line
    • Shift + Enter: New line within a list
    • Ctrl/Cmd + Z: Undo
    • Ctrl/Cmd + Y: Redo
    • Ctrl/Cmd + C: Copy
    • Ctrl/Cmd + X: Cut
    • Ctrl/Cmd + A: Select all
    • Ctrl/Cmd + S: Save

    Navigation & Selection

    • ←: Move left
    • Shift + ←: Expand selection left
    • Ctrl/Cmd + ←: Move left by word
    • Ctrl/Cmd + Shift + ←: Expand selection left by word
    • →: Move right
    • Shift + →: Expand selection right
    • Ctrl/Cmd + →: Move right by word
    • Ctrl/Cmd + Shift + →: Expand selection right by word
    • ↑: Move up
    • Shift + ↑: Expand selection up
    • ↓: Move down
    • Shift + ↓: Expand selection down
    • Tab: Increase indentation or move to the next control
    • Shift + Tab: Move to the previous control
    • Esc: Exit format painter

    Text Formatting

    • Ctrl/Cmd + B: Bold
    • Ctrl/Cmd + I: Italic
    • Ctrl/Cmd + U: Underline
    • Ctrl + Shift + X: Strikethrough
    • Ctrl/Cmd + {: Increase font size
    • Ctrl/Cmd + }: Decrease font size
    • Ctrl/Cmd + Shift + >: Superscript
    • Ctrl/Cmd + Shift + <: Subscript

    Alignment & Lists

    • Ctrl/Cmd + L: Align left
    • Ctrl/Cmd + E: Align center
    • Ctrl/Cmd + R: Align right
    • Ctrl/Cmd + J: Justify
    • Ctrl/Cmd + Shift + J: Distributed alignment
    • Ctrl/Cmd + Shift + I: Unordered list
    • Ctrl/Cmd + Shift + U: Ordered list

    Heading Styles

    • Ctrl + Alt/Option + 0: Normal text
    • Ctrl + Alt/Option + 1: Heading 1
    • Ctrl + Alt/Option + 2: Heading 2
    • Ctrl + Alt/Option + 3: Heading 3
    • Ctrl + Alt/Option + 4: Heading 4
    • Ctrl + Alt/Option + 5: Heading 5
    • Ctrl + Alt/Option + 6: Heading 6