مخرجات السكربت: line وhistogram وbands وmarkers وlevels وtable وpanel
سكربت المستخدم يعيد مصفوفة مخرجات، يُعرَّف كلٌّ منها بشكله. خمسة أشكال تُرسم على الـ canvas (line وhistogram وbands وmarkers وlevels) واثنان يُصاغان بطاقتَي DOM قابلتين للسحب (table وpanel). وكل مخرَج يُنمَّط قبل بلوغه الراسم، وكل ما لا يُعرَف يُبلَّغ عنه بدل إسقاطه بصمت.
Senzoukria · التوثيق · آخر تحديث: سبتمبر 2026
أين تجده
- الموضع
- القيمة المعادة من compute() في أي سكربت مستخدم؛ وتُرسم على الرسم حين يكون السكربت معروضًا
- الهدفان
- «On the chart» (فوق السعر) أو «Own pane» (لوحة بارتفاع 90 بكسل تحت الرسم)
- حدود الـ DOM
- table: 50 صفًّا و8 أعمدة؛ وpanel: 50 مدخلًا؛ والزائد يُقتطع
- المفتاح الزمني
- يجب أن تساوي point.time قيمة bucketTsNs لشمعة (حقبة بالنانوثانية)؛ وتُهمَل النقاط الأخرى
ما الذي يفعله
لا يعرف الراسم إلا قيم SeriesOutput؛ ولا يرى أبدًا السكربت الذي أنتجها. ولهذا تتشارك المؤشرات المدمجة وسكربتات المستخدم الأشكال نفسها وقواعد التنميط نفسها: فالنقطة خارج الشموع المرئية تُهمَل، والقيمة غير المنتهية تصير فجوة (value: null)، والقيمة null المكتوبة عن قصد، مثلًا أثناء إحماء متوسّط متحرّك، تُحفَظ قلمًا مرفوعًا بدل قطعة كاذبة.
ويُختار هدف الرسم لكل سكربت. فـ «On the chart» يضع المخرَج فوق السعر؛ و«Own pane» يحجز لوحةً ارتفاعها مثبَّت من الراسم عند 90 بكسل. ولأن الجداول ولوحات القيم عناصر DOM، فإن سكربت لوحة لم يبقَ من مخرجاته إلا جدول لا يحجز لوحةً فارغة: فالفصل بين مخرجات الـ canvas ومخرجات الـ DOM يقع قبل أن يعدّ الراسم اللوحات.
الأشكال وحقولها
| الشكل | الحقول | الافتراضيات المطبَّقة |
|---|---|---|
| line | points [{time, value|null}]، وstyle {color, width, style} | اللون #7ed321؛ والعرض مقيَّد بين 0.5 و12؛ والنمط solid أو dashed أو dots |
| histogram | points [{time, value}]، وpositiveColor، وnegativeColor | #22c55e للموجب و#ef4444 للسالب؛ والشمعة بلا قيمة منتهية لا تصدر نقطة |
| bands | مصفوفات نقاط upper وbasis وlower، وfillAlpha، وstyle | fillAlpha بقيمة 0.12، مقيَّدة بين 0 و1؛ وstyle كما في line |
| markers | markers [{time, price, kind, color, label?}] | kind هو dot ما لم يكن arrow-up أو arrow-down أو square؛ واللون #7ed321 |
| levels | levels [{price, from, to|null, color, label?, style?}] | to بقيمة null يمدّ المستوى إلى الحافة اليمنى؛ ولا يُشترط إلا price وfrom |
| table | title?، وcolumns [{key, label, align?}]، وrows [{key: string|number|null}] | يُرفض بلا عمود؛ و8 أعمدة و50 صفًّا على الأكثر؛ ومفاتيح الصفوف غير المعروفة تُسقَط |
| panel | title?، وentries [{label, value, color?}] | 50 مدخلًا على الأكثر؛ والمدخل الذي ليست قيمته سلسلةً ولا عددًا منتهيًا يُتخطّى |
بطاقتا table وpanel
تُصاغ الجداول ولوحات القيم بطاقاتٍ عائمة فوق الرسم لأن الجدول يجب أن يُقرأ ويُحدَّد ويُنسخ، وهو ما لا يقدّمه الـ canvas، ولأن لوحةً بارتفاع 90 بكسل لا تحمل إلا ثلاثة أسطر. ويُعنوَن كل بطاقة باسم السكربت، متبوعًا بـ « · » ثم عنوان المخرَج حين يُعطى. وتُسحب البطاقات من رأسها؛ ويُحفظ موضع كلٍّ منها لكل مخرَج تحت المفتاح orderflow.seriesTables.v1 عند نهاية السحب. وبلا موضع محفوظ، تتدرّج البطاقات من الزاوية العليا اليمنى (60 بكسل نزولًا و12 بكسل إلى الداخل، بإزاحة 26 بكسلًا و14 بكسلًا لكل بطاقة إضافية) حتى لا تتراكب بطاقتان تمامًا أبدًا.
ويُحدَّث الـ DOM مرّةً واحدة في كل إطار رسم، لا بمعدّل نشر الشموع البالغ 4 هرتز، وتُطبع الخلية الفارغة «—» بدل 0. ومحاذاة العمود افتراضيًّا إلى اليسار؛ والسكربت الذي يريد الأعداد إلى اليمين يضبط align: "right" على العمود.
كيف تستعمله
تبني مساعدات lib الأشكال الشائعة: lib.line(chronoBars, values, color, width) وlib.histogram وlib.markers وlib.levels وlib.table(columns, rows, title) وlib.panel. والمصفوفات المُمرَّرة إلى مساعدات lib بترتيب زمني تصاعدي، فاعكس أولًا الشموع الواردة بالأحدث أولًا. ويستطيع سكربت واحد إعادة عدّة مخرجات، مثل مخرَج bands ومخرَج line لـ VWAP بنطاقات سيغما.
والشكل المرفوض لا يختفي: فيُوسَم السكربت في لوحة المؤشرات، حيث يصير السطر تحت اسمه «Unrecognised return value. An indicator returns a series, lines or markers — see "Indicator: what to return".» بدل هدف رسمه. والسكربت الذي يعيد مخرجات لا ترسم شيئًا يُوسَم «empty»، وهو ما يميّز «إنه لا يعمل» عن «لم يكن هناك شيء ليُعرض».
الحدود والمزالق
- العروض دون 0.5 أو فوق 12 بكسلًا تُقيَّد؛ وأسماء الأنماط غير المعروفة تعود إلى solid.
- ونقاط histogram ذات القيمة null أو غير المنتهية تُزال بالكامل، بخلاف الخطوط حيث تكون null فجوة.
- وlevels قطعٌ مفهرَسة بـ price وfrom؛ وهي لا تُرشَّح بوقت الشمعة، فطابعة from أقدم من التاريخ المحمَّل تبدأ ببساطة عند الحافة اليسرى.
- والجدول الذي يزيد على 50 صفًّا يُقتطع؛ فاكتب الاقتطاع في العنوان بنفسك إن كان العدد مهمًّا.
صفحات ذات صلة
هذه الصفحة بلغات أخرى
أسئلة شائعة
- لماذا ليس جدولي في اللوحة التي اخترتها؟
- الجداول ولوحات القيم تُصاغ دائمًا بطاقات DOM فوق الرسم، مهما كان هدف الرسم. والهدف لا يؤثّر إلا في أشكال الـ canvas مثل الخطوط والمدرَّجات.
- كيف أُظهر فجوة بدل خطّ إلى الصفر أثناء الإحماء؟
- أعِد value: null لتلك النقاط. فالراسم يرفع القلم؛ أمّا الصفر فسيرسم قطعةً كاذبة.
- هل أستطيع نقل بطاقة الجدول والاحتفاظ بمكانها؟
- نعم. اسحبها من رأسها؛ فيُخزَّن الموضع لكل مخرَج في localStorage ويُستعاد حين يُفتح الرسم من جديد.