يشترك كل لوحة معلومات يعرضها Sprucely.io - سواء أُنشئت عبر بيئة تشغيل JavaScript المستقلة، أو مكوّنات React المستقلة، أو كانت محفوظة في حسابك - في بنية JSON الأساسية نفسها: كائن config يحمل التنسيق العام للوحة المعلومات، وكائن data يصف شجرة عناصر الواجهة. يوثّق هذا المرجع بنية JSON هذه بالكامل، إلى جانب صيغة مجموعة البيانات التي تُقرأ منها، ونوع المخطط الذي ينبغي اختياره لتركيبة معيّنة من الأعمدة. للاطلاع على تعليمات التضمين، راجع ملاحظات التكامل البسيط للوحة المعلومات.
JSON لوحة المعلومات
كل لوحة معلومات هي كائن JSON واحد يضم مفتاحين على المستوى الأعلى: config الذي يحمل التنسيق العام للوحة المعلومات، وdata وهو شجرة من عقد عناصر واجهة مصنّفة حسب النوع، تبدأ من جذر واحد للوحة المعلومات. تحتوي كل عقدة على حقل type، وبالنسبة لأنواع الحاويات، على مصفوفة children من العقد المتداخلة.
dash- جذر لوحة المعلومات. يوجد دائماً عنصر واحد فقط منه، في أعلى الشجرة.dash_stacker_hor/dash_stacker_ver- يرتّب عناصره الفرعية في صف أو عمود.dash_chart- مخطط، بأحد أنواع المخططات المدعومة (انظر أدناه).dash_table- جدول بيانات.dash_text- كتلة نصية.dash_image- صورة مرفوعة.dash_spacer- فراغ ثابت بين عناصر الواجهة.
يقبل كل عنصر واجهة الحقول التنسيقية نفسها، بصرف النظر عن نوعه:
size- حجم عنصر الواجهة على طول المحور الرئيسي لحاويته: ‘Auto’، ‘<n>px’ أو ‘<n>%’.padding- الحشو الداخلي، على سبيل المثال ‘10px’ (باستثناء dash_spacer).backgroundColor- لون CSS، على سبيل المثال ‘#FFFFFF’ أو ‘transparent’.borderRadius/borderWidth- نصف قطر الزوايا وسماكة الحدّ، على سبيل المثال ‘10px’.borderColor- لون CSS للحدّ.shadow- true أو false؛ يضيف ظلاً منسدلاً.
عناصر المخططات
يشترك كل مخطط في الحقول نفسها؛ أما أيّ من x وy وd وr يُستخدَم، ونوع العمود الذي يقبله كل منها، فيتوقف على نوع المخطط - يُغطّى كل نوع من أنواع المخططات المدعومة في قسم فرعي خاص به أدناه، مع مثال حي مُعروض من مجموعة بيانات صغيرة مشتركة واحدة.
datasetId- مجموعة البيانات التي يقرأ منها هذا المخطط - يجب أن تطابق اسم مجموعة بيانات.chartType- area, bar, cell, dot, hexbin or line.title- عنوان اختياري للمخطط.dataFunction- دالة التجميع المطبَّقة علىd: count (default), sum, average, min, max, median or stddev. اتركdبلا قيمة عند استخدام count.x- العمود المستخدَم للبُعد X (مطلوب في جميع أنواع المخططات).y- العمود المستخدَم للبُعد Y (cell وdot وhexbin فقط، وهو مطلوب في هذه الأنواع الثلاثة).d- العمود المجمَّع في بُعد القيمة/اللون في المخطط.r- العمود المستخدَم لبُعد نصف القطر (dot فقط، وهو مطلوب).seasonX/seasonY- يجمّع عموداً زمنياً ضمن فترة متكرّرة: year, quarter, month, week, dayofyear, day, dayofweek, hour, minute or second.
تُصنَّف أعمدة الأبعاد على أنها تصنيفية أو زمنية أو مستمرة استناداً إلى نوعها المُعلَن - انظر قسم JSON مجموعة البيانات أدناه. عندما تكون dataFunction هي count، يُترك بُعد d بلا قيمة - إذ لا يحتاج العدّ (count) إلى عمود قيمة. أما أي دالة تجميع أخرى (sum, average, min, max, median or stddev) فتتطلّبه.
يجب تعبئة الأبعاد التي يتطلّبها نوع المخطط: لا يمكن رسم cell وdot وhexbin بدون y، ولا يمكن رسم dot بدون r. ويُرفض أي طلب يُغفل أحدها، لذا إذا لم تتضمّن مجموعة البيانات عموداً مناسباً فاختر نوع مخطط لا يحتاج إليه - إذ تكتفي area وbar وline بـx وحده، بينما يرسم hexbin بُعدين اثنين دون عمود نصف قطر.
أعمدة
يقبل x عموداً تصنيفياً أو مستمراً أو زمنياً. يجب أن يكون d مستمراً، ولا يُستخدَم إلا عندما لا تكون dataFunction هي count. يُسمح باستخدام seasonX عندما يكون x عموداً زمنياً، لتجميعه ضمن فترة متكرّرة مثل يوم الأسبوع. لا يُستخدَم y ولا r.
خطوط
يقبل x عموداً مستمراً أو زمنياً - وليس تصنيفياً. يجب أن يكون d مستمراً، ولا يُستخدَم إلا عندما لا تكون dataFunction هي count. الموسمية غير مدعومة. لا يُستخدَم y ولا r.
مساحات
يقبل x عموداً مستمراً أو زمنياً - وليس تصنيفياً. يجب أن يكون d مستمراً، ولا يُستخدَم إلا عندما لا تكون dataFunction هي count. الموسمية غير مدعومة. لا يُستخدَم y ولا r.
خلايا
يتطلّب كل من x وy عموداً تصنيفياً، أو عموداً زمنياً مفعَّلاً فيه الموسمية (seasonX لـx، وseasonY لـy). يجب أن يكون d مستمراً، ولا يُستخدَم إلا عندما لا تكون dataFunction هي count. يتطلّب seasonY أيضاً أن يكون x قد تحوّل بالفعل إلى بُعد تصنيفي - سواء كان عموداً تصنيفياً فعلياً، أو عموداً زمنياً مضبوطاً عليه seasonX. لا يُستخدَم r.
نقاط
يقبل x وy عموداً مستمراً أو زمنياً. يجب أن يكون كل من r وd مستمراً - ولا يكون تصنيفياً أو زمنياً أبداً. الموسمية غير مدعومة. تُقرأ مخططات النقاط بشكل أفضل مع مجموعات بيانات تضم حتى بضع مئات من الصفوف.
سداسيات
يقبل كل من x وy عموداً مستمراً أو زمنياً - وليس تصنيفياً. يجب أن يكون d مستمراً، ولا يُستخدَم إلا عندما لا تكون dataFunction هي count. الموسمية غير مدعومة. لا يُستخدَم r.
عناصر أخرى
جدول (dash_table)
datasetId- مجموعة البيانات المراد عرضها.fontFamily- Arial افتراضياً؛ إحدى الخطوط التالية: Arial, Calibri, Cambria, Century Gothic, Courier New, Garamond, Helvetica, Consolas/Monaco (Monospace), Lucida Bright, Lucida Sans, Segoe UI, Tahoma, Verdana.fontSize- 12px افتراضياً؛ 6-256px أو 1-10vw.color- inherit افتراضياً.bold/italic- true أو false، وfalse افتراضياً.ratio- نسبة العرض إلى الارتفاع، رقم من 0.125 to 16.
نص (dash_text)
text- النص المراد عرضه.fontFamily/fontSize(افتراضياً 3vw) /color/bold/italic- كما هي الحال في عنصر الجدول.justifyContent/alignItems- ‘0’ للبداية، ‘1’ للوسط أو ‘2’ للنهاية.
صورة (dash_image)
assetId- أصل صورة مرفوع.objectFit- none افتراضياً؛ none, contain, cover or fill.
فاصل (dash_spacer)
size- إلزامي؛ 100px افتراضياً؛ 0-100% أو 30-1000px.
مكدسات (dash_stacker_hor, dash_stacker_ver)
children- عناصر الواجهة المتداخلة، مرتَّبة في صف (dash_stacker_hor) أو عمود (dash_stacker_ver).gap- ‘10px’ افتراضياً؛ المسافة الفاصلة بين العناصر الفرعية.minHeight- الحد الأدنى لارتفاع المكدس.
JSON مجموعة البيانات
مجموعة البيانات هي كائن JSON واحد يضم اسماً وأعمدة مصنّفة حسب النوع وصفوفاً:
{
"name": "Orders",
"headers": ["region", "category", "amount", "quantity"],
"types": ["VARCHAR", "VARCHAR", "FLOAT", "INTEGER"],
"entries": [
["North", "Electronics", 120.50, 2],
["South", "Clothing", 89.95, 1],
["North", "Furniture", 432.00, 5],
["South", "Electronics", 74.50, 1]
]
}name- اسم مجموعة البيانات؛ تشير إليه المخططات والجداول عبر حقلdatasetIdالخاص بها.headers- أسماء الأعمدة، بالترتيب نفسه لكل صف في entries.types- نوع عمود واحد لكل عنوان - انظر الفئات أدناه.entries- الصفوف، كل منها مصفوفة من القيم بترتيب العناوين.
اختيارياً، تُحدِّد row_start وrow_end وcol_start وcol_end نطاقاً فرعياً من entries لاستيراده، يبدأ ترقيمه من صفر ويشمل الحدّين - وهو مفيد عند إضافة الصفوف الجديدة فقط من جدول أكبر. تُغطّي القيم الأربع جميعها النطاق الكامل افتراضياً:
{
"name": "Orders",
"headers": ["region", "amount"],
"types": ["VARCHAR", "FLOAT"],
"entries": [ ["North", 120.50], ["South", 89.95], ["North", 432.00], ["South", 74.50] ],
"row_start": 0,
"row_end": 1,
"col_start": 0,
"col_end": 1
}يُصنَّف كل نوع عمود على أنه تصنيفي أو زمني أو مستمر، وهذا ما يحدّد أبعاد المخطط التي يمكن استخدامه فيها - انظر أقسام عناصر المخططات أعلاه:
- تصنيفي -
BIT, BITSTRING, BOOLEAN, BOOL, LOGICAL, BLOB, BYTEA, BINARY, VARBINARY, UUID, VARCHAR, CHAR, BPCHAR, TEXT, STRING - زمني -
DATE, TIME, TIMESTAMP, DATETIME, TIMESTAMP WITH TIME ZONE, TIMESTAMPTZ - مستمر - كل نوع آخر، على سبيل المثال
INTEGER, FLOAT, DOUBLE, BIGINT, DECIMAL
يجب أن تطابق مراجع الأعمدة في المخطط (x, y, d, r) اسم عنوان مطابقةً تامة، بما في ذلك حالة الأحرف.
الأنماط وتجاوزات السمة
تُضبط ألوان لوحة المعلومات مرة واحدة في config.style.widget وتُطبَّق على كل عنصر واجهة لا يتجاوزها:
color- لون النص الافتراضي.backgroundColor- خلفية لوحة المعلومات الافتراضية.primaryColor- لون المقدّمة/السلسلة النشطة، يُستخدَم للعناوين والسلسلة المتأثرة بالتصفية المتقاطعة.primaryColorSubtle- الطرف المنخفض من التدرّج اللوني المستخدَم في مخططات cell وdot وhexbin.secondaryColor- لون الخلفية/السلسلة غير المصفّاة.
يمكن لأي عنصر واجهة أن يتجاوز تنسيقه الخاص مباشرة على عقدته في JSON - backgroundColor وcolor وpadding وborderRadius وborderWidth وborderColor وshadow. يتجاوز المثال أدناه ألوان مخطط واحد وزواياه، بينما تحتفظ بقية لوحة المعلومات بالسمة المشتركة:
{
"type": "dash_chart",
"datasetId": "Orders",
"chartType": "hexbin",
"x": "amount",
"y": "quantity",
"backgroundColor": "#F5F0FF",
"borderRadius": "12px",
"borderWidth": "1px",
"borderColor": "#6E2BDC",
"shadow": true
}مثال كامل
لوحة معلومات صغيرة تجمع بين عنوان، ومخططين جنباً إلى جنب، وجدول، جميعها يقرأ من مجموعة بيانات واحدة:
{
"config": {
"type": "dashboard",
"style": {
"widget": {
"color": "#000000",
"backgroundColor": "#FFFFFF",
"primaryColor": "#6E2BDC",
"primaryColorSubtle": "#E2D5F8",
"secondaryColor": "#CCCCCC"
}
}
},
"data": {
"type": "dash",
"children": [
{ "type": "dash_text", "text": "Orders Overview", "fontSize": "2vw", "justifyContent": "0" },
{
"type": "dash_stacker_hor",
"children": [
{ "type": "dash_chart", "datasetId": "Orders", "chartType": "bar", "x": "region", "dataFunction": "count" },
{ "type": "dash_chart", "datasetId": "Orders", "chartType": "cell", "x": "region", "y": "category", "dataFunction": "count" }
]
},
{ "type": "dash_table", "datasetId": "Orders" }
]
}
}