@agile-team/mach-report 2.15.0 → 2.17.0

package/dist/xlsx.cjs

@@ -1,3 +1,4 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const E=require("./progress-B0ctFpKf.cjs"),w=require("./workbook-session-Bjv1YCRK.cjs"),R=require("./render-plan-7xpGrCEl.cjs"),P=require("./media-B7vnpD8k.cjs"),A=require("./grid-geometry-CZ_cYB6O.cjs"),b=require("./style-UgIJSA1F.cjs"),z=require("./capabilities-CAh2Nrue.cjs"),m=require("./region-binding-workflow-DIYJdCUr.cjs");function O(e,t,r){let n=r*72/25.4;if(!Number.isFinite(n)||t+Math.ceil(n/409)-1>1048576)throw new Error("Excel 图片占位超过工作表行数上限");for(;n>0;){if(t>1048576)throw new Error("Excel 图片占位超过工作表行数上限");const o=Math.min(409,n);e.getRow(t++).height=o,n-=o}return t}function N(e,t,r){let n=Math.round(t*36e3),o=0;if(!Number.isSafeInteger(n))throw new Error("Excel 图片锚点超出安全坐标范围");for(e.properties.defaultColWidth??=8.43;o<16384;){const l=e.getColumn(o+1).width??e.properties.defaultColWidth,i=Math.round(w.excelColumnWidthToMm(l)*36e3);if(!Number.isSafeInteger(i)||i<=0)throw new Error("Excel 图片锚点所在列宽无效");if(n<i)return{col:o+n/i,row:r-1,nativeCol:o,nativeColOff:n,nativeRow:r-1,nativeRowOff:0};n-=i,o++}throw new Error("Excel 图片锚点超过16384列上限")}function L(e,t,r){let n=r*72/25.4;if(!Number.isFinite(n)||Math.abs(n)>1048576*409)throw new Error("Excel 图片纵向偏移超过工作表范围");const o=l=>{const i=e.getRow(l).height??e.properties.defaultRowHeight??15;if(!Number.isFinite(i)||i<=0)throw new Error("Excel 图片锚点所在行高无效");return i};for(;n<0&&t>1;)n+=o(--t);for(;t<=1048576&&n>=o(t);)n-=o(t++);if(t>1048576||n<0)throw new Error("Excel 图片移动到工作表边界之外");return{nativeRow:t-1,nativeRowOff:Math.round(n*25.4/72*36e3)}}function G(e,t,r){const n=P.createImageMediaInspector(t),o=new Map;return{write(l,i,a,s){if(![i.widthMm,i.heightMm,i.leftMm].every(Number.isFinite)||i.widthMm<0||i.heightMm<0||i.leftMm<0)throw new Error("Excel 图片尺寸无效");if(!i.widthMm||!i.heightMm)return a;if(!i.imageData||!/^data:image\/(png|jpe?g);base64,/i.test(i.imageData))return r.push(`${i.nid??i.kind}: Excel 图片仅支持 PNG/JPEG data URI，已跳过`),a;const c=n(i.imageData);let d=o.get(c.dataUrl);d===void 0&&(d=e.addImage({base64:c.dataUrl,extension:c.extension}),o.set(c.dataUrl,d));const h=s?a:O(l,a,i.heightMm);return l.addImage(d,{tl:{...N(l,s?.leftMm??i.leftMm,a),...s?L(l,a,s.offsetMm):{}},ext:{width:i.widthMm*96/25.4,height:i.heightMm*96/25.4},editAs:"oneCell"}),h}}}function W(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function B(e,t){const r=e.meta?.xlsxFlow;if(r===void 0)return;if(!W(r)||r.version!=="1.0"||!Number.isSafeInteger(r.columnStart)||Number(r.columnStart)<0)throw new Error("Excel 多区域几何标记无效，不能按列序猜测输出");if(!e.grid)throw new Error("Excel 多区域输出只接受显式网格组件");const n=r,o=e.grid.colWidthsMm;if(!o?.length||n.columnStart+o.length>t.length||o.some((l,i)=>Math.abs(l-t[n.columnStart+i])>.001))throw new Error("Excel 多区域列位置与网格列宽不一致");return n}function $(e){const t=e.meta?.xlsxFlow;if(t===void 0){if(e.components.some(n=>n.meta?.xlsxFlow!==void 0))throw new Error("Excel 多区域页面缺少完整列几何标记");return}const r=j(t,e.meta?.reportScope);for(const n of e.components){const o=B(n,r.widths);if(!o)throw new Error("Excel 多区域页面混入没有区域几何的组件，请使用独立页面模板");const l=r.widths.slice(0,o.columnStart).reduce((a,s)=>a+s,e.marginLeftMm??0),i=n.grid.colWidthsMm.reduce((a,s)=>a+s,0);if(Math.abs(l-n.leftMm)>.01||Math.abs(i-n.widthMm)>.01)throw new Error("Excel 多区域标记与真实横向位置不一致")}return r}function j(e,t){if(!W(e)||e.version!=="1.0"||typeof e.sheet!="string"||!e.sheet.trim()||typeof e.templateId!="string"||!e.templateId.trim())throw new Error("Excel 多区域工作表标识无效");if(!Array.isArray(e.fullWidthsMm)||!e.fullWidthsMm.length||e.fullWidthsMm.length>16384||e.fullWidthsMm.some(r=>typeof r!="number"||!Number.isFinite(r)||r<=0||r>2e3))throw new Error("Excel 多区域完整列宽无效");if(t!==void 0&&(typeof t!="string"||!t.trim()))throw new Error("Excel 多区域报表命名空间无效");return{key:JSON.stringify([t??e.templateId,e.sheet]),sheet:e.sheet,widths:e.fullWidthsMm}}function v(e){return Math.round(e*1e6)/1e6}function D(e,t,r,n,o){return e.components.filter(l=>n?l.pageAnchor==="header"?t===0:l.pageAnchor==="footer"?t===r-1:l.table?.role!=="header"?!0:o.has(l.table.id)?!1:(o.add(l.table.id),!0):!0)}function H(e,t,r,n){const o=e.components.filter(i=>!t.includes(i)&&i.table?.role==="header"),l=t.filter(i=>!i.pageAnchor).reduce((i,a)=>Math.max(i,a.topMm+a.heightMm),e.marginTopMm??0);return t.map(i=>{let a=i.topMm;return r&&i.pageAnchor==="footer"&&(a=l),a-=o.filter(s=>s.topMm+s.heightMm<=a+.001).reduce((s,c)=>s+c.heightMm,0),{component:i,layout:A.resolveGridLayout(i.grid,i.widthMm,i.heightMm),top:a,column:B(i,n).columnStart}})}function _(e,t,r){const n=t.length-1;if(n*r.length>1e6)throw new Error("Excel 多区域单页超过 100 万几何单元格，请减小预览分页高度或列数");const o=new Map(t.map((a,s)=>[a,s])),l=new Map,i=new Map;for(const a of e)for(const s of a.layout.cells){if(!Object.keys(s.cell).length)continue;const c=o.get(v(a.top+s.yMm)),d=o.get(v(a.top+s.yMm+s.heightMm)),h=a.column+s.ci,u=h+(s.cell.colSpan??1),g=`${c}:${h}`;for(let f=c;f<d;f++)for(let x=h;x<u;x++){const y=`${f}:${x}`;if(i.has(y))throw new Error("Excel 多区域实际单元格互相覆盖，已终止输出，未覆盖已有内容");i.set(y,g)}l.set(g,{...s.cell,style:b.mergeComponentStyles(a.component.style,s.cell.style),rowSpan:d-c,colSpan:u-h})}return Array.from({length:n},(a,s)=>{const c=[];for(let d=0;d<r.length;d++){const h=`${s}:${d}`,u=l.get(h);u?(c.push(u),d+=(u.colSpan??1)-1):i.has(h)||c.push(null)}return c})}function q(e,t){const r=new Set,n=[];let o;for(const[l,{page:i}]of e.entries()){const a=$(i);if(o&&(a.key!==o.key||a.widths.length!==o.widths.length||a.widths.some((g,f)=>Math.abs(g-o.widths[f])>.001)))throw new Error("Excel 多区域分页的工作表或列结构不一致");o??=a;const s=D(i,l,e.length,t,r),c=H(i,s,t,a.widths);if(!c.length)continue;const d=[...new Set(c.flatMap(g=>[...g.layout.rows.map(f=>v(g.top+f.pos)),v(g.top+g.component.heightMm)]))].sort((g,f)=>g-f),h=_(c,d,a.widths),u=d.slice(1).map((g,f)=>g-d[f]);n.push({kind:"rect",leftMm:0,topMm:0,widthMm:a.widths.reduce((g,f)=>g+f,0),heightMm:u.reduce((g,f)=>g+f,0),grid:{cells:h,colWidthsMm:a.widths,rowHeightsMm:u}})}return n}const F=72/25.4,U=32767,X=253;function M(e,t){if(typeof e!="string")return;if(e.length>U)throw new Error(`Excel 单元格 ${t} 最多支持 32767 个字符，无法无损导出；内容未裁剪`);let r=0;for(let n=0;n<e.length;n++)if(e.charCodeAt(n)===10&&++r>X)throw new Error(`Excel 单元格 ${t} 最多支持 253 个换行，无法无损导出；内容未改写`)}function p(e){if(!e)return;const t=e.replace("#","");return/^[0-9a-fA-F]{6}$/.test(t)?`FF${t.toUpperCase()}`:void 0}function T(e,t={}){e.font={name:t.fontFamily,bold:t.bold===!0,italic:t.italic===!0,underline:t.underline===!0,size:b.resolveFontSize(t).fontSizePt,color:p(t.color)?{argb:p(t.color)}:void 0}}const S={a3:{width:297,height:420,code:8},a4:{width:210,height:297,code:9},a5:{width:148,height:210,code:11}};function K(e,t,r,n){if(t&&t!=="auto")return S[t].code;const o=Math.min(e.pageWidthMm,e.pageHeightMm),l=Math.max(e.pageWidthMm,e.pageHeightMm),i=Object.values(S).find(a=>Math.abs(o-a.width)<=1&&Math.abs(l-a.height)<=1);return i?i.code:(n.push(`page ${r+1}: 自定义纸张 ${e.pageWidthMm}×${e.pageHeightMm}mm 无对应 Excel 纸型，打印设置回退 A4；可显式配置 paperSize`),S.a4.code)}function J(e,t,r,n){const o=typeof t.text=="string"?t.text:"";if(r!=="raw"||!Object.prototype.hasOwnProperty.call(t,"value")){M(o,e.address),e.value=o;return}const l=t.value;if(l===null||typeof l=="string"||typeof l=="boolean"||typeof l=="number"&&Number.isFinite(l)){M(l,e.address),e.value=l,t.numberFormat&&(e.numFmt=t.numberFormat);return}M(o,e.address),e.value=o,n.push(`原始单元格值无效，已保留显示文本：${e.address}`)}function V(e){const t=$(e);return t?{id:`xlsx-flow:${t.key}`,title:t.sheet,wide:!0,flow:!0}:Q(e)}function Q(e){const r=e.components.filter(n=>n.table!==void 0)[0]?.table;if(!(!r||typeof r.id!="string"||!r.id.trim()||!Array.isArray(r.columnKeys)||!r.columnKeys.length)){for(const n of e.components){if(n.table){if(!n.grid||n.table.id!==r.id)return;continue}if(n.grid||n.kind!=="text"&&!R.isImageBackedComponent(n))return}return{id:r.id,title:r.title,wide:r.layout==="wide"||e.layout==="wide"}}}function Y(e,t){const r=new Set;for(const[n,o]of e.pages.entries())if(!t[n])for(const l of o.components)typeof l.table?.id=="string"&&r.add(l.table.id);return r}function C(e){return e.layout==="wide"||e.components.some(t=>t.table?.layout==="wide")}function Z(e,t,r){const n=[],o=e.pages.map(V),l=Y(e,o);for(const[i,a]of e.pages.entries()){const s=o[i],c=s&&!l.has(s.id),d=t==="pages"||!c?void 0:s;if(t==="continuous"&&!d)throw new Error(`page ${i+1}: continuous Excel 需要完整、单一的逻辑表来源；自由布局请使用 sheetMode: 'pages'`);const h=d!==void 0&&(t==="continuous"||d.wide);!h&&t!=="pages"&&C(a)&&r.push(`page ${i+1}: 混合或缺少逻辑表来源，已保留独立 Sheet，未猜测合并内容`);const u=n[n.length-1];h&&u?.continuous&&u.tableId===d.id?u.pages.push({page:a,index:i}):n.push({pages:[{page:a,index:i}],continuous:h,...h?{tableId:d.id,title:d.title}:{},...s?.flow?{flow:!0,title:s.title}:{}})}return n}function k(e,t,r){return!e||e.length===t.length&&e.every((n,o)=>r(n,t[o]))}function ee(e,t,r,n){const o=e.table,l=t.columns.map(s=>s.size),i=k(n.keys,o.columnKeys,(s,c)=>s===c),a=k(n.widths,l,(s,c)=>Math.abs(s-c)<=.001);if(o.columnKeys.length!==l.length||!i||!a)throw new Error(`page ${r+1}: 连续 Excel 逻辑表 ${o.id} 的列结构或列宽不一致`);if(n.keys??=o.columnKeys,n.widths??=l,o.role==="header"){if(o.rowIndex!==-1)throw new Error(`page ${r+1}: 连续 Excel 表头 rowIndex 必须为 -1`);n.headerSeen=!0}else{if(!["body","group-header","subtotal","grand-total"].includes(o.role)||o.rowIndex!==n.expectedRow)throw new Error(`page ${r+1}: 连续 Excel 逻辑行来源不连续或重复（期望 ${n.expectedRow}）`);n.expectedRow+=t.rows.length}if(t.cells.some(s=>s.cell.children?.length))throw new Error(`page ${r+1}: 连续 Excel 暂不支持嵌套组件；请使用独立 Sheet 导出并检查告警`)}function te(e,t){const r={expectedRow:0,headerSeen:!1};for(const{page:n,index:o}of e.pages)for(const l of n.components){const i=t.get(l);l.table&&i&&ee(l,i,o,r)}if(!r.headerSeen)throw new Error("连续 Excel 逻辑表缺少明确表头来源")}function ne(e,t,r){let n=(e?.replace(/[\\/*?:[\]]/g," ").replace(/\s+/g," ").trim()||`Sheet${t+1}`).slice(0,31).replace(/^'+|'+$/g,"").trim()||`Sheet${t+1}`;n.toLowerCase()==="history"&&(n+=" 报表");let o=n,l=1;for(;r.has(o.toLowerCase());){const i=` (${++l})`;o=n.slice(0,31-i.length)+i}return r.add(o.toLowerCase()),o}function ie(e){const t=new Set;function r(n,o,l,i){return n<=o?n:(t.has(l)||(e.push(i),t.add(l)),o)}return{column:n=>r(n,255,"column","Excel 单列宽度上限为 255 字符，超宽列已收敛至 255；单元格值完整保留，显示范围可能受限"),row:n=>r(n,409,"row","Excel 行高上限为 409pt，超高行已收敛至 409pt；单元格值完整保留，显示范围可能受限")}}async function re(e,t){const r=e.flow?q(e.pages,e.continuous).map(i=>({comp:i,pageIndex:e.pages[0].index})):e.pages.flatMap(({page:i,index:a},s)=>i.components.filter(c=>!e.continuous||(c.pageAnchor!=="header"||s===0)&&(c.pageAnchor!=="footer"||s===e.pages.length-1)).map(c=>({comp:c,pageIndex:a}))),n=new Map;let o=1,l=0;for(const{comp:i}of r)if(i.grid){const a=A.resolveGridLayout(i.grid,i.widthMm,i.heightMm);n.set(i,a),o=Math.max(o,a.columns.length);const s=t(a.cells.length);s&&await s}else i.kind==="text"&&(l=Math.max(l,i.widthMm));if(o>16384)throw new Error("Excel 最多支持 16384 列，无法无损导出此报表");return{components:r,grids:n,columnCount:o,textWidthMm:l}}function oe(e,t,r){const{page:n,index:o}=e.pages[0],l=t!==void 0&&t!=="auto";return(e.continuous||C(n))&&!l?{}:{pageSetup:{paperSize:K(n,t,o,r),orientation:n.pageWidthMm>n.pageHeightMm?"landscape":"portrait",fitToPage:!0,...e.continuous?{fitToWidth:1,fitToHeight:0}:{}}}}function le(e){const t=p(e.borderColor??e.lineColor),r={style:"thin",...t?{color:{argb:t}}:{}};return{...e.borderTop!==!1?{top:r}:{},...e.borderLeft!==!1?{left:r}:{},...e.borderBottom!==!1?{bottom:r}:{},...e.borderRight!==!1?{right:r}:{}}}function ae(e,t){e.alignment={horizontal:t.align??"left",vertical:t.verticalAlign??"middle",wrapText:!0};const r=p(t.backgroundColor);r&&(e.fill={type:"pattern",pattern:"solid",fgColor:{argb:r}}),e.border=le(t),T(e,t)}function se(e,t){for(const[r,n]of t.columns.entries()){const o=e.sheet.getColumn(r+1),l=e.limits.column(w.mmToExcelColumnWidth(n.size));(o.width==null||o.width<l)&&(o.width=l)}}function ce(e,t,r){for(const[n,o]of t.rows.entries()){const l=e.sheet.getRow(r+n),i=e.limits.row(o.size*F);(l.height==null||l.height<i)&&(l.height=i)}}function de(e,t,r,n){const o=Math.max(1,Math.min(t.cell.colSpan??1,r.columns.length-t.ci)),l=Math.max(1,Math.min(t.cell.rowSpan??1,r.rows.length-t.ri));(o>1||l>1)&&e.mergeCells(n+t.ri,t.ci+1,n+t.ri+l-1,t.ci+o)}async function he(e,t,r,n,o){if(n+r.rows.length-1>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");ce(e,r,n);for(const l of r.cells){const i=e.sheet.getCell(n+l.ri,l.ci+1);J(i,l.cell,e.valueMode,e.warnings),l.cell.children?.length&&e.warnings.push(`page ${o+1} ${t.nid??t.kind} cell ${l.ri+1}:${l.ci+1}: 嵌套组件内容暂不支持 xlsx 导出，已跳过`),ae(i,b.mergeComponentStyles(t.style,l.cell.style)),l.cell.indentMm&&(i.alignment={...i.alignment,indent:Math.min(250,Math.max(1,Math.round(l.cell.indentMm/2.5)))}),de(e.sheet,l,r,n);const a=e.schedule();a&&await a}return n+r.rows.length}function ue(e,t,r,n){const o=Array.isArray(t.lines)&&t.lines.length>0?t.lines.join(`
-`):t.text??"",l=e.sheet.getRow(r),i=l.getCell(1);t.richParagraphs?.length||M(o,i.address),i.value=t.richParagraphs?.length?{richText:t.richParagraphs.flatMap((s,c)=>[...c?[{text:`
-`}]:[],...s.segments.map(d=>{const h=b.mergeComponentStyles(t.style,d.style);return{text:d.kind==="field"?d.field??"":d.text??"",font:{name:h.fontFamily,bold:h.bold,italic:h.italic,underline:h.underline,size:b.resolveFontSize(h).fontSizePt,...p(h.color)?{color:{argb:p(h.color)}}:{}}}})])}:o,typeof i.value=="object"&&i.value&&"richText"in i.value&&M(i.value.richText.map(s=>s.text).join(""),i.address),i.alignment={horizontal:t.style?.align??"left",vertical:t.style?.verticalAlign??"middle",wrapText:!0};const a=p(t.style?.backgroundColor);return a&&(i.fill={type:"pattern",pattern:"solid",fgColor:{argb:a}}),T(i,t.style),n>1&&e.sheet.mergeCells(r,1,r,n),l.height=e.limits.row(t.heightMm*F),r+1}function ge(e,t,r){const n=t+r-1;e.views=[{state:"frozen",ySplit:n,xSplit:0}],e.pageSetup.printTitlesRow=`1:${n}`}async function fe(e,t,r,n){!t.grids.size&&t.textWidthMm>0&&(e.sheet.getColumn(1).width=e.limits.column(w.mmToExcelColumnWidth(t.textWidthMm)));for(const i of t.grids.values()){se(e,i);const a=e.schedule(i.columns.length);a&&await a}let o=1,l=!1;for(const{comp:i,pageIndex:a}of t.components){const s=r&&i.table?.role==="header";if(s&&l)continue;if(o>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");const c=t.grids.get(i);if(c)s&&(ge(e.sheet,o,c.rows.length),l=!0),o=await he(e,i,c,o,a);else if(i.kind==="text")o=ue(e,i,o,t.columnCount);else if(R.isImageBackedComponent(i)){const d=w.importedImageOverlay(i,r),h=n.write(e.sheet,i,d?.row??o,d);d||(o=h)}else e.warnings.push(`page ${a+1} ${i.nid??i.kind}: 组件类型 ${i.kind} 暂不支持 xlsx 导出，已跳过`)}}function me(e){if(e.valueMode!==void 0&&e.valueMode!=="text"&&e.valueMode!=="raw")throw new Error("xlsx valueMode 必须是 text 或 raw");if(e.paperSize!==void 0&&e.paperSize!=="auto"&&!Object.prototype.hasOwnProperty.call(S,e.paperSize))throw new Error("xlsx paperSize 必须是 auto、a3、a4 或 a5");if(e.sheetMode!==void 0&&!["auto","pages","continuous"].includes(e.sheetMode))throw new Error("xlsx sheetMode 必须是 auto、pages 或 continuous")}async function we(e,t={}){me(t),E.assertOutputActive(t.signal);const r=z.reportOutputDiagnostics(e,"xlsx",t),n=new w.ExcelJSRuntime.Workbook,o=[],l=G(n,t,o),i=ie(o),a=Z(e,t.sheetMode,o),s=new Set,c=E.createOutputScheduler(t);for(const[h,u]of a.entries()){const g=await re(u,c);u.continuous&&!u.flow&&te(u,g.grids);const f=u.pages[0].page,x=t.sheetName?.(h)??ne(u.title,h,s);s.add(x.toLowerCase());const y=n.addWorksheet(x,oe(u,t.paperSize,o)),I=t.valueMode??(C(f)||u.continuous||u.flow?"raw":"text");E.assertOutputActive(t.signal),await fe({sheet:y,warnings:o,limits:i,valueMode:I,schedule:c},g,u.continuous,l),await E.outputCheckpoint(t,h+1,a.length)}E.assertOutputActive(t.signal);const d=await n.xlsx.writeBuffer();return E.assertOutputActive(t.signal),{workbook:n,buffer:d,warnings:o,diagnostics:r}}exports.importExcelTemplate=w.importExcelTemplate;exports.inspectExcelWorkbook=w.inspectExcelWorkbook;exports.openExcelWorkbook=w.openExcelWorkbook;exports.bindExcelTemplate=m.bindExcelTemplate;exports.createExcelBindingDocument=m.createExcelBindingDocument;exports.createExcelBindingSession=m.createExcelBindingSession;exports.createExcelRegionBindingDocument=m.createExcelRegionBindingDocument;exports.createExcelRegionBindingSession=m.createExcelRegionBindingSession;exports.excelBindingCellRange=m.excelBindingCellRange;exports.excelBindingRowRange=m.excelBindingRowRange;exports.getExcelSheetWindow=m.getExcelSheetWindow;exports.parseExcelBindingSession=m.parseExcelBindingSession;exports.parseExcelRegionBindingSession=m.parseExcelRegionBindingSession;exports.validateExcelBindingFields=m.validateExcelBindingFields;exports.validateExcelBindingRecipe=m.validateExcelBindingRecipe;exports.validateExcelBindingRegions=m.validateExcelBindingRegions;exports.validateExcelRegionBindings=m.validateExcelRegionBindings;exports.validateExcelRegionFields=m.validateExcelRegionFields;exports.validateExcelRegionGeometry=m.validateExcelRegionGeometry;exports.renderPlanToXlsx=we;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const w=require("./style-C22Pbv3T.cjs"),x=require("./progress-B0ctFpKf.cjs"),p=require("./workbook-session-DN5LSA5C.cjs"),C=require("./component-tree-DkGLEfZC.cjs"),N=require("./media-B7vnpD8k.cjs"),A=require("./grid-geometry-CZ_cYB6O.cjs"),R=require("./assets-Dfs2ElxI.cjs"),m=require("./region-binding-workflow-O2Cni3mF.cjs");function B(e,t){return{richText:e.flatMap((o,n)=>[...n?[{text:`
+`}]:[],...o.segments.map(r=>{const s=w.mergeComponentStyles(t,r.style),i=s.color?.replace(/^#/,"");return{text:r.kind==="field"?r.field??"":r.text??"",font:{name:s.fontFamily,bold:s.bold,italic:s.italic,underline:s.underline,size:w.resolveFontSize(s).fontSizePt,.../^[a-f\d]{6}$/i.test(i??"")?{color:{argb:`FF${i.toUpperCase()}`}}:{}}}})])}}function L(e,t){const o=e.children?.filter(s=>s.kind==="text"&&!s.grid)??[];if(!e.richParagraphs?.length&&!o.length)return;const n=w.mergeComponentStyles(t,e.style),r=e.richParagraphs?.length?[...e.richParagraphs]:e.text?[{segments:[{text:e.text}]}]:[];for(const s of o){const i=w.mergeComponentStyles(n,s.style),l=s.richParagraphs?.length?s.richParagraphs:[{segments:[{text:s.lines?.join(`
+`)??s.text??""}]}];for(const a of l)r.push({...a,segments:a.segments.map(c=>({...c,style:w.mergeComponentStyles(i,c.style)}))})}return B(r,n)}function G(e,t,o){let n=o*72/25.4;if(!Number.isFinite(n)||t+Math.ceil(n/409)-1>1048576)throw new Error("Excel 图片占位超过工作表行数上限");for(;n>0;){if(t>1048576)throw new Error("Excel 图片占位超过工作表行数上限");const r=Math.min(409,n);e.getRow(t++).height=r,n-=r}return t}function j(e,t,o){let n=Math.round(t*36e3),r=0;if(!Number.isSafeInteger(n))throw new Error("Excel 图片锚点超出安全坐标范围");for(e.properties.defaultColWidth??=8.43;r<16384;){const s=e.getColumn(r+1).width??e.properties.defaultColWidth,i=Math.round(p.excelColumnWidthToMm(s)*36e3);if(!Number.isSafeInteger(i)||i<=0)throw new Error("Excel 图片锚点所在列宽无效");if(n<i)return{col:r+n/i,row:o-1,nativeCol:r,nativeColOff:n,nativeRow:o-1,nativeRowOff:0};n-=i,r++}throw new Error("Excel 图片锚点超过16384列上限")}function D(e,t,o){let n=o*72/25.4;if(!Number.isFinite(n)||Math.abs(n)>1048576*409)throw new Error("Excel 图片纵向偏移超过工作表范围");const r=s=>{const i=e.getRow(s).height??e.properties.defaultRowHeight??15;if(!Number.isFinite(i)||i<=0)throw new Error("Excel 图片锚点所在行高无效");return i};for(;n<0&&t>1;)n+=r(--t);for(;t<=1048576&&n>=r(t);)n-=r(t++);if(t>1048576||n<0)throw new Error("Excel 图片移动到工作表边界之外");return{nativeRow:t-1,nativeRowOff:Math.round(n*25.4/72*36e3)}}function H(e,t,o){const n=N.createImageMediaInspector(t),r=new Map;return{write(s,i,l,a){if(![i.widthMm,i.heightMm,i.leftMm].every(Number.isFinite)||i.widthMm<0||i.heightMm<0||i.leftMm<0)throw new Error("Excel 图片尺寸无效");if(!i.widthMm||!i.heightMm)return l;if(!i.imageData||!/^data:image\/(png|jpe?g);base64,/i.test(i.imageData))return o.push(`${i.nid??i.kind}: Excel 图片仅支持 PNG/JPEG data URI，已跳过`),l;const c=n(i.imageData);let d=r.get(c.dataUrl);d===void 0&&(d=e.addImage({base64:c.dataUrl,extension:c.extension}),r.set(c.dataUrl,d));const g=a?l:G(s,l,i.heightMm);return s.addImage(d,{tl:{...j(s,a?.leftMm??i.leftMm,l),...a?D(s,l,a.offsetMm):{}},ext:{width:i.widthMm*96/25.4,height:i.heightMm*96/25.4},editAs:"oneCell"}),g}}}function F(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function W(e,t){const o=e.meta?.xlsxFlow;if(o===void 0)return;if(!F(o)||o.version!=="1.0"||!Number.isSafeInteger(o.columnStart)||Number(o.columnStart)<0)throw new Error("Excel 多区域几何标记无效，不能按列序猜测输出");if(!e.grid)throw new Error("Excel 多区域输出只接受显式网格组件");const n=o,r=e.grid.colWidthsMm;if(!r?.length||n.columnStart+r.length>t.length||r.some((s,i)=>Math.abs(s-t[n.columnStart+i])>.001))throw new Error("Excel 多区域列位置与网格列宽不一致");return n}function P(e){const t=e.meta?.xlsxFlow;if(t===void 0){if(e.components.some(n=>n.meta?.xlsxFlow!==void 0))throw new Error("Excel 多区域页面缺少完整列几何标记");return}const o=_(t,e.meta?.reportScope);for(const n of e.components){const r=W(n,o.widths);if(!r)throw new Error("Excel 多区域页面混入没有区域几何的组件，请使用独立页面模板");const s=o.widths.slice(0,r.columnStart).reduce((l,a)=>l+a,e.marginLeftMm??0),i=n.grid.colWidthsMm.reduce((l,a)=>l+a,0);if(Math.abs(s-n.leftMm)>.01||Math.abs(i-n.widthMm)>.01)throw new Error("Excel 多区域标记与真实横向位置不一致")}return o}function _(e,t){if(!F(e)||e.version!=="1.0"||typeof e.sheet!="string"||!e.sheet.trim()||typeof e.templateId!="string"||!e.templateId.trim())throw new Error("Excel 多区域工作表标识无效");if(!Array.isArray(e.fullWidthsMm)||!e.fullWidthsMm.length||e.fullWidthsMm.length>16384||e.fullWidthsMm.some(o=>typeof o!="number"||!Number.isFinite(o)||o<=0||o>2e3))throw new Error("Excel 多区域完整列宽无效");if(t!==void 0&&(typeof t!="string"||!t.trim()))throw new Error("Excel 多区域报表命名空间无效");return{key:JSON.stringify([t??e.templateId,e.sheet]),sheet:e.sheet,widths:e.fullWidthsMm}}function v(e){return Math.round(e*1e6)/1e6}function q(e,t,o,n,r){return e.components.filter(s=>n?s.pageAnchor==="header"?t===0:s.pageAnchor==="footer"?t===o-1:s.table?.role!=="header"?!0:r.has(s.table.id)?!1:(r.add(s.table.id),!0):!0)}function U(e,t,o,n){const r=e.components.filter(i=>!t.includes(i)&&i.table?.role==="header"),s=t.filter(i=>!i.pageAnchor).reduce((i,l)=>Math.max(i,l.topMm+l.heightMm),e.marginTopMm??0);return t.map(i=>{let l=i.topMm;return o&&i.pageAnchor==="footer"&&(l=s),l-=r.filter(a=>a.topMm+a.heightMm<=l+.001).reduce((a,c)=>a+c.heightMm,0),{component:i,layout:A.resolveGridLayout(i.grid,i.widthMm,i.heightMm),top:l,column:W(i,n).columnStart}})}function X(e,t,o){const n=t.length-1;if(n*o.length>1e6)throw new Error("Excel 多区域单页超过 100 万几何单元格，请减小预览分页高度或列数");const r=new Map(t.map((l,a)=>[l,a])),s=new Map,i=new Map;for(const l of e)for(const a of l.layout.cells){if(!Object.keys(a.cell).length)continue;const c=r.get(v(l.top+a.yMm)),d=r.get(v(l.top+a.yMm+a.heightMm)),g=l.column+a.ci,u=g+(a.cell.colSpan??1),h=`${c}:${g}`;for(let f=c;f<d;f++)for(let E=g;E<u;E++){const b=`${f}:${E}`;if(i.has(b))throw new Error("Excel 多区域实际单元格互相覆盖，已终止输出，未覆盖已有内容");i.set(b,h)}s.set(h,{...a.cell,style:w.mergeComponentStyles(l.component.style,a.cell.style),rowSpan:d-c,colSpan:u-g})}return Array.from({length:n},(l,a)=>{const c=[];for(let d=0;d<o.length;d++){const g=`${a}:${d}`,u=s.get(g);u?(c.push(u),d+=(u.colSpan??1)-1):i.has(g)||c.push(null)}return c})}function K(e,t){const o=new Set,n=[];let r;for(const[s,{page:i}]of e.entries()){const l=P(i);if(r&&(l.key!==r.key||l.widths.length!==r.widths.length||l.widths.some((h,f)=>Math.abs(h-r.widths[f])>.001)))throw new Error("Excel 多区域分页的工作表或列结构不一致");r??=l;const a=q(i,s,e.length,t,o),c=U(i,a,t,l.widths);if(!c.length)continue;const d=[...new Set(c.flatMap(h=>[...h.layout.rows.map(f=>v(h.top+f.pos)),v(h.top+h.component.heightMm)]))].sort((h,f)=>h-f),g=X(c,d,l.widths),u=d.slice(1).map((h,f)=>h-d[f]);n.push({kind:"rect",leftMm:0,topMm:0,widthMm:l.widths.reduce((h,f)=>h+f,0),heightMm:u.reduce((h,f)=>h+f,0),grid:{cells:g,colWidthsMm:l.widths,rowHeightsMm:u}})}return n}const $=72/25.4,J=32767,V=253;function M(e,t){if(typeof e!="string")return;if(e.length>J)throw new Error(`Excel 单元格 ${t} 最多支持 32767 个字符，无法无损导出；内容未裁剪`);let o=0;for(let n=0;n<e.length;n++)if(e.charCodeAt(n)===10&&++o>V)throw new Error(`Excel 单元格 ${t} 最多支持 253 个换行，无法无损导出；内容未改写`)}function y(e){if(!e)return;const t=e.replace("#","");return/^[0-9a-fA-F]{6}$/.test(t)?`FF${t.toUpperCase()}`:void 0}function I(e,t={}){e.font={name:t.fontFamily,bold:t.bold===!0,italic:t.italic===!0,underline:t.underline===!0,size:w.resolveFontSize(t).fontSizePt,color:y(t.color)?{argb:y(t.color)}:void 0}}const S={a3:{width:297,height:420,code:8},a4:{width:210,height:297,code:9},a5:{width:148,height:210,code:11}};function Q(e,t,o,n){if(t&&t!=="auto")return S[t].code;const r=Math.min(e.pageWidthMm,e.pageHeightMm),s=Math.max(e.pageWidthMm,e.pageHeightMm),i=Object.values(S).find(l=>Math.abs(r-l.width)<=1&&Math.abs(s-l.height)<=1);return i?i.code:(n.push(`page ${o+1}: 自定义纸张 ${e.pageWidthMm}×${e.pageHeightMm}mm 无对应 Excel 纸型，打印设置回退 A4；可显式配置 paperSize`),S.a4.code)}function Y(e,t,o,n){const r=typeof t.text=="string"?t.text:"";if(o!=="raw"||!Object.prototype.hasOwnProperty.call(t,"value")){M(r,e.address),e.value=r;return}const s=t.value;if(s===null||typeof s=="string"||typeof s=="boolean"||typeof s=="number"&&Number.isFinite(s)){M(s,e.address),e.value=s,t.numberFormat&&(e.numFmt=t.numberFormat);return}M(r,e.address),e.value=r,n.push(`原始单元格值无效，已保留显示文本：${e.address}`)}function Z(e){const t=P(e);return t?{id:`xlsx-flow:${t.key}`,title:t.sheet,wide:!0,flow:!0}:ee(e)}function ee(e){const o=e.components.filter(n=>n.table!==void 0)[0]?.table;if(!(!o||typeof o.id!="string"||!o.id.trim()||!Array.isArray(o.columnKeys)||!o.columnKeys.length)){for(const n of e.components){if(n.table){if(!n.grid||n.table.id!==o.id)return;continue}if(n.grid||n.kind!=="text"&&!C.isImageBackedComponent(n))return}return{id:o.id,title:o.title,wide:o.layout==="wide"||e.layout==="wide"}}}function te(e,t){const o=new Set;for(const[n,r]of e.pages.entries())if(!t[n])for(const s of r.components)typeof s.table?.id=="string"&&o.add(s.table.id);return o}function k(e){return e.layout==="wide"||e.components.some(t=>t.table?.layout==="wide")}function ne(e,t,o){const n=[],r=e.pages.map(Z),s=te(e,r);for(const[i,l]of e.pages.entries()){const a=r[i],c=a&&!s.has(a.id),d=t==="pages"||!c?void 0:a;if(t==="continuous"&&!d)throw new Error(`page ${i+1}: continuous Excel 需要完整、单一的逻辑表来源；自由布局请使用 sheetMode: 'pages'`);const g=d!==void 0&&(t==="continuous"||d.wide);!g&&t!=="pages"&&k(l)&&o.push(`page ${i+1}: 混合或缺少逻辑表来源，已保留独立 Sheet，未猜测合并内容`);const u=n[n.length-1];g&&u?.continuous&&u.tableId===d.id?u.pages.push({page:l,index:i}):n.push({pages:[{page:l,index:i}],continuous:g,...g?{tableId:d.id,title:d.title}:{},...a?.flow?{flow:!0,title:a.title}:{}})}return n}function T(e,t,o){return!e||e.length===t.length&&e.every((n,r)=>o(n,t[r]))}function ie(e,t,o,n){const r=e.table,s=t.columns.map(a=>a.size),i=T(n.keys,r.columnKeys,(a,c)=>a===c),l=T(n.widths,s,(a,c)=>Math.abs(a-c)<=.001);if(r.columnKeys.length!==s.length||!i||!l)throw new Error(`page ${o+1}: 连续 Excel 逻辑表 ${r.id} 的列结构或列宽不一致`);if(n.keys??=r.columnKeys,n.widths??=s,r.role==="header"){if(r.rowIndex!==-1)throw new Error(`page ${o+1}: 连续 Excel 表头 rowIndex 必须为 -1`);n.headerSeen=!0}else{if(!["body","group-header","subtotal","grand-total"].includes(r.role)||r.rowIndex!==n.expectedRow)throw new Error(`page ${o+1}: 连续 Excel 逻辑行来源不连续或重复（期望 ${n.expectedRow}）`);n.expectedRow+=t.rows.length}}function re(e,t){const o={expectedRow:0,headerSeen:!1};for(const{page:n,index:r}of e.pages)for(const s of n.components){const i=t.get(s);s.table&&i&&ie(s,i,r,o)}if(!o.headerSeen)throw new Error("连续 Excel 逻辑表缺少明确表头来源")}function oe(e,t,o){let n=(e?.replace(/[\\/*?:[\]]/g," ").replace(/\s+/g," ").trim()||`Sheet${t+1}`).slice(0,31).replace(/^'+|'+$/g,"").trim()||`Sheet${t+1}`;n.toLowerCase()==="history"&&(n+=" 报表");let r=n,s=1;for(;o.has(r.toLowerCase());){const i=` (${++s})`;r=n.slice(0,31-i.length)+i}return o.add(r.toLowerCase()),r}function se(e){const t=new Set;function o(n,r,s,i){return n<=r?n:(t.has(s)||(e.push(i),t.add(s)),r)}return{column:n=>o(n,255,"column","Excel 单列宽度上限为 255 字符，超宽列已收敛至 255；单元格值完整保留，显示范围可能受限"),row:n=>o(n,409,"row","Excel 行高上限为 409pt，超高行已收敛至 409pt；单元格值完整保留，显示范围可能受限")}}async function le(e,t){const o=e.flow?K(e.pages,e.continuous).map(i=>({comp:i,pageIndex:e.pages[0].index})):e.pages.flatMap(({page:i,index:l},a)=>i.components.filter(c=>!e.continuous||(c.pageAnchor!=="header"||a===0)&&(c.pageAnchor!=="footer"||a===e.pages.length-1)).map(c=>({comp:c,pageIndex:l}))),n=new Map;let r=1,s=0;for(const{comp:i}of o)if(i.grid){const l=A.resolveGridLayout(i.grid,i.widthMm,i.heightMm);n.set(i,l),r=Math.max(r,l.columns.length);const a=t(l.cells.length);a&&await a}else i.kind==="text"&&(s=Math.max(s,i.widthMm));if(r>16384)throw new Error("Excel 最多支持 16384 列，无法无损导出此报表");return{components:o,grids:n,columnCount:r,textWidthMm:s}}function ae(e,t,o){const{page:n,index:r}=e.pages[0],s=t!==void 0&&t!=="auto";return(e.continuous||k(n))&&!s?{}:{pageSetup:{paperSize:Q(n,t,r,o),orientation:n.pageWidthMm>n.pageHeightMm?"landscape":"portrait",fitToPage:!0,...e.continuous?{fitToWidth:1,fitToHeight:0}:{}}}}function ce(e){const t=y(e.borderColor??e.lineColor),o={style:"thin",...t?{color:{argb:t}}:{}};return{...e.borderTop!==!1?{top:o}:{},...e.borderLeft!==!1?{left:o}:{},...e.borderBottom!==!1?{bottom:o}:{},...e.borderRight!==!1?{right:o}:{}}}function de(e,t){e.alignment={horizontal:t.align??"left",vertical:t.verticalAlign??"middle",wrapText:!0};const o=y(t.backgroundColor);o&&(e.fill={type:"pattern",pattern:"solid",fgColor:{argb:o}}),e.border=ce(t),I(e,t)}function he(e,t){for(const[o,n]of t.columns.entries()){const r=e.sheet.getColumn(o+1),s=e.limits.column(p.mmToExcelColumnWidth(n.size));(r.width==null||r.width<s)&&(r.width=s)}}function ge(e,t,o){for(const[n,r]of t.rows.entries()){const s=e.sheet.getRow(o+n),i=e.limits.row(r.size*$);(s.height==null||s.height<i)&&(s.height=i)}}function fe(e,t,o,n){const r=Math.max(1,Math.min(t.cell.colSpan??1,o.columns.length-t.ci)),s=Math.max(1,Math.min(t.cell.rowSpan??1,o.rows.length-t.ri));(r>1||s>1)&&e.mergeCells(n+t.ri,t.ci+1,n+t.ri+s-1,t.ci+r)}async function ue(e,t,o,n){if(n+o.rows.length-1>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");ge(e,o,n);for(const r of o.cells){const s=e.sheet.getCell(n+r.ri,r.ci+1);Y(s,r.cell,e.valueMode,e.warnings);const i=L(r.cell,t.style);i&&(M(i.richText.map(c=>c.text).join(""),s.address),s.value=i);const l=t.grid?.paddingMm??.5;for(const c of r.cell.children??[])C.isImageBackedComponent(c)&&!c.grid&&e.images.write(e.sheet,c,n+r.ri,{leftMm:r.xMm+l+(r.cell.indentMm??0)+c.leftMm,offsetMm:l+c.topMm});de(s,w.mergeComponentStyles(t.style,r.cell.style)),r.cell.indentMm&&(s.alignment={...s.alignment,indent:Math.min(250,Math.max(1,Math.round(r.cell.indentMm/2.5)))}),fe(e.sheet,r,o,n);const a=e.schedule();a&&await a}return n+o.rows.length}function me(e,t,o,n){const r=Array.isArray(t.lines)&&t.lines.length>0?t.lines.join(`
+`):t.text??"",s=e.sheet.getRow(o),i=s.getCell(1);t.richParagraphs?.length||M(r,i.address),i.value=t.richParagraphs?.length?B(t.richParagraphs,t.style):r,typeof i.value=="object"&&i.value&&"richText"in i.value&&M(i.value.richText.map(a=>a.text).join(""),i.address),i.alignment={horizontal:t.style?.align??"left",vertical:t.style?.verticalAlign??"middle",wrapText:!0};const l=y(t.style?.backgroundColor);return l&&(i.fill={type:"pattern",pattern:"solid",fgColor:{argb:l}}),I(i,t.style),n>1&&e.sheet.mergeCells(o,1,o,n),s.height=e.limits.row(t.heightMm*$),o+1}function we(e,t,o){const n=t+o-1;e.views=[{state:"frozen",ySplit:n,xSplit:0}],e.pageSetup.printTitlesRow=`1:${n}`}async function pe(e,t,o,n){!t.grids.size&&t.textWidthMm>0&&(e.sheet.getColumn(1).width=e.limits.column(p.mmToExcelColumnWidth(t.textWidthMm)));for(const i of t.grids.values()){he(e,i);const l=e.schedule(i.columns.length);l&&await l}let r=1,s=!1;for(const{comp:i,pageIndex:l}of t.components){const a=o&&i.table?.role==="header";if(a&&s)continue;if(r>1048576)throw new Error("Excel 最多支持 1048576 行，无法无损导出此报表");const c=t.grids.get(i);if(c)a&&(we(e.sheet,r,c.rows.length),s=!0),r=await ue(e,i,c,r);else if(i.kind==="text")r=me(e,i,r,t.columnCount);else if(C.isImageBackedComponent(i)){const d=p.importedImageOverlay(i,o),g=n.write(e.sheet,i,d?.row??r,d);d||(r=g)}else e.warnings.push(`page ${l+1} ${i.nid??i.kind}: 组件类型 ${i.kind} 暂不支持 xlsx 导出，已跳过`)}}function xe(e){if(e.valueMode!==void 0&&e.valueMode!=="text"&&e.valueMode!=="raw")throw new Error("xlsx valueMode 必须是 text 或 raw");if(e.paperSize!==void 0&&e.paperSize!=="auto"&&!Object.prototype.hasOwnProperty.call(S,e.paperSize))throw new Error("xlsx paperSize 必须是 auto、a3、a4 或 a5");if(e.sheetMode!==void 0&&!["auto","pages","continuous"].includes(e.sheetMode))throw new Error("xlsx sheetMode 必须是 auto、pages 或 continuous")}async function Me(e,t={}){xe(t),x.assertOutputActive(t.signal);const o=t.assetRegistry||t.assetRenderers?await R.resolvePlanAssets(e,{...t,format:"xlsx"}):{plan:e,diagnostics:[]};e=o.plan;const n=[...o.diagnostics,...R.reportOutputDiagnostics(e,"xlsx",t)],r=new p.ExcelJSRuntime.Workbook,s=[],i=H(r,t,s),l=se(s),a=ne(e,t.sheetMode,s),c=new Set,d=x.createOutputScheduler(t);for(const[u,h]of a.entries()){const f=await le(h,d);h.continuous&&!h.flow&&re(h,f.grids);const E=h.pages[0].page,b=t.sheetName?.(u)??oe(h.title,u,c);c.add(b.toLowerCase());const z=r.addWorksheet(b,ae(h,t.paperSize,s)),O=t.valueMode??(k(E)||h.continuous||h.flow?"raw":"text");x.assertOutputActive(t.signal),await pe({sheet:z,warnings:s,limits:l,valueMode:O,schedule:d,images:i},f,h.continuous,i),await x.outputCheckpoint(t,u+1,a.length)}x.assertOutputActive(t.signal);const g=await r.xlsx.writeBuffer();return x.assertOutputActive(t.signal),{workbook:r,buffer:g,warnings:s,diagnostics:n}}exports.importExcelTemplate=p.importExcelTemplate;exports.inspectExcelWorkbook=p.inspectExcelWorkbook;exports.openExcelWorkbook=p.openExcelWorkbook;exports.bindExcelTemplate=m.bindExcelTemplate;exports.createExcelBindingDocument=m.createExcelBindingDocument;exports.createExcelBindingSession=m.createExcelBindingSession;exports.createExcelRegionBindingDocument=m.createExcelRegionBindingDocument;exports.createExcelRegionBindingSession=m.createExcelRegionBindingSession;exports.excelBindingCellRange=m.excelBindingCellRange;exports.excelBindingRowRange=m.excelBindingRowRange;exports.getExcelSheetWindow=m.getExcelSheetWindow;exports.parseExcelBindingSession=m.parseExcelBindingSession;exports.parseExcelRegionBindingSession=m.parseExcelRegionBindingSession;exports.validateExcelBindingFields=m.validateExcelBindingFields;exports.validateExcelBindingRecipe=m.validateExcelBindingRecipe;exports.validateExcelBindingRegions=m.validateExcelBindingRegions;exports.validateExcelRegionBindings=m.validateExcelRegionBindings;exports.validateExcelRegionFields=m.validateExcelRegionFields;exports.validateExcelRegionGeometry=m.validateExcelRegionGeometry;exports.renderPlanToXlsx=Me;

package/dist/xlsx.d.cts

@@ -64,6 +64,27 @@ export declare type AnyExcelBindingDocumentResult = ExcelBindingDocumentResult |
 
 export declare type AnyExcelBindingSession = ExcelBindingSession | ExcelRegionBindingSession;
 
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+
+declare interface AssetRenderOptions extends OutputDiagnosticOptions, ImageMediaOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+
 declare type AutoFilter = string | {
     	from: string | { row: number; column: number };
     	to: string | { row: number; column: number };
@@ -414,6 +435,11 @@ declare interface CommentProtection {
     		lockText: 'True' | 'False';
     	}
 
+declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 declare interface ComponentBinding {
     field: string;
@@ -423,6 +449,16 @@ declare interface ComponentBinding {
     emptyText?: string;
 }
 
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
 declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
 declare interface ComponentStyle {
@@ -1152,6 +1188,8 @@ declare interface GradientStop {
 }
 
 declare interface GridCell {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -1243,6 +1281,8 @@ declare interface Image_2 {
     	buffer?: Buffer_2;
 }
 
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+
 declare interface ImageHyperlinkValue {
     	hyperlink: string;
     	tooltip?: string;
@@ -1433,6 +1473,26 @@ declare interface Margins {
     	footer: number;
 }
 
+declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+
+declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+
+declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -1447,6 +1507,10 @@ declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 
 declare interface Media {
@@ -1469,6 +1533,11 @@ declare interface OutputDiagnostic {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 
@@ -1831,7 +1900,15 @@ declare type ReportExpression = {
     args: readonly ReportExpression[];
 };
 
-declare interface ReportFieldContract {
+declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+
+declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+
+declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -1846,6 +1923,17 @@ declare interface ReportFieldContract {
     unit?: string;
 }
 
+declare interface ReportFieldSemantics {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat;
+    calculation?: ReportFieldCalculation;
+}
+
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -3062,7 +3150,7 @@ declare interface XlsxReadOptions {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 原生 richText 保留基础字形；未支持组件、段落专有排版与单元格嵌套组件计入 diagnostics / warnings
  */
-export declare interface XlsxRenderOptions extends OutputDiagnosticOptions, XlsxImageOptions {
+export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */

package/dist/xlsx.d.ts

@@ -64,6 +64,27 @@ export declare type AnyExcelBindingDocumentResult = ExcelBindingDocumentResult |
 
 export declare type AnyExcelBindingSession = ExcelBindingSession | ExcelRegionBindingSession;
 
+declare interface AssetRenderBudget {
+    /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
+    maxAssets?: number;
+    /** Maximum image payload bytes per new asset, default 32 MiB. */
+    maxImageBytes?: number;
+    /** Maximum total image payload bytes for new assets, default 128 MiB. */
+    maxTotalImageBytes?: number;
+    /** Wall-clock budget, including adapters that ignore AbortSignal. Default 30 seconds. */
+    maxDurationMs?: number;
+}
+
+declare interface AssetRenderOptions extends OutputDiagnosticOptions, ImageMediaOptions {
+    assetRenderers?: Partial<Record<ImageComponentKind, ComponentImageRenderer>>;
+    /** Explicit id/version registry; unbound components continue using assetRenderers by kind. */
+    assetRegistry?: ComponentAssetRegistry;
+    assetBudget?: AssetRenderBudget;
+    /** Default throw prevents an incomplete export; placeholder retains the component and emits diagnostics. */
+    assetFailure?: "throw" | "placeholder";
+    signal?: AbortSignal;
+}
+
 declare type AutoFilter = string | {
     	from: string | { row: number; column: number };
     	to: string | { row: number; column: number };
@@ -414,6 +435,11 @@ declare interface CommentProtection {
     		lockText: 'True' | 'False';
     	}
 
+declare interface ComponentAssetRegistry {
+    rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
+    hasExtension(id: string, version: string, kind: string): boolean;
+}
+
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
 declare interface ComponentBinding {
     field: string;
@@ -423,6 +449,16 @@ declare interface ComponentBinding {
     emptyText?: string;
 }
 
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
 declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
 
 declare interface ComponentStyle {
@@ -1152,6 +1188,8 @@ declare interface GradientStop {
 }
 
 declare interface GridCell {
+    /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
+    richParagraphs?: RichParagraph[];
     text?: string;
     rawText?: string;
     /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
@@ -1243,6 +1281,8 @@ declare interface Image_2 {
     	buffer?: Buffer_2;
 }
 
+declare type ImageComponentKind = "image" | "chart" | "barcode" | "qrcode";
+
 declare interface ImageHyperlinkValue {
     	hyperlink: string;
     	tooltip?: string;
@@ -1433,6 +1473,26 @@ declare interface Margins {
     	footer: number;
 }
 
+declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+
+declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+
+declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+
 declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -1447,6 +1507,10 @@ declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
 }
 
 declare interface Media {
@@ -1469,6 +1533,11 @@ declare interface OutputDiagnostic {
     componentPath?: readonly number[];
     kind: string;
     nid?: string;
+    /** Declarative extension identity only; no property values or business binding data enter diagnostics. */
+    extension?: {
+        id: string;
+        version: string;
+    };
     message: string;
 }
 
@@ -1831,7 +1900,15 @@ declare type ReportExpression = {
     args: readonly ReportExpression[];
 };
 
-declare interface ReportFieldContract {
+declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
+
+declare interface ReportFieldCalculation {
+    /** Business-owned explanation, never executable JavaScript or an inferred business formula. */
+    description: string;
+    dependsOn: readonly string[];
+}
+
+declare interface ReportFieldContract extends ReportFieldSemantics {
     field: string;
     label?: string;
     type: "text" | "number" | "boolean" | "date" | "decimal";
@@ -1846,6 +1923,17 @@ declare interface ReportFieldContract {
     unit?: string;
 }
 
+declare interface ReportFieldSemantics {
+    description?: string;
+    /** Explicit meaning of null/missing; does not convert blanks into zero. */
+    missingMeaning?: string;
+    /** Recommended aggregation; none marks non-additive measures such as ratios. No aggregation runs implicitly. */
+    aggregation?: ReportFieldAggregation;
+    /** Shared presentation only; raw values and calculation precision remain unchanged. */
+    format?: ColumnFormat;
+    calculation?: ReportFieldCalculation;
+}
+
 declare interface ReportFlowBand {
     /** Exact stable component IDs. Static components use nid, lists use id. */
     componentIds: string[];
@@ -3062,7 +3150,7 @@ declare interface XlsxReadOptions {
  *   目标是"财务能直接用的对账表"而非复刻版面）
  * - 原生 richText 保留基础字形；未支持组件、段落专有排版与单元格嵌套组件计入 diagnostics / warnings
  */
-export declare interface XlsxRenderOptions extends OutputDiagnosticOptions, XlsxImageOptions {
+export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImageOptions {
     /** 工作表命名（连续表默认使用标题，其余默认 "Sheet1" 起序）。 */
     sheetName?: (sheetIndex: number) => string;
     /** auto 默认将 wide 逻辑表合并为连续 Sheet；pages 保留逐页；continuous 要求明确的表来源。 */