توثيق HotXLS

أعضاء API إضافية في واجهة XLSX

تغطي هذه الصفحة أعضاء API العامة الأصغر المعلَنة بواسطة lxHandleX، بما في ذلك خيارات تصدير HTML والدوال المساعدة للمستدعين الذين يعملون مباشرةً مع مراجع خلايا XLSX أو نص حمولة XML

حد ذاكرة مصفوفة الصيغ

property FormulaArrayMemoryLimit: Int64;
      
يحدّ من الحمولة المخصصة لمصفوفات الصيغ المولَّدة مثل MUNIT، وافتراضيه 64 ميبيبايت، وينطبق على عمّال إعادة الحساب المتوازية، ويحصر القيم دون عنصر Double واحد

خيارات تصدير HTML

type
  TXLSXHtmlExportOptions = class
    constructor Create;
    property Title: WideString;
    property WriteDocument: Boolean;
    property IncludeStyles: Boolean;
    property IncludeBOM: Boolean;
    property TableClass: WideString;
  end;
      
Title يضبط عنوان المستند عندما تكون WriteDocument بالقيمة True
WriteDocument عندما تكون بالقيمة True، يكتب مستند HTML كاملًا. وعندما تكون بالقيمة False، يكتب مقطع الجدول فقط
IncludeStyles يتحكم فيما إذا كان HTML المصدَّر يتضمن CSS مولَّدًا ومعلومات الأنماط المضمَّنة
IncludeBOM يتحكم فيما إذا كان إخراج الملف والتدفق يبدأ بـ BOM ‏UTF-8
TableClass يضيف اسم فئة CSS إلى عنصر <table> المولَّد

الدوال المساعدة لمراجع XLSX

function XlsxColumnLabel(Col: Integer): WideString;
function XlsxCellRef(Row, Col: Integer): WideString;
function XlsxColumnIndex(const ColumnLabel: WideString): Integer;
function XlsxParseCellRef(const Ref: WideString; out Row, Col: Integer): Boolean;
function XlsxParseRangeRef(const Ref: WideString; out Row1, Col1, Row2, Col2: Integer): Boolean;
      
XlsxColumnLabel يحوّل فهرس عمود قائمًا على الواحد إلى تسمية عمود بأسلوب A1 مثل A وZ وAA
XlsxCellRef يبني مرجع خلية بأسلوب A1 من رقمَي صف وعمود قائمَين على الواحد
XlsxColumnIndex يحوّل تسمية عمود بأسلوب A1 إلى فهرس عمود قائم على الواحد
XlsxParseCellRef يحلل مرجع خلية واحدًا بأسلوب A1 ويعيد إحداثيات الصف والعمود
XlsxParseRangeRef يحلل نطاقًا مستطيلًا بأسلوب A1 ويعيد حدودًا شاملة قائمة على الواحد

الدوال المساعدة لإفلات أحرف XML في XLSX

function XlsxEscapeText(const Value: WideString): WideString;
function XlsxEscapeAttr(const Value: WideString): WideString;
      
تُفلِت XlsxEscapeText محتوى عقدة نص XML، بينما تُفلِت XlsxEscapeAttr قيم سمات XML وتحافظ على المسافة البيضاء في السمة التي يجب أن تقرأها Excel بشكل مطابق

الأنواع الداعمة لأعضاء XLSX المتقدمة

يمرّر أعضاء XLSX المتقدمة الموثقة في ملف المساعدة هذا النوعَ البسيطة التالية ويعيدها، والمعلَنة في lxHandleX

{ Find and replace }
TXLSXFindFlag = (lxfMatchCase, lxfWholeCell, lxfSearchFormulas,
  lxfUseWildcards, lxfBackward, lxfByColumns);
TXLSXFindOptions = set of TXLSXFindFlag;
TXLSXReplaceAction = (raReplace, raSkip, raAbort);
TXLSXReplaceEvent = function(ARow, ACol: Integer;
  const ACurrentText: WideString; var ANewText: WideString):
  TXLSXReplaceAction of object;

{ Progress and recalculation policy }
TXLSXProgressPhase = (xlsxProgressReading, xlsxProgressWriting,
  xlsxProgressCalculating, xlsxProgressExporting);
TXLSXProgressState = (ppsBegin, ppsWork, ppsEnd);
TXLSXRecalcMode = (xrmManual, xrmIfDirty, xrmAlways);
TXLSXPasswordEvent = procedure(Sender: TObject;
  var PassWord: WideString) of object;

{ Custom document properties (docProps/custom.xml) }
TXLSXCustomPropType = (xcptText, xcptNumber, xcptDate, xcptBoolean);
TXLSXCustomProperty = class
  Name: WideString;
  PropType: TXLSXCustomPropType;
{ + TextValue, NumberValue, DateValue, BoolValue accessors }
end;

{ Table styles, fills, sorts, external links, controls, sparklines }
TXLSXTableStyleSectionKind = (xltssWholeTable, xltssHeaderRow,
  xltssTotalRow, xltssFirstColumn, xltssLastColumn, xltssFirstRowStripe,
  xltssSecondRowStripe, xltssFirstColumnStripe, xltssSecondColumnStripe,
  xltssFirstHeaderCell, xltssLastHeaderCell, xltssFirstTotalCell,
  xltssLastTotalCell { + subtotal and subheading slots });
TXLSXFillPattern = (xlsxFillNone, xlsxFillSolid, xlsxFillGray125
  { + the remaining ECMA-376 pattern values });
TXLSXGradientKind = (xlsxGradientNone, xlsxGradientLinear, xlsxGradientPath);
TXLSXSortBy = (xlsxBsValue, xlsxBsCellColor, xlsxBsFontColor, xlsxBsIcon);
TXLSXSortMethod = (xlsxSmNone, xlsxSmStroke, xlsxSmPinYin);
TXLSXExternalLinkKind = (xlsxExternalLinkUnknown, xlsxExternalLinkWorkbook,
  xlsxExternalLinkDde { + the remaining link kinds });
TXLSXFormControlType = (xfcButton, xfcCheckBox, xfcRadioButton, xfcComboBox,
  xfcListBox);
TXLSXSparklineAxisType = (xlsxSparklineAxisIndividual,
  xlsxSparklineAxisGroup, xlsxSparklineAxisCustom);
TXLSXSparklineEmptyCells = (xlsxSparklineEmptyGap, xlsxSparklineEmptyZero,
  xlsxSparklineEmptySpan);

{ Chart authoring and layout }
TXLSXChartBarGrouping = (xlsxBarGroupClustered, xlsxBarGroupStacked,
  xlsxBarGroupPercentStacked);
TXLSXChartMarkerSymbol = (xlsxMarkerAuto, xlsxMarkerCircle, xlsxMarkerDash,
  xlsxMarkerDiamond, xlsxMarkerDot, xlsxMarkerPlus, xlsxMarkerSquare,
  xlsxMarkerStar, xlsxMarkerTriangle, xlsxMarkerX, xlsxMarkerNone);
TXLSXChartDataLabelPos = (xlsxDlblPosDefault, xlsxDlblPosCenter,
  xlsxDlblPosInEnd, xlsxDlblPosOutEnd, xlsxDlblPosBestFit, xlsxDlblPosLeft,
  xlsxDlblPosRight, xlsxDlblPosTop, xlsxDlblPosBottom);
TXLSXChartMutable = class;     { mutable base of the chart model nodes }
TXLSXChartLayoutRect = record
  Left, Top, Right, Bottom: Double;
end;
TXLSXChartResolvedLayout = record
  ChartRect: TXLSXChartLayoutRect;
  TitleRect: TXLSXChartLayoutRect;
  LegendRect: TXLSXChartLayoutRect;
  PlotOuterRect: TXLSXChartLayoutRect;
  PlotInnerRect: TXLSXChartLayoutRect;
  { + per-axis title rectangles and visibility flags }
end;

{ Pagination keep-together blocks }
TXLSXKeepTogetherRange = record
  Row1, Row2: Integer;
  Level: Integer;
  ReplaceBiggerLevels: Boolean;
end;
TXLSXKeepTogetherCols = record
  Col1, Col2: Integer;
  Level: Integer;
  ReplaceBiggerLevels: Boolean;
end;

{ Diagnostics records }
TXLSXValidationIssue = record
  Row, Col: Integer;
  ValidationIndex: Integer;
  Reason: WideString;
end;
TXLSXUnknownFunctionInfo = record
  Sheet: Integer;
  Row, Col: Integer;
  Name: WideString;
  LocationKind: TXLSFormulaSymbolLocationKind;
  DefinedNameIndex: Integer;
  DefinedName: WideString;
end;
TXLSXRowMajorOrder = record
  CellOrder: array of Integer;
  RowStarts: array of Integer;
  MaxRow: Integer;
end;
      
Find and replaceتقبل TXLSXWorksheet.FindText / FindTextIn ‏TXLSXFindOptions (مطابقة حالة الأحرف، الخلية الكاملة، البحث في الصيغ، البدائل، المسح العكسي، المسح بالأعمدة) ويأخذ ReplaceText ‏TXLSXReplaceEvent تختار نتيجته raReplace أو raSkip أو raAbort لكل مطابقة، مع ANewText قابل للكتابة للاستبدالات لكل خلية
Progress and savingيوصل TXLSXWorkbook.OnProgress / OnProgressEx ‏TXLSXProgressPhase و(في الشكل الموسع) TXLSXProgressState مع علم Abort؛ وRecalcBeforeSave من نوع TXLSXRecalcMode يختار إعادة حساب يدوية أو للمتغيرات المتسخة فقط أو دائمة قبل التسلسل؛ وOnPassword من نوع TXLSXPasswordEvent يزود كلمتي مرور الفتح والكتابة
Custom propertiesTXLSXWorkbook.CustomProperties مجموعة TXLSXCustomProperties بمنشئات مكتوبة الأنواع AddText / AddNumber / AddDate / AddBoolean وFindByName وDelete وClear، إضافة إلى تعداد Count وItems؛ ويوسم كل TXLSXCustomProperty قيمته بنوع TXLSXCustomPropType المطابق لتعيين متغيرات ECMA-376
Style overlaysتدير TXLSXStyleOverlays التجاوزات لكل نطاق فوق الأنماط المخزنة: ينشئ Add تجاوزًا، ويعيد ApplyToCell تنسيق خلية واحدة، وتجيب Resolve وResolveRowDefault وResolveColumnDefault عن طلبات البحث عن الأنماط أثناء التحميل، ويبلّغ HasVirtualStyle عن الأنماط المولَّدة، ويحد MaxVirtualRow الصفوف الافتراضية، ويزيح ApplyStructuralEdit التراكبات بعد تحرير الصفوف أو الأعمدة، وتدير Clear وCount وItems المجموعة
Styles, fills, and overlaysيكشف TXLSXFill عن Pattern وGradientKind وGradientStops عبر TXLSXFillPattern وTXLSXGradientKind وTXLSXGradientStop؛ وTXLSXWorksheet.StyleOverlays مجموعة TXLSXStyleOverlays تحمل إدخالات TXLSXStyleOverlay مستطيلًا وأجزاء التنسيق المتأثرة ونمط الخلية المتجاوز
Tables, sorts, and linksتبني أنماط الجداول المخصصة (TXLSXWorkbook.CustomTableStyles) تنسيق الأقسام من خانات TXLSXTableStyleSectionKind: توفر المجموعة Add وFindByName وDelete وClear وCount وItems، بينما يكشف كل TXLSXCustomTableStyle عن Name وSectionSize وPivotStyle وTableStyleFlag ويجيب عن طلبات HasSection / ResolveSection؛ وتصنف شروط الفرز المفاتيح بـ TXLSXSortBy وترتيب النص بـ TXLSXSortMethod؛ وTXLSXExternalLink.Kind من نوع TXLSXExternalLinkKind ويسرد كل ارتباط إدخالات TXLSXExternalDefinedName مع Name وRefersTo
Custom XML partsيحافظ TXLSXWorkbook.CustomXmlParts على XML مخصص خاص بكل عنصر: تحافظ Add وDelete وClear على الأجزاء، ويحمل كل TXLSXCustomXmlPart حمولته في Xml إضافة إلى ItemId وقائمة نصوص SchemaRefs لعلاقات المخططات (AddSchemaRef يلحق إدخالًا)، وتنجو الأجزاء المحفوظة في رحلة الحفظ دون تغيير
Cell style payloadsTXLSXCellStylePayload حزمة أنماط غير قابلة للتغيير وقابلة للمشاركة تُرفق بخلايا مفردة: يدير Acquire / Release عددها المرجعي، وينسخها Clone، ويختبر IsDefault النمط الافتراضي، ويحدد InternKey الحمولات المتساوية كي يتمكن التخزين من إزالة تكرارها
Controls, drawings, and sparklinesTXLSXWorksheet.FormControls مجموعة TXLSXFormControls من كائنات TXLSXFormControl — يكشف كل منها ControlType وCaption وMacroName وLinkedCell وقائمته Items — مكتوبة الأنواع بواسطة TXLSXFormControlType، مع TXLSXFormControlItems التي تحمل نص العناصر لكل عنصر تحكم؛ ويبلّغ كائنات الرسم عن نوعها عبر TXLSDrawingObjectKind، وتكشف مجموعات sparkline عن قياس المحور وسلوك الخلايا الفارغة عبر TXLSXSparklineAxisType وTXLSXSparklineEmptyCells
Chartsتصنف مجموعات الرسم والسلاسل تجميع الأعمدة ورموز العلامات ومواضع تسميات البيانات بتعدادات TXLSXChartBarGrouping وTXLSXChartMarkerSymbol وTXLSXChartDataLabelPos؛ وتتشارك عقد نموذج المخطط الفئة الأساسية TXLSXChartMutable، ويملا TXLSXChartLayoutResolver.ResolveChart ‏TXLSXChartResolvedLayout من مستطيلات TXLSXChartLayoutRect للمخطط والعنوان ووسيلة الإيضاح ومنطقة الرسم وعناوين المحاور
Pagination keep blocksتحافظ KeepRowsTogether / KeepColumnsTogether على سطح ترقيم صفحات XLSX على سجلي TXLSXKeepTogetherRange وTXLSXKeepTogetherCols كي تبقي تخطيط فواصل الصفحات الكتلة في صفحة واحدة
Diagnosticsيعيد TXLSXWorksheet.CheckDataValidations سجلات TXLSXValidationIssue (الخلية، فهرس التحقق، السبب)؛ ويعيد TXLSXWorkbook.ScanUnknownFunctions سجلات TXLSXUnknownFunctionInfo تحدد موقع الاستدعاءات غير المنفذة في الخلايا والأسماء المعرَّفة؛ ويملا TXLSXCells.GetStorageStatistics سجل TXLSXCellStorageStatistics بمحاسبة الخلايا وكتل الصفوف وبايتات كل حمولة والخلايا الفارغة المنسقة؛ ويعيد TXLSXWorksheet.BuildRowMajorCellOrder ‏TXLSXRowMajorOrder يصف ترتيب الاجتياز في الذاكرة للخلايا المملوءة
يقرأ TXLSXWorkbook.FormulaLocale ويكتب وسم الإعدادات المحلية المستخدم عند تحليل الصيغ وتسلسلها، محاكيًا معالجة الإعدادات المحلية للصيغ في المصنف الكلاسيكي

مقاطع الجداول (Slicers)

تُكتب مقاطع الجداول Slicers ‏(Excel 2013+) وتُفحص عبر مجموعتين: تحمل TXLSXWorksheet.Slicers عروض المقاطع لكل ورقة (TXLSXSlicer)، وتحمل TXLSXWorkbook.SlicerCaches مصادر البيانات المشتركة (TXLSXSlicerCache)

property TXLSXWorksheet.Slicers: TXLSXSlicers;
property TXLSXWorkbook.SlicerCaches: TXLSXSlicerCaches;

{ TXLSXSlicers }
function Add(ATable: TXLSXTable; const AColumnName: WideString): TXLSXSlicer; overload;
function Add(ATable: TXLSXTable; const AColumnName: WideString;
  ARow1, ACol1, ARow2, ACol2: Integer): TXLSXSlicer; overload;
function IndexByName(const AName: WideString): Integer;
function FindByName(const AName: WideString): TXLSXSlicer;
procedure Delete(Index: Integer);
procedure Clear;
property Count: Integer;
property Items[Index: Integer]: TXLSXSlicer;

{ TXLSXSlicer view }
property Name: WideString;          { workbook-unique }
property CacheName: WideString;
property Cache: TXLSXSlicerCache;
property Caption: WideString;
property StartItem: Integer;
property ColumnCount: Integer;
property ColumnWidth: WideString;
property ShowCaption: Integer;
property StyleName: WideString;
property LockedPosition: Integer;
property RowHeight: WideString;
property RowHeightEmu: Integer;
procedure SetBounds(ARow1, ACol1, ARow2, ACol2: Integer);
property FromRow, FromCol, ToRow, ToCol: Integer;   { anchor cell corners }
property FromRowOff, FromColOff, ToRowOff, ToColOff: Integer; { EMU offsets }
property AnchorType: TXLSXAnchorEditAs;
property HasAnchor: Boolean;

{ TXLSXSlicers, load-path entry }
function AddInternal: TXLSXSlicer;

{ TXLSXSlicerCache }
property Name: WideString;          { e.g. Slicer_Region }
property SourceName: WideString;    { source table column / pivot field }
property IsTableCache: Boolean;
property IsPivot: Boolean;
property IsNonOlapPivot: Boolean;
property ItemCount: Integer;
property ItemCacheIndex[Index: Integer]: Integer;
property ItemSelected[Index: Integer]: Boolean;
function SetSelectedItems(const CacheItemIndices: array of Integer): Integer;
function ClearSelection: Integer;
property TableId: Integer;
property TableColumnId: Integer;
property SortOrder: WideString;     { '' | ascending | descending }
property CrossFilter: WideString;   { '' | none | showItemsWithDataAtTop | showItemsWithNoData }
property CustomListSort: Integer;   { -1 absent, else 0/1 }

{ TXLSXSlicerCaches }
function Add: TXLSXSlicerCache;
function FindByName(const AName: WideString): TXLSXSlicerCache;
function IndexOfName(const AName: WideString): Integer;
function FindForTableColumn(ATableId, ATableColumnId: Integer): TXLSXSlicerCache;
procedure Delete(Index: Integer);
procedure Clear;
property Count: Integer;
property Items[Index: Integer]: TXLSXSlicerCache;
      

يبني Slicers.Add(Table, ColumnName) مقطع Slicer من البداية إلى النهاية: يسجّل أو يعيد استخدام الذاكرة المؤقتة الداعمة المسماة Slicer_<column>، ويحجز اسم #N/A المعرَّف المطابق، ويكتب امتداد slicerList لورقة العمل، ويثبت العرض بمرساة رسم متوافقة مع الترميز يغطي إشعارها الاحتياطي إصدارات Excel الأقدم؛ ويثبت الحمل الزائد الثاني مستطيل العرض، وإلا فتُستخدم مرساة افتراضية إلى يمين الجدول

تُحلَّل العروض والذاكرات المؤقتة المحمَّلة عند الفتح، وتُعاد استخدام الذاكرات المؤقتة المشتركة عبر العروض، وحذف آخر عرض لذاكرة مؤقتة يسقطها؛ وتحتفظ الخصائص والامتدادات غير المعروفة بتمثيلها الأصلي، بينما تتبع ارتباطات الجداول معرفات الجداول المحفوظة وتتبع اتصالات Pivot المدعومة هويات الأوراق المحفوظة

تكشف ذاكرات non-OLAP Pivot المؤقتة المستوردة المدعومة عن فحص أعضاء مُنمَّط وتغييرات تحديد محمية عبر IsNonOlapPivot و ItemCount و ItemCacheIndex و ItemSelected و SetSelectedItems و ClearSelection؛ راجع تحديد Slicer‏ Pivot لمعرفة سلوك العرض المشترك والذرية عند الفشل وحد قناع الحقل نفسه المستورد

تحتفظ ذاكرات Pivot المؤقتة غير المدعومة ببايتاتها الأصلية؛ ويمكن الوصول إلى عرض Slicer محمَّل أيضًا ككائن رسم عبر TXLSXDrawingObject.Slicer

مثال

var
  Ref: WideString;
  Row, Col: Integer;
begin
  Ref := XlsxCellRef(10, 5);
  if XlsxParseCellRef(Ref, Row, Col) then
    Worksheet.Cells.Item[Row, Col].Value := 'Checked';
end;
    

راجع واجهة برمجة تطبيقات بنية المصنف لمعرفة عقود callbacks الإدخال/الإخراج ومجمّعات أنماط المُسلسِل والتحقق من الملفات المشفرة ومخطط تبعيات الـ workspace