ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

canvas-editor 数据结构完全指南:深入解析 IElement 文档模型

canvas-editor 数据结构完全指南:深入解析 IElement 文档模型 前端UI组件富文本【免费下载链接】canvas-editorA Canvas/SVG-based rich text editor项目地址https://gitcode.com/gh_mirrors/ca/canvas-editor点击查看免费下载导读canvas-editor 是一个基于 Canvas/SVG 渲染的富文本编辑器其所有内容——从一段普通文字到表格、图片、控件、公式——最终都被抽象为统一的IElement数据结构。本文以官方文档 docs/guide/schema.md 为骨架结合 Element.ts 等源码逐字段讲解这套文档模型读完你将领会如何构造、读取和扩展元素数据并能在二次开发时准确找到各字段的底层实现。一、为什么需要统一的 IElement 模型Canvas 渲染与 DOM 不同编辑器无法依赖浏览器排版必须自行维护一份可序列化、可重绘的文档数据。IElement就是这份数据的原子单元一行文字、一张图片、一个表格、一个控件在数据层都是一个元素。真正渲染时由 Draw.ts 及其下的粒子系统TextParticle、ImageParticle、TableParticle等把它们画到 Canvas 上。从源码看IElement并非一个手写的大对象而是通过 TypeScript 交叉类型组合而成Element.tsexport type IElement IElementBasic IElementStyle IElementRule IElementGroup IElementTrace ITable IHyperlinkElement ISuperscriptSubscript ISeparator IControlElement ICheckboxElement IRadioElement ILaTexElement IDateElement IImageElement IBlockElement ITitleElement IListElement IAreaElement ILabelElement IPageBreakElement这种组合式接口设计意味着文档里可选的字段源码中分属不同语义模块理解这一点有助于按模块记忆字段。二、基础字段每个元素的通用身份interface IElement { id?: string; type?: { TEXT text, IMAGE image, TABLE table, HYPERLINK hyperlink, SUPERSCRIPT superscript, SUBSCRIPT subscript, SEPARATOR separator, PAGE_BREAK pageBreak, CONTROL control, CHECKBOX checkbox, RADIO radio, LATEX latex, TAB tab, DATE date, BLOCK block }; value: string; valueList?: IElement[]; // 复合元素超链接、标题、列表等使用 extension?: unknown; externalId?: string; hide?: boolean; hint?: string; // 悬浮提示文案需在配置中开启 hint 总开关 }各字段要点id元素唯一标识编辑器的查找、更新、删除 API如updateElementById、deleteElementById均依赖它定位元素。type元素类型枚举。注意文档中的枚举只是示意源码 ElementType 实际还包含AREA area、TITLE title、LIST list、LABEL label四个类型它们由valueList组合而成属于复合元素。此外value字段对任何元素都是必填的接口中为value: string非可选。valueList复合元素的核心。超链接、标题、列表、区域这些容器型元素并不直接持有正文而是通过valueList递归嵌套一组IElement。extension任意类型的扩展字段用于携带业务自定义数据externalId则是接入方系统如 CRM、ERP中的外部主键便于与业务数据对齐。hide控制元素是否渲染hint悬浮提示文案需要先在编辑器配置中开启 hint 总开关才生效。三、样式字段行内排版属性font?: string; // 字体 size?: number; // 字号 width?: number; // 宽 height?: number; // 高 bold?: boolean; // 加粗 color?: string; // 文字颜色 highlight?: string; // 高亮背景 italic?: boolean; // 斜体 underline?: boolean; // 下划线 strikeout?: boolean; // 删除线 rowFlex?: { LEFT left, CENTER center, RIGHT right, ALIGNMENT alignment, JUSTIFY justify }; rowMargin?: number; // 行间距 letterSpacing?: number; // 字间距 textDecoration?: { style?: TextDecorationStyle };rowFlex控制该元素在整行中的对齐方式源码枚举 RowFlex 与之完全一致left左对齐、center居中、right右对齐、alignment两端对齐、justify分散对齐。它是行级而非页级的对齐与段落的textAlign概念不同。textDecoration.style用于更精细的装饰样式如波浪线、双线等见 Text.ts 中的TextDecorationStyle。四、组信息与批注场景groupIds?: string[]; // 组信息-可用于批注等其他成组使用场景groupIds让多个元素可以归属到同一逻辑组典型用途是批注选中一段文字打批注时编辑器把相关元素编入同一组便于统一高亮、统一删除。五、表格最复杂的元素结构conceptId?: string; colgroup?: { width: number }[]; trList?: { height: number; pagingRepeat?: boolean; // 跨页时作为表头行重复 extension?: unknown; externalId?: string; tdList: { colspan: number; // 跨列数 rowspan: number; // 跨行数 conceptId?: string; verticalAlign?: VerticalAlign; // 垂直对齐 backgroundColor?: string; // 单元格背景色 borderTypes?: TdBorder[]; // 单元格边框 slashTypes?: TdSlash[]; // 斜线表头 value: IElement[]; // 单元格内容 extension?: unknown; externalId?: string; disabled?: boolean; // 内容不可编辑 deletable?: boolean; // 内容不可删除 hint?: string; // 单元格悬浮提示文案 }[]; }[]; borderType?: TableBorder; // 表格边框样式 borderColor?: string; // 边框颜色 borderWidth?: number; // 边框宽度 borderExternalWidth?: number; // 外边框宽度 tableToolDisabled?: boolean; // 禁用表格工具表格的value字段通常为空字符串真正的数据在colgroup列宽与trList行集合中。要点三层嵌套表格元素 →trList[]行→tdList[]单元格每个单元格的value又是IElement[]可以装下任意行内元素。colspan/rowspan是必填字段参与单元格合并布局。边框枚举见 Table.tsTableBorder有all、empty、external、internal、dash五种整体边框TdBorder为单元格四边top/right/bottom/leftTdSlash支持forward正斜线/与back反斜线\两种表头斜线。pagingRepeatTr.ts让表格跨页时在每一页顶端重复渲染该行常用于长表头。渲染层跨页拆分信息由ITableRowFragmentElement.ts维护数据层仍保持单一表格仅渲染时按页拆行。六、超链接、上下标与分割线// 超链接 url?: string; // 上下标 actualSize?: number; // 分割线 dashArray?: number[]; // 分割线的虚线样式数组 lineWidth?: number; // 分割线的线宽 paperDirection?: PaperDirection; // 分页符之后页面的纸张方向超链接type: hyperlink的元素通过valueList存放链接文字url存放跳转地址见 Element.ts 的IHyperlinkElement。上下标superscript/subscript元素用actualSize记录实际渲染字号通常小于正常字号。分割线dashArray是虚线数组如[2, 2]lineWidth是线宽。分页符paperDirection声明分页符之后页面的纸张方向这是PAGE_BREAK元素独有的属性。七、控件交互式表单组件control?: IControl; // 控件数据结构详见控件-配置 controlComponent?: { PREFIX prefix, POSTFIX postfix, PLACEHOLDER placeholder, VALUE value, CHECKBOX checkbox, RADIO radio };control字段是完整独立的IControl数据结构Control.ts包含控件类型text/select/checkbox/radio/date/number、当前值value: IElement[] | null、占位符、前后缀、校验规则、级联规则、计算公式等完整配置其详细说明见 控件-配置。controlComponent标记该控件元素当前渲染的是哪一部分前缀、后缀、占位符、值、复选框、单选框。源码 ControlComponent 还额外包含PRE_TEXT/POST_TEXT两个枚举值对应IControlBasic中的preText/postText字段。八、复选框、单选框、LaTeX 与日期checkbox?: { value: boolean | null }; radio?: { value: boolean | null }; laTexSVG?: string; dateFormat?: string;复选框/单选框value为boolean | nullnull表示半选/未设置状态。配合controlComponent中的CHECKBOX/RADIO使用。LaTeXlaTexSVG存放公式渲染后的 SVG 字符串由 LaTexParticle.ts 负责渲染。日期dateFormat声明日期的展示格式如YYYY-MM-DD。九、图片显示、浮动、裁剪与题注imgDisplay?: { INLINE inline, BLOCK block }; // 图片显示方式 imgFloatPosition?: { x: number; y: number; pageNo?: number }; // 浮动定位 imgCrop?: { x, y, width, height }; // 裁剪坐标相对于原图 imgCaption?: { // 题注 value: string; // 题注内容支持 {imageNo} 占位符 color?: string; font?: string; size?: number; top?: number; // 题注与图片的间距 }; imgToolDisabled?: boolean; // 禁用图片工具栏 imgPreviewDisabled?: boolean; // 禁用图片预览imgDisplay决定图片是inline随文字流排版还是block块级独占。imgFloatPosition用于浮动图片的绝对定位pageNo指定所在页码。imgCrop四个数值均为相对原图的坐标与尺寸。imgCaption.value支持{imageNo}占位符渲染时自动替换为图片序号。图片相关接口组合见 Element.ts。十、内容块iframe 与视频block?: { type: { IFRAME iframe, VIDEO video }; iframeBlock?: { src?: string; srcdoc?: string; sandbox?: string[]; allow?: string[] }; videoBlock?: { src: string }; };block用于嵌入外部内容定义在 Block.tstype: iframe时配置iframeBlocksrc或srcdoc二选一前者加载外部 URL后者内联 HTML 文档sandbox声明沙箱权限allow声明特性权限如autoplay、fullscreen。type: video时配置videoBlock.src为视频地址。渲染层对应 IFrameBlock.ts 与 VideoBlock.ts。十一、标题与列表level?: TitleLevel; title?: { conceptId?: string; deletable?: boolean; disabled?: boolean }; listType?: ListType; listStyle?: ListStyle; listWrap?: boolean; listLevel?: number;标题type: title的复合元素通过valueList存放标题文字level取值源码 TitleLevel 中的first到sixth六级title.conceptId用于跨文档关联同一标题deletable/disabled控制删除与编辑权限。列表type: list同样以valueList承载列表项内容listType有序/无序、listStyle序号样式、listWrap是否换行、listLevel缩进层级共同决定列表外观。十二、区域与标签areaId?: string; area?: { extension?: unknown; top?: number; // 区域顶部偏移 hide?: boolean; // 是否隐藏 borderColor?: string; // 边框颜色 backgroundColor?: string; // 背景色 mode?: AreaMode; // 区域模式 deletable?: boolean; // 是否可删除 placeholder?: IPlaceholder; // 占位符 }; labelId?: string; label?: { color?: string; // 文字颜色 backgroundColor?: string; // 背景色 borderRadius?: number; // 圆角 padding?: IPadding; // 内边距 };区域type: area是另一种复合元素valueList装区域内容见 Element.ts 的IAreaElement适合做可整体移动、可折叠的内容分组配置接口见 Area.ts。标签label让元素渲染为带底色圆角的小徽标常用于状态标记或分类标注。十三、从数据到画布IElement 的渲染链路理解数据模型后再看渲染链路会更清晰编辑器维护一个扁平的IElement[]列表这是文档的逻辑层。Draw.ts 按元素顺序逐行排版将每个元素映射为IElementPosition含页码、行号、坐标、度量信息见 Element.ts。各类Particle文字、图片、表格、公式、控件等根据位置信息在 Canvas 上绘制。复合元素标题、列表、区域、超链接在排版时递归展开valueList因此逻辑层保持树状嵌套、渲染层保持扁平绘制。这种数据扁平、结构嵌套的设计让 history/HistoryManager.ts 可以基于元素列表做增量 diff 与撤销重做也让数据导出JSON 序列化天然可读、可迁移。十四、实战建议与延伸阅读构造元素时务必给value赋值表格单元格的colspan/rowspan必填复合元素请使用valueList而非字符串拼装。自定义业务数据优先使用extension与externalId不要污染标准字段以保证后续升级兼容。读写 API元素的增删改查可配合insertElementList、updateElementById、deleteElementById、getElementById等命令使用相关说明见 command-execute 与 command-get。类型定义入口完整的IElement类型定义在 Element.ts相关枚举在 dataset/enum 目录下按模块拆分二次开发时按图索骥即可。赞分享前端UI组件富文本【免费下载链接】canvas-editorA Canvas/SVG-based rich text editor项目地址https://gitcode.com/gh_mirrors/ca/canvas-editor点击查看免费下载相关推荐Canvas-Editor项目数据结构深度解析Canvas Editor项目数据结构深度解析 前言 Canvas Editor作为一个功能强大的富文本编辑器其核心在于对文档数据结构的定义与处理。本文将深入前端UI组件富文本深入解析AgentPress数据库架构Supabase表结构与关系模型完全指南 深入解析AgentPress数据库架构Supabase表结构与关系模型完全指南 AgentPress作为一款基于Supabase构建的AI Agents人工智能大模型AI AgentAI 应用后端前端LLM 网关自主智能体本地部署AI 技能工具调用Qwen3.5-35B-A3B-OptiQ-4bit震撼发布Apple Silicon专属4-bit混合精度模型如何突破性能极限Qwen3.5 35B A3B OptiQ 4bit震撼发布Apple Silicon专属4 bit混合精度模型如何突破性能极限 Qwen3.5 35B A大模型模型量化NLP上一篇GitHub_Trending/hac/hackathon教程合集从入门到高级应用下一篇keras-rl与其他深度学习框架集成PyTorch、TensorFlow等创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表