وثائق HotXLS

الفئة TXLSXRange

الوحدة: lxHandleX
يمثل نطاقًا مستطيلًا لورقة عمل XLSX تعيده TXLSXWorksheet.Range أو RCRange أو UsedRange أو EntireRow أو EntireColumn. النطاق مجرد عرض خفيف فوق ورقة العمل الخاصة به؛ فهو لا يملك بيانات الخلايا

الإعلان

TXLSXBuiltinCellStyle = (
  xbsNormal, xbsGood, xbsBad, xbsNeutral,
  xbsCalculation, xbsCheckCell, xbsExplanatoryText, xbsInput,
  xbsLinkedCell, xbsNote, xbsOutput, xbsWarningText,
  xbsHeading1, xbsHeading2, xbsHeading3, xbsHeading4, xbsTitle, xbsTotal,
  xbsAccent1, xbsAccent2, xbsAccent3, xbsAccent4, xbsAccent5, xbsAccent6);

TXLSXRange = class
  constructor Create(ASheet: TXLSXWorksheet; ARow1, ACol1, ARow2, ACol2: Integer);
  function RefA1: WideString;
  function SaveAsHTML(const FileName: WideString): Integer; overload;
  function SaveAsHTML(const FileName: WideString; Options: TXLSXHtmlExportOptions): Integer; overload;
  function SaveAsHTML(Stream: TStream): Integer; overload;
  function SaveAsHTML(Stream: TStream; Options: TXLSXHtmlExportOptions): Integer; overload;

  property Sheet: TXLSXWorksheet;
  property Row1, Col1, Row2, Col2: Integer;
  property RowCount, ColCount: Integer;

  procedure SetValue(const V: Variant);
  procedure SetFormula(const F: WideString);
  function SetArrayFormula(const F: WideString): Integer;
  procedure ClearValues;
  procedure Clear;
  procedure ClearAll;

  procedure SetFontIndex(AIdx: Integer);
  procedure SetFillIndex(AIdx: Integer);
  procedure SetBorderIndex(AIdx: Integer);
  procedure SetNumberFormatIndex(AIdx: Integer);
  procedure SetAlignmentIndex(AIdx: Integer);
  procedure SetNumberFormat(const Fmt: WideString);
  procedure SetBorders(Kind: TXLSXBorderEdgeKind; Style: TXLSXBorderStyle); overload;
  procedure SetBorders(Kind: TXLSXBorderEdgeKind; Style: TXLSXBorderStyle; Color: LongWord); overload;
  procedure SetLocked(ALocked: Boolean);
  procedure SetFormulaHidden(AHidden: Boolean);

  procedure AutoFitColumns(AMinWidth: Double = 0; AMaxWidth: Double = 0);
  procedure AutoFitRows(AMinHeight: Double = 0; AMaxHeight: Double = 0);
  procedure Merge; overload;
  procedure Merge(Across: OleVariant); overload;
  procedure Unmerge;
  function Offset(DRow, DCol: Integer): TXLSXRange;
  function Resize(NewRowCount, NewColCount: Integer): TXLSXRange;
  procedure Sort(AKeyColumn: Integer; ADescending: Boolean = False); overload;
  procedure Sort(const AKeyColumns: array of Integer; const ADescending: array of Boolean); overload;
  procedure ApplyBuiltinStyle(AStyle: TXLSXBuiltinCellStyle);
  procedure CopyTo(ADestRow, ADestCol: Integer);
  procedure MoveTo(ADestRow, ADestCol: Integer);
  procedure InsertRows;
  procedure DeleteRows;
  procedure InsertCols;
  procedure DeleteCols;
  procedure ApplyFormatPatch(ASource: TXLSXRange; AParts: TXLSXFormatParts);
  function CopyToClipboard: Boolean;
  function SaveAsPDF(const FileName: WideString): Integer; overload;
  function SaveAsPDF(Stream: TStream): Integer; overload;
  function SetDynamicArrayFormula(const F: WideString): Integer;
end;

الأعضاء

العضو المعنى
Create(ASheet, ARow1, ACol1, ARow2, ACol2) يبني نطاقًا جديدًا مملوكًا لورقة العمل ووحّد الزوايا المعكوسة بحيث تكون Row1/Col1 دائمًا إحداثيتي أعلى اليسار
RefA1 إرجاع مرجع النطاق كنص A1. النطاقات أحادية الخلية تعيد مرجع خلية واحدًا مثل B2
SaveAsHTML تقبل التحميلات الزائدة ذات الخيارات TXLSXHtmlExportOptions الخصائص Title وWriteDocument وIncludeStyles وIncludeBOM وTableClass. اضبط WriteDocument على False لإخراج جزء جدول؛ واضبط IncludeBOM على False عند تضمين المخرجات في استجابة UTF-8 قائمة. الخيارات نفسها متاحة لتصدير HTML لنطاق محدد. وتحافظ المخرجات المصدَّرة على الارتباطات التشعبية للخلايا كمراسي <a>، والصور المرساة كـ URI صور data: ضمن السطر عندما تقع داخل المستطيل المحدد. كما تُصدَّر تعليقات الخلايا داخل المستطيل المحدد بصيغة مهرَّبة <td> ذات السمة title. عندما يكون IncludeStyles مفعّلًا، تُصدَّر القيم الصريحة ColWidth كعروض <col>، والقيم الصريحة RowHeight كأنماط ارتفاع <tr>. وتُصدَّر أجزاء النص الغني في الخلايا كعناصر <span> مهرَّبة مع أنماط خط ولون وتوكيد وتسطير ضمن السطر، عندما يكون IncludeStyles مفعّلًا. وتُصدَّر حدود الخلايا كقواعد CSS border-left وborder-right وborder-top وborder-bottom، عندما يكون IncludeStyles مفعّلًا. أما الصفوف والأعمدة المخفية المشار إليها بـ RowHidden / ColHidden، بالإضافة إلى الأعمدة ذات العرض الصفري الصريح، فتُستثنى من الجدول المولَّد ومن <colgroup>. وتُصدَّر إعدادات المحاذاة الرأسية كقواعد CSS vertical-align، عندما يكون IncludeStyles مفعّلًا
SetValue / SetFormula يكتب نفس القيمة أو نص الصيغة إلى كل خلية في النطاق عبر مجموعة خلايا ورقة العمل
SetArrayFormula يعيّن صيغة مصفوفة CSE متعددة الخلايا على النطاق. تخزّن الخلية العلوية اليسرى نص الصيغة وترسو نطاق الانسكاب، بينما تشير الخلايا المتبقية إلى تلك الخلية الجذر بحيث يقيّم كل خلية عنصرها الخاص من نتيجة المصفوفة. مرّر نص الصيغة دون الأقواس المتعرجة المحيطة
ClearValues / Clear / ClearAll ClearValues وClear يزيلان القيم والصيغ مع الحفاظ على فهارس الأنماط. ClearAll يمسح فهارس الأنماط أيضًا
SetFontIndex / SetFillIndex / SetBorderIndex / SetNumberFormatIndex / SetAlignmentIndex يطبق فهارس لوحة المصنف (التي تبدأ من 1) على كل خلية في النطاق. مرّر 0 لمسح فهرس الخلية المقابل
SetNumberFormat يبحث عن سلسلة تنسيق أرقام في لوحة المصنف أو يضيفها، ثم يطبق الفهرس الناتج (الذي يبدأ من 1) على النطاق. التنسيق الفارغ يمسح فهرس كل خلية
SetBorders يؤلف أضلاع الحدود فوق النطاق. TXLSXBorderEdgeKind يقبل xlsxEdgeAll وxlsxEdgeOutline وxlsxEdgeInside وxlsxEdgeInsideHorizontal وxlsxEdgeInsideVertical وxlsxEdgeTop وxlsxEdgeBottom وxlsxEdgeLeft وxlsxEdgeRight وxlsxEdgeDiagonalUp وxlsxEdgeDiagonalDown. استخدم محددات الأضلاع المحيطية والداخلية لبناء حدود الجدول دون استبدال إعدادات الأضلاع الأخرى
SetLocked / SetFormulaHidden يطبق أعلام حماية الخلايا على كل خلية في النطاق عبر إعادة استخدام مخزن أنماط الحماية في المصنف
AutoFitColumns / AutoFitRows يمرر إلى دوال الضبط التلقائي في ورقة العمل على حدود أعمدة النطاق أو صفوفه. تُمرَّر حدود العرض والارتفاع الاختيارية كما هي للحفاظ على تخطيطات التقارير داخل حدود التصميم
Merge / Unmerge Merge وMerge(False) ينشئان مستطيلًا مدمجًا واحدًا. Merge(True) ينشئ نطاقًا مدمجًا واحدًا لكل صف، بما يطابق سلوك الدمج عبر الصفوف في Excel. Unmerge يزيل تطابقًا تامًا لنطاق مدمج
Offset / Resize إرجاع نطاقًا آخر مملوكًا لورقة العمل بعد إزاحته من الحدود الحالية أو بعد تغيير حجمه إلى عدد الصفوف والأعمدة المطلوب
Sort يرتب صفوف هذا النطاق حسب عمود مفتاح واحد أو حسب عدة أعمدة مفاتيح بترتيب الأولوية ADescending يحدد الترتيب التصاعدي أو التنازلي لكل مفتاح؛ والإدخالات المحذوفة تُرتَّب افتراضياً تصاعدياً. القيم الفارغة تأتي أخيراً
ApplyBuiltinStyle يطبق المظهر المرئي لنمط خلية مدمج في Excel على كل خلية في النطاق. تكتب الدالة المساعدة تنسيقاً مباشراً بإضافة الخط والتعبئة المطابقين إلى مخازن المصنف وإسناد الفهارس الناتجة إلى الخلايا
CopyTo / MoveTo ينسخ أو ينقل النطاق بأكمله إلى خلية أعلى-يسار الوجهة. القيم والصيغ وحمولات النص المنسّق ومؤشرات الأنماط والتعليقات والارتباطات التشعبية ومراسي الرسم تُمرَّر عبر دوال مساعدة نسخ النطاق ونقله في ورقة العمل
InsertRows / DeleteRows / InsertCols / DeleteCols ينفذ إدراج صفوف أو أعمدة كاملة وحذفها على حدود النطاق. تمرّر هذه الدوال المساعدة العمليات إلى إزاحة الصفوف/الأعمدة في ورقة العمل لتبقى الصيغ والمراجع والمرشحات ونطاقات إعداد الصفحة ونطاقات المخططات والأسماء والصور ومراسي المخططات متوائمة مع الشبكة المعدَّلة
ApplyFormatPatch يطبق أنماط تنسيق انتقائية من نطاق مصدر آخر إلى هذا النطاق باستخدام أعلام TXLSXFormatParts
CopyToClipboard ينسخ قيم النطاق وأنماطه إلى حافظة Windows
SaveAsPDF يصدّر نطاق الخلايا كملف PDF أو تدفق باستخدام محرك عرض PDF داخل العملية
SetDynamicArrayFormula يعيّن صيغة مصفوفة ديناميكية على النطاق، مع دعم سلوك الانسكاب الديناميكي في Excel

الملكية والحدود

النطاقات مملوكة لورقة العمل التي أنشأتها وتحرر معها ولا ينبغي لكود التطبيق استدعاء Free على TXLSXRange ولا ينبغي الاحتفاظ بمرجع نطاق بعد إتلاف ورقة العمل أو المصنف
الإحداثيات الرقمية تبدأ من 1. إنشاء النطاق يصحح الزوايا المعكوسة ويحصر الحدود في حدود ورقة عمل XLSX

مثال

var
  Wb: TXLSXWorkbook;
  Ws: TXLSXWorksheet;
  Body: TXLSXRange;
begin
  Wb := TXLSXWorkbook.Create;
  try
    Ws := Wb.Sheets.Add('Report');
    Body := Ws.Range['B2:D20'];
    Body.SetNumberFormat('#,##0.00');
    Body.SetBorders(xlsxEdgeOutline, xlsxBorderThin, $FF808080);
    Body.Sort(2);
    Body.ApplyBuiltinStyle(xbsAccent1);
    Ws.Range['F2:G3'].SetArrayFormula('MMULT(A2:B3,D2:E3)');
    Body.AutoFitColumns;
    Body.SaveAsHTML('report-fragment.html');
  finally
    Wb.Free;
  end;
end;

انظر أيضاً