D3.js 5 - selection

d3-selection




d

تسمح التحديدات بتحويل قوي يستند إلى البيانات لنموذج كائن المستند (DOM): تعيين attributes styles properties ومحتوى HTML أو text ، وأكثر من ذلك. باستخدام تحديدات enter enter ، يمكنك أيضًا add عناصر أو remove لتتوافق مع البيانات.

تقوم طرق التحديد عادةً بإرجاع التحديد الحالي ، أو تحديد جديد ، مما يسمح بالتطبيق المختصر لعمليات متعددة على تحديد معين عبر تسلسل الطريقة. على سبيل المثال ، لتعيين النمط واللون لكل عناصر الفقرة في الوثيقة الحالية:

d3.selectAll("p")
    .attr("class", "graf")
    .style("color", "red");

هذا يعادل:

var p = d3.selectAll("p");
p.attr("class", "graf");
p.style("color", "red");

حسب الاصطلاح ، تستخدم طرق التحديد التي ترجع التحديد الحالي أربعة مسافات للمسافة البادئة ، بينما تستخدم الأساليب التي ترجع تحديدًا جديدًا اثنين فقط. يساعد هذا في الكشف عن تغييرات السياق من خلال جعلها تخرج عن السلسلة:

d3.select("body")
  .append("svg")
    .attr("width", 960)
    .attr("height", 500)
  .append("g")
    .attr("transform", "translate(20,20)")
  .append("rect")
    .attr("width", 920)
    .attr("height", 460);

التحديدات غير قابلة للتغيير. جميع طرق التحديد التي تؤثر على العناصر المحددة (أو ترتيبها) تُرجع تحديدًا جديدًا بدلاً من تعديل التحديد الحالي. ومع ذلك ، لاحظ أن العناصر قابلة للتغيير بالضرورة ، حيث إن التحديدات تؤدي إلى تحويلات المستند!

تثبيت

إذا كنت تستخدم NPM ، npm install d3-selection . خلاف ذلك ، قم بتنزيل أحدث إصدار . يمكنك أيضًا التحميل مباشرةً من d3js.org ، إما كمكتبة مستقلة أو كجزء من D3 4.0 . يتم دعم بيئات AMD و CommonJS و vanilla. في الفانيليا ، يتم تصدير d3 العالمية:

<script src="https://d3js.org/d3-selection.v1.min.js"></script>
<script>

var div = d3.selectAll("div");

</script>

جرب اختيار d3 في متصفحك.

مرجع API

اختيار العناصر

تقبل طرق التحديد سلاسل محددات W3C مثل .fancy لتحديد عناصر مع الفئة الفاخرة ، أو div لتحديد عناصر DIV. تأتي طرق التحديد في نموذجين: select and selectAll: السابق يختار فقط عنصر المطابقة الأول ، بينما يختار الأخير جميع عناصر المطابقة في ترتيب الوثيقة. أساليب تحديد المستوى الأعلى ، d3.select و d3.selectAll ، الاستعلام المستند بأكمله؛ أساليب selection.selectAll ، selection.selectAll ، تقييد التحديد على أحفاد العناصر المحددة.

D3. اختيار () Source

d3.select العنصر الجذر ، document.documentElement . يمكن أيضًا استخدام هذه الوظيفة لاختبار التحديدات ( instanceof d3.selection ) أو لتوسيع النموذج الأولي للتحديد. على سبيل المثال ، لإضافة طريقة للتحقق من خانات الاختيار:

d3.selection.prototype.checked = function(value) {
  return arguments.length < 1
      ? this.property("checked")
      : this.property("checked", !!value);
};

ثم للاستخدام:

d3.selectAll("input[type=checkbox]").checked(true);
D3. حدد ( محدد ) Source

لتحديد العنصر الأول الذي يطابق سلسلة المحدد المحدد . إذا لم تتطابق أي عناصر مع المحدد ، فتُرجع تحديدًا فارغًا. إذا تطابقت عناصر متعددة مع المحدد ، فسيتم تحديد العنصر المطابق الأول فقط (بترتيب المستند). على سبيل المثال ، لتحديد أول عنصر ربط:

var anchor = d3.select("a");

إذا لم يكن المحدد سلسلة ، فاختيار العقدة المحددة ؛ هذا مفيد إذا كان لديك بالفعل إشارة إلى عقدة ، مثل this داخل مستمع الحدث أو عمومي مثل document.body . على سبيل المثال ، لعمل فقرة باللون الأحمر:

d3.selectAll("p").on("click", function() {
  d3.select(this).style("color", "red");
});
D3. selectAll ( محدد ) Source

يحدد كل العناصر التي تطابق سلسلة المحدد . سيتم تحديد العناصر بترتيب المستند (من الأعلى إلى الأسفل). إذا لم تتطابق أي عناصر في المستند مع المحدد ، أو إذا كان المحدد فارغًا أو غير محدد ، فستُرجع تحديدًا فارغًا. على سبيل المثال ، لتحديد كل الفقرات:

var paragraph = d3.selectAll("p");

إذا كان المحدد ليس سلسلة ، فبدلاً من ذلك يحدد مجموعة العقد المحددة ؛ هذا مفيد إذا كان لديك بالفعل إشارة إلى العقد ، مثل this.childNodes داخل مستمع الحدث أو عالمي مثل document.links . قد تكون العقد بدلاً من ذلك عبارة عن صفيف زائف مثل NodeList أو arguments . على سبيل المثال ، لتلوين جميع الروابط باللون الأحمر:

d3.selectAll(document.links).style("color", "red");
الاختيار . حدد ( محدد ) Source

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

var b = d3.selectAll("p").select("b");

إذا كان المحدد وظيفة ، فسيتم تقييمه لكل عنصر محدد ، بالترتيب ، بحيث يتم تمرير المسند الحالي ( د ) ، والفهرس الحالي ( i ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]). يجب أن ترجع عنصرًا ، أو لاغًا إذا لم يكن هناك عنصر مطابق. على سبيل المثال ، لتحديد الأخوة السابقة لكل فقرة:

var previous = d3.selectAll("p").select(function() {
  return this.previousElementSibling;
});

بخلاف selection.selectAll ، لا يؤثر التحديد .select على التجميع: فهو يحافظ على بنية المجموعة وفهارسها الحالية ، وينشر البيانات (إن وجدت) إلى الأطفال selection.selectAll . يلعب التجميع دورًا مهمًا في ربط البيانات . راجع التحديدات المتداخلة وكيف تعمل التحديدات لمعرفة المزيد حول هذا الموضوع.

الاختيار . selectAll ( محدد ) Source

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

var b = d3.selectAll("p").selectAll("b");

إذا كان المحدد وظيفة ، فسيتم تقييمه لكل عنصر محدد ، بالترتيب ، بحيث يتم تمرير المسند الحالي ( د ) ، والفهرس الحالي ( i ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]). يجب أن تقوم بإرجاع صفيف من العناصر (أو صفيف زائف ، مثل NodeList) ، أو الصفيف الفارغ إذا لم تكن هناك عناصر مطابقة. على سبيل المثال ، لتحديد الأشقاء السابقة والتالية لكل فقرة:

var sibling = d3.selectAll("p").selectAll(function() {
  return [
    this.previousElementSibling,
    this.nextElementSibling
  ];
});

بخلاف selection.select ، التحديد .selectAll يؤثر على التجميع: يتم تجميع كل سليل محدد بواسطة العنصر الأصل في التحديد الأصلي. يلعب التجميع دورًا مهمًا في ربط البيانات . راجع التحديدات المتداخلة وكيف تعمل التحديدات لمعرفة المزيد حول هذا الموضوع.

الاختيار . مرشح ( مرشح ) Source

لتصفية التحديد ، وإرجاع تحديد جديد يحتوي فقط على العناصر التي يكون عامل التصفية المحدد صحيحًا لها. قد يتم تحديد المرشح كسلسلة محدد أو وظيفة. إذا كان المرشح وظيفة ، فسيتم تقييمه لكل عنصر محدد ، بالترتيب ، بحيث يتم تمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]).

على سبيل المثال ، لتصفية مجموعة من صفوف الجدول لتحتوي فقط على صفوف متساوية:

var even = d3.selectAll("tr").filter(":nth-child(even)");

هذا يكافئ تقريباً استخدام d3.selectAll مباشرةً ، على الرغم من أن الفهارس قد تكون مختلفة:

var even = d3.selectAll("tr:nth-child(even)");

وبالمثل ، باستخدام وظيفة:

var even = d3.selectAll("tr").filter(function(d, i) { return i & 1; });

أو باستخدام selection.select

var even = d3.selectAll("tr").select(function(d, i) { return i & 1 ? this : null; });

لاحظ أن :nth-child الفئة الزائفة :nth-child هي فهرس قائم على أساس واحد بدلاً من فهرس يستند إلى صفر. أيضًا ، لا تتضمن وظائف المرشح أعلاه نفس المعنى بالضبط :nth-child ؛ يعتمدون على فهرس التحديد بدلاً من عدد عناصر الأخوة السابقة في DOM.

يحتفظ التحديد الذي تمت تصفيته والذي تم إرجاعه array.filter هذا التحديد ، ولكن مثل array.filter ، لا يحتفظ بالفهارس لأنه قد تتم إزالة بعض العناصر ؛ استخدم selection.select حدد للحفاظ على الفهرس ، إذا لزم الأمر.

الاختيار . دمج ( أخرى ) Source

إرجاع تحديد جديد يدمج هذا التحديد مع التحديد الآخر المحدد. يحتوي الاختيار الذي تم إرجاعه على نفس عدد المجموعات ونفس أولياء الأمور في هذا الاختيار. يتم تعبئة أي عناصر مفقودة (خالية) في هذا التحديد بالعنصر المقابل ، إذا كان موجودًا (غير فارغ) ، من التحديد المحدد. (إذا كان الاختيار الآخر يحتوي على مجموعات إضافية أو أولياء أمور ، فسيتم تجاهلهم.)

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

var circle = svg.selectAll("circle").data(data) // UPDATE
    .style("fill", "blue");

circle.exit().remove(); // EXIT

circle = circle.enter().append("circle") // ENTER
    .style("fill", "green")
  .merge(circle) // ENTER + UPDATE
    .style("stroke", "black");

راجع selection.data للحصول على شرح أكثر اكتمالا لهذا الرمز ، والذي يعرف بنمط التحديث العام.

لا تهدف هذه الطريقة إلى تسلسل التحديدات التعسفية ، ومع ذلك: إذا كان كل من هذا الاختيار والاختيار الآخر المحدد يحتويان على عناصر (غير خالية) في الفهرس نفسه ، فسيتم إرجاع عنصر هذا التحديد في الدمج ويتم تجاهل عنصر التحديد الآخر .

D3. مطابقة ( محدد ) Source

بالنظر إلى المحدد المحدد ، تُرجع دالة تُرجع صواب إذا كان this العنصر matches المحدد المحدد. يتم استخدام هذه الطريقة داخليًا عن طريق selection.filter . على سبيل المثال ، هذا:

var div = selection.filter("div");

تعادل:

var div = selection.filter(d3.matcher("div"));

(على الرغم من أن D3 ليس طبقة توافق ، فإن هذا التطبيق يدعم التطبيقات التي يسبقها البائع بسبب التوحيد الأخير للعنصر .matches.)

D3. محدد ( محدد ) Source

بالنظر إلى المحدد المحدد ، تقوم بإرجاع دالة تقوم بإرجاع أول نسل this العنصر يطابق المحدد المحدد. يتم استخدام هذه الطريقة داخليًا عن طريق selection.select . على سبيل المثال ، هذا:

var div = selection.select("div");

تعادل:

var div = selection.select(d3.selector("div"));
D3. selectorAll ( محدد ) Source

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

var div = selection.selectAll("div");

تعادل:

var div = selection.selectAll(d3.selectorAll("div"));
D3. نافذة ( عقدة ) Source

إرجاع نافذة المالك للعقدة المحددة. إذا كانت العقدة عقدة ، فتُرجع طريقة العرض الافتراضية لمستند المالك ؛ إذا كانت العقدة وثيقة ، فتُرجع طريقة العرض الافتراضية ؛ إرجاع وإلا العقدة .

D3. النمط ( العقدة ، الاسم ) Source

إرجاع قيمة خاصية النمط بالاسم المحدد للعقدة المحددة. إذا كانت العقدة تحتوي على نمط مضمّن يحمل الاسم المحدد ، فسيتم إرجاع قيمتها ؛ وإلا ، يتم إرجاع قيمة الخاصية المحسوبة . انظر أيضا styles .

تعديل العناصر

بعد تحديد العناصر ، استخدم طرق تحويل التحديد للتأثير على محتوى المستند. على سبيل المثال ، لتعيين سمة الاسم ونمط اللون لعنصر الربط:

d3.select("a")
    .attr("name", "fred")
    .style("color", "red");

لتجربة التحديدات ، تفضل بزيارة d3js.org وافتح وحدة تحكم مطور برامج المتصفح لديك! (في Chrome ، افتح وحدة التحكم بـ ⌥⌘J.) حدد عناصر ، ثم افحص التحديد الذي تم إرجاعه لمعرفة العناصر المحددة وكيفية تجميعها. طرق اختيار الاتصال وشاهد كيف يتغير محتوى الصفحة.

الاختيار . attr ( الاسمالقيمة ]) Source

إذا تم تحديد قيمة ، قم بتعيين السمة بالاسم المحدد على القيمة المحددة في العناصر المحددة وإرجاع هذا التحديد. إذا كانت القيمة ثابتة ، يتم إعطاء جميع العناصر نفس قيمة السمة ؛ وإلا ، إذا كانت القيمة دالة ، فسيتم تقييمها لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار ذلك DOM الحالي عنصر ( العقد [ i ]). ثم يتم استخدام قيمة الإرجاع للدالة لتعيين سمة كل عنصر. ستؤدي القيمة الخالية إلى إزالة السمة المحددة.

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

قد يحتوي الاسم المحدد على بادئة مساحة اسم ، مثل xlink:href لتحديد سمة href في مساحة اسم XLink. انظر Namespaces لخريطة مساحات الأسماء المدعومة ؛ يمكن تسجيل مساحات أسماء إضافية عن طريق إضافة إلى الخريطة.

الاختيار . مصنفة ( أسماءالقيمة ]) Source

إذا تم تحديد قيمة ، تقوم بتعيين أو إلغاء تخصيص أسماء فئات CSS المحددة على العناصر المحددة عن طريق تعيين سمة class أو تعديل خاصية classList وإرجاع هذا التحديد. الأسماء المحددة هي سلسلة من أسماء الفئات مفصولة بمسافة. على سبيل المثال ، لتعيين الفئات foo bar للعناصر المحددة:

selection.classed("foo bar", true);

إذا كانت القيمة صادقة ، فسيتم تعيين جميع الفئات للفئات المحددة ؛ خلاف ذلك ، والفصول غير المعينة. إذا كانت القيمة دالة ، فسيتم تقييمها لكل عنصر محدد ، بالترتيب ، بحيث يتم تمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]). ثم يتم استخدام قيمة الإرجاع للدالة لتعيين أو إلغاء تخصيص الفئات في كل عنصر. على سبيل المثال ، لربط الصف بشكل عشوائي مع نصف العناصر المحددة في المتوسط:

selection.classed("foo", function() { return Math.random() > 0.5; });

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

الاختيار . النمط ( الاسمالقيمةالأولوية ]]) Source

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

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

تحذير: على عكس العديد من سمات SVG ، عادةً ما تحتوي أنماط CSS على وحدات مرتبطة. على سبيل المثال ، تعد 3px قيمة خاصية عرض حد صالحة ، بينما 3 ليس كذلك. تقوم بعض المستعرضات ضمنيًا بتعيين وحدة px (بكسل) لقيم رقمية ، ولكن لا تفعل جميع المستعرضات: IE ، على سبيل المثال ، يطرح خطأ "وسيطات غير صالحة"!

الاختيار . خاصية ( الاسمالقيمة ]) Source

تحتوي بعض عناصر HTML على خصائص خاصة لا يمكن معالجتها باستخدام السمات أو الأنماط ، مثل value النصية لحقل النموذج value المنطقية checked لمربع الاختيار. استخدم هذه الطريقة للحصول على أو تعيين هذه الخصائص.

إذا تم تحديد قيمة ، فقم بتعيين الخاصية بالاسم المحدد على القيمة المحددة في العناصر المحددة. إذا كانت القيمة ثابتة ، فسيتم إعطاء كل العناصر نفس قيمة الخاصية ؛ وإلا ، إذا كانت القيمة دالة ، فسيتم تقييمها لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار ذلك DOM الحالي عنصر ( العقد [ i ]). ثم يتم استخدام قيمة الإرجاع للدالة لتعيين خاصية كل عنصر. ستحذف قيمة فارغة الخاصية المحددة.

إذا لم يتم تحديد قيمة ، فتُرجع قيمة الخاصية المحددة للعنصر الأول (غير الفارغ) في التحديد. هذا مفيد بشكل عام فقط إذا كنت تعرف أن التحديد يحتوي على عنصر واحد بالضبط.

الاختيار . النص ([ القيمة ]) Source

إذا تم تحديد قيمة ، فقم بتعيين محتوى النص على القيمة المحددة على جميع العناصر المحددة ، مع استبدال أي عناصر فرعية موجودة. إذا كانت القيمة ثابتة ، فسيتم إعطاء كل العناصر نفس محتوى النص ؛ وإلا ، إذا كانت القيمة دالة ، فسيتم تقييمها لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار ذلك DOM الحالي عنصر ( العقد [ i ]). ثم يتم استخدام قيمة الإرجاع للدالة لتعيين محتوى النص لكل عنصر. سوف قيمة فارغة مسح المحتوى.

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

الاختيار . أتش تي أم أل ([ قيمة ]) Source

إذا تم تحديد قيمة ، قم بتعيين HTML الداخلي على القيمة المحددة على جميع العناصر المحددة ، مع استبدال أي عناصر تابعة موجودة. إذا كانت القيمة ثابتة ، فسيتم إعطاء جميع العناصر نفس HTML الداخلي ؛ وإلا ، إذا كانت القيمة دالة ، فسيتم تقييمها لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار ذلك DOM الحالي عنصر ( العقد [ i ]). ثم يتم استخدام قيمة الإرجاع للدالة لتعيين HTML الداخلي لكل عنصر. سوف قيمة فارغة مسح المحتوى.

إذا لم يتم تحديد قيمة ، فتُرجع HTML الداخلي للعنصر (غير الفارغ) الأول في التحديد. هذا مفيد بشكل عام فقط إذا كنت تعرف أن التحديد يحتوي على عنصر واحد بالضبط.

استخدم add أو selection.insert بدلاً من ذلك لإنشاء محتوى selection.insert إلى البيانات ؛ هذه الطريقة مخصصة عندما تريد القليل من HTML ، لنقل التنسيق الغني. أيضًا ، التحديد .html معتمد فقط على عناصر HTML. لا تدعم عناصر SVG والعناصر الأخرى بخلاف HTML خاصية HTML الداخلية ، وبالتالي لا تتوافق مع التحديد .html. XMLSerializer استخدام XMLSerializer لتحويل الشجرة الفرعية DOM إلى نص. انظر أيضًا ملف polyners الخاص بـ innersvg ، والذي يوفر ميزة دعم خاصية HTML الداخلية في عناصر SVG.

الاختيار . إلحاق ( نوع ) Source

إذا كان النوع المحدد عبارة عن سلسلة ، فإن إلحاق عنصر جديد من هذا النوع (اسم العلامة) هو آخر عنصر في كل عنصر محدد ، أو قبل الأخ التالي التالي في تحديد التحديث إذا كان هذا enter . يسمح لك السلوك الأخير لتحديدات الإدخال بإدراج عناصر في DOM بترتيب متوافق مع البيانات المنضمة الجديدة ؛ ومع ذلك ، لاحظ أن selection.order قد يظل مطلوبًا في حالة تغيير عناصر التحديث ترتيبًا ( أي إذا كان ترتيب البيانات الجديدة غير متوافق مع البيانات القديمة).

إذا كان النوع المحدد دالة ، فسيتم تقييمه لكل عنصر محدد ، بالترتيب ، بحيث يتم تمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]). يجب أن ترجع هذه الوظيفة عنصرًا سيتم إلحاقه. (عادةً ما تقوم الدالة بإنشاء عنصر جديد ، ولكنها قد تُرجع بدلاً من ذلك عنصرًا موجودًا.) على سبيل المثال ، لإلحاق عنصر DIV بكل فقرة:

d3.selectAll("p").append("div");

هذا يعادل:

d3.selectAll("p").append(function() {
  return document.createElement("div");
});

وهو ما يعادل:

d3.selectAll("p").select(function() {
  return this.appendChild(document.createElement("div"));
});

في كلتا الحالتين ، تقوم هذه الطريقة بإرجاع تحديد جديد يحتوي على العناصر الملحقة. يرث كل عنصر جديد بيانات العناصر الحالية ، إن وجدت ، بنفس طريقة selection.select .

قد يحتوي الاسم المحدد على بادئة مساحة اسم ، مثل svg:text لتحديد سمة text في مساحة اسم SVG. انظر Namespaces لخريطة مساحات الأسماء المدعومة ؛ يمكن تسجيل مساحات أسماء إضافية عن طريق إضافة إلى الخريطة. إذا لم يتم تحديد مساحة اسم ، فسيتم توريث مساحة الاسم من العنصر الأصل ؛ أو ، إذا كان الاسم أحد البادئات المعروفة ، فسيتم استخدام مساحة الاسم المقابلة (على سبيل المثال ، يعني svg:svg ).

الاختيار . تضاف ( النوعقبل ]) Source

إذا كان النوع المحدد عبارة عن سلسلة ، أدخل عنصرًا جديدًا من هذا النوع (اسم العلامة) قبل أن يتطابق العنصر الأول مع المحدد قبل المحدد لكل عنصر محدد. على سبيل المثال ، محدد قبل :first-child سوف يسبق العقد قبل الطفل الأول. إذا لم يتم تحديد من قبل ، فسيتم إلغاء القيم الافتراضية. (لإلحاق عناصر بترتيب متوافق مع البيانات المنضمة ، استخدم add . add .)

بدلاً من ذلك ، يمكن تحديد كلٍّ من النوعين وما قبله كدالات يتم تقييمها لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا كتيار عنصر DOM ( العقد [ i ]). يجب أن تقوم دالة الكتابة بإرجاع عنصر لإدراجه ؛ يجب أن ترجع الدالة السابقة العنصر الفرعي الذي يجب إدراج العنصر من قبله. على سبيل المثال ، لإلحاق عنصر DIV بكل فقرة:

d3.selectAll("p").insert("div");

هذا يعادل:

d3.selectAll("p").insert(function() {
  return document.createElement("div");
});

وهو ما يعادل:

d3.selectAll("p").select(function() {
  return this.insertBefore(document.createElement("div"), null);
});

في كلتا الحالتين ، تقوم هذه الطريقة بإرجاع تحديد جديد يحتوي على العناصر الملحقة. يرث كل عنصر جديد بيانات العناصر الحالية ، إن وجدت ، بنفس طريقة selection.select .

قد يحتوي الاسم المحدد على بادئة مساحة اسم ، مثل svg:text لتحديد سمة text في مساحة اسم SVG. انظر Namespaces لخريطة مساحات الأسماء المدعومة ؛ يمكن تسجيل مساحات أسماء إضافية عن طريق إضافة إلى الخريطة. إذا لم يتم تحديد مساحة اسم ، فسيتم توريث مساحة الاسم من العنصر الأصل ؛ أو ، إذا كان الاسم أحد البادئات المعروفة ، فسيتم استخدام مساحة الاسم المقابلة (على سبيل المثال ، يعني svg:svg ).

الاختيار . إزالة () Source

يزيل العناصر المحددة من الوثيقة. إرجاع هذا الاختيار (العناصر التي تمت إزالتها) والتي يتم فصلها الآن عن DOM. لا يوجد حاليًا واجهة برمجة تطبيقات مخصصة لإضافة العناصر التي تمت إزالتها مرة أخرى إلى المستند ؛ ومع ذلك ، يمكنك تمرير دالة إلى add أو selection.insert لإعادة إضافة عناصر.

الاختيار . استنساخ ([ عميق ]) Source

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

selection.select(function() {
  return this.parentNode.insertBefore(this.cloneNode(deep), this.nextSibling);
});
الاختيار . فرز ( مقارنة ) Source

إرجاع تحديد جديد يحتوي على نسخة من كل مجموعة في هذا الاختيار مصنفة وفقًا لوظيفة المقارنة . بعد الفرز ، أعد إدراج العناصر لمطابقة الترتيب الناتج (لكل selection.order ).

يتم تمرير دالة المقارنة ، التي تخلف عن ascending ، في بيانات عنصرين ( أ) و ( ب) للمقارنة. يجب أن تُرجع إما قيمة سالبة أو موجبة أو صفرية. إذا كانت سالبة ، فيجب أن تكون قبل ب ؛ إذا كانت موجبة ، فيجب أن تكون بعد b ؛ خلاف ذلك ، أ و ب تعتبر متساوية والنظام تعسفي.

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

الاختيار . ترتيب () Source

أعد إدراج العناصر في المستند بحيث يطابق ترتيب المستند لكل مجموعة ترتيب التحديد. هذا يعادل selection.sort إذا تم فرز البيانات بالفعل ، ولكن أسرع بكثير.

الاختيار . رفع () Source

أعد إدراج كل عنصر محدد ، بالترتيب ، باعتباره آخر طفل تابع لوالده. أي ما يعادل:

selection.each(function() {
  this.parentNode.appendChild(this);
});
الاختيار . أقل () Source

أعد إدراج كل عنصر محدد ، بالترتيب ، كطفل أول لوالده. أي ما يعادل:

selection.each(function() {
  this.parentNode.insertBefore(this, this.parentNode.firstChild);
});
D3. إنشاء ( اسم ) Source

بالنظر إلى اسم العنصر المحدد ، تقوم بإرجاع تحديد عنصر واحد يحتوي على عنصر منفصل من الاسم المحدد في المستند الحالي.

D3. الخالق ( الاسم ) Source

بالنظر إلى اسم العنصر المحدد ، تُرجع الدالة التي تنشئ عنصرًا من الاسم المحدد ، على افتراض أن this هو العنصر الأصل. يتم استخدام هذه الطريقة داخليًا عن طريق add و selection.insert لإنشاء عناصر جديدة. على سبيل المثال ، هذا:

selection.append("div");

تعادل:

selection.append(d3.creator("div"));

راجع namespace للحصول على تفاصيل حول بادئات مساحة الاسم المدعومة ، مثل عناصر SVG.

ربط البيانات

للحصول على مقدمة عن عمليات ربط بيانات D3 ، راجع التفكير باستخدام الصلات. انظر أيضًا أمثلة نمط التحديث العام .

الاختيار . البيانات ([ البياناتالمفتاح ]]) Source

يربط مجموعة البيانات المحددة بالعناصر المحددة ، مع إرجاع تحديد جديد يمثل اختيار التحديث : العناصر المرتبطة بنجاح بالبيانات. يعرّف أيضًا تحديدات enter exit على التحديد الذي تم إرجاعه ، والذي يمكن استخدامه لإضافة أو إزالة عناصر لتتوافق مع البيانات الجديدة. البيانات المحددة هي مجموعة من القيم التعسفية (على سبيل المثال ، الأرقام أو الكائنات) ، أو دالة تُرجع مجموعة من القيم لكل مجموعة. عند تخصيص البيانات لأحد العناصر ، يتم تخزينها في الخاصية __data__ ، مما يجعل البيانات " __data__ " ومتاحة عند إعادة التحديد.

يتم تحديد البيانات لكل مجموعة في الاختيار. إذا كان الاختيار يحتوي على مجموعات متعددة (مثل d3.selectAll متبوعة selection.selectAll ) ، فيجب تحديد البيانات كدالة. سيتم تقييم هذه الوظيفة لكل مجموعة بالترتيب ، حيث يتم تمرير البيانات الأصلية للمجموعة ( d ، والتي قد تكون غير محددة) ، وفهرس المجموعة ( i ) ، والعقد الأصلية ( العقد ) الخاصة بالتحديد ، مع اعتبار ذلك العنصر الرئيسي للمجموعة. على سبيل المثال ، لإنشاء جدول HTML من مصفوفة من الأرقام:

var matrix = [
  [11975,  5871, 8916, 2868],
  [ 1951, 10048, 2060, 6171],
  [ 8010, 16145, 8090, 8045],
  [ 1013,   990,  940, 6907]
];

var tr = d3.select("body")
  .append("table")
  .selectAll("tr")
  .data(matrix)
  .enter().append("tr");

var td = tr.selectAll("td")
  .data(function(d) { return d; })
  .enter().append("td")
    .text(function(d) { return d; });

في هذا المثال ، تكون وظيفة البيانات هي وظيفة الهوية: لكل صف جدول ، تقوم بإرجاع الصف المقابل من مصفوفة البيانات.

إذا لم يتم تحديد وظيفة مفتاح ، فسيتم تعيين مسند البيانات الأول للعنصر المحدد الأول ، والمسند الثاني للعنصر المحدد الثاني ، وما إلى ذلك. قد يتم تحديد وظيفة رئيسية للتحكم في أي مسند يتم تعيينه لأي عنصر ، مع استبدال مؤشر الربط الافتراضي ، عن طريق حساب معرف سلسلة لكل مسند وعنصر. يتم تقييم هذه الوظيفة الرئيسية لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( d ) ، والفهرس الحالي ( i ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]) . السلسلة التي تم إرجاعها هي مفتاح العنصر. ثم يتم تقييم الوظيفة الرئيسية أيضًا لكل مسودة جديدة في البيانات ، ويتم تمريرها إلى المسند الحالي ( د ) ، والفهرس الحالي ( 1 ) ، وبيانات المجموعة الجديدة ، مع اعتبار ذلك عنصر DOM الأصلي للمجموعة ؛ السلسلة التي تم إرجاعها هي مفتاح المسند. يتم تعيين مسند مفتاح معين للعنصر باستخدام مفتاح المطابقة. إذا كان للعديد من العناصر نفس المفتاح ، فإن العناصر المكررة توضع في اختيار الخروج ؛ إذا كانت البيانات المتعددة لها نفس المفتاح ، يتم وضع البيانات المكررة في تحديد الإدخال.

على سبيل المثال ، بالنظر إلى هذا المستند:

<div id="Ford"></div>
<div id="Jarrah"></div>
<div id="Kwon"></div>
<div id="Locke"></div>
<div id="Reyes"></div>
<div id="Shephard"></div>

يمكنك ربط البيانات بالمفتاح على النحو التالي:

var data = [
  {name: "Locke", number: 4},
  {name: "Reyes", number: 8},
  {name: "Ford", number: 15},
  {name: "Jarrah", number: 16},
  {name: "Shephard", number: 31},
  {name: "Kwon", number: 34}
];

d3.selectAll("div")
  .data(data, function(d) { return d ? d.name : this.id; })
    .text(function(d) { return d.number; });

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

يتم إرجاع التحديدات وإدخال التحديدات في ترتيب البيانات ، بينما يحتفظ تحديد الخروج بترتيب التحديد قبل الانضمام. إذا تم تحديد وظيفة مفتاح ، فقد لا يتطابق ترتيب العناصر في التحديد مع ترتيبها في المستند ؛ استخدام selection.order أو selection.sort حسب الحاجة. لمعرفة المزيد حول كيفية تأثير الوظيفة الأساسية على الصلة ، راجع مخطط شريطي ، الجزء 2 ، وثبات الكائن .

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

var circle = svg.selectAll("circle") // 1
  .data(data) // 2
    .style("fill", "blue"); // 3

circle.exit().remove(); // 4

circle = circle.enter().append("circle") // 5, 9
    .style("fill", "green") // 6
  .merge(circle) // 7
    .style("stroke", "black"); // 8

تقسيم هذا إلى خطوات منفصلة:

  1. يتم تحديد أي دوائر موجودة (والتي هي أحفاد اختيار svg ).
  2. يتم ربط هذه الدوائر selection.data ، مع إعادة الدوائر المطابقة: تحديد التحديث .
  3. يتم إعطاء دوائر التحديث هذه تعبئة زرقاء.
  4. تتم إزالة أي دوائر حالية لا تتطابق مع البيانات الجديدة - تحديد الخروج -.
  5. يتم add دوائر جديدة بأي بيانات جديدة لا تتطابق مع أي دائرة حالية: تحديد الإدخال .
  6. يتم إعطاء هذه الدوائر دخول ملء الأخضر.
  7. يتم إنشاء اختيار جديد يمثل union دخول وتحديث الدوائر.
  8. يتم إعطاء دوائر الدخول والتحديث هذه ضربة سوداء.
  9. يتم تخزين هذه الدوائر في circle المتغيرة.

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

إذا لم يتم تحديد البيانات ، فتُرجع هذه الطريقة صفيف البيانات للعناصر المحددة.

لا يمكن استخدام هذه الطريقة لمسح البيانات المرتبطة ؛ استخدم selection.datum .

الاختيار . أدخل () Source

إرجاع تحديد الإدخال: عقد العناصر النائبة لكل مسند لا يحتوي على عنصر DOM مطابق في التحديد. (يكون اختيار الإدخال فارغًا selection.data التي لم يتم إرجاعها عن طريق selection.data . البيانات).

يستخدم اختيار الإدخال عادة لإنشاء عناصر "مفقودة" تتوافق مع البيانات الجديدة. على سبيل المثال ، لإنشاء عناصر DIV من مجموعة من الأرقام:

var div = d3.select("body")
  .selectAll("div")
  .data([4, 8, 15, 16, 23, 42])
  .enter().append("div")
    .text(function(d) { return d; });

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

<div>4</div>
<div>8</div>
<div>15</div>
<div>16</div>
<div>23</div>
<div>42</div>

من الناحية النظرية ، فإن العناصر النائبة في اختيار الإدخال هي مؤشرات إلى العنصر الأصل (في هذا المثال ، نص الوثيقة). عادةً ما يتم استخدام اختيار الإدخال بشكل مؤقت فقط لإلحاق العناصر ، وغالبًا ما يتم union مع تحديد التحديث بعد الإلحاق ، بحيث يمكن تطبيق التعديلات على كل من عناصر الإدخال والتحديث.

الاختيار . خروج () Source

إرجاع تحديد الخروج: عناصر DOM الموجودة في التحديد التي لم يتم العثور على مسودة جديدة بها. (يكون تحديد الخروج فارغًا selection.data التي لم يتم إرجاعها عن طريق selection.data . البيانات).

عادةً ما يستخدم اختيار الخروج لإزالة العناصر "الزائدة عن الحاجة" المقابلة للبيانات القديمة. على سبيل المثال ، لتحديث عناصر DIV التي تم إنشاؤها مسبقًا باستخدام مجموعة جديدة من الأرقام:

div = div.data([1, 2, 4, 8, 16, 32], function(d) { return d; });

نظرًا لأنه تم تحديد وظيفة مفتاح (كدالة هوية) ، وأن البيانات الجديدة تحتوي على الأرقام [4 ، 8 ، 16] التي تطابق العناصر الموجودة في المستند ، فإن تحديد التحديث يحتوي على ثلاثة عناصر DIV. مع ترك هذه العناصر كما هي ، يمكننا إلحاق عناصر جديدة بـ [1 ، 2 ، 32] باستخدام اختيار الإدخال:

div.enter().append("div").text(function(d) { return d; });

وبالمثل ، لإزالة العناصر الخارجة [15 ، 23 ، 42]:

div.exit().remove();

الآن يبدو نص المستند كما يلي:

<div>1</div>
<div>2</div>
<div>4</div>
<div>8</div>
<div>16</div>
<div>32</div>

يطابق ترتيب عناصر DOM ترتيب البيانات لأن ترتيب البيانات القديم وترتيب البيانات الجديدة كانا متسقين. إذا كان ترتيب البيانات الجديد مختلفًا ، فاستخدم selection.order لإعادة ترتيب العناصر في DOM. راجع مؤشر ترابط نموذج التحديث العام لمزيد من المعلومات حول عمليات ربط البيانات.

الاختيار . مسند ([ قيمة ]) Source

الحصول على أو ربط البيانات المرتبطة لكل عنصر محدد. بخلاف selection.data ، هذه الطريقة لا تحسب صلة ولا تؤثر على الفهارس أو تحديدات الدخول والخروج.

إذا تم تحديد قيمة ، فقم بتعيين البيانات المرتبطة بالعنصر على القيمة المحددة في جميع العناصر المحددة. إذا كانت القيمة ثابتة ، يتم إعطاء نفس العناصر لكل مسند ؛ خلاف ذلك، إذا كانت القيمة هي وظيفة، فإنه يتم تقييم لكل عنصر من عناصر محددة، في النظام، يتم تمريرها مسند الحالي ( د )، والمؤشر الحالي ( ط )، والمجموعة الحالية ( العقد )، مع هذا كما DOM الحالي عنصر ( العقد [ i ]). ثم يتم استخدام الوظيفة لضبط البيانات الجديدة لكل عنصر. سيتم حذف قيمة فارغة البيانات المنضمة.

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

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

<ul id="list">
  <li data-username="shawnbot">Shawn Allen</li>
  <li data-username="mbostock">Mike Bostock</li>
</ul>

يمكنك كشف سمات البيانات المخصصة عن طريق تعيين بيانات كل عنصر كخاصية dataset المدمجة :

selection.datum(function() { return this.dataset; })

التعامل مع الأحداث

للتفاعل ، تتيح التحديدات الاستماع إلى الأحداث وإرسالها.

الاختيار . على ( أسماء الأسماءمستمعخيارات ]]) Source

إضافة أو إزالة مستمع إلى كل عنصر محدد لأسماء الأحداث المحددة . و typenames هو نوع الحدث سلسلة، مثل click، mouseoverأو submit؛ يمكن استخدام أي نوع من أحداث DOM التي يدعمها متصفحك. يمكن أن يتبع النوع اختياريا فترة ( . ) واسم ؛يسمح الاسم الاختياري بتسجيل عمليات الاسترجاعات المتعددة لتلقي الأحداث من نفس النوع ، مثل click.fooو click.bar. لتحديد أسماء متعددة ، قم بفصل أسماء الأسماء بمسافات ، مثل input changeأو click.foo click.bar.

عندما يتم إرسال حدث محدد على عنصر محدد ، سيتم تقييم المستمع المحدد للعنصر ، ويتم تمريره الحالي ( د ) ، والفهرس الحالي ( ط ) ، والمجموعة الحالية ( العقد ) ، مع هذا كتيار عنصر DOM ( العقد [ i ]). يرى المستمعون دائمًا أحدث مسرد لعنصرهم ، لكن الفهرس هو خاصية التحديد ويتم إصلاحه عند تعيين المستمع ؛ لتحديث الفهرس ، قم بإعادة تعيين المستمع. للوصول إلى الحدث الحالي داخل المستمع ، استخدم d3.event .

إذا تم تسجيل مستمع حدث سابقًا لنفس الاسم المطبوع على عنصر محدد ، تتم إزالة المستمع القديم قبل إضافة المستمع الجديد. لإزالة مستمع ، مرّر لاغياً كمستمع . لإزالة كافة المستمعين لاسم معين، تمرير باطل كما المستمع و .fooكما typename ، حيث fooهو الاسم؛ لإزالة كافة المستمعين مع عدم وجود اسم تحديد .باسم typename .

يمكن لكائن الخيارات الاختياري تحديد خصائص حول مستمع الأحداث ، مثل ما إذا كان يتم التقاطه أو عدمه ؛ انظر element.addEventListener .

إذا كان المستمع لم يتم تحديد، يعود المستمع المعينة حاليا من أجل الحدث المحدد typename في أول (غير الصفرية) العنصر المحدد، إن وجدت. إذا تم تحديد أسماء متعددة ، فسيتم إرجاع المستمع المطابق الأول.

الاختيار . إرسال ( نوعالمعلمات ]) Source

يرسل حدثًا مخصصًا من النوع المحدد إلى كل عنصر محدد ، بالترتيب. يمكن تحديد خريطة معلمات اختيارية لتعيين خصائص إضافية للحدث. قد يحتوي على الحقول التالية:

  • bubbles - إذا كان هذا صحيحًا ، يتم إرسال الحدث إلى الأسلاف بترتيب عكسي.
  • cancelable- إذا كان هذا صحيحًا ، فيُسمح للحدث .preventDefault.
  • detail - أي بيانات مخصصة مرتبطة بالحدث.

إذا المعلمات هي وظيفة، فإنه يتم تقييم لكل عنصر من عناصر محددة، في النظام، يتم تمريرها مسند الحالي ( د )، والمؤشر الحالي ( ط )، والمجموعة الحالية ( العقد )، مع هذا كعنصر DOM الحالي ( العقد [ i ]). يجب أن ترجع خريطة المعلمات للعنصر الحالي.

D3. هدف

event الحالي ، إن وجد. يتم تعيين هذا أثناء استدعاء مستمع الحدث ، وتتم إعادة تعيينه بعد انتهاء المستمع. استخدم هذا للوصول إلى حقول الأحداث القياسية مثل event.timeStampevent.timeStamp والأساليب مثل event.preventDefault . في حين يمكنك استخدام مواليد event.pageX و event.pageY ، غالبا ما يكون أكثر ملاءمة لتحويل موقف الحدث لنظام الإحداثيات المحلية من الحاوية التي حصلت على الحدث باستخدام d3.mouse ، d3.touch أو d3.touches .

إذا كنت تستخدم Babel أو Webpack أو أي حزمة أخرى من ES6 إلى ES5 ، فاحذر من أن قيمة d3.event تتغير خلال حدث ما! يجب أن يكون استيراد d3.event و ملزمة على الهواء مباشرة ، لذلك قد تحتاج لتكوين محزم لاستيراد من وحدات ES6 D3 وليس من حزمة UMD ولدت. ليس كل من jsnext:main يلاحظون jsnext:main . حذار أيضا من الصراعات مع window.event العالمية.

D3. customEvent ( حدث ، مستمعذلكوسيطات ]]) Source

استدعاء المحدد المستمع ، وذلك باستخدام المحدد أن this السياق وتمرير المحدد الحجج ، إن وجدت. أثناء الاستدعاء ، يتم تعيين d3.event على الحدث المحدد ؛ بعد إرجاع المستمع (أو إلقاء خطأ) ، تتم استعادة d3.event إلى قيمتها السابقة. بالإضافة إلى ذلك ، يعين الحدث .sourceEvent إلى القيمة السابقة لـ d3.event ، مما يسمح للأحداث المخصصة بالاحتفاظ بمرجع إلى الحدث الأصلي الأصلي. إرجاع القيمة التي تم إرجاعها بواسطة المستمع .

D3. الماوس ( الحاوية ) Source

إرجاع إحداثي x و y d3.event بالنسبة للحاوية المحددة . قد تكون الحاوية عبارة عن عنصر حاوية HTML أو SVG ، مثل عنصر G أو عنصر SVG . يتم إرجاع الإحداثيات كصفيف مكون من عنصرين من الأرقام [ س ، ص ].

D3. المس ( الحاويةاللمسات ] ، المعرف ) Source

إرجاع إحداثيات x و y مع المعرف المحدد المرتبط d3.event المتعلق بالحاوية المحددة . قد تكون الحاوية عبارة عن عنصر حاوية HTML أو SVG ، مثل عنصر G أو عنصر SVG . يتم إرجاع الإحداثيات كصفيف مكون من عنصرين من الأرقام [ س ، ص ]. إذا لم يكن هناك اتصال مع المعرف المحدد في اللمسات ، فستُرجع لاغية ؛ يمكن أن يكون هذا مفيدًا لتجاهل أحداث touchmove حيث تحركت بعض اللمسات فقط. إذا لم يتم تحديد اللمسات ، فسيتم تعيين الإعدادات الافتراضية للحدث الحاليchangedTouches الممتلكات.

D3. اللمسات ( الحاويةاللمسات ]) Source

إرجاع إحداثي x و y اللمسات المقترنة d3.event نسبة إلى الحاوية المحددة . قد تكون الحاوية عبارة عن عنصر حاوية HTML أو SVG ، مثل عنصر G أو عنصر SVG . يتم إرجاع الإحداثيات كصفيف من صفائف مكونة من عنصرين من الأرقام [[ x1 ، y1 ] ، [ x2 ، y2 ] ، ...]. إذا لم يتم تحديد اللمسات ، فسيتم تعيينها تلقائيًا إلى خاصية touches للحدث الحالي .

D3. clientPoint ( الحاوية ، الحدث ) Source

إرجاع إحداثي x و y للحدث المحدد بالنسبة للحاوية المحددة . ( قد يكون الحدث أيضًا touch .) قد تكون الحاوية عنصر حاوية HTML أو SVG ، مثل عنصر G أو عنصر SVG . يتم إرجاع الإحداثيات كصفيف مكون من عنصرين من الأرقام [ س ، ص ].

التحكم في التدفق

للاستخدام المتقدم ، توفر الاختيارات طرقًا لتدفق التحكم المخصص.

الاختيار . كل ( وظيفة ) Source

تستدعي الوظيفة المحددة لكل عنصر محدد ، بالترتيب ، لتمرير المسند الحالي ( د ) ، والفهرس الحالي ( i ) ، والمجموعة الحالية ( العقد ) ، مع اعتبار هذا العنصر DOM الحالي ( العقد [ i ]). يمكن استخدام هذه الطريقة لاستدعاء تعليمات برمجية عشوائية لكل عنصر محدد ، وهي مفيدة لإنشاء سياق للوصول إلى بيانات الأصل والطفل في وقت واحد ، مثل:

parent.each(function(p, j) {
  d3.select(this)
    .selectAll(".child")
      .text(function(d, i) { return "child " + d.name + " of " + p.name; });
});

انظر مضاعفات الحجم دونات للحصول على مثال.

الاختيار . استدعاء ( وظيفةالحجج ... ]) Source

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

function name(selection, first, last) {
  selection
      .attr("first-name", first)
      .attr("last-name", last);
}

قل الان:

d3.selectAll("div").call(name, "John", "Snow");

هذا يعادل تقريبا:

name(d3.selectAll("div"), "John", "Snow");

الفرق الوحيد هو أن اختيار .call دوما بإرجاع اختيار وليس القيمة المرجعة من يسمى وظيفة ، name.

الاختيار . فارغة () Source

إرجاع صحيح إذا كان هذا التحديد لا يحتوي على عناصر (غير خالية).

الاختيار . العقد () Source

إرجاع مجموعة من جميع العناصر (غير الفارغة) في هذا التحديد.

الاختيار . عقدة () Source

إرجاع العنصر الأول (غير الفارغ) في هذا التحديد. إذا كان التحديد فارغًا ، فتُرجع خالية.

الاختيار . حجم () Source

إرجاع العدد الإجمالي للعناصر في هذا الاختيار.

المتغيرات المحلية

يسمح لك السكان المحليون في D3 بتحديد الحالة المحلية بشكل مستقل عن البيانات. على سبيل المثال ، عند تقديم مضاعفات صغيرة من بيانات السلاسل الزمنية ، قد ترغب في استخدام نفس المقياس x لجميع المخططات ، لكن مع النطاقات y المميزة لمقارنة الأداء النسبي لكل مقياس. يتم تحديد السكان المحليين D3 بواسطة عناصر DOM: في المجموعة ، يتم تخزين القيمة على العنصر المحدد ؛ عند الحصول على ، يتم استرداد القيمة من عنصر معين أو أقرب سلف يحددها.

D3. Sourceمحلي ()Source

تعلن عن متغير محلي جديد. فمثلا:

var foo = d3.local();

مثل var، كل محلي هو إشارة رمزية متميزة. على عكس var، يتم تحديد قيمة كل محلي أيضًا بواسطة DOM.

المحلية . ضبط ( عقدة ، قيمة ) Source

يعين قيمة هذا المحلي على العقدة المحددة إلى القيمة ، وإرجاع القيمة المحددة . وغالبا ما تتم هذه العملية باستخدام selection.each :

selection.each(function(d) { foo.set(this, d.value); });

إذا كنت تقوم فقط بتعيين متغير واحد ، ففكر في استخدام properties :

selection.property(foo, function(d) { return d.value; });
المحلية . الحصول على ( عقدة ) Source

إرجاع قيمة هذا المحلي على العقدة المحددة . إذا لم تحدد العقدة هذا المحلي ، فتُرجع القيمة من أقرب سلف يعرّفها. إرجاع غير محدد إذا لم يكن هناك سلف يعرف هذا المحلي.

المحلية . إزالة ( عقدة ) Source

حذف قيمة هذا المحلي من العقدة المحددة . إرجاع صحيح إذا كانت العقدة حددت هذا المحلي قبل الإزالة ، وخطأ في غير ذلك. إذا كان الأجداد يعرّفون هذه اللغة أيضًا ، فلن تتأثر هذه التعريفات ، وبالتالي local.getlocal.get تُرجع القيمة الموروثة.

المحلية . toString () Source

إرجاع المعرّف الذي تم إنشاؤه تلقائيًا لهذا المحلي. هذا هو اسم الخاصية التي يتم استخدامها لتخزين قيمة المحلية على العناصر، وبالتالي يمكنك أيضا تعيين أو الحصول على قيمة محلية باستخدام عنصر [ المحلية ] أو باستخدام properties .

مساحات

مساحات أسماء XML ممتعة! حق؟ لحسن الحظ يمكنك تجاهلها في الغالب.

D3. مساحة الاسم ( الاسم ) Source

يؤهل الاسم المحدد ، والذي قد يحتوي أو لا يحتوي على بادئة مساحة اسم. إذا كان الاسم يحتوي على نقطتين ( :) ، فإن السلسلة الفرعية قبل النقطتين يتم تفسيرها على أنها بادئة مساحة الاسم ، والتي يجب تسجيلها في Namespaces . بإرجاع كائن spaceو localالصفات التي تصف URL مساحة الاسم الكامل واسم المحلي. فمثلا:

d3.namespace("svg:text"); // {space: "http://www.w3.org/2000/svg", local: "text"}

إذا كان الاسم لا يحتوي على نقطتين ، فستقوم هذه الوظيفة فقط بإرجاع اسم الإدخال.

D3. مساحات الاسم Source

خريطة بادئات مساحة الاسم المسجلة. القيمة الأولية هي:

{
  svg: "http://www.w3.org/2000/svg",
  xhtml: "http://www.w3.org/1999/xhtml",
  xlink: "http://www.w3.org/1999/xlink",
  xml: "http://www.w3.org/XML/1998/namespace",
  xmlns: "http://www.w3.org/2000/xmlns/"
}

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

原文