@canvas-components/react-print-design 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 canvas-components contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @canvas-components/react-print-design
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+面向 React 的 Canvas 打印模板编辑器，包含工具栏、组件栏、图层和页面列表、属性面板、撤销重做以及 JSON、HTML、PNG、PDF 导出和打印。导出格式集中在 `ReactDropdown` 菜单中；点击格式后可在弹窗中修改文件名，拖出文件时使用当前文件名。编辑器的画布和文档操作由 `@canvas-components/print-design` 提供，表单和可调面板优先组合 `@canvas-components/react-components`。PDF 导出为实验性功能，当前将页面作为图片嵌入 PDF，文字暂不可选中。
+
+## 安装
+
+```bash
+pnpm add @canvas-components/react-print-design react react-dom
+```
+
+## 基础用法
+
+```tsx
+import { ReactPrintDesign } from "@canvas-components/react-print-design";
+import type { PrintDesignDocument } from "@canvas-components/print-design";
+import { useState } from "react";
+
+export function TemplateEditor() {
+  const [document, setDocument] = useState<PrintDesignDocument>();
+
+  return (
+    <div style={{ width: "100%", height: 720 }}>
+      <ReactPrintDesign onChange={setDocument} />
+    </div>
+  );
+}
+```
+
+传入 `document` 可加载外部模板并使用受控更新；`data` 提供 `{{field.path}}` 变量预览数据，`onChange` 返回文档副本。组件也接受 `readonly`、`showGrid`、`zoom` 和 `editor={false}` 等属性。默认编辑器会注入自身样式，容器需要有明确高度。
+
+组件栏提供文本、形状、分割线、图片、条形码、二维码和图表。选中分割线后，可在属性面板设置方向、线型、颜色和线宽；尺寸、位置及旋转也可在通用属性中调整。
+
+开发排查时可设置 `debug` 开启 Canvas 调试覆盖层。它会显示元素边界、当前选区和指针命中的元素；也可通过对象配置单独控制各层：
+
+```tsx
+<ReactPrintDesign debug={{ showHitTarget: true, showElementBounds: true }} />
+```
+
+编辑器默认显示毫米刻度尺和辅助线，可用 `showRulers`、`showGuides`、`showMarginGuides` 控制初始状态。辅助线会在刻度尺上显示位置标记和毫米值，可拖放到纸张外的画布区域。拖动上方或左侧刻度尺可创建辅助线，拖动辅助线可调整位置，拖回对应刻度尺或选中后按 Delete/Backspace 可移除。工具栏“打印边距”开关显示页面四边的打印边距线，边距值可在页面属性中配置。
+
+### 画布辅助配置
+
+左侧“配置”面板（React 编辑器）可控制刻度尺、辅助线、打印边距和最近组件间距的显示，还能设置左右面板的最小、最大及当前宽度。拖动面板分隔条会更新当前宽度。配置面板还可调整以下原生选项：
+
+- `snapToGuides`：默认开启。组件边缘和中心吸附到辅助线；辅助线吸附到纸张边缘、中心、打印边距和组件位置。按住 Alt 临时关闭。
+- `snapTolerance`：默认 6 CSS 像素，不随缩放改变屏幕吸附距离。
+- `dragThreshold`：默认 4 CSS 像素。选中后超过此距离才开始移动、缩放、旋转、辅助线拖拽或画布平移。
+- `showMeasurements`：默认开启，标注选中组件与上下左右投影相交的最近可见组件间距，单位毫米；旋转组件使用外接矩形测量。
+- `zoomDuration`：默认 180 毫秒，设为 0 关闭缩放过渡。
+
+按住空格拖拽或拖拽纸张空白/外部区域可平移查看；平移和缩放不会修改打印文档或导出内容。
+
+#### 刻度与辅助线外观
+
+左侧“配置”面板支持调整刻度尺字号/背景和辅助线数值字号/背景，原生实例可通过以下选项或 `updateOptions()` 实时设置：
+
+| 选项                      | 默认值    | 说明                        |
+| ------------------------- | --------- | --------------------------- |
+| `rulerFontSize`           | 9         | 刻度尺字号，8–16 CSS px     |
+| `rulerBackground`         | `#f8fafc` | 刻度尺背景色                |
+| `guideFontSize`           | 9         | 辅助线数值字号，8–24 CSS px |
+| `guideBackground`         | `#cffafe` | 辅助线圆角标签背景色        |
+| `guideSelectedBackground` | `#ffedd5` | 选中辅助线的标签背景色      |
+
+标签随字号自动调整尺寸，保持与纸张 8px 间距。
+
+辅助线颜色可通过配置面板或原生选项设置：`guideColor` 控制普通辅助线（默认青色），`marginGuideColor` 控制打印边距辅助线（默认紫色）。纸张内线条与纸张外延长线同步更新，选中标记保留高亮。
+
+### 表格组件
+
+左侧“表格”可点击添加或拖入画布。右侧提供静态数据 JSON、数组路径绑定、表头显隐、行高、字号及列配置；列可添加、删除、隐藏，配置 ListTable 的单元格类型、宽度、对齐与汇总。高级“列配置 JSON”支持嵌套表头和 `moneyFormat`、`cellStyle`、`dataFormat` 等声明式配置。JSON 草稿校验通过后才写入文档，可使用设计器撤销/重做。预览与 HTML/PDF 导出按页面高度拆分表格记录。
+
+静态数据支持按行展开、直接编辑字段和增删数据行，保留数值、布尔值及嵌套字段类型，复杂对象可用 JSON 编辑。动态绑定使用设计器 `data` 中的数组路径，显示有效记录数和前 5 行预览；切换模式保留静态记录。示例页提供 `order.items` 数据源。表头、表格体、汇总行各自支持背景色和文字色，默认背景透明，可通过“背景透明”开关切换。
+
+画布与左侧元素图层共用右键菜单：剪切、复制、粘贴、生成副本、层级调整、组合/取消组合、对齐、锁定/解锁、显示/隐藏、删除，以及全选和撤销重做。空白画布提供全部解锁、显示全部图层与适合页面。右键已选元素保留多选；复制粘贴使用当前设计器实例内剪贴板，粘贴偏移 5mm 并重建组合 ID。菜单支持方向键、Home/End 和 Esc。
+
+左侧点击组合的子图层只选中该子图层，点击组合标题选中其成员；画布点击组合成员时选中整个组合，拖动时整体移动。元素超过 80 个时，左侧自动启用虚拟列表，只挂载可视区域与预加载行，支持展开分组、滚动和拖拽排序。
+
+右侧“图层对齐”对所有元素类型及组合提供水平/垂直位置操作。单个图层或完整组合相对纸张对齐，多选相对选区对齐；完整组合保持内部布局，独立选中的子图层只移动自身。两端对齐按等间距排列，分散对齐按等中心距排列，至少需要三个独立图层或组合，首尾位置不变。锁定图层禁用操作，支持撤销/重做；文本内容对齐仍单独位于“文本样式”。
+
+所有组件右侧统一提供“数据”面板，支持“静态数据”和“动态绑定”切换，保留两种模式下的配置。基础组件可编辑内容、图片地址、颜色和线宽对应的字段，绑定模式显示路径及解析预览；字段路径支持数组索引，也可输入 `{{字段}}` 模板。图表保留分类、数值系列及数组绑定，表格保留静态行编辑、列配置及数组绑定。原文本、编码内容、图片地址和形状/分割线颜色线宽入口统一移入数据面板。
+
+数据方式使用按钮切换。动态绑定时可直接编辑“默认内容”，缺失、空值或无效字段会回退，`0` 和 `false` 保持有效；图表和表格提供显式的缺失数据源回退开关，有效空数组不回退。画布悬停动态图层时在右上角展示“动态绑定”，提示包含绑定路径；标记不会打印或导出。
+
+字段路径复用 `ReactCascader`，从当前传入的 mock/data 解析对象、数组和字段类型，支持搜索、清空及数组索引。图表/表格数组数据源选择器只展示数组路径，分类、系列、表格列字段从当前记录样本合并解析。数据更新后选项同步更新，缺失的已选路径保持回显。为避免大数据阻塞，字段解析最多展开 16 层、3000 个节点，并采样前 100 条记录、每层前 200 个字段。
+
+表格/图表使用专用数据源适配：表格可选择记录数组或 `{ dataSource, columns }`，通过“使用数据源列配置”导入 ListTable 的声明式列属性（回调不写入 JSON 模板）；图表可选择记录数组、ListTable 记录集，或直接选择 `ListTableChartData` 的 `{ labels, keys?, series: [{ name, data }] }`。直接图表数据不显示分类/数值字段映射，并保留稳定类别 keys。适配逻辑位于原生 `print-design/model`，React 面板只负责配置，避免后续 ReactListTable 集成产生反向依赖。
+
+单组件、组合与多选边框均提供八个控制句柄：左右调整宽度，上下调整高度，四角同时调整宽高，以对边或对角为锚点；组合同步缩放成员位置和尺寸。操作保留拖拽阈值、最小尺寸及撤销/重做；只读或包含锁定成员时不提供控制柄。