The IElement interface represents a single content element in the document. Elements can be text, images, tables, controls, and more.
Interface Definition
src/editor/interface/Element.ts
type IElement = IElementBasic &
IElementStyle &
IElementRule &
IElementGroup &
ITable &
IHyperlinkElement &
ISuperscriptSubscript &
ISeparator &
IControlElement &
ICheckboxElement &
IRadioElement &
ILaTexElement &
IDateElement &
IImageElement &
IBlockElement &
ITitleElement &
IListElement &
IAreaElement &
ILabelElement
Basic Properties
IElementBasic
The text content or value of the element. Empty string for non-text elements.
Unique identifier for the element
Element type (TEXT, IMAGE, TABLE, CONTROL, etc.). Defaults to TEXT if not specified.
Custom extension data for storing arbitrary information
External system identifier
Style Properties
IElementStyle
Element width (for images, controls, etc.)
Element height (for images, controls, etc.)
Text color (hex format, e.g., ‘#FF0000’)
Background highlight color
Row alignment (LEFT, CENTER, RIGHT, JUSTIFY, ALIGNMENT)
Advanced text decoration styling
Element Type Properties
Image Elements
How image is displayed: INLINE, BLOCK, FLOAT_TOP, FLOAT_BOTTOM
imgFloatPosition
{ x: number, y: number, pageNo?: number }
Position for floating images
Crop coordinates (normalized 0-1)
Image caption configuration
Table Elements
Table cell ID (when inside a table)
Table row ID (when inside a table)
Table ID (when inside a table)
Title/Heading Elements
Heading level (FIRST = H1, SECOND = H2, etc.)
Child elements for title/hyperlink/list
List Elements
List type: UL (unordered) or OL (ordered)
List marker style (DISC, CIRCLE, DECIMAL, etc.)
Hyperlink Elements
Hyperlink group identifier
Control Elements
Form control configuration
Control component type (PREFIX, POSTFIX, VALUE, etc.)
Other Element Types
Standalone checkbox configuration
Standalone radio button configuration
Block element configuration
Rules & Grouping
Whether element is hidden
Group identifiers for grouped elements
Element Examples
Simple Text
const textElement: IElement = {
value: 'Hello World'
}
Formatted Text
const boldText: IElement = {
value: 'Important',
bold: true,
color: '#FF0000',
size: 18
}
Image
const image: IElement = {
type: ElementType.IMAGE,
value: 'data:image/png;base64,...',
width: 300,
height: 200,
imgDisplay: ImageDisplay.BLOCK
}
Heading
const heading: IElement = {
value: 'Chapter 1',
level: TitleLevel.FIRST,
titleId: 'title-1'
}
Hyperlink
const link: IElement = {
type: ElementType.HYPERLINK,
value: '',
url: 'https://example.com',
valueList: [
{ value: 'Click here' }
]
}
List Item
const listItem: IElement = {
value: 'First item',
listType: ListType.UL,
listStyle: ListStyle.DISC,
listId: 'list-1'
}
Table
const table: IElement = {
type: ElementType.TABLE,
value: '',
colgroup: [
{ width: 100 },
{ width: 200 }
],
trList: [
{
tdList: [
{ valueList: [{ value: 'Cell 1' }] },
{ valueList: [{ value: 'Cell 2' }] }
]
}
]
}
Usage in Commands
Inserting Elements
const elements: IElement[] = [
{ value: 'Normal text ' },
{ value: 'bold text', bold: true },
{ value: ' and ' },
{ value: 'italic', italic: true }
]
editor.command.executeInsertElementList(elements)
Getting Elements
const data = editor.command.getValue()
// data.main is IElement[]
data.main.forEach(element => {
if (element.type === ElementType.IMAGE) {
console.log('Found image:', element.width, element.height)
}
})
Updating Elements
editor.command.executeUpdateElementById({
id: 'element-123',
properties: {
bold: true,
color: '#0000FF',
size: 20
}
})
Helper Functions
Canvas Editor exports utility functions for working with elements:
splitText
Splits text into individual character elements:
import { splitText } from '@hufe921/canvas-editor'
const elements = splitText('Hello')
// Returns: [
// { value: 'H' },
// { value: 'e' },
// { value: 'l' },
// { value: 'l' },
// { value: 'o' }
// ]
getElementListByHTML
Converts HTML to element list:
import { getElementListByHTML } from '@hufe921/canvas-editor'
const html = '<p>Hello <b>World</b></p>'
const elements = getElementListByHTML(html)
getTextFromElementList
Extracts plain text from elements:
import { getTextFromElementList } from '@hufe921/canvas-editor'
const elements: IElement[] = [
{ value: 'Hello ' },
{ value: 'World', bold: true }
]
const text = getTextFromElementList(elements)
// Returns: 'Hello World'
TypeScript Usage
import { IElement, ElementType } from '@hufe921/canvas-editor'
function processElement(element: IElement) {
if (element.type === ElementType.IMAGE) {
// TypeScript knows element has image properties
console.log(element.width, element.height)
}
if (element.bold) {
console.log('Bold text:', element.value)
}
}