要素の選択

選択とは、DOMの要素の集合です。通常、これらの要素は、クラスがfancyの要素の場合は.fancy、DIV要素を選択する場合はdivなど、セレクターによって識別されます。

選択メソッドには、selectとselectAllの2つの形式があります。前者は最初に一致する要素のみを選択し、後者はドキュメントの順序で一致するすべての要素を選択します。トップレベルの選択メソッドであるd3.selectとd3.selectAllは、ドキュメント全体をクエリします。サブ選択メソッドであるselection.selectとselection.selectAllは、選択した要素の子孫に選択を制限します。直接の子については、selection.selectChildとselection.selectChildrenもあります。

慣例により、selection.attrのように現在の選択を返す選択メソッドは4つのスペースのインデントを使用しますが、新しい選択を返すメソッドは2つのみを使用します。これは、チェーンから目立つようにすることで、コンテキストの変化を明らかにするのに役立ちます。

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);

selection()

ソース · ルート要素であるdocument.documentElementを選択します。

const root = d3.selection();

この関数は、選択のテスト (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);

select(selector)

ソース · 指定されたselector文字列に一致する最初の要素を選択します。

const svg = d3.select("#chart");

selectorに一致する要素がない場合は、空の選択を返します。複数の要素がselectorに一致する場合は、最初に一致する要素（ドキュメント順）のみが選択されます。たとえば、最初のアンカー要素を選択するには

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

selectorが文字列でない場合は、代わりに指定されたノードを選択します。これは、document.bodyなど、すでにノードへの参照を持っている場合に便利です。

d3.select(document.body).style("background", "red");

または、クリックした段落を赤くするには

d3.selectAll("p").on("click", (event) => d3.select(event.currentTarget).style("color", "red"));

selectAll(selector)

ソース · 指定されたselector文字列に一致するすべての要素を選択します。

const p = d3.selectAll("p");

要素はドキュメントの順序（上から下）で選択されます。ドキュメント内にselectorに一致する要素がない場合、またはselectorがnullまたは未定義の場合は、空の選択を返します。

selectorが文字列でない場合は、代わりに指定されたノードの配列を選択します。これは、イベントリスナー内のthis.childNodesやdocument.linksなどのグローバル変数など、すでにノードへの参照を持っている場合に便利です。ノードは、イテラブル、またはNodeListなどの擬似配列にすることもできます。たとえば、すべてのリンクを赤くするには

d3.selectAll(document.links).style("color", "red");

selection.select(selector)

ソース · 選択された各要素について、指定されたselector文字列に一致する最初の要素の子孫を選択します。

const b = d3.selectAll("p").select("b"); // the first <b> in every <p>

現在の要素に対して指定されたセレクターに一致する要素がない場合、返される選択内の現在のインデックスの要素はnullになります。（selectorがnullの場合、返される選択内のすべての要素はnullになり、結果として空の選択になります。）現在の要素に関連付けられたデータがある場合、このデータは対応する選択された要素に伝播されます。複数の要素がセレクターに一致する場合、ドキュメントの順序で最初に一致する要素のみが選択されます。

selectorが関数の場合、選択された各要素について、現在のデータ（d）、現在のインデックス（i）、および現在のグループ（nodes）を渡して、順番に評価されます。thisは現在のDOM要素（nodes[i]）です。要素を返す必要があります。一致する要素がない場合は、nullを返します。たとえば、各段落の前の兄弟を選択するには

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

selection.selectAllとは異なり、selection.selectはグループ化に影響を与えません。既存のグループ構造とインデックスを保持し、データ（存在する場合）を選択された子に伝播します。グループ化は、データ結合で重要な役割を果たします。このトピックの詳細については、ネストされた選択と選択の仕組みを参照してください。

注意

selection.selectは、親のデータを選択された子に伝播します。

selection.selectAll(selector)

ソース · 選択された各要素について、指定されたselector文字列に一致する子孫要素を選択します。

const b = d3.selectAll("p").selectAll("b"); // every <b> in every <p>

返される選択の要素は、この選択で対応する親ノードによってグループ化されます。現在の要素に対して指定されたセレクターに一致する要素がない場合、またはselectorがnullの場合、現在のインデックスのグループは空になります。選択された要素は、この選択からデータを継承しません。子にデータを伝播するには、selection.dataを使用してください。

selectorが関数の場合、選択された各要素について、現在のデータ（d）、現在のインデックス（i）、および現在のグループ（nodes）を渡して、順番に評価されます。thisは現在のDOM要素（nodes[i]）です。要素の配列（またはイテラブル、またはNodeListなどの擬似配列）を返す必要があります。一致する要素がない場合は、空の配列を返す必要があります。たとえば、各段落の前の兄弟と次の兄弟を選択するには

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

selection.selectとは異なり、selection.selectAllはグループ化に影響します。選択された各子孫は、元の選択の親要素によってグループ化されます。グループ化は、データ結合で重要な役割を果たします。このトピックの詳細については、ネストされた選択と選択の仕組みを参照してください。

selection.filter(filter)

ソース · 選択をフィルター処理し、指定されたfilterがtrueである要素のみを含む新しい選択を返します。たとえば、テーブル行の選択をフィルター処理して、偶数行のみを含むようにするには

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

これは、d3.selectAllを直接使用することとほぼ同じですが、インデックスが異なる場合があります。

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

filterは、セレクター文字列または関数のいずれかとして指定できます。filterが関数の場合、選択された各要素について、現在のデータ（d）、現在のインデックス（i）、および現在のグループ（nodes）を渡して、順番に評価されます。thisは現在のDOM要素（nodes[i]）です。関数を使用する場合

const even = d3.selectAll("tr").filter((d, i) => i & 1);

または、selection.selectを使用する（および、現在の要素を参照するためにthisが必要なので、アロー関数を避ける）場合

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

:nth-child擬似クラスは、ゼロベースのインデックスではなく、1ベースのインデックスであることに注意してください。また、上記のフィルター関数は、:nth-childとまったく同じ意味ではありません。これらは、DOM内の先行する兄弟要素の数ではなく、選択インデックスに依存しています。

返されるフィルタリングされた選択は、この選択の親を保持しますが、array.filterと同様に、一部の要素が削除される可能性があるため、インデックスを保持しません。必要に応じて、インデックスを保持するにはselection.selectを使用してください。

selection.selectChild(selector)

ソース · 現在の選択の各要素のうち、selectorに一致する（最初の）子を持つ新しい選択を返します。

d3.selectAll("p").selectChild("b") // the first <b> child of every <p>

selectorが指定されていない場合は、最初の子（存在する場合）を選択します。selectorが文字列として指定されている場合は、一致する最初の子（存在する場合）を選択します。selectorが関数の場合は、各子ノードに対して順番に評価され、子（child）、子のインデックス（i）、および子リスト（children）が渡されます。このメソッドは、セレクターが真値を返す最初の子（存在する場合）を選択します。

注意

selection.selectChildは、親のデータを選択された子に伝播します。

selection.selectChildren(selector)

ソース · 現在の選択の各要素の子のうち、selectorに一致するものを新しい選択として返します。selectorが指定されていない場合は、すべての子を選択します。selectorが文字列として指定されている場合は、一致する子（存在する場合）を選択します。selectorが関数の場合は、各子ノードに対して順番に評価され、子（child）、子のインデックス（i）、および子リスト（children）が渡されます。このメソッドは、セレクターが真値を返すすべての子を選択します。

selection.selection()

ソース · 選択を返します（transition.selectionとの対称性のため）。

matcher(selector)

ソース · 指定されたselectorが与えられた場合、this要素が指定されたセレクターと一致する場合はtrueを返す関数を返します。このメソッドは、selection.filterによって内部的に使用されます。例えば、これは

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

これは同等です

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

（D3は互換性レイヤーではありませんが、最近のelement.matchesの標準化により、この実装はベンダープレフィックス付きの実装をサポートしています。）

selector(selector)

ソース · 指定されたselectorが与えられた場合、指定されたセレクターに一致するthis要素の最初の子孫を返す関数を返します。このメソッドは、selection.selectによって内部的に使用されます。例えば、これは

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

これは同等です

const div = selection.select(d3.selector("div"));

selectorAll(selector)

ソース · 指定されたselectorが与えられた場合、指定されたセレクターに一致するthis要素のすべての子孫を返す関数を返します。このメソッドは、selection.selectAllによって内部的に使用されます。例えば、これは

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

これは同等です

const div = selection.selectAll(d3.selectorAll("div"));

window(node)

ソース · 指定されたnodeのオーナーウィンドウを返します。nodeがノードの場合は、オーナーDocumentのデフォルトビューを返します。nodeがドキュメントの場合は、そのデフォルトビューを返します。それ以外の場合は、nodeを返します。

style(node, name)

ソース · 指定されたnodeの、指定されたnameを持つスタイルプロパティの値を返します。nodeが指定されたnameのインラインスタイルを持つ場合、その値が返されます。それ以外の場合は、計算されたプロパティ値が返されます。selection.styleも参照してください。