مزودات الاستعلام التلقائية

متاحة منذ الإصدار 2.384.99 عبر واجهة مصنفات XLSX على Windows؛ ولا يجري الاختيار التلقائي للمزود إلا أثناء تحديث استعلام صريح

تحديث استعلام موجود

Workbook.QueryProviders.BaseDirectory := 'C:\Data';
Workbook.QueryProviders.MaxInputBytes := 64 * 1024 * 1024;
Workbook.QueryProviders.MaxResultCells := 2000000;
Workbook.QueryProviders.TimeoutSeconds := 30;
Status := Sheet.RefreshQueryTable('ImportedData', 1000000);

TXLSXWorkbook.QueryProviders: TXLSQueryProviderDispatcher يعرض موزِّعًا تمتلكه المصنفات قادمًا من lxQueryProviders؛ ولا تحرّر الموزِّع يدويًا

TXLSXWorksheet.RefreshQueryTable(const AName: WideString; AMaxRows: Integer = 1000000; AOnProgress: TXLSQueryRefreshProgress = nil): Integer والحمولة الزائدة التي تأخذ AIndex مبنيًا على الصفر تختاران استعلامًا موجودًا وتستخدمان هذا الموزِّع

تبقى الحمولات الزائدة القائمة التي تقبل TXLSQueryTableProvider صريحًا تستخدم ذلك المزود مباشرة، بما في ذلك رفضها القائم للمزود المفقود؛ وهي لا تلجأ إلى التوزيع التلقائي

يعيد التحديث 1 عند النجاح و0 عند الإلغاء أو -1 عند الفشل، مع رمزي تشخيص 1401 و1400 تحت xlsOperationRefresh؛ ويظل تطبيق النتائج المعاملاتي القائم والتحقق من المخطط والسلاسل الحرفية وسلوك التنسيق كما هو

يُدعى هذان التشخيصان xlsDiagnosticQueryRefreshCancelled وxlsDiagnosticQueryRefreshFailed؛ ويجري الحصول على حارس الكتابة للمصنف قبل تحويل الحالة، لذا فإن عرض قراءة مجمَّدًا أو أي رفض آخر من حارس الكتابة يثير استثناء

لا يجلب فتح المصنف أو حفظه بيانات الاتصال أبدًا ولا يقيّم الاستعلامات ولا يتصرف بناءً على بيانات RefreshOnLoad الوصفية المحفوظة؛ فحدِّث كل استعلام مطلوب صراحةً قبل حفظ نتيجته

المزودات المدمجة المدعومة

• xlckText يقرأ نصًا محليًا محدَّدًا أو ثابت العرض بفك ترميز صارم لـ UTF-8 وUTF-16LE وUTF-16BE وWindows-1252 وLatin-1، مع صفوف بداية مهيأة وأنواع حقول مدعومة تشمل ستة ترتيبات للتواريخ وحقولًا متخطاة؛ كما يدعم الإدخال المحدَّد سجلات متعددة الأسطر داخل اقتباسات
• xlckAdo وxlckOleDb وxlckOdbc تستخدم مشغلات ADO وقواعد البيانات المثبتة على Windows باتصالات ومجموعات سجلات للقراءة فقط؛ CommandType = 2 يختار نص SQL وCommandType = 3 يختار أمر جدول
• xlckWeb يستخدم WinHTTP على Windows لطلب GET مجهول الهوية عبر HTTP أو HTTPS لجدول HTML مستطيل واحد غير فارغ يُختار بفهرسه الموجب أو باسمه؛ ومجموعات محارف الاستجابة المدعومة هي UTF-8 وUTF-16 وWindows-1252 وLatin-1

يوفر BaseDirectory الأساس للمسارات النصية المحلية النسبية فقط؛ أما سلاسل اتصال قواعد البيانات وعناوين URL للويب فتبقى بيانات اتصال صريحة

الترميز النصي غير المحدَّد يقبل إدخال ASCII فقط ما لم تحدد علامة ترتيب بايتات مدعومة الترميز؛ والإدخال غير ASCII يتطلب ترميزًا مدعومًا صريحًا أو علامة ترتيب بايتات

في اتصال Text محدَّد، اضبط TextPrompt = False وTextDelimited = True ومحدِّدًا واحدًا بالضبط، دون دمج المحددات المتتالية؛ والاتصالات المنشأة حديثًا افتراضيها الطلب بالمطالبة والمحدِّد Tab، لذا امسح TextTab عند اختيار محدِّد آخر

النص ثابت العرض

اضبط TextPrompt = False وTextDelimited = False، ثم أضف TextFields بترتيب Position مبني على الصفر بتزايد صارم بدءًا من الصفر؛ وينتهي كل حقل عند الموضع التالي أو عند ناهي السجل الفيزيائي، ويستبعد xltiftSkip حقلَه من النتيجة

تُحسب المواضع بوحدات شيفرة UTF-16 مفككة لا بايتات الإدخال؛ ويُرفض حدٌّ يقطع زوجًا بديلًا، وتنهي CRLF وLF وCR السجلات بشكل مستقل عن إعدادات المحدِّد والاقتباس

تُقلَّم حشوة الحقول قبل التحويل، بما في ذلك النص ذو النوع الصريح، مطابقةً سلوك الاستيراد الأصلي ثابت العرض المُتحقق منه؛ وتبقى علامات الاقتباس ومحارف Tab ومحارف المحدِّد داخل الحقل إدخالًا حرفيًا، وتزوّد السجلات القصيرة حقولًا ختامية فارغة دون تغيير المخطط المعلن

بدون TextFields يصبح كل سجل حقلًا عامًا واحدًا؛ TextFirstRow يختار أول سجل مخطط، وQuery.Headers يتخطى قيم ذلك السجل، وتظل السجلات الفارغة الصريحة صفوفًا

تنطبق حدود الصفوف وبايتات الإدخال وخلايا النتيجة وحد 32767 وحدة شيفرة للحقل القائمة؛ وتمسح البيانات الوصفية غير الصالحة أو إخفاقات التحويل أو الإدخال المفرط البياناتَ المجهَّزة قبل تحديث ورقة العمل المعاملاتي، بينما يحفظ الإلغاء خلايا النتيجة السابقة

Connection.TextPrompt := False;
Connection.TextDelimited := False;
Connection.TextFields.Add(xltiftGeneral, 0);
Connection.TextFields.Add(xltiftText, 8);
Status := Sheet.RefreshQueryTable('Imported');

في اتصال Web، اضبط WebHtmlTables = True وWebHtmlFormat = 'none'؛ والطلبات المدعومة ترفض بيانات الاعتماد المضمّنة والأجزاء والمصادقة وإعادة التوجيه

ترفض المزودات المدمجة البيانات الوصفية غير المدعومة في كل نوع اتصال تابع لها؛ فتحديث قواعد البيانات يرفض أوامر OLAP أو أوامر الخادم والواسطة عبر ملف اتصال وكلمات المرور المخزنة ومطالبات بيانات الاعتماد، وتحديث Text يرفض مطالبات الملفات، بينما يتطلب تحديث Web بيانات جدول مجهولة الهوية

معاملات قواعد البيانات محددة النوع

تدعم أوامر نص SQL علامات ? الموضعية المرتبطة عبر ADO Command بترتيب Connection.Parameters؛ وقيم المعاملات لا تستبدل نص SQL أبدًا، والأسماء تعنون الارتباطات دون تغيير الترتيب الموضعي

يسرد الفحص المسبق العلامات خارج السلاسل داخل اقتباس مفرد والمعرِّفات داخل اقتباس مزدوج أو backticks والمعرِّفات بين أقواس معقوفة والتعليقات السطرية وتعليقات الكتل المتداخلة، بما في ذلك الاقتباسات المزدوجة وهروب الأقواس؛ وتُرفض الاقتباسات أو التعليقات غير المقفلة وعدم تطابق عدد العلامات قبل فتح اتصال

استخدم ParameterType = 'value' مع ValueKind صريح من xlcpvInteger أو xlcpvDouble أو xlcpvBoolean أو xlcpvString وخاصية القيمة المقابلة له؛ والصفر وFalse والسلاسل الفارغة قيمٌ فعلية، بينما لا يستنتج xlcpvNone قيمةً أثناء التنفيذ

Connection.CommandType := 2;
Connection.CommandText := 'SELECT Amount FROM Sales WHERE Amount > ?';
with Connection.Parameters.Add do
begin
  Name := 'MinimumAmount';
  ParameterType := 'value';
  ValueKind := xlcpvInteger;
  IntegerValue := 0;
  SqlType := 4;
end;
Status := Sheet.RefreshQueryTable('SalesQuery');

استخدم ParameterType = 'cell' وValueKind = xlcpvCell وCellReference لمرجع ورقة عمل محلي مؤهل بالكامل مثل Inputs!$A$1 أو 'Sales Input'!B2؛ وأسماء أوراق العمل المقتبسة تستخدم فاصلة اقتباس مزدوجة، وتُرفض النطاقات والمصنفات الخارجية والأسماء ومراجع الخلايا غير المؤهلة

يلتقط تحديث ورقة العمل القيم العددية المخزنة وذاكرة الصيغ المؤقتة المتاحة دون إعادة حساب أو تجسيد خلايا محزومة؛ وتُرفض ذواكر الصيغ المفقودة وخلايا الأخطاء، بينما توفر الخلية المفقودة أو الفارغة قيمة SQL null فقط مع نوع SQL مدعوم صريح

يحتفظ التقاط الخلية بنوع Variant الأصلي، ما يتيح قيم Int64 الموقعة وCurrency والتواريخ محددة النوع وnull دون اختزالها إلى حقول الأعداد الصحيحة 32-بت أو القيم الحرفية Double المحفوظة؛ والتواريخ وnull وقيم Int64 المخزنة مباشرة تقع خارج نموذج البيانات الوصفية للمعاملات الأصلي، فاستخدم ارتباطات الخلايا محددة النوع لتلك القيم

يستخدم SqlType رموز أنواع ODBC SQL المعيَّنة صراحةً إلى أنواع ADO؛ وهو ليس قيمة من تعداد ADO DataTypeEnum

تقبل الأنواع الصريحة المدعومة كذلك SQL null؛ وتُرفض المصفوفات وVariants المراجع والأخطاء والأعداد غير المنتهية وأنواع SQL غير المدعومة والتحويلات التي تفقد دقة الأعداد الصحيحة، بينما يتطلب NUMERIC أو DECIMAL بيانات دقة ومقياس لا يوفرها API الارتباط هذا

يتلقى ADO القيمة محددة النوع وحجمها المعلن، مع وحدة شيفرة واحدة على الأقل مخصصة للنص الفارغ؛ وتبقى المشغلات الأصلية مسؤولة عن لهجة SQL وأنواع المعاملات المدعومة وتحويلات النتائج، لذا قد يرفض مزود مثبَّت ارتباطًا صالحًا أو يملك قدرات رقمية أو زمنية أضيق

يستخدم Jet وACE ارتباطات OLE DATE محددة النوع لقيم DATE وTIME وTIMESTAMP المتحقق منها حفاظًا على التاريخ والوقت باستقلال عن إسقاطات نص الطابع الزمني المعتمدة على الإعدادات المحلية؛ وتبقى قواعد التحقق من DATE وTIME سارية، وتبقى قدرات إسقاط null خاصة بكل مزود

تتطلب المعاملات أمر نص SQL وتقتصر على 1024 معاملًا لكل جلب و255 وحدة شيفرة للاسم و32767 وحدة شيفرة لكل قيمة نصية؛ ونص الأمر ومراجع المعاملات والأسماء والحمولات تستهلك كذلك ميزانية بايتات الإدخال

تُرفض المطالبات وخصائص امتداد المعاملات غير المعروفة؛ ويبقى RefreshOnChange بيانات وصفية محفوظة لا تُطلق تحديثًا في الخلفية، ولا يحل فتح المصنف أو حفظه الخلايا أو ينفّذ الأوامر

يدعم Fetch المباشر القيم الحرفية؛ ويقبل FetchWithCellResolver(Connection, Query, MaxRows, out Data, var Abort, AResolver) نداءً عكسيًا من نوع TXLSQueryParameterCellResolver لقيم الخلايا، وتشير نتيجته المنطقية إلى توفُّر قيمة مخزنة

النداء العكسي مرتبط بنطاق الاستدعاء ولا يُحفظ؛ ويزوّد التحديث التلقائي لورقة العمل المُحلِّلَ المحلي الخاص به، بينما تبقى المزودات المخصصة المسجلة متقدمة وتمتلك دلالات معاملاتها

يدعم تحديث Web جداول text/html عادية بلا خلايا ممتدة أو جداول مختارة متداخلة أو محتوى مدفوع بالنصوص البرمجية؛ وتُرفض التخطيطات والكيانات غير المدعومة بدلًا من إنتاج بيانات جزئية

تسجيل مزود مخصص

Workbook.QueryProviders.RegisterProvider(xlckWeb, CustomProvider);
try
  Status := Sheet.RefreshQueryTable('RemoteData');
finally
  Workbook.QueryProviders.RegisterProvider(xlckWeb, nil);
end;

يبني TXLSQueryProviderDispatcher.Create موزِّعًا مستقل الملكية للاستخدام المباشر؛ وينشئ المصنف نظيرته الخاصة ويمتلكها

يثبّت RegisterProvider(AKind: TXLSConnectionKind; AProvider: TXLSQueryTableProvider) معالجًا مستعارًا لنوع اتصال معلن، وnil يلغي تسجيله؛ ويجب أن يطول عمر المعالج عمرَ التسجيل

يتقدم المعالج المسجل على المزود المدمج ويمكنه دعم مصادقة أو أنواع اتصال خاصة بالتطبيق؛ وتُرفض تغييرات التسجيل وتغييرات الإعدادات والتوزيع العكسي أثناء الجلب، وتُرفض قيم التعداد غير الصالحة قبل الوصول إلى المصفوفة

يتسلم Fetch(Connection, Query, MaxRows, out Data, var Abort) بيانات وصفية منفصلة أثناء تحديث ورقة العمل ويعيد TXLSQueryResultData مستطيلة؛ وتمسح عملية الإلغاء أو الاستثناءات النتائجَ المجهزة قبل نشرها

حدود الموارد

افتراضي MaxInputBytes هو 67108864 بايت ويقيّد إدخال Text أو Web وحمولات نتائج قواعد البيانات المدعومة؛ وافتراضي MaxResultCells هو 2000000 خلية ويقيّد النتيجة المستطيلة

افتراضي TimeoutSeconds هو 30 ويهيئ أطوار قواعد البيانات أو HTTP الأصلية المدعومة؛ وهو ليس موعدًا نهائيًا مضمونًا للعملية الكاملة ولا لمزود مخصص

يجب أن تكون الإعدادات الثلاثة وMaxRows موجبة، وأن يتسع المهلة في عدد صحيح أصلي بالمللي ثانية؛ ويرفض الموزِّع الصفوف والأعمدة والخلايا الزائدة دون بتر، بينما تُفرض حدود البايتات والإدخال من المزودات المدمجة وتبقى مسؤولية المعالج المسجل في الجلبات المخصصة

يتحقق تحديث ورقة العمل من كل قيم النتائج ويعيد الخلايا وبيانات الاستعلام أو الجدول الوصفية بعد الإلغاء أو أخطاء التطبيق؛ وتبقى المزودات المخصصة مسؤولة عن احترام حدود عملياتها الخارجية

ارتباطات نتائج XLSX الأصلية

تستخدم استعلامات قواعد البيانات المدعومة بالجداول علاقة الجدول بجدول الاستعلام ومعرِّفات الحقول المتماسكة وهويات الأعمدة واسم وجهة محلي مخفي؛ وتحتفظ وجهات Text وWeb المدعومة المستقلة بمدى نتيجتها

يعرض TXLSXTable.ColumnUniqueNames[Index]: WideString هويات أعمدة أصلية مبنية على الصفر ويحفظها عبر الإسناد والنسخ وإعادة الفتح مع ColumnQueryTableFieldIds

اتصال Text قديم مرتبط مباشرة كجدول خارجي ليس شكل تصدير أصليًا مدعومًا ويرفضه الحفظ قبل الإخراج؛ ويمكن للقيم النصية المحدَّثة صراحةً أن تملأ جدولًا عاديًا، أو يوفر مشغل نصوص ADO/ODBC مثبَّت استعلام قاعدة بيانات مدعومًا بجدول

تبقى العلاقات المستوردة وXML الامتدادات غير ذات الصلة أو غير المدعومة محفوظة؛ فهذه الميزة لا تحول الرسوم الخارجية المعتمة إلى استعلامات قابلة للتحديث مدعومة

راجع واجهات الاستعلام الاتصالية والمعاملاتية للتحقق من الوجهات ونداءات التقدم ونموذج البيانات الوصفية المحيط