dataset serialize

مجموعة البيانات التسلسلية لـ Delphi و Lazarus (FPC)

DataSet Serialize هي مجموعة من الميزات لجعل العمل مع JSON و DataSet بسيط. يحتوي على ميزات مثل تصدير أو استيراد السجلات إلى مجموعة بيانات ، والتحقق من صحة ما إذا كانت JSON لديها جميع السمات المطلوبة (تم إدخالها مسبقًا في مجموعة البيانات) ، أو تصدير أو استيراد بنية حقول مجموعات البيانات بتنسيق JSON. بالإضافة إلى إدارة JSON المتداخلة من خلال التفاصيل الرئيسية أو استخدام TDATASETFIELD (يمكنك اختيار الطريقة التي تناسبك بشكل أفضل). كل هذا باستخدام مساعدي الفصل ، مما يجعله أكثر بساطة وأسهل في الاستخدام.

المتطلبات الأساسية لدلفي

• [Optional] للراحة ، أوصي باستخدام Boss (مدير التبعية لـ Delphi) للتثبيت ، ببساطة عن طريق تشغيل الأمر أدناه على محطة (Windows PowerShell على سبيل المثال):

 boss install github.com/viniciussanchez/dataset-serialize

التثبيت اليدوي لدلفي

إذا اخترت التثبيت يدويًا ، فما عليك سوى إضافة المجلدات التالية إلى مشروعك ، في Project> Options> Building> Delphi Compiler> Search Path

 ../dataset-serialize/src

ابدء

توجد جميع الميزات التي تقدمها SARASET Serialize في الفئة المساعد في مجموعة بيانات الوحدة. لبدء تشغيل مشروعك ، ما عليك سوى إضافة مرجعك إلى مكان الحاجة إلى وظيفتك. هذا مثال:

 uses DataSet.Serialize;

دعونا الآن نلقي نظرة على كل ميزة ، قواعدها وخصائصها ، لتقديم أفضل ما في ذلك لجميع المستخدمين.

مجموعة البيانات إلى JSON

يبدو أن إنشاء كائن JSON يحتوي على معلومات من سجل مجموعة البيانات بمثابة مهمة بسيطة للغاية. لكن هذه المهمة أصبحت أسهل. يحتوي Serialize على وظيفتين لهذا ، وهما TojsonObject و Tojsonarray. دعونا نلقي نظرة على استخدام الوظائف:

 var
  LJSONArray: TJSONArray;
  LJSONObject: TJSONObject;  
begin
  LJSONObject := qrySamples.ToJSONObject(); // export a single record
  LJSONArray := qrySamples.ToJSONArray(); // export all records 
end ;

ما هو الفرق بين الوظيفتين؟ ستقوم TojsonObject بتحويل سجل مجموعة البيانات الحالي إلى TJsonObject. سيتم تحويل Tojsonarray إلى TJsonArray جميع سجلات مجموعة البيانات وليس فقط السجل المحدد.

حدود

• AChildRecords - يشير إلى ما إذا كان سيتم تصدير سجلات الأطفال (عبر التفاصيل الرئيسية أو TDATASETFIELD).
• يشير AOnlyUpdatedRecords - إلى ما إذا كان سيتم تصدير السجلات التي تم تعديلها فقط (تم إضافة السجلات أو تغييرها أو حذفها). هذه الميزة متاحة فقط عند استخدام FireDac. يجب أن تكون خاصية CacheDupdates صحيحة ؛

tojsonoBject

• إذا كانت مجموعة البيانات فارغة أو لم يتم تعيينها ، فسيتم إرجاع كائن JSON فارغ ( {} ) ؛
• سيتم تجاهل الحقل الذي لا يحتوي على خاصية مرئية (حقيقية).
• سيكون اسم السمة في JSON دائمًا اسم الحقل في الحالة السفلية ، حتى لو كان اسم الحقل في الحالة العليا ؛
• إذا كان الحقل من نوع tdatasetfield ، يتم إنشاء JSON المتداخلة (JSONOBJECT إذا كان مجرد سجل طفل ، أو JSONARRAY إذا كان أكثر من واحد). الطريقة الأنسب لهذا النوع من المواقف هي إنشاء تفاصيل رئيسية ؛
• سيتم تصدير جميع سجلات الأطفال باعتبارها jsonarray.
• عند استخدام معلمة AonlyupdatedRecords لطريقة TojsonObject أو TojsonArray ، تتم إضافة عنصر JSON إلى خاصية "Object_state" المسؤولة عن تحديد ما حدث للسجل (تم حذفه أو تغييره أو تغييره) ؛
• عند إنشاء مجموعة JSON لتمثيل JSON المتداخل باستخدام التفاصيل الرئيسية ، سيكون اسم مجموعة البيانات هو اسم سمة JSON التي تم إنشاؤها. هناك قاعدة حيث يبدأ اسم مجموعة البيانات بـ Qry (Query) أو MT (memtable) ، يتم تجاهل هذه الأحرف الأولى ، تاركة فقط الباقي كاسم السمة في JSON.

توجوناراي

• إذا كانت مجموعة البيانات فارغة أو لم يتم تعيينها ، فسيتم إرجاع مجموعة JSON فارغة ( [] ) ؛
• يتبع نفس القواعد مثل TojsonObject ؛

حفظ وتحميل بنية

ميزة غير مفيدة للغاية ولكنها مهمة هي الحافز والبنية. كما قال الاسم بالفعل ، من الممكن حفظ البنية الكاملة للحقول التي تم تكوينها في مجموعة البيانات وأيضًا تحميل بنية بتنسيق JSON. إليك مثال على كيفية تحميل وتصدير حقول مجموعات البيانات:

 var
  LJSONArray: TJSONArray;
begin
  LJSONArray := qrySamples.SaveStructure;
  qrySamples.LoadStructure(LJSONArray, True);
end ;

يتم التحكم في الخصائص التالية:

Alignment, FieldName, DisplayLabel, DataType, Size, Key, Origin, Required, Visible, ReadOnly, and AutoGenerateValue ؛

حدود

• AOwns - يشير إلى من هو المسؤول عن تدمير JSON التي تم تمريرها كمعلمة.

وحشية

• إذا كان عدد حقل مجموعة البيانات يساوي صفرًا ، فسيتم إرجاع مجموعة JSON فارغة ( [] ) ؛

الحمل

• لا يمكن تنشيط مجموعة البيانات ولا يجب أن يكون لها حقول محددة ؛

التحقق من صحة JSON

تعد وظيفة ValidateJson مفيدة للغاية عندما نريد التحقق من صحة الخادم على سبيل المثال إذا كان لدى JSON الذي تلقيناه في الطلب جميع المعلومات المطلوبة. من الناحية العملية ، يتم اجتياز جميع الحقول في مجموعة البيانات ، والتحقق مما إذا كانت الحقول المطلوبة قد تم إدخالها في JSON. إذا كان الحقل مطلوبًا ولم يتم إدخاله في JSON ، فسيتم إضافته إلى مجموعة JSON التي يتم إرجاعها بواسطة الوظيفة. انظر المثال أدناه:

 begin
  LJSONArray := qrySamples.ValidateJSON( ' {"country":"Brazil"} ' );
end ;

عند استلام {"country": "Brazil"} ، على افتراض أن مجموعة البيانات لدينا لديها 3 حقول (ID ، First_Name ، Country) ، وحقل ID و First_Name ، سيتم إرجاع ما يلي:

 [{"field":"id","error":"Id not informed"},{"field":"firstName","error":"Name not informed"}]

حدود

• ALang - مسؤول عن تغيير اللغة المستخدمة في تجميع الرسائل (الافتراضي هو اللغة الإنجليزية) ؛
• AOwns - يشير إلى من هو المسؤول عن تدمير JSON التي تم تمريرها كمعلمة ؛

ValidateJson

• إذا لم يتم تعيين JSON أو عدد الحقول يساوي صفرًا ، فسيتم إثارة استثناء.
• اللغة الافتراضية للرسائل هي اللغة الإنجليزية.
• حتى إذا تم إدخال جميع الحقول المطلوبة ، يتم إرجاع مجموعة JSON فارغة ( [] ) ؛
• يجب أن يكون للحقل المطلوب خاصية مطلوبة مساوية للواحد.
• يمكن استخدام خاصية DisplayLabel لتخصيص الرسالة ؛

تحميل من JSON

يتيح لك DataSet Serializa تحميل مجموعة بيانات مع JsonObject و JSonarray وحتى JSON المتداخلة جميعها ملخصة بطريقة واحدة: loadfromjson (). إليك مثال على كيفية استخدامه:

 begin
  qrySamples.LoadFromJSON( ' {"firstName":"Vinicius Sanchez","country":"Brazil"} ' );
end ;

حدود

• AOwns - يشير إلى من هو المسؤول عن تدمير JSON التي تم تمريرها كمعلمة ؛

loadfromjson

• إذا لم يتم تعيين JSON أو DataSet ، فلن يتم القيام بأي شيء ؛
• إذا لم يتم تنشيط مجموعة البيانات وليست فئة TFDMemtable ، فلن يتم القيام بأي شيء ؛
• إذا كانت مجموعة البيانات من النوع TFDMemtable ، فهي ليست نشطة وحقول العد تساوي صفرًا ، فسيتم إنشاء الحقول وفقًا لاحتياجات JSON. سيكون نوع البيانات مساوياً لـ Ftstring وحجم ما يساوي 4096 ؛
• عندما تكون خاصية "Object_State" في JSON ، يتم إجراء عمليات التحقق التالية:
  • إذا كان مساويًا للإدراج ، يتم تنفيذ إلحاق على مجموعة البيانات ؛
  • إذا تم تعديله أو حذفه ، يتم إجراء موقع في مجموعة البيانات للعثور على السجل المراد معالجته. إذا لم يتم العثور على السجل ، فلن يتم القيام بأي شيء. لتنفيذ موقع ، يتم البحث عن الحقول الرئيسية داخل JSON ؛
  • إذا تم تعديله يساوي طريقة تحرير مجموعة البيانات ؛
  • إذا تم حذفه يساوي طريقة حذف مجموعة البيانات ؛
• إذا لم يتم العثور على خاصية "Object_State" في JSON ، فسيتم استدعاء طريقة الإلحاق ؛
• عند تحميل مجموعة بيانات مع JSON ، يتم تجاهل الحقول التي يتم قراءتها أو مرئية (خاطئة) ؛
• إذا لم يتم العثور على سمة في JSON مع اسم الحقل (وليس حساسة للحالة) ، أو أنها nullo ، يتم تجاهل الحقل (nullo / فارغة) ؛
• عند تحميل مجموعة بيانات مع JSON التي تحتوي على JSON المتداخلة باستخدام التفاصيل الرئيسية ، حسب الاتفاقية ، من المتوقع أن يكون اسم مجموعة البيانات الطفل هو نفسه اسم سمة JSON الذي يمثل قائمة الأطفال المراد تحميلها. قد لا يزال يحتوي اسم مجموعة بيانات الطفل على الأحرف الأولى من القرص (الاستعلام) أو MT (memtable) ، حيث سيتم تجاهلها ؛

دمج من JSON

مع تسلسل مجموعة البيانات ، لا يزال بإمكانك تغيير تسجيل مجموعة البيانات ببساطة باستخدام MergeFromJsonObject. الوظيفة تشبه loadfromjson. مثال على الاستخدام هو لخوادم REST عندما يتم طرح الفعل المستخدم في الطلب (وليس بالضرورة) ، في هذه الحالة لا نريد تضمين سجل جديد ولكن لتغيير السجل الحالي.

 begin
  qrySamples.MergeFromJSONObject( ' {"firstName":"Vinicius","country":"United States"} ' );
end ;

حدود

• AOwns - يشير إلى من هو المسؤول عن تدمير JSON التي تم تمريرها كمعلمة ؛

mergefromjsonoBject

• نفس عمليات التحقق من عمليات التحميل fromjson ؛

التكوينات

يمكنك تخصيص بعض ميزات مجموعة البيانات:

• إدخال التاريخ هو UTC (المنطقة الزمنية)

TDataSetSerializeConfig.GetInstance.DateInputIsUTC := True;

• تصدير القيم الفارغة

  TDataSetSerializeConfig.GetInstance. Export .ExportNullValues := True;

• محاولات لتحويل سلسلة إلى JSON عندما تبدأ السلسلة بـ {أو [

  TDataSetSerializeConfig.GetInstance. Export .TryConvertStringToJson := True;

• تصدير الحقول فقط مرئية

  TDataSetSerializeConfig.GetInstance. Export .ExportOnlyFieldsVisible := True;

• تصدير مجموعة بيانات الأطفال ككائن JSON (عندما يكون لديك سجل واحد فقط)

  TDataSetSerializeConfig.GetInstance. Export .ExportChildDataSetAsJsonObject := False;

• تصدير كبير كسلسلة

  TDataSetSerializeConfig.GetInstance. Export .ExportLargeIntAsString := False;

• تصدير BCD كما تعويم

  TDataSetSerializeConfig.GetInstance. Export .ExportBCDAsFloat := False;

• استيراد حقول فقط مرئية

  TDataSetSerializeConfig.GetInstance. Import .ImportOnlyFieldsVisible := True;

• BASE64 فك تشفير حقول النقطة على الاستيراد

  TDataSetSerializeConfig.GetInstance. Import .DecodeBase64BlobField := True;

• قم بإزالة مساحة فارغة على اسم FieldName

  TDataSetSerializeConfig.GetInstance.RemoveBlankSpaceFieldName := True; // default

• تعريف اسم الحالة

  // cndNone, cndLower, cndUpper, cndLowerCamelCase, cndUpperCamelCase
  TDataSetSerializeConfig.GetInstance.CaseNameDefinition := TCaseNameDefinition.cndLowerCamelCase;
  
  TCaseNameDefinition.cndNone:
  [ { "MOB_ICADASTRO":11795,"MOB_EMI_REG":6,"CODIGODOCLIENTE":1,"CDOCUMEN1":"999999" } ]
  
  TCaseNameDefinition.cndLower:
  [ { "mob_icadastro":11795,"mob_emi_reg":6,"codigodocliente":1,"cdocumen1":"999999" } ]

  TCaseNameDefinition.cndUpper:
  [ { "MOB_ICADASTRO":11795,"MOB_EMI_REG":6,"CODIGODOCLIENTE":1,"CDOCUMEN1":"999999" } ]

  TCaseNameDefinition.cndLowerCamelCase:
  [ { "mobIcadastro":11795,"mobEmiReg":6,"codigodocliente":1,"cdocumen1":"999999" } ]

  TCaseNameDefinition.cndUpperCamelCase:
  [ { "MobIcadastro":11795,"MobEmiReg":6,"Codigodocliente":1,"Cdocumen1":"999999" } ]  

• تاريخ التنسيق (لنوع حقل التصدير يساوي ftdate)

  TDataSetSerializeConfig.GetInstance. Export .FormatDate := ' YYYY-MM-DD ' ;

• تنسيق العملة (لنوع حقل التصدير يساوي FTCurrency)

  TDataSetSerializeConfig.GetInstance. Export .FormatCurrency := ' 0.00## ' ;

• تنسيق تعويم (لنوع حقل التصدير يساوي ftfloat)

  TDataSetSerializeConfig.GetInstance. Export .FormatFloat := ' ,0.00 ' ;

• تحديد بادئات مجموعة البيانات

  TDataSetSerializeConfig.GetInstance.DataSetPrefix := [ ' mt ' , ' qry ' ];

عينات

تحقق من مشروع العينة لدينا لكل موقف معروض أعلاه في العملية. إذا كان لديك أي أسئلة أو اقتراح ، فيرجى الاتصال أو تقديم طلب السحب أو إنشاء مشكلة.

المساهمون في الكود

رخصة

DataSet-Serialize مجاني ومفتوح المصدر مرخصة بموجب ترخيص معهد ماساتشوستس للتكنولوجيا.

وحدنا نذهب أسرع. معا نذهب أبعد من ذلك.