Configuration

The Canvas Editor provides extensive configuration options through the IEditorOption interface. This guide covers all available configuration options for customizing the editor’s behavior and appearance.

Basic Setup

When initializing the editor, you can pass configuration options as the third parameter:

import Editor from '@hufe921/canvas-editor'

const container = document.querySelector('#editor')
const data = {
  main: [
    { value: 'Hello Canvas Editor!' }
  ]
}

const options = {
  mode: EditorMode.EDIT,
  defaultFont: 'Microsoft YaHei',
  defaultSize: 16,
  margins: [100, 120, 100, 120]
}

const editor = new Editor(container, data, options)

Editor Modes

mode

EditorMode

default:"EditorMode.EDIT"

Controls the editor’s operational mode.Available modes from src/editor/dataset/enum/Editor.ts:17:

EDIT - Full editing mode with all features enabled
CLEAN - Hides auxiliary elements for clean view
READONLY - Document is read-only, no editing allowed
FORM - Only form controls are editable
PRINT - Print mode with hidden auxiliary elements
DESIGN - Design mode ignoring readonly/deletable rules
GRAFFITI - Graffiti mode for freehand drawing

const editor = new Editor(container, data, {
  mode: EditorMode.EDIT
})

Default Text Styling

Configure default text appearance for new content.

defaultFont

string

Default font family for text content.

defaultSize

number

Default font size in pixels.

defaultColor

string

Default text color (CSS color format).

defaultType

string

Default content type.

minSize

number

Minimum allowed font size.

maxSize

number

Maximum allowed font size.

const options = {
  defaultFont: 'Arial',
  defaultSize: 14,
  defaultColor: '#333333',
  minSize: 8,
  maxSize: 72
}

Page Layout

width

number

Page width in pixels.

height

number

Page height in pixels.

margins

IMargin

Page margins as [top, right, bottom, left] array in pixels.Type definition from src/editor/interface/Margin.ts:1:

type IMargin = [top: number, right: number, bottom: number, left: number]

pageMode

PageMode

Controls page layout mode:

PageMode.PAGING - Traditional paged layout
PageMode.CONTINUITY - Continuous scroll layout

paperDirection

PaperDirection

Paper orientation:

PaperDirection.VERTICAL - Portrait orientation
PaperDirection.HORIZONTAL - Landscape orientation

pageGap

number

Gap between pages in pixels (for paged mode).

const options = {
  width: 794,
  height: 1123,
  margins: [100, 120, 100, 120],
  pageMode: PageMode.PAGING,
  paperDirection: PaperDirection.VERTICAL,
  pageGap: 20
}

Rendering Configuration

scale

number

Display scale factor (zoom level).

renderMode

RenderMode

Rendering optimization mode:

RenderMode.SPEED - Optimized for performance
RenderMode.COMPATIBILITY - Better browser compatibility

printPixelRatio

number

Pixel ratio for print output quality.

const options = {
  scale: 1.0,
  renderMode: RenderMode.SPEED,
  printPixelRatio: 2
}

Text Behavior

wordBreak

WordBreak

Word breaking behavior:

WordBreak.BREAK_ALL - Break anywhere
WordBreak.BREAK_WORD - Break at word boundaries

defaultBasicRowMarginHeight

number

Default basic row margin height.

defaultRowMargin

number

Default row margin.

defaultTabWidth

number

Default tab character width.

const options = {
  wordBreak: WordBreak.BREAK_WORD,
  defaultBasicRowMarginHeight: 8,
  defaultRowMargin: 0,
  defaultTabWidth: 32
}

Selection and Highlighting

rangeColor

string

Selection range color.

rangeAlpha

number

Selection range opacity (0-1).

rangeMinWidth

number

Minimum width for selection range.

highlightAlpha

number

Highlight overlay opacity (0-1).

highlightMarginHeight

number

Vertical margin for highlight areas.

const options = {
  rangeColor: '#AECBFA',
  rangeAlpha: 0.6,
  rangeMinWidth: 5,
  highlightAlpha: 0.3,
  highlightMarginHeight: 2
}

Search Configuration

searchMatchColor

string

Background color for search matches.

searchNavigateMatchColor

string

Background color for the active search match.

searchMatchAlpha

number

Opacity for search match highlighting (0-1).

const options = {
  searchMatchColor: '#FFFF00',
  searchNavigateMatchColor: '#FF9900',
  searchMatchAlpha: 0.6
}

Text Decorations

underlineColor

string

Default underline color.

strikeoutColor

string

Default strikethrough color.

defaultHyperlinkColor

string

Default color for hyperlinks.

const options = {
  underlineColor: '#000000',
  strikeoutColor: '#FF0000',
  defaultHyperlinkColor: '#0000FF'
}

Resizer and Indicators

resizerColor

string

Color of element resizer handles.

resizerSize

number

Size of resizer handles in pixels.

marginIndicatorSize

number

Size of margin indicators.

marginIndicatorColor

string

Color of margin indicators.

const options = {
  resizerColor: '#4285F4',
  resizerSize: 5,
  marginIndicatorSize: 35,
  marginIndicatorColor: '#BABABA'
}

Interaction Configuration

inactiveAlpha

number

Opacity for inactive elements (0-1).

historyMaxRecordCount

number

Maximum number of undo/redo history records.

scrollContainerSelector

string

CSS selector for custom scroll container.

pageOuterSelectionDisable

boolean

Disable selection outside page boundaries.

const options = {
  inactiveAlpha: 0.6,
  historyMaxRecordCount: 100,
  scrollContainerSelector: '.editor-container',
  pageOuterSelectionDisable: false
}

Feature Restrictions

Array of context menu keys to disable.

shortcutDisableKeys

string[]

Array of keyboard shortcut keys to disable.

letterClass

string[]

Custom character classes for text processing.

const options = {
  contextMenuDisableKeys: ['copy', 'paste'],
  shortcutDisableKeys: ['Ctrl+P'],
  letterClass: ['custom-letter-class']
}

Advanced Options

maskMargin

IMargin

Margins for mask overlay as [top, right, bottom, left].

locale

string

Locale code for internationalization (e.g., ‘en’, ‘zh-CN’).

const options = {
  maskMargin: [0, 0, 0, 0],
  locale: 'en'
}

Component Options

The editor supports extensive configuration for various components:

Table Options

Configure table appearance and behavior

Header & Footer

Customize header and footer sections

Watermark

Add and configure watermarks

Page Numbers

Configure page numbering

Table Configuration

table

ITableOption

Configuration for table elements.

From src/editor/interface/table/Table.ts:3:

const options = {
  table: {
    tdPadding: [5, 10, 5, 10],
    defaultTrMinHeight: 42,
    defaultColMinWidth: 50,
    defaultBorderColor: '#000000',
    overflow: false
  }
}

header

IHeader

Header section configuration (from src/editor/interface/Header.ts:3).

footer

IFooter

Footer section configuration (similar structure to header).

const options = {
  header: {
    top: 50,
    maxHeightRadio: MaxHeightRatio.HALF,
    disabled: false,
    editable: true,
    inactiveAlpha: 0.5
  },
  footer: {
    bottom: 50,
    maxHeightRadio: MaxHeightRatio.HALF,
    disabled: false,
    editable: true,
    inactiveAlpha: 0.5
  }
}

Watermark

watermark

IWatermark

Watermark configuration (from src/editor/interface/Watermark.ts:4).

const options = {
  watermark: {
    data: 'CONFIDENTIAL',
    type: WatermarkType.TEXT,
    color: '#AEB3B7',
    opacity: 0.3,
    size: 120,
    font: 'Microsoft YaHei',
    repeat: true,
    gap: [100, 100]
  }
}

Page Numbers

pageNumber

IPageNumber

Page numbering configuration (from src/editor/interface/PageNumber.ts:4).

const options = {
  pageNumber: {
    bottom: 60,
    size: 12,
    font: 'Microsoft YaHei',
    color: '#000000',
    rowFlex: RowFlex.CENTER,
    format: '{pageNo}',
    numberType: NumberType.ARABIC,
    disabled: false,
    startPageNo: 1
  }
}

Additional Component Options

Control Options

control

IControlOption

Form control appearance and behavior.

const options = {
  control: {
    placeholderColor: '#DCDFE6',
    bracketColor: '#000000',
    prefix: '{',
    postfix: '}',
    borderWidth: 1,
    borderColor: '#000000',
    activeBackgroundColor: '#ECF5FF',
    disabledBackgroundColor: '#F5F7FA'
  }
}

Checkbox & Radio

checkbox

ICheckboxOption

Checkbox element styling.

radio

IRadioOption

Radio button element styling.

More Options

cursor: Cursor appearance configuration
title: Document title configuration
placeholder: Placeholder text configuration
group: Element grouping options
pageBreak: Page break configuration
zone: Zone-specific settings
background: Background configuration
lineBreak: Line break behavior
whiteSpace: Whitespace rendering
separator: Separator line styling
lineNumber: Line numbering configuration
pageBorder: Page border styling
badge: Badge element configuration
graffiti: Graffiti mode settings
label: Label element configuration
imgCaption: Image caption defaults
list: List element configuration

Mode Rules

modeRule

IModeRule

Special rules for different editor modes (from src/editor/interface/Editor.ts:168).

const options = {
  modeRule: {
    [EditorMode.PRINT]: {
      imagePreviewerDisabled: true,
      backgroundDisabled: false
    },
    [EditorMode.READONLY]: {
      imagePreviewerDisabled: false
    },
    [EditorMode.FORM]: {
      controlDeletableDisabled: true
    }
  }
}

Complete Configuration Example

import Editor, {
  EditorMode,
  PageMode,
  PaperDirection,
  RenderMode,
  WordBreak,
  RowFlex
} from '@hufe921/canvas-editor'

const container = document.querySelector('#editor')
const data = {
  main: [
    { value: 'Hello Canvas Editor!' }
  ]
}

const options = {
  // Editor mode
  mode: EditorMode.EDIT,
  locale: 'en',
  
  // Default styling
  defaultFont: 'Microsoft YaHei',
  defaultSize: 16,
  defaultColor: '#333333',
  minSize: 8,
  maxSize: 72,
  
  // Page layout
  width: 794,
  height: 1123,
  margins: [100, 120, 100, 120],
  pageMode: PageMode.PAGING,
  paperDirection: PaperDirection.VERTICAL,
  pageGap: 20,
  
  // Rendering
  scale: 1.0,
  renderMode: RenderMode.SPEED,
  printPixelRatio: 2,
  
  // Text behavior
  wordBreak: WordBreak.BREAK_WORD,
  defaultBasicRowMarginHeight: 8,
  defaultRowMargin: 0,
  defaultTabWidth: 32,
  
  // Selection
  rangeColor: '#AECBFA',
  rangeAlpha: 0.6,
  highlightAlpha: 0.3,
  
  // Search
  searchMatchColor: '#FFFF00',
  searchNavigateMatchColor: '#FF9900',
  searchMatchAlpha: 0.6,
  
  // Components
  header: {
    top: 50,
    disabled: false
  },
  pageNumber: {
    bottom: 60,
    size: 12,
    rowFlex: RowFlex.CENTER,
    format: '{pageNo}'
  },
  watermark: {
    data: 'DRAFT',
    opacity: 0.2,
    size: 100,
    repeat: true
  }
}

const editor = new Editor(container, data, options)

Runtime Configuration Updates

Some configuration options cannot be changed after initialization. The IUpdateOption type excludes these immutable options:

mode
width
height
scale
pageGap
pageMode
paperDirection
historyMaxRecordCount
scrollContainerSelector

To update configuration at runtime, use the appropriate command methods:

// Update specific options via commands
editor.command.executeSetLocale('zh-CN')
editor.command.executePageScale(1.5)

Next Steps

Styling Guide

Learn about styling and theming

Data Structure

Understand the document data format

API Reference

Explore all available API methods

Examples

See real-world implementation examples

Getting Started

Core Concepts

Features

Advanced

Guides

Basic Setup

Editor Modes

Default Text Styling

Page Layout

Rendering Configuration

Text Behavior

Selection and Highlighting

Search Configuration

Text Decorations

Resizer and Indicators

Interaction Configuration

Feature Restrictions

Advanced Options

Component Options

Table Options

Header & Footer

Watermark

Page Numbers

Table Configuration

Header & Footer

Watermark

Page Numbers

Additional Component Options

Mode Rules

Complete Configuration Example

Runtime Configuration Updates

Next Steps

Styling Guide

Data Structure

API Reference

Examples

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Features

Advanced

Guides

​Basic Setup

​Editor Modes

​Default Text Styling

​Page Layout

​Rendering Configuration

​Text Behavior

​Selection and Highlighting

​Search Configuration

​Text Decorations

​Resizer and Indicators

​Interaction Configuration

​Feature Restrictions

​Advanced Options

​Component Options

Table Options

Header & Footer

Watermark

Page Numbers

​Table Configuration

​Header & Footer

​Watermark

​Page Numbers

​Additional Component Options

​Mode Rules

​Complete Configuration Example

​Runtime Configuration Updates

​Next Steps

Styling Guide

Data Structure

API Reference

Examples

Build docs developers (and LLMs) love

Basic Setup

Editor Modes

Default Text Styling

Page Layout

Rendering Configuration

Text Behavior

Selection and Highlighting

Search Configuration

Text Decorations

Resizer and Indicators

Interaction Configuration

Feature Restrictions

Advanced Options

Component Options

Table Configuration

Header & Footer

Watermark

Page Numbers

Additional Component Options

Mode Rules

Complete Configuration Example

Runtime Configuration Updates

Next Steps