行列
打印及单独渲染
> 该功能方便把设计器中元素的渲染层拿出来，放到其它页面中单独显示 ### 功能背景 在设计器中设计好元素后，比如数据表格，进行了相关的行和列的设置，绑定了数据源，默认它可以在设计器附带的打印页面中展示。 如果想把这个数据表格单独拿出来，放在现有的页面中，则可以使用该功能。 ### 使用方式 首先在设计器中对需要单独展示的元素做设计，完成后单独拿到该元素的`JSON`描述数据。 比如我们使用`文本`元素来在其它页面中单独展示，则在设计器中只放一个`文本`元素进行设计。完成设计后，在示例页面中点击保存，弹出展示编辑区数据的对话框，在这里面找到文本元素的`JSON`数据，把该元素的这个完整的`JSON`数据拿出来，以备在其它页面中使用。  也可以对元素使用右键`复制JSON数据`或工具栏中的`复制JSON数据`按钮获取JSON数据 > 示例图片中截图即是某一个文本元素的完整`JSON`数据描述 ### 配置目标页面 线上demo页面：https://xinglie.github.io/report-designer/standalone.html 源码页面：https://github.com/xinglie/report-designer/blob/master/standalone.html 打包时，会对项目中的所有元素展示层单独打包到`dist/viewer.js`文件里，方便在其它页面引入使用。 比如在示例页面中，先引入独立使用的`js`文件`dist/viewer.js`，然后调用`viewer.element`方法，则会在相应的节点里，把指定的元素展示层显示进来。 viewer.element接受2个参数 `viewer.element:(nodeOrId,elementJSONData)=>void` `nodeOrId`:页面上渲染元素的`DOM`节点或节点`id` `elementJSONData`:元素数据，即前文提到的该元素设计器中产出的`JSON`数据 该方法无返回值 如果元素本身绑定了数据，则需要外部请求数据，和`JSON`数据一起传进来，因为设计元素的展示层自身并不请求数据，需要外部准备好。 如果需要对元素拆分，则需要自己根据`props`的配置信息，自行拆分，多配置几个节点即可。 **并非所有的元素都支持单独拿出来使用，比如页码器，比如流程图中的连接线等，当然，这些元素在传入属性时，补充好数据也是支持单独使用的**
设计器技术方案
### 分 分而治之的思路在各行各业都可以看到，设计器里也不例外。 在设计器里所有的一切都是分而独立的，比如头部元素栏、工具栏、标尺等。大到面板，小到可被设计的元素均是互相隔离且独立的，彼此之间不知道对方存在。理论上设计器中只要被拆分的界面均可以渲染到其它页面的任意位置上，这为调整软件界面布局提供了很大的便利。 分的思路也为我们插件化的工程打下了良好的基础，当某些功能不需要或添加新功能时，只需要简单的删除或增加相应的代码即可。在设计器中，所有的一切均为插件化，包括基础的工具栏、标尺、右键菜单等，这些仅是设计器中数据状态的一个展示层，不与设计器核心代码偶合 设计器中的核心模块也是采用分的思路进行开发，历史记录、剪切板、元素操作、吸附对齐、选区、快捷键等均为互相独立的模块，这些模块所有的操作都是控制内存中的数据对象，即使没有界面一样可以完成数据的修改变换。当然，界面的存在仅是对这份数据对象进行可视化展示，实时反映内存中数据的状态和对应的可操作项，便于向用户反馈和方便数据修改。 ### 合 大的组织还是需要独立的单元互相合作来完成更复杂的事情 项目中所有父到子的传递均由参数直接控制，即子提供控制参数，在父级进行传参控制。所有子到父的传递均是标准的`DOM`事件派发，这样更利于与第三方进行合作，只需要把设计器中的元素当成标准的`HTML`标签即可，所有事件均可以通过标准的`addEventListener`及`removeEventListener`进行添加和移除 所有需要联动的元素均由中介者进行控制，元素各自仍是互相独立的，通讯控制则交与中介进行管理，这样在不引入中介时，彼此不会联动，引入中介时，由中介控制它们进行联动。中介模块也是插件化的存在。
皮肤与多语言
### 皮肤 如果需要修改设计器的外观，可修改`tmpl/assets/_var.less`提取的变量即可，具体可查看文件内的变量注释。 通常只需要修改品牌色，其它颜色自适应，如果有较强的视觉要求，则可自行调整其它颜色变量 ### 多语言 项目支持多语言设置，但目前仅提供了中文包，如上图。 可自行提供如英文包放入并在`tmpl/i18n/index.ts`中引用即可 ### 更新 > 2022-08-16已支持英文语言包，目前用于测试，只做了少量翻译。设计器实现的是无刷新语言切换，只需要仿照现有的语言包扩展其它语言即可完成多国语言版。 **风险点：中文翻译成其它语言时，有可能会很长，导致界面不美观，需要根据不同的语言进行适当的界面调整**
## 概述 设计器元素支持应用`@keyframes`指定的`css`动画，您可以把常用动画封装成单独的`css`文件，供设计器使用。 设计器目前以插件的方式使用`Animate.css`提供的动画，您可以通过[https://animate.style/](https://animate.style/)访问`Animate.css`官网了解更多信息 ### 动画面板 动画面板默认不展示，您需要通过设计器右上角的面板列表中找到动画面板通过点击图标打开，或使用快捷键：`数字6`按下后打开，具体动画面板的图标及位置如下图所示 打开后动画面板将会展示在设计区的下方，如下图所示 ### 操控区域 > 操控区域用于设置动画时间轴的长度、间隙、重置及播放等功能 通过上图1下面的数字框，您可以修改时间轴的长度。目前默认时间最小时长为10s，最大时长为60s。可通过配置修改 通过上图2下面的数字框，您可以修改时间轴上最小时间的间隔。目前默认最小10px，最大20px。可通过配置修改 通过上图3下面的按钮，您可以停用或启用动画功能。该按钮方便您查看元素在应用动画前是什么状态，应用动画后是什么状态。 通过上图4下面的按钮，您可以一键重置时间轴到起始区域。 通过上图5下面的按钮，您可以让设计器播放或暂停动画，来查看整个时间段内或某个时间点的动画效果 ### 时间轴区域 > 通过时间轴您可以拖动时刻线查看某个时间点动画的效果 时刻线在拖动过程中，左、右两侧会出现自动滚屏提示区域，当您把拖动的设备如鼠标放置在该区域内时，时间轴会自动向右或左进行滚屏，无须您松开鼠标移动时间轴后再拖动。 ### 元素区域 > 通过元素区域您可以查看当前设计区哪些元素应用了哪些动画，同时您可以添加、修改、删除某个元素的某些动画 目前设计区内的元素在支持动画的情况下，将会自动出现在元素区域内(`这个可通过配置修改为仅选中元素且支持动画的元素才出现在元素区域内`)。 上图1区域内的元素，会自动联动设计区元素的状态作出相应的展示，如元素只读、禁用、启用等状态。同时为了方便您的查看，当您把设备如鼠标放置在1区域内的元素上时，设计区内的对应的元素会自动出现遮盖提示，如果您还是无法确定是哪个元素，也可以通过点击使设计区内的元素选中。 通过点击上图3区域，将会打开添加动画的弹框，您可以在弹框内选择需要的动画，添加后动画将会出现在2区域内。添加动画的弹框将在后面介绍。 上图2区域内添加的动画，您可以通过点击重新打开动画选择框，进行动画的修改或替换。当您的设备如鼠标悬停在该区域内时，会出现删除按钮，如果您对该动画不满意可以删除。...
相关技术及链接
### 前端类库 ~~使用`magix`的`v5`版本，该库由本人所写，开源地址：https://github.com/thx/magix/tree/v5 文档链接：https://thx.github.io/magix/~~ ### 打包工具 ~~使用`magix-composer`的`3.x`版本，该库由本人所写，开源地址：https://github.com/thx/magix-composer~~ ### 组件及样式 ~~该可视化项目所使用的基础组件及样式借签这里，仓库：https://github.com/thx/magix-gallery 文档：https://thx.github.io/magix-gallery/~~ ~~`magix-gallery`由本人发起，目前别人在维护~~ ~~样式和使用的部分组件均全部在当前项目中重写和重构~~ > 2024.4.15 由于一些不太好的原因，以上类库或工具已存档私有，如果您需要上述源码，可以联系我获取。无论开源还是闭源，都请尊重别人的劳动成果。 ### 其它 该软件中的所有功能，整体设计和架构以及相关代码均由本人独立完成。使用的第三方组件和库在下方有说明
### 迷你模式 > 该设计器可以嵌入到其他页面中的某个区域内，和现有系统更好的融合 为了保证显示的完整，嵌入的区块请保证至少宽`960px` 首先在页面中，添加如下的`html` ```html some other text left right bottom text ``` 请注意上面`html`中`id`为`app`的节点，到时候设计器会渲染在该节点里。为了更好的体验，你可以在`app`这个节点里添加一些`loading`动画，设计器加载完渲染时，会清除`app`节点下的内容并渲染设计器。 完整示例源码请查看：https://github.com/xinglie/report-designer/blob/master/mini.html 在线demo示例请查看：https://xinglie.github.io/report-designer/mini.html ### 自定义排版 在设计器中默认的界面中，设计器会提供一些交互方案，比如顶部元素的展示、面板的拖动处理等。 在这些交互的原则中，其之一就是严格控制设计器显示的内容在指定的区域内，比如面板不能拖动到指定的`DOM`元素外边来。这是因为宿主页面的界面和交互是未知的，我们不能干扰和影响宿主页面的展示行为。 如果要对迷你模式进行近一步的界面控制，可以使用拆分再重新组织界面的方式。 完整示例源码请查看：https://github.com/xinglie/report-designer/blob/master/split.html 在线demo示例请查看：https://xinglie.github.io/report-designer/split.html 以下讲解下代码和思路 首先组织自己想要展示的`HTML`结构，如下示例 ```html left 这里可以放一个加载动画......
接口及配置说明
> 部分可设计元素支持通过接口与数据源绑定，方便展示或打印，这里介绍下相关的数据格式和绑定思路 ### 接口统一格式 项目中所有用到的接口均按以下统一格式返回 ```js { "data":any, //根据接口的具体作用，返回相应的如数组、对象等结构的数据 "success": boolean,//接口状态，成功为true，失败为false，当失败时，最好在"message"中提供相应的失败信息 "message": "" //当接口异常时可提供的信息 } ``` > 如果您购买了源码，则设计器中所有接口统一由`designer/service.ts`中发出，而状态`success`及数据`data`均可以在这里适配成其它现有接口的格式，无须按这里描述的格式进行处理。 > 另外一种适配方案是，通过提供的配置项`response`进行适配，返回上述格式即可，设计器并不要求您一定修改现有接口为上述结构，如果您还是不明白，可以联系作者。您只需要知道上述提到的格式只是设计器默认的数据格式而已，并且可以很方便的适配成其它结构。 ### 全部数据源接口 > 该接口为设计器数据源面板中，显示的树形列表，如下图所示 该接口返回后端都有哪些数据接口可供使用，可查看当前项目中使用的一份写死的格式：https://github.com/xinglie/report-designer/blob/master/apis/fields.json 说明一下data中的格式 ```js { "data":[{//数组格式，可设置多个数据源 "name":...
### 拉框选择 鼠标在编辑区中按下，然后拖动。鼠标会拖出一个虚线矩形方框，当鼠标拖出的虚线方框与元素所在的矩形相交或包含关系时，则对应的元素进入被选中状态。 当元素被旋转后，部分元素所在的矩形也会随着旋转，同样旋转后的矩形也需要与鼠标拖出的虚线矩形相交或包含时，元素才进入被选中状态 鼠标在拉框选择的时候，按下了Shift键，则本次拉框选择会叠加之前选中的元素。即进入多选模式 #### 当拉框选择遇上容器元素 1. 当鼠标在某个容器格子内按下时，仅支持拉框选择当前格子内的元素，不支持框选当前格子外的元素(因格子可以无限嵌套，如果要框选格子外的元素，计算量太大) 2. 当容器格子内有元素选中时，且按下Shift或Ctrl或Cmd多选时，鼠标在容器元素外框选，当框中容器元素时，容器格子内的元素选择被取消(当容器被选中时，它所包含的子元素会取消选中状态)。当框选到容器元素后又取消时，容器格子内的之前选择的元素则会自动再次被选中 **任何操作如果有可能给用户后悔操作时，均有后悔操作。所有功能如果可以给快捷键时，均有相应的快捷键，尤其对于一些不便于鼠标操作时，肯定有对应的快捷键。** ### 鼠标点选 鼠标直接点击目标元素，目标元素进入选中状态。 在按下Shift或Ctrl的同时，使用鼠标点击目标元素，进入多选状态。当目标元素处于未选中状态时，进入选中状态。如果目标元素已处于选中状态，会取消选中状态。 ### tab键 依`z`轴从小到大选择编辑区中的元素，当编辑区中的元素过多且有重叠，不方便使用鼠标选择时有用。如果按下Tab同时按下了Shift则按`z`轴从大到小的顺序依次选中元素 ### 结构树面板 当鼠标`hover`在结构树面板中的元素时，会在编辑区显示一个半透明主题色矩形，告诉使用者当前对应是编辑区哪个元素。 当鼠标单击结构树面板中的元素时，该元素进入选中状态。 在按下Shift或Ctrl的同时点击结构树面板中的元素，进入多选状态。鼠标下的元素如果处于未选中状态时，进入选中状态。否则会取消选中状态。 **当元素处于单选、多选、组合等状态时，其被选中元素的边框会表现出不同的显示，方便使用人员进行区分。**
读写与权限控制
### 需求背景 在有权限设置的系统里，比如管理员和普通用户，管理员可预设一些必须存在的元素及元素位置，普通用户可在此基础上增加其它需要的元素。 管理员添加的元素在普通用户那里只读，不能调整位置、改变大小、删除等操作 ### 功能使用 设计器已支持元素只读，可查看只读示例，只读需要通过代码来设置，目前无法通过界面指定 ### 操作细节 #### z轴 只读元素无法调整z轴，但普通用户新增的元素支持和这些只读元素调整z轴，毕竟谁遮盖谁需要交与最终使用者决定 #### 容器 容器在只读的情况下也允许向格子内增加元素 如果容器元素未设置只读，而子元素设置只读，则容器可以被删除，连同只读的子元素。可设置为子元素如果有只读，则不允许删除容器 #### 拖动对齐 只读元素可以提供对齐功能，方便在拖动其它元素时与这些只读元素对齐 #### 清空设计区 如设计区有容器，且只读，但容器内放入了普通元素，则清空时，清除所有非只读元素
> 序号器元素用于在打印时，前端按一定规则生成相应的数字或其它字符串 #### 使用 1. 首先添加`序号器`元素到设计区 2. 选中`序号器`元素后，在右侧面板会展示`序号器`元素相应的属性设置 ##### 显示格式 > 显示格式用于进一步控制字符串的生成，以适应复杂需求 `{#}`格式是变量占位符，`序号器`按下方规则生成序号后，填充`{#}`所在的位置 ##### 计算方式 > 以何种方式生成序号，目前支持等差和等比计算方式 ##### 起始值 > 生成序号时，从哪个数字开始生成 ##### 公差或公比 > 以等差或等比生成时，下一个数字相较与前一个数字的公差或公比 ##### 补零 > 生成的最终数字是否在前面进行补0，通过补0可确保生成的字符串长度一致 #####...