أسطورة

UI.legend يرسو أسطورة في زاوية القماش: صف واحد لكل فئة، كل منها به حامل اللون والملصق وعدد العقد الموجودة خلفه. مشيراً إلى صف الأضواء تلك الفئة على القماش؛ يؤدي النقر فوق أحدها إلى إخفاءه، وبالتالي تتضاعف وسيلة الإيضاح كـ أسرع مرشح في واجهة المستخدم.

const options = {
    UI: {
        legend: { key: 'type', title: 'Node type' },
    },
}

قد لا تحتاج إلى هذه الكتلة على الإطلاق: مع عدم وجود UI.legend، تظهر وسيلة إيضاح ** عليها امتلك** عندما يتم شرح ألوان الرسم البياني الخاص بك بواسطة render.nodeTypeAccessor المعلن - راجع تشغيل بشكل افتراضي. UI.legend: false يطفئه.

يحتاج الرسم البياني الذي يشفر عدة أشياء في وقت واحد إلى عدة مفاتيح: تمرير sections بدلاً من مفتاح واحد - راجع عدة مفاتيح في وقت واحد.

تعد وسيلة الإيضاح جزءًا من chrome، لذا فهي تظهر في الوضعين full وlight فقط — viewer و static ليس لديهما شيء.

الأسطورة لا تلون أي شيء أبدًا

الأسطورة هي وصفية. يقرأ اللون الذي تم حل العارض له بالفعل العقدة (renderer.getNodeStyle(node).color) والإبلاغ عنها. التلوين يبقى حيث هو كان: render.defaultNodeStyle.color، render.nodeStyleMap، أو نمط لكل عقدة — عادةً عبر ColorPaletteMapper. قم بتغيير اللوحة وستتبع الأسطورة من تلقاء نفسها.

قيد التشغيل بشكل افتراضي

لا تستحق الأسطورة إظهارها دون سؤال إلا إذا كانت مضمونة لقول الحقيقة، لذا فإن يبدأ التشغيل التلقائي من شيء أعلنته بالفعل وليس من التخمين حول بياناتك: render.nodeTypeAccessor، البعد الذي تشير إليه nodeStyleMap الساعة.

ومع ذلك، فإن وجود مرشح ليس كافيًا - حيث يمكن للبُعد تقسيم بياناتك بدونه أي علاقة بألوانها. لذلك قبل تقديم أي شيء، الأسطورة يتحقق من أن هذا البعد يوضح الألوان:

• يتم تحديد كل فئة بالضبط واحد اللون؛
• يوجد على الأقل two ألوان مميزة (وإلا فإن الألوان لا توضح الفئات متباعدة)؛
• توجد فئات 24 على الأكثر - يُنتج البُعد المشابه للمعرف قيمة واحدة لكل العقدة، ولكل منها لونها الخاص، والتي من شأنها أن تبحر من خلال الاختيار أعلاه.

إذا فشل أي من ذلك، فلن تظهر وسيلة إيضاح ولن يتم تسجيل أي شيء: لم تطلب واحدة. يتم أيضًا تخطي وسيلة الإيضاح التلقائية بعد 5000 عقدة، حيث يتم أخذ عينات من كل عقدة اللون لا يستحق الدفع مقابل غير المدعوين - هذا يحذر منه، وبالتالي فإن الغياب يستحق قابل للتفسير. الإعلان UI.legend (أو true) يرفع كليهما.

// nothing declared → a legend appears iff `type` explains the colours
render: { nodeTypeAccessor: (node) => node.getData().type, nodeStyleMap: { … } }

UI: { legend: false }   // never
UI: { legend: true }    // derive from nodeTypeAccessor, check or no check
UI: { legend: { position: 'top-right' } }   // automatic entries, your placement

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

من أين تأتي الإدخالات

مشتقة من مفتاح البيانات

key هو التكوين الكامل في الحالة الشائعة: القيم المميزة لـ node.getData()[key] تصبح الصفوف، بترتيب الظهور لأول مرة، تحمل القيمة نفسها.

UI: { legend: { key: 'type' } }

يساهم المفتاح قيمة المصفوفة بصف واحد لكل عنصر، ويتم احتساب العقدة ضمن كل منهما (tags: ['public', 'critical'] يظهر تحت كليهما).

شيئان يستحقان المعرفة حول الصفوف المشتقة:

• العقد بدون قيمة للمفتاح (null، undefined، '') لا تحصل على أي صف، و لا يمكن للأسطورة أن تخفيها أبدًا - فهي تعمل فقط على الفئات التي تدرجها. وقت التطوير تحذير يسمي المفتاح وعدد العقد غير الممثلة.
• فئة مطلية بأكثر من لون تحتفظ باللون الأول الموجود مع علامة تحذير: صف واحد يمكن أن يعرض عينة واحدة فقط. قم بتعريف الإدخالات بنفسك إذا كان التجميع ليس لونًا واحدًا حقًا.

الإدخالات المعلنة

قم بتمرير entries عندما لا تكون الفئات مفتاح بيانات عادي — مجموعات محسوبة، ملصقات مترجمة، مقياس ألوان ثابت. كل إدخال يحمل predicate خاص به، وهو ما تقوم به مرشحات التبديل.

UI: {
    legend: {
        title: 'Tier',
        entries: [
            { id: 'edge', label: 'Edge', color: '#0072B2',
              predicate: (node) => node.getData().type === 'web' },
            { id: 'storage', label: 'Storage', color: '#009E73',
              predicate: (node) => ['database', 'cache'].includes(node.getData().type) },
        ],
    },
}

entries قد تكون أيضًا دالة في الرسم البياني، ويتم إعادة حلها كلما ظهرت البيانات التغييرات - بحيث تتبع القائمة البيانات دون تغيير الإقرار:

UI: {
    legend: {
        key: 'type',
        entries: (graph) => distinct(graph, 'type').map((type) => ({
            id: type,
            label: t(`type.${type}`),        // translated, used verbatim
            color: palette.getColor(type),
        })),
    },
}

الإعلان عن كل من entries و key هو الحل الأوسط المفيد الموضح أعلاه: تعطي الإدخالات التسميات والألوان، ويوفر key المسند الافتراضي (data[key] === id) للمدخلات التي لا تحمل واحدة. دخول مع لا يحذر ولا يتطابق مع أي شيء.

تستمر حالة تبديل الصف بعد إعادة الدقة؛ إدخال يختفي من البيانات يفقدها بدلاً من البقاء كشبح مخفي.

عدة مفاتيح في وقت واحد

رسم بياني يشفر ثلاثة أشياء - النوع في التعبئة، والمصدر في العلبة، العلاقة في السكتة الدماغية - تحتاج إلى ثلاثة مفاتيح، وليس واحدا. مرر sections وسيحصل كل منهما كتلة خاصة بها تحمل عنوانًا، مكدسة من أعلى إلى أسفل في أمر الإعلان داخل واحد راسٍ بطاقة:

UI: {
    legend: {
        position: 'bottom-left',        // the card docks; sections don't
        sections: [
            { key: 'type',  title: 'Element' },
            { key: 'scope', title: 'Provenance' },
            { key: 'tlp',   title: 'Sharing', filterable: false },
        ],
    },
}

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

المرشحات ومعا

يقوم كل قسم قابل للتصفية بتشغيل الفلتر الخاص به، ومحرك الاستعلام يقوم بذلك: قم بإيقاف attribute في القسم الأول وإيقاف self في الثاني، وماذا تبقى على القماش العقد التي تكون ولا. كل قسم show all يمسح هذا القسم فقط.

يكتب القسم إلى __legend:<id>، حيث يكون المعرف هو id الخاص بالقسم، وإلا فهو key وإلا مكانه في المكدس (section-0). وسيلة إيضاح مفتاح واحد — الكائن النموذج - يحتفظ بالبساطة __legend التي استخدمها دائمًا. كما هو الحال مع أسطورة وحيدة، قسم الذي key أسماءه select / multiselect وجه معلن يقود هذا الوجه بدلاً من ذلك، وإخوته هم غير متأثر.

ربط الحواف بدلاً من العقد

يسرد القسم الذي يعلن scope: 'edge' أنواع علاقات ** الخاصة بالرسم البياني ** مع سطر * * حامل - لون الحد، والشرطة، والعلامة كما يحلها العارض - ومفاتيح التبديل الخاصة به إخفاء طبقات الحافة بدلاً من العقد. إنه موجود بجانب الأقسام ذات نطاق العقدة في نفس البطاقة ويتركهم دون مساس. راجع طبقات الحافة للتعرف على الميزة بأكملها.

UI: {
    legend: {
        sections: [
            { key: 'type', title: 'Element' },
            { key: 'kind', title: 'Relationship', scope: 'edge' },
        ],
    },
}

تسمية البعد الذي تصمم به

القسم الذي لا يحتوي على key ولا entries هو البعد الذي أعلنته بالفعل render.nodeTypeAccessor — التهجئة الوحيدة لبعد التصميم الذي ليس كذلك مفتاح بيانات عادي. إنه يتخطى فحص الألوان: داخل قائمة sections لقد طلبت ذلك. قسم واحد فقط يمكنه القيام بذلك؛ يتم إسقاط ثانية مع تحذير.

UI: { legend: { sections: [{}, { key: 'scope', title: 'Provenance' }] } }
//                         ↑ whatever nodeTypeAccessor returns, headed "Type"

قسم مغلق على البعد اللوني

يتم أخذ العينات ** من الألوان التي حلها العارض**، وهذا هو الوحيد قناة الأسطورة يمكن قراءتها. قسم مرتبط ببُعد لا تقوم الألوان بتشفيره - المصدر، عندما يتم رسم المصدر على شكل حاوية - يحصل على لون الأول عقدة في كل فئة، ويحذر من أن الفئة تعرض أكثر من واحدة. أعلن entries مع color الخاص بك في هذا القسم لإعطائه عينات تعني ذلك شيئا.

الفضاء

يتم طي الأقسام بشكل فردي؛ alt-انقر فوق أي رتبة رتبة لطي أو فتح الجزء بالكامل كومة في وقت واحد. لا يزال كل قسم يقوم بتمرير قائمته الخاصة بعد maxVisibleEntries، و يتم تغطية البطاقة ككل مقابل ارتفاع اللوحة القماشية ويتم تمريرها بدلاً من ذلك يتزايد بعد ذلك - لذا تبقى ستة أقسام داخل إطار العرض.

قسم يتحول إلى لا يوجد إدخالات (مفتاح لا تحمله عقدة، فارغ الإعلان) يتم تخطيه بالكامل بدلاً من إظهاره كمربع عنوان فارغ؛ بطاقة التي تكون جميع أقسامها فارغة، لا تعرض أي شيء على الإطلاق.

تحوم فئة

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

صف على قسم scope: 'edge' يضيء خطوط، مع تراجع العقد مع الطبقات الأخرى. حافة مطوية في مجموعة مغلقة أو مجموعة تبسيط تضيء الخط المرسوم في مكانها.

إن الإشارة إلى فئة تم إيقاف تشغيلها بالفعل لا تؤدي إلى تعتيم أي شيء - لا يوجد شيء تركت على القماش حتى تضيء.

highlightOnHover: false يطفئه لقسم. مفتاح filterable: false يبرز أيضًا، حيث يكون هو الشيء الوحيد الذي يفعله الصف.

يمكن إضاءة نفس المجموعة من الكود، والاحتفاظ بها حتى يتم مسحها:

graph.emphasiseElements(graph.getMutableNodes().filter((node) => node.getData()?.type === 'md5'))
graph.clearEmphasis()

كلاهما يأخذ العناصر التي رسمها العارض، لذلك يقرأان getMutableNodes() / getMutableEdges() بدلاً من أصحاب الاستنساخ.

التصفية

يؤدي تبديل صف إلى كتابة مرشح إلى graph.queryEngine — نفس المحرك لوحة الفلتر محركات الأقراص - لذلك لا شيء فيها هو ثانية متوازية آلية:

• تمت إضافة العقد بعد تبديل، في فئة مخفية، تصل مخفية.
• تظل الفئة المخفية مخفية داخل الرسم البياني الفرعي للمجموعة الموسعة.
• resetFilters()، أو Reset، يعيد إضاءة كل صف.
• مع كل صف يظهر، تتم إزالة الفلتر **، وبالتالي فإن عدد عوامل التصفية النشطة للرأس لا يبلغ عن أسطورة لا تخفي أي شيء.

افتراضيًا، تمتلك وسيلة الإيضاح مفتاح تصفية محجوزًا خاصًا بها (__legend) مطابقًا من خلال المسند - واحد لكل قسم، بمسافة الاسم __legend:<id>، في نموذج مكدس.

مشاركة مرشح مع اللوحة

عندما key يسمي المعلن select / multiselect وجه، الأسطورة تقود مفتاح هذا الوجه بدلاً من ذلك. تصبح وسيلة الإيضاح واللوحة بعد ذلك عرضين لمرشح واحد: قم بإيقاف تشغيل العينة و يؤدي التحديد المتعدد للوحة إلى إسقاط هذه القيمة؛ اختر القيم في اللوحة ووسيلة الإيضاح إعادة الأضواء وفقا لذلك.

UI: {
    filter: { facets: [{ key: 'type', label: 'Type', type: 'multiselect', options: … }] },
    legend: { key: 'type' },   // ⇒ writes setFilter('type', …)
}

نتيجتان للتحدث بلغة اللجنة:

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

إذا كان key يسمي وجهًا من نوع آخر (text، regex، numberRange، boolean) فإن تحتفظ وسيلة الإيضاح بمفتاحها الخاص وتحذر - ليس لقائمة القيم أي معنى هناك.

قراءة التبديلات

يتم الإعلان عن كل تبديل في ناقل حدث البيانات:

graph.on('legendToggle', ({ section, hidden, visible }) => {
    localStorage.setItem(`legend.hidden.${section}`, JSON.stringify(hidden))
})

section هو معرف القسم الذي تم تبديله، و hidden / visible هو ذلك صفوف القسم. تُبلغ وسيلة الإيضاح ذات المفتاح الواحد عن المعرف المشتق الخاص بها (key، else section-0).

الاستعادة هي نفس الدعوة التي تقوم بها وسيلة الإيضاح:

graph.queryEngine.setFilter('__legend', { value: visible, matchMode: 'exact' })

تغيير وسيلة الإيضاح في وقت التشغيل

graph.setLegend(config) يستبدل UI.legend مباشر. الرسم البياني الذي بدأ بدون تقوم الأسطورة ببناء واحدة على الفور، وتقوم false بإزالتها - مسح مرشحها باستخدام لذلك، لا يبقى شيء مخفيًا وراء أسطورة ذهبت.

graph.setLegend({ key: 'zone', title: 'Region' })
graph.setLegend({ sections: [{ key: 'zone' }, { key: 'tier' }] })
graph.setLegend(false)        // remove it
graph.setLegend(true)         // back to the derived one

يؤدي التبديل بين النموذجين إلى إعادة تسمية مفاتيح التصفية، وبالتالي فإن مرشحات النموذج تحتاج إلى إعادة تسمية يسقط اليسار: لا يبقى شيء مخفيا وراء قسم قد ذهب.

خيارات

UI.legend تأخذ أيضًا منطقية: false تمنع وسيلة الإيضاح، true تشتق واحدة من render.nodeTypeAccessor دون فحص الألوان أولاً. كل شيء أدناه هو شكل الكائن.

النموذج stacked هو { enabled?, position?, sections }: sections هي القائمة أدناه ناقص position، وenabled / position قم بوصف البطاقة بأكملها.

الخيار	اكتب	الافتراضي	ماذا يفعل
enabled	boolean	true	false يحتفظ بالإقرار ولكنه لا يظهر شيئًا (مثل legend: false).
id	string	key وإلا section-<index>	هوية القسم: مفتاح التصفية الخاص به (__legend:<id>) والحقل legendToggle section.
title	string	جميل key وإلا 'Legend'	نص الرأس، مستخدم حرفيًا (حتى يمكن ترجمته).
key	string	—	مفتاح البيانات الذي يتم اشتقاق الصفوف منه، والمسند الافتراضي للإدخالات المعلنة. احذف هذا وentries للأسطورة تلقائي.
entries	LegendEntry[] | (graph) => LegendEntry[]	—	الصفوف المعلنة تتم إعادة حل الوظيفة عند تغيير البيانات.
position	'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'	'bottom-right' في الوضع full وإلا 'bottom-left'	أي ركن من أركان القماش يتم الالتحام به. ينتمي إلى البطاقة، لذا فهو ليس خيار قسم. 'top-left' يشارك مرساته مع لوحة الأدوات السياقية، التي تغطي وسيلة الإيضاح أثناء فتحها.
collapsible	boolean	true	أظهر الشيفرون الذي يطويها إلى عنوانها.
collapsed	boolean	false	ابدأ مطوية.
showCounts	boolean	true	إظهار عدد العقد لكل فئة (على الرسم البياني بأكمله، بحيث لا يومض أثناء التبديل).
filterable	boolean	true	false يعرض مفتاحًا عاديًا وغير تفاعلي.
highlightOnHover	boolean	true	يؤدي تحريك الصف إلى إضاءة هذا الخط على اللوحة القماشية وتعتيم الباقي.
maxVisibleEntries	number	12	الصفوف المعروضة قبل تمرير القائمة داخل وسيلة الإيضاح.

أ LegendEntry هو { id, label?, color, badge?, predicate?, order? }. id هو الصف الهوية، والقيمة المكتوبة على عامل التصفية، والاحتياطي للتسمية.

عندما يتم تمييز العقد عن بعضها بواسطة شارة بدلاً من ملئها، قم بإعطاء الإدخال badge والصف يظهر العلامة بدلاً من النقطة. يتم رسمها على الطريقة يرسمه القماش، وتأخذ الشارة التي تحمل الرقم color الإدخال. التصفية لم تتغير.

{ id: 'enriched', label: 'From enrichment', color: '#8b5cf6',
  badge: { svgIcon: sparkle }, predicate: (node) => node.getData().enriched }

maxVisibleEntries هو سقف واحد على ارتفاع الأسطورة؛ القماش هو الآخر.

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

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

التفاعل

لفتة	تأثير
قم بتمرير صف واحد	قم بإضاءة تلك الفئة على القماش، وقم بتعتيم كل شيء آخر
انقر فوق صف	إخفاء/إظهار تلك الفئة
Alt-انقر فوق صف	إظهار هذه الفئة فقط
العنوان إظهار الكل	أعد إضاءة كل صف (يمسح مرشح وسيلة الإيضاح)
رأس عكس	قم بتبديل الفئات التي تظهر
رأس شيفرون	أضعاف هذا القسم إلى عنوانه
Alt-انقر على الشيفرون	قم بطي أو فتح كل قسم مرة واحدة

الصفوف عبارة عن أزرار حقيقية: يمكن الوصول إليها بواسطة علامة التبويب، والتبديل Enter / Space، وaria-pressed يحمل الدولة. يتم رسم صف مخفي باستخدام عينة مجوفة و نص خافت، لذلك اللون ليس الإشارة الوحيدة أبدًا.

شاهد بطاقة معرض أسطورة قابلة للتصفية للحصول على مثال حي، و LegendOptions / LegendGroupOptions ل أنواع كاملة.