dsh-drawai 0.2.5 → 0.2.7

package/README.md

@@ -4,7 +4,7 @@
 
 # dsh-drawai
 
-[![GitHub stars](https://img.shields.io/github/stars/fourzkw/dsh-drawai?style=social)](https://github.com/fourzkw/dsh-drawai) [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/fourzkw/dsh-drawai?style=social)](https://github.com/fourzkw/dsh-drawai) [![npm downloads](https://img.shields.io/npm/dt/dsh-drawai)](https://www.npmjs.com/package/dsh-drawai) [![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 ## 功能一览
 
@@ -56,7 +56,7 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 
 | 入口 | 你能得到什么 |
 |---|---|
-| **右侧栏画布** | 打开或新建画布、画节点与连线、就地改字、图层、分区、顺序、多选对齐、查找、微移、多页切换、复制粘贴、导出 SVG / PNG（含导出选中） |
+| **右侧栏画布** | 打开或新建画布、画节点与连线、就地改字、图层、分区、顺序、多选对齐、查找、微移、多页切换、复制粘贴、导出 SVG / PNG / 透明 PNG（4×，含导出选中） |
 | **`diagram_apply`** | 让模型按 ops 改图：增删改、重接边、复制、排序、分层、导出；支持 `ids` 批量、`as` 别名、`expectRevision` |
 | **`diagram_read`** | 让模型看见图的结构与样式、图层与父级、页面尺寸、你此刻的选区、文件指纹 `revision` |
 | **选中与回退** | 你选中什么模型就知道什么；模型的每一轮改动都能在界面上退回去 |
@@ -78,7 +78,7 @@ dsh plugin --profile web add github:fourzkw/dsh-drawai
 | **图层** | 列出 / 新建 / 显示隐藏 / 锁定 / 重命名 / 删除（合并到邻层）/ 选中移层 / 设为当前层；隐藏与锁定写入文件 |
 | **顺序** | 置顶 / 上移 / 下移 / 置底 —— 写回时**真的改动文件里单元的先后**（否则重新打开就变回去了） |
 | **自定义数据** | 右键「编辑数据」，按 `key=value` 一行一项改单元属性；按 user object 存回文件，drawio 打开不会丢 |
-| **导出** | SVG / PNG(2×)；「看一眼画布效果」走 DSH 附件服务，**不在工作区落文件** |
+| **导出** | SVG / PNG(4×) / 透明 PNG(4×)；「看一眼画布效果」走 DSH 附件服务，**不在工作区落文件** |
 | **回退** | 「编辑 → 撤销 AI 改动」最多可以连着退 8 步 |
 
 ## 🤖 两个工具 / The two tools
@@ -211,7 +211,7 @@ id / layer / parent、选区能上报给模型、写回是逐单元的、画布
 - **多页**：可切换编辑当前页（视图菜单）；其它页保存时原样保留。AI 可用 `diagram_read` / `diagram_apply` 的 `page` 参数指定页。多页的**新建页**尚未实现。
 - 独立 `edgeLabel` 单元只读；`entityRelation` 等其它 edgeStyle、箭头字形、旋转 / 翻转 / 透明、stencil 形状只保留、不渲染；`.drawio.svg` / `.png` / `.html` 内嵌载体不支持。
 - **图片**：内嵌 SVG（`data:image/svg+xml,…`）与内嵌位图（PNG/JPEG/GIF/WebP data URI）都会画出来；**外链 / 相对路径**图片仍按矩形占位，单元原样保留（工作区磁盘上的图片文件画布直接读不到——要复刻请用 `traceImage`）。
-- 导出只有 SVG 与 PNG(2×)：没有 PDF。
+- 导出只有 SVG、PNG(4×) 与透明 PNG(4×)：没有 PDF。
 - 交互细节：对齐辅助线只跟节点比（不与折点、端点对齐）；单条选中的连线不能复制。
 
 完整的取舍与实现细节在 [docs/design.md](docs/design.md)。

package/lib/client.js

@@ -7677,6 +7677,7 @@ window.__ModuleLoader__.load({
           if (junk[i].parentNode !== null) junk[i].parentNode.removeChild(junk[i])
         }
         const ids = opts !== undefined && opts !== null && Array.isArray(opts.ids) ? opts.ids : null
+        const transparent = opts !== undefined && opts !== null && opts.transparent === true
         let boundsDoc = current
         if (ids !== null && ids.length > 0) {
           const filtered = docFilteredToIds(current, ids)
@@ -7716,22 +7717,35 @@ window.__ModuleLoader__.load({
         // 就是严格模式）会因为"用了未声明的前缀"整份丢弃：导出的 SVG/PNG 里那张图凭空消失。
         clone.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink')
         clone.removeAttribute('style')
-        // 网格纸在实时视图里只铺满"当前视口"；导出要铺满整图，否则缩放状态下网格会断掉。
-        const grid = clone.querySelector('rect[fill^="url(#drawai-grid-major"]')
-        if (grid !== null) {
-          grid.setAttribute('x', String(bounds.minX - pad))
-          grid.setAttribute('y', String(bounds.minY - pad))
-          grid.setAttribute('width', String(w))
-          grid.setAttribute('height', String(h))
-        }
-        // 网格图案是半透明的：不加一层底色的话，PNG 出来是透明背景。
-        const paper = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
-        paper.setAttribute('x', String(bounds.minX - pad))
-        paper.setAttribute('y', String(bounds.minY - pad))
-        paper.setAttribute('width', String(w))
-        paper.setAttribute('height', String(h))
-        paper.setAttribute('fill', mode === 'dark' ? '#1b1b1b' : '#ffffff')
-        clone.insertBefore(paper, clone.firstChild)
+        // 视口底：网格纸（url(#drawai-grid-major…)）或关网格时的实色纸。它是 svg 下第一个 <rect>。
+        let pageRect = null
+        for (let i = 0; i < clone.childNodes.length; i += 1) {
+          const child = clone.childNodes[i]
+          if (child.nodeType === 1 && String(child.nodeName).toLowerCase() === 'rect') {
+            pageRect = child
+            break
+          }
+        }
+        if (transparent) {
+          // 透明导出：底纸/网格都要拿掉，否则 alpha 通道会被盖成不透明。
+          if (pageRect !== null && pageRect.parentNode !== null) pageRect.parentNode.removeChild(pageRect)
+        } else {
+          // 网格纸在实时视图里只铺满"当前视口"；导出要铺满整图，否则缩放状态下网格会断掉。
+          if (pageRect !== null) {
+            pageRect.setAttribute('x', String(bounds.minX - pad))
+            pageRect.setAttribute('y', String(bounds.minY - pad))
+            pageRect.setAttribute('width', String(w))
+            pageRect.setAttribute('height', String(h))
+          }
+          // 网格图案是半透明的：不加一层底色的话，PNG 出来是透明背景。
+          const paper = document.createElementNS('http://www.w3.org/2000/svg', 'rect')
+          paper.setAttribute('x', String(bounds.minX - pad))
+          paper.setAttribute('y', String(bounds.minY - pad))
+          paper.setAttribute('width', String(w))
+          paper.setAttribute('height', String(h))
+          paper.setAttribute('fill', mode === 'dark' ? '#1b1b1b' : '#ffffff')
+          clone.insertBefore(paper, clone.firstChild)
+        }
         return { node: clone, width: w, height: h }
       }
 
@@ -7837,12 +7851,17 @@ window.__ModuleLoader__.load({
         setTimeout(() => URL.revokeObjectURL(url), 2000)
       }
 
-      function downloadPng(node, width, height, filename) {
+      function downloadPng(node, width, height, filename, opts) {
         const markup = new XMLSerializer().serializeToString(node)
         const url = URL.createObjectURL(new Blob([markup], { type: 'image/svg+xml;charset=utf-8' }))
         const image = new Image()
         image.onload = () => {
-          const scale = 2
+          // 默认 4×（与透明高质量同档）。过大时压到浏览器常见 canvas 上限，避免整图失败。
+          let scale = opts !== undefined && opts !== null && typeof opts.scale === 'number' && opts.scale > 0 ? opts.scale : 4
+          const transparent = opts !== undefined && opts !== null && opts.transparent === true
+          // Chromium / 多数桌面浏览器单边可到 16384；再高容易在部分环境创建失败。
+          const maxEdge = 16384
+          while (scale > 1 && (width * scale > maxEdge || height * scale > maxEdge)) scale = scale / 2
           const canvas = document.createElement('canvas')
           canvas.width = Math.max(1, Math.round(width * scale))
           canvas.height = Math.max(1, Math.round(height * scale))
@@ -7851,8 +7870,10 @@ window.__ModuleLoader__.load({
             URL.revokeObjectURL(url)
             return
           }
-          context.fillStyle = mode === 'dark' ? '#1b1b1b' : '#ffffff'
-          context.fillRect(0, 0, canvas.width, canvas.height)
+          if (transparent !== true) {
+            context.fillStyle = mode === 'dark' ? '#1b1b1b' : '#ffffff'
+            context.fillRect(0, 0, canvas.width, canvas.height)
+          }
           context.drawImage(image, 0, 0, canvas.width, canvas.height)
           URL.revokeObjectURL(url)
           canvas.toBlob((blob) => {
@@ -9274,19 +9295,23 @@ window.__ModuleLoader__.load({
       // 导出。刻意放在 effect 里跑：按钮先清掉选中，等这一帧渲染完（DOM 里没有手柄和选中框了）
       // 再序列化，产物才干净。若在点击回调里直接导，会把手柄一起拍进去。
       //
-      // 两种触发形态：菜单里点的是字符串（'svg' / 'png'）→ 浏览器下载；AI 要的是对象
-      // （`{format, requestId, name}`）→ svg 把文本回执给宿主落盘、png 仍走浏览器下载。
-      // 导出选中：`{format, ids}` —— 不清选区（还要用 ids），从克隆里剔掉未选中的单元。
+      // 两种触发形态：菜单里点的是字符串（'svg' / 'png'）→ 浏览器下载；对象形态
+      // （`{format, requestId?, name?, ids?, transparent?, scale?}`）→ 菜单的选区/透明导出，
+      // 或 AI 的 `{format, requestId, name}`（svg 回执落盘、png 仍走浏览器下载）。
       React.useEffect(() => {
         if (exportRequest === null) return
         const request = exportRequest
         setExportRequest(null)
-        const fromAi = typeof request === 'object' && request !== null
-        const format = fromAi ? request.format : request
-        const requestId = fromAi && typeof request.requestId === 'string' ? request.requestId : null
-        const askedName = fromAi && typeof request.name === 'string' && request.name.length > 0 ? request.name : null
-        const exportIds = fromAi && Array.isArray(request.ids) ? request.ids : null
-        const built = buildExportSvg(exportIds !== null ? { ids: exportIds } : undefined)
+        const fromObj = typeof request === 'object' && request !== null
+        const format = fromObj ? request.format : request
+        const requestId = fromObj && typeof request.requestId === 'string' ? request.requestId : null
+        const askedName = fromObj && typeof request.name === 'string' && request.name.length > 0 ? request.name : null
+        const exportIds = fromObj && Array.isArray(request.ids) ? request.ids : null
+        const transparent = fromObj && request.transparent === true
+        const scale = fromObj && typeof request.scale === 'number' && request.scale > 0 ? request.scale : 4
+        const built = buildExportSvg(
+          exportIds !== null || transparent ? { ids: exportIds !== null ? exportIds : undefined, transparent: transparent } : undefined,
+        )
         if (built === null) {
           if (requestId !== null) reportExportResult(requestId, format, { ok: false, error: '画布还没准备好，导出没做成' })
           else if (exportIds !== null) setSaveNote('导出选中失败：选区里没有可导出的单元')
@@ -9297,7 +9322,9 @@ window.__ModuleLoader__.load({
         const name =
           askedName !== null
             ? askedName
-            : String(source).split(/[\\/]/).pop().replace(/\.drawio$/i, '') + (exportIds !== null ? '-selection' : '')
+            : String(source).split(/[\\/]/).pop().replace(/\.drawio$/i, '') +
+              (exportIds !== null ? '-selection' : '') +
+              (transparent ? '-transparent' : '')
         if (format === 'svg') {
           const markup = new XMLSerializer().serializeToString(built.node)
           // AI 要的是"落成工作区里的一个文件"：把文本回执给宿主，由它写在 .drawio 旁边。
@@ -9309,7 +9336,7 @@ window.__ModuleLoader__.load({
           downloadBlob(new Blob([markup], { type: 'image/svg+xml;charset=utf-8' }), name + '.svg')
           return
         }
-        downloadPng(built.node, built.width, built.height, name + '.png')
+        downloadPng(built.node, built.width, built.height, name + '.png', { scale: scale, transparent: transparent })
         // PNG 走浏览器下载（AI 触发的也一样）：宿主写二进制得另开通道，而"点一次导出"就有的东西
         // 不值得为它搬 base64。下载成不成浏览器不给回执，所以这里只报"已经交给下载"。
         if (requestId !== null) {
@@ -9333,7 +9360,7 @@ window.__ModuleLoader__.load({
           return
         }
         setSaveNote('正在把画布渲成图片给 AI 看…')
-        // 与手动导出同一档 2×；体量不再由客户端预检截断（宿主对 render-result 放开了 body 上限）。
+        // AI 看图用 2×（比手动导出的 4× 更轻）；体量不再由客户端预检截断（宿主对 render-result 放开了 body 上限）。
         // 部署附件服务若自带 maxImageBytes，仍会在那一侧拒收。
         renderPngPayload(built.node, built.width, built.height, 2)
           .then((payload) => {
@@ -11249,12 +11276,20 @@ window.__ModuleLoader__.load({
                 { hint: '矢量，可再编辑', disabled: empty },
               ),
               item(
-                '导出 PNG（2×）',
+                '导出 PNG（4×）',
                 () => {
                   setSelectedIds([])
-                  setExportRequest('png')
+                  setExportRequest({ format: 'png', scale: 4 })
                 },
-                { hint: '位图，适合贴到文档里', disabled: empty },
+                { hint: '高质量位图，白/深色底，适合贴到文档里', disabled: empty },
+              ),
+              item(
+                '导出透明 PNG（4×）',
+                () => {
+                  setSelectedIds([])
+                  setExportRequest({ format: 'png', transparent: true, scale: 4 })
+                },
+                { hint: '高质量透明背景，适合叠到幻灯片/海报上', disabled: empty },
               ),
               item(
                 '导出选中为 SVG',
@@ -11263,8 +11298,13 @@ window.__ModuleLoader__.load({
               ),
               item(
                 '导出选中为 PNG',
-                () => setExportRequest({ format: 'png', ids: selectedIds.slice() }),
-                { hint: '只导出当前选区', disabled: empty || selectedIds.length === 0 },
+                () => setExportRequest({ format: 'png', ids: selectedIds.slice(), scale: 4 }),
+                { hint: '只导出当前选区（白/深色底，4×）', disabled: empty || selectedIds.length === 0 },
+              ),
+              item(
+                '导出选中为透明 PNG',
+                () => setExportRequest({ format: 'png', ids: selectedIds.slice(), transparent: true, scale: 4 }),
+                { hint: '选区透明背景，4× 分辨率', disabled: empty || selectedIds.length === 0 },
               ),
             ],
           },

package/lib/index.js

@@ -944,15 +944,14 @@ async function applyOps(doc, ops, out, opctx) {
     }
 
     if (kind === 'addNode') {
-      // `svg` 给了（非 null）= 这个节点的内容是一张图，标签可以省。
-      // 注意**内容合不合法**交给 nodeStyleFromOp 去判（那里才有精确的报错）——
-      // 在这里按"是不是合法 SVG"决定要不要 label，会让一段写坏的标记先撞上"label 缺失"。
-      const svgOp = has(op, 'svg') && op.svg !== null && op.svg !== undefined
-      // 标签在 drawio 里是**可选**的（`value=""` 就是一个没有文字的单元）——
-      // 内嵌 SVG 的节点通常只画图不带字，所以给 svg 内容时可以省掉 label。
-      const label = typeof op.label === 'string' && op.label.length > 0 ? op.label : svgOp ? '' : undefined
-      if (label === undefined) {
-        throw new Error('ops[' + i + '] addNode needs a non-empty string "label"（画图不带字的 svg 节点可以省 label，但要给 "svg" 内容）')
+      // 标签在 drawio 里是可选的（`value=""` = 没有文字的单元）。装饰面板 / 底框 /
+      // 内嵌 SVG 都可以省 label 或给 ""；没给就当空串。给了就必须是 string。
+      let label = ''
+      if (has(op, 'label') && op.label !== null && op.label !== undefined) {
+        if (typeof op.label !== 'string') {
+          throw new Error('ops[' + i + '] addNode "label" must be a string（装饰面板可省或给 ""）')
+        }
+        label = op.label
       }
       let id = typeof op.id === 'string' && op.id.length > 0 ? op.id : undefined
       if (id !== undefined && findNode(id) >= 0) {
@@ -969,17 +968,22 @@ async function applyOps(doc, ops, out, opctx) {
         // 形状/配色是糖，落盘只有 style 键；不给就是 drawio 缺省（空串 = 普通矩形 + 缺省配色）。
         style: style,
         // svg 节点缺省是**正方形**：按标签文字估宽（estimateWidth）对图没有意义。
+        // 空 label 的装饰面板也请显式给 w/h，否则会落到最短标签估宽（130）。
         w: numberOr(op.w, svgNode ? DEFAULT_SVG_W : estimateWidth(label)),
         h: numberOr(op.h, svgNode ? DEFAULT_SVG_H : DEFAULT_H),
       }
       if (typeof op.layer === 'string' && op.layer.length > 0) node.layer = resolveLayerRef(op.layer, 'ops[' + i + '] addNode layer')
-      // 关键：只有显式给了坐标才写入。缺省写 (0,0) 会让 placeMissing 以为"坐标齐全"而不补位，
+      // 位置：只有显式给了坐标才写入。缺省写 (0,0) 会让 placeMissing 以为"坐标齐全"而不补位，
       // 新节点就会堆在原点压住别人。
       if (has(op, 'x')) node.x = numberOr(op.x, 0)
       if (has(op, 'y')) node.y = numberOr(op.y, 0)
       doc.nodes.push(node)
       recordCreated(id, 'node', label)
-      notes.push('+ node ' + id + (svgNode ? ' [svg]' : ' "' + label + '"') + (has(op, 'x') || has(op, 'y') ? ' at explicit coords' : ' (position pending)'))
+      notes.push(
+        '+ node ' + id +
+          (svgNode ? ' [svg]' : label.length > 0 ? ' "' + label + '"' : ' (empty label)') +
+          (has(op, 'x') || has(op, 'y') ? ' at explicit coords' : ' (position pending)'),
+      )
       continue
     }
 
@@ -2018,6 +2022,8 @@ diagram_read —— 返回里的 path 就是它（这两条是一致的，同一
 - **改一组用 ids**：{op:"setStyle", ids:["n1","n2","n5"], style:"green"} —— setStyle / setLabel /
   move / remove 都收 ids，不要为了"把这几个改成绿色"发 12 个 op。批量 move 只收 dx/dy
   （给一个绝对 x/y 等于把它们叠成一摞，宿主会直接拒绝）。
+- **addNode 的 label 可省或给 ""**：装饰面板 / 底框 / 纯色块不需要字时直接省掉；空 label 时请显式给 w/h
+  （否则按最短标签估宽 130）。有字的节点照常写 label。
 - **引用刚建的那个用 as**：{op:"addNode", label:"开始", as:"start"} 之后，同一个 ops 数组里
   from/to/id 可以直接写 "start"。id 省略时是自动分配的（n 几/e 几），猜编号在非空画布上必错。
 - **返回值里看 created/changed/removed**：新建单元的 id（含自动分配的）在这里，接着引用它们
@@ -2072,7 +2078,7 @@ diagram_read —— 返回里的 path 就是它（这两条是一致的，同一
       浏览器按 XML 解析会直接丢弃这份图 —— 屏幕上什么都没有，也不报错）。
     · 默认 **imageAspect=0 = 拉伸铺满**节点框；想让图形等比缩放居中就加 keys:{imageAspect:1}
       （那就把 w/h 设成图形的比例，否则四周会留白）。
-    · svg 节点**可以没有 label**（画图不带字）；要图下面带文字就照常给 label，它画在图上。
+    · svg 节点通常不带 label（画图不带字）；要图上叠字就照常给 label。普通矩形/面板同样可以省 label。
     · 颜色写在 SVG 自己身上（fill/stroke）—— 配色参数对它是无效的（图片不受 fillColor/strokeColor 影响）。
     · 内容上限 250000 字符；**别放位图/base64**（那是图片不是图形，本画布画不出来）。
     · 改内容只能整段替换（没有"改某一根线"的 op）：先 read 拿回当前 svg，改完整段写回。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-drawai",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "type": "module",
   "description": "DSH 右侧栏的可编辑画布 + AI 语义绘图工具（diagram_apply / diagram_read），直接读写原生 .drawio 文件",
   "license": "MIT",