مرجع API خواننده و نویسنده مستقیم
TXLSDirectReader و TXLSDirectWriter بستههای XLSX را بدون نگهداشتن شبکه کامل کاربرگ در حافظه پردازش میکنند، بنابراین فراخوانیهای API که یک برگه را توصیف میکنند باید قبل یا در طول فاز پخش متناظر انجام شوند
چرخه حیات نویسنده و مقادیر سلول
TXLSDirectWriter.BeginFile یا BeginStream یک بسته را شروع میکند، روشهای کاربرگ هر بار یک کاربرگ را تعریف میکنند و Finish بسته نهایی را تثبیت میکند
| سلولهای اسکالر | WriteString، WriteRichString، WriteNumber، WriteBoolean، WriteDateTime و WriteError |
| سلولهای فرمول | WriteFormula، WriteFormulaNumber، WriteFormulaString، WriteFormulaBoolean، WriteFormulaDateTime و WriteFormulaError نتایج کششدهٔ ارائهشده توسط فراخواننده را میپذیرند |
| رشتههای مشترک | UseSharedStrings تکرارزدایی رشته در سطح بسته را فعال میکند |
| آمار | CellCount تعداد سلولهای صادرشده را گزارش میدهد |
| قابهای ثابت | FreezePanes(ColSplit, RowSplit) یک تقسیم منجمد در ستون و سطر مبتنی بر 1 دادهشده مینویسد |
سطرها و ستونها در سطح عمومی نویسنده مبتنی بر یک هستند و باید به ترتیب رو به جلوی کاربرگ ارائه شوند
سبکهای قابل استفاده مجدد
AddCellStyle یک دسته سبک غیرقابلتغییر در سطح بسته ثبت میکند و CloneCellStyle یک دسته جدید بدون نگهداشتن سطرهای کاربرگ مشتق میکند
نامهای تعریفشده و ابرپیوندها
AddDefinedName، AddLocalDefinedName، AddDefinedRange و AddLocalDefinedRange نامهای سطح کتاب کار یا برگه را قبل از نهاییسازی بسته اضافه میکنند
AddHyperlink، AddHyperlinkRange، AddInternalHyperlink و AddInternalHyperlinkRange روابط خارجی یا مکانهای داخلی برگه را برای یک سلول یا یک محدوده صادر میکنند
اعتبارسنجی داده
AddDataValidation و AddDataValidationSqRef سطح کامل قواعد را در معرض دید قرار میدهند، در حالی که AddListValidation، AddWholeNumberValidation، AddDecimalValidation، AddDateValidation، AddTimeValidation، AddTextLengthValidation و AddCustomValidation کمککنندههای تایپشده ارائه میدهند
قالببندی شرطی
AddConditionalFormat، AddConditionalFormatExpression، AddConditionalFormatContainsText، AddConditionalFormatNotContainsText، AddConditionalFormatBeginsWith، AddConditionalFormatEndsWith، AddConditionalFormatTop10، AddConditionalFormatAboveAverage، AddConditionalFormatDuplicateValues، AddConditionalFormatUniqueValues، AddConditionalFormatContainsBlanks، AddConditionalFormatNotContainsBlanks، AddConditionalFormatContainsErrors و AddConditionalFormatNotContainsErrors قواعد اسکالر اضافه میکنند
AddConditionalFormatDataBar، AddConditionalFormatColorScale2، AddConditionalFormatColorScale3 و AddConditionalFormatIconSet قواعد بصری اضافه میکنند؛ ClearConditionalFormats قواعد در انتظار را برای کاربرگ جاری حذف میکند
فیلتر خودکار و جداول
AddAutoFilterValue، AddAutoFilterDateGroup و AddAutoFilterSortCondition فیلتر کاربرگ را پیکربندی میکنند
AddTable یک بخش جدول ایجاد میکند و AddTableFilterValue، AddTableFilterDateGroup و AddTableSortCondition وضعیت فیلتر و مرتبسازی آن را پیکربندی میکنند
حفاظت و شکست صفحه
ProtectSheet، UnprotectSheet، AddProtectedRange و ClearProtectedRanges حفاظت کاربرگ را پیکربندی میکنند؛ ProtectWorkbook و UnprotectWorkbook قفلهای ساختار و پنجره کتاب کار را پیکربندی میکنند
AddHorizontalPageBreak و AddVerticalPageBreak شکستهای صفحه دستی را برای کاربرگ جاری صادر میکنند
تشخیص ذخیرهسازی خواننده مستقیم
TXLSDirectReader.SharedStringMemoryLimit حافظه رمزگشاییشدهٔ رشته مشترک را محدود میکند، SharedStringsOnDisk مهاجرت به ذخیرهسازی نمایهشدهٔ موقت را گزارش میدهد، SharedStringCount تعداد ورودیهای بارگذاریشده را گزارش میدهد و ParallelDiag تشخیص محدود تجزیهگر موازی را در معرض دید قرار میدهد
پیشبینی خواننده و وضعیت فرمول
FirstRow، LastRow، IncludeColumn و ClearColumnProjection انتخاب سطر و ستون مبتنی بر 1 را قبل از تخصیص مقدار، فرمول یا rich text به تجزیهکننده کاربرگ میفرستند
IncludeFormulaText بهصورت پیشفرض true است؛ غیرفعال کردن آن مقادیر کششده، مختصات، استایلها و HasFormula را نگه میدارد در حالی که FormulaTextAvailable false میشود و Formula خالی میماند
مکاننمای سطر
TXLSRowCursor.Open فایلها یا جریانهای XLS، XLSX، XLSM، ODS، CSV و TSV را میپذیرد؛ تشخیص خودکار ZIP بستههای ODS را از کتابکارهای Open XML قبل از باز شدن برگه تفکیک میکند
SelectSheet و SelectSheetByName یک کاربرگ انتخاب میکنند؛ SheetCount، SheetNames، SheetIndex، RowIndex و Eof وضعیت پیمایش را در معرض میگذارند و SharedStringMemoryLimit همان سیاست محدود رشته مشترکِ خواننده مستقیم را اعمال میکند
FirstRow، LastRow، IncludeColumn و ClearColumnProjection از همان فیلترهای مبتنی بر 1 در همه قالبهای cursor استفاده میکنند؛ گزینههای پاس بین FindFirst و EOF قابل تغییر نیستند اما بعد از EOF، انتخاب برگه یا بستن دوباره قابل تغییر میشوند
هر TXLSRowCursorCell مقدار HasFormula را مستقل از FormulaTextAvailable گزارش میکند؛ XLS کلاسیک وجود فرمول و نتایج کششده را ارائه میکند بدون آنکه ادعا کند متن توکن در دسترس است و IncludeFormulaText میتواند متن فرمول XLSX و ODS را قبل از انباشت سرکوب کند
پیمایش ODS یک قالب سطر فیزیکی نگه میدارد، بلوکهای سطر تکراری را به بازه درخواستی برش میزند، مستقیماً بین ستونهای انتخابی داخل بازههای تکراری میپرد، از روی سلولهای پوششدادهشده بدون برگرداندن آنها بهعنوان مقدار حرکت میکند و شمارشهای تکرار نامعتبر یا محدود به شبکه را از طریق OnSkippedRecord گزارش میکند
State بین xrcsClosed، xrcsBeforeFirst، xrcsActive، xrcsEof، xrcsCancelled و xrcsFaulted تمایز میگذارد؛ Cancel idempotent است، سطر جاری را باطل میکند و جریان کاربرگ فعال را آزاد میکند در حالی که منبع را نگه میدارد تا یک انتخاب صریح برگه بتواند گذر جدیدی شروع کند
overload جریانی بهصورت پیشفرض xsoBorrowed است، موقعیت اولیه فراخوان را هنگام بستن برمیگرداند و برای انتقال مالکیت پس از یک باز شدن موفق، xsoOwned میپذیرد؛ باز شدنهای ناموفق هرگز مالکیت فراخوان را مصرف نمیکنند
CurrentRowView آرایه سطر جاری را بدون کپی کردن قرض میگیرد و قبل از هر دسترسی یک نسل را بررسی میکند؛ جلو رفتن، انتخاب، لغو، بستن یا نابود کردن cursor نما را باطل میکند و در دسترسیهای بعدی EXLSRowCursorViewInvalidated raise میکند
PeakRowBufferedBytes یک تخمین یکنوا از آخرین Open است از رکوردهای سلول، payload های مدیریتشده، rich text و دادههای بکاند قالب که برای یک سطر منطقی نگه داشته میشوند؛ این مقدار برای عیبیابی رگرسیونی حافظه محدود است نه حسابداری دقیق heap
SheetPassesStarted شمار شروعهای موفق بکاند کاربرگ را میشمارد؛ دیدن نام برگهها یا رد کردن یک برگه از طریق فاساد callback، بخش کاربرگ را باز نمیکند
آداپتور callback رو به جلو
TXLSForwardReader رمزگشایی XLS، XLSX، ODS، CSV و TSV را به TXLSRowCursor میسپارد، هر سلول سطر جاری را به یک callback از نوع OnCell تبدیل میکند و همان قراردادهای کران سطر، پیشبینی ستون، وضعیت فرمول، rich text، گذرواژه، رکورد ردشده، موقعیت جریان و بافر محدود را حفظ میکند
PeakRowBufferedBytes و SheetPassesStarted عیبیابیهای مشترک cursor را روی سطح callback در معرض میگذارند، در حالی که XLS کلاسیک علاوه بر آنها ClassicBytesRead و ClassicPeakBufferedBytes را هم نگه میدارد
رویدادها و نوعهای رکورد خواننده
خواننده و row cursor فراخوانیهای اختیاری و رکوردهای ساده را در معرض میگذارند که همگی در lxDirectRead اعلان شدهاند. هر callback شکلی یکسان دارد: رکورد یک آیتم جریانی را توصیف میکند و تنظیم Abort اسکن را متوقف میکند (رویدادهای برگه علاوه بر آن SkipSheet را هم میپذیرند)
| سلولها | OnCell (از نوع TXLSDirectCellEvent) به ازای هر سلول یک TXLSDirectCell تحویل میدهد که Kind آن (TXLSDirectCellKind: xdkEmpty، xdkNumber، xdkString، xdkBoolean، xdkDate، xdkError) فیلد مقدار پُرشده را انتخاب میکند؛ rich text بهصورت یک TXLSDirectRichText حامل مدخلهای TXLSDirectRichTextRun حرکت میکند که هرکدام یک TXLSDirectRichColor (از نوع TXLSDirectRichColorKind)، TXLSDirectRichUnderline و TXLSDirectRichVertAlign بههمراه دادههای اختیاری TXLSDirectPhoneticProperties و TXLSDirectPhoneticRun دارند |
| قاببندی برگه | OnSheet (TXLSDirectSheetEvent) میتواند قبل از تجزیه سلولها یک کاربرگ کامل را رد کند؛ OnSkippedRecord (TXLSDirectSkippedEvent) محتوای بدشکل یا ناقص را با شناسه رکورد و دلیل گزارش میکند |
| چیدمان برگه | OnDimension، OnSheetFormat، OnColumn، OnRow، OnMerge و OnPane رکوردهای TXLSDirectDimension، TXLSDirectSheetFormat، TXLSDirectColumn، TXLSDirectRow، TXLSDirectMerge و TXLSDirectPane را تحویل میدهند؛ وضعیت pane از TXLSDirectPaneState استفاده میکند (xdpsSplit، xdpsFrozen، xdpsFrozenSplit، xdpsUnknown) |
| وضعیت cursor | TXLSRowCursor.State یک TXLSRowCursorState است (xrcsClosed، xrcsBeforeFirst، xrcsActive، xrcsEof، xrcsCancelled، xrcsFaulted)؛ overload جریانیِ Open یک TXLSStreamOwnership میگیرد (xsoBorrowed پیشفرض و xsoOwned برای انتقال مالکیت) و CurrentRowView یک نمای قرضی از نوع IXLSRowCursorView برمیگرداند که ویژگی Valid آن دسترسی را محافظت میکند و ValueByCol آن یک سلول از سطر قرضی را بدون کپی میخواند؛ نما با جلو رفتن cursor باطل میشود |
نوعهای پارامتر و استایل نویسنده
کمکیکنندههای نوعدار نویسنده (lxDirectWrite) رکورد و enum میپذیرند تا فراخوانیها بدون تخصیص حافظه بمانند: WriteRichString یک TXLSDirectRichText میگیرد؛ AddCellStyle یک استایل در سطح بسته از یک TXLSDirectCellStyle میسازد که تراز (TXLSDirectHorizontalAlignment، TXLSDirectVerticalAlignment)، زیرخط (TXLSDirectUnderline)، الگوی fill (TXLSDirectFillPattern) و اضلاع کادر (TXLSDirectStyleBorder با TXLSDirectBorderSide) آن مدل استایل OOXML را بازتاب میدهند. قالببندیهای شرطی یک TXLSDirectConditionalFormat با TXLSDirectCfKind / TXLSDirectCfOperator / TXLSDirectCfValue / TXLSDirectCfValueKind و TXLSDirectIconSetType میفرستند، اعتبارسنجی داده یک TXLSDirectDataValidation، جدولها یک TXLSDirectTable، ابرپیوندها یک TXLSDirectHyperlink، نامهای تعریفشده یک TXLSDirectDefinedName، استایلهای تفاضلی یک TXLSDirectDxfStyle، نظرات یک TXLSDirectComment، تصاویر یک TXLSDirectImage با TXLSDirectImageFormat، نمودارها یک TXLSDirectChart با TXLSDirectChartSeries و TXLSDirectChartType، ادغامها یک TXLSDirectMergeRange، محدودههای محافظتشده یک TXLSDirectProtectedRange، حفاظت برگه یک مجموعه TXLSDirectSheetProtectionOptions از TXLSDirectSheetProtectionOption، وضعیت مرتبسازی auto-filter یک TXLSDirectSortState، گزینههای ستون یک TXLSDirectColumnOption و هندسه صفحه یک رکورد TXLSDirectPageMargins
TXLSDirectNeedRow = procedure(Sender: TObject; RowIndex: Integer;
var Eof: Boolean) of object;
function XLSDirectColName(Col: Integer): WideString;
function XLSDirectParseRef(const Ref: WideString;
out Col, Row: Integer): Boolean;
function XLSDirectPasswordHash(const Password: WideString): WideString;
OnNeedRow سطرها را از برنامه میکشد: تأمینکننده سلولهای سطر را مستقیماً از طریق نویسنده مینویسد و Eof = False میگذارد، یا با Eof = True اتمام را اعلام میکند تا حلقه متوقف شود. این کمیها بین مختصات و primitive های حفاظت تبدیل انجام میدهند: XLSDirectColName یک ستون مبتنی بر صفر را به حروف A1 آن میکشد، XLSDirectParseRef یک ارجاع سلول A1 را تجزیه میکند و XLSDirectPasswordHash هش قدیمی گذرواژهای را محاسبه میکند که رکوردهای حفاظت برگه ذخیره میکنند