d3 选择集的 XML 命名空间机制详解：d3.namespace 与 d3.namespaces

在 D3（Data-Driven Documents，当前仓库版本为 d3 v7.9.0）中操作 DOM 时，你几乎可以完全忽略 XML 命名空间——只要始终在 HTML 里创建 HTML 元素即可。但一旦你需要在 SVG 内部嵌入 HTML 内容（典型场景是 foreignObject），或者设置带命名空间前缀的属性（如 xlink:href），就必须理解 d3-selection 模块提供的两个命名空间工具：d3.namespace 和 d3.namespaces。本文基于 namespaces.md 展开，结合仓库中的文档结构与依赖配置，说明这套机制的工作原理、默认值以及扩展方式，读完后你能够独立完成 SVG/HTML 混合文档的元素创建、带前缀属性的读写，以及为自定义命名空间注册前缀。

什么时候需要显式指定命名空间

官方文档的态度很明确："XML namespaces are fun! Right? Fortunately you can mostly ignore them."——你通常可以忽略它们。少数必须显式指定命名空间的场景，是向属于另一个命名空间的父元素追加子元素。最典型的例子是在 SVG 的 foreignObject 元素中创建一个 HTML div：

d3.create("svg")
  .append("foreignObject")
    .attr("width", 300)
    .attr("height", 100)
  .append("xhtml:div")
    .text("Hello, HTML!");

这段代码的关键在于最后一行：foreignObject 属于 SVG 命名空间，而 div 属于 XHTML 命名空间。因此追加元素时必须写成带前缀的 xhtml:div，d3-selection 才会通过 document.createElementNS 在正确的命名空间中创建该元素，而不是继承父元素的 SVG 命名空间。如果不带前缀直接写 .append("div")，创建出来的元素会落在错误的命名空间里，导致 HTML 内容无法按预期渲染。

这一点也解释了为什么 docs/components/PlotRender.js 这类文档渲染辅助代码需要直接封装 createElementNS(namespace, tagName)、setAttributeNS(namespace, name, value) 和 removeAttributeNS(namespace, name, value) 等方法——从源码结构看，凡是涉及跨命名空间创建与属性操作的场景，底层都是围绕这三组 DOM API 展开的。

用 d3.create 与 append 跨命名空间创建元素

上文示例使用了 d3.create，这里补充它与 append/insert 的命名空间语义差异，方便对照使用。根据 d3-selection 修改篇 的说明：

• d3.create(name) 返回包含一个游离元素的单元素选择集，默认假定 HTML 命名空间。因此要创建 SVG 或其他非 HTML 元素时，必须显式指定命名空间前缀，例如 d3.create("svg")（svg 是已知前缀，等价于 svg:svg）；
• *selection*.append(name) 与 *selection*.insert(name) 中，元素名可带命名空间前缀，如 svg:text 表示在 SVG 命名空间中创建 text 元素；
• 若追加的元素不带前缀，其命名空间将从父元素继承；若名字本身是已知前缀（如 svg），则直接使用对应命名空间。

这三条规则与 d3.namespace 的实现语义是一体的：前缀决定创建时使用的 createElementNS 参数，前缀缺失时则走继承路径。

d3.namespace：解析带前缀的名称

d3.namespace(name) 用于限定（qualify）一个可能带命名空间前缀的名称，返回描述完整命名空间 URL 与局部名称的对象：

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

其解析规则为：

• 若 name 中包含冒号（:），冒号前的子串被解释为命名空间前缀，且该前缀必须已注册在 d3.namespaces 中；
• 返回值是包含 space（完整命名空间 URL）与 local（局部名称）两个属性的对象；
• 若 name 不含冒号，函数原样返回输入名称——这意味着对普通 HTML 元素名（如 "div"）做限定是无副作用的。

从 CHANGES.md 的历史记录可以确认这套 API 的来源：D3 4.0 的大改名中，原 d3.ns.prefix 前缀映射被重命名为 d3.namespaces，d3.ns.qualify 方法被重命名为 d3.namespace。也就是说 d3.namespace 就是早期 d3.ns.qualify 的后继者，负责"前缀 → 命名空间 URL"的限定工作。

在完整的 D3 入口中，这两个 API 随 d3-selection 一并导出：src/index.js 中的 export * from "d3-selection" 语句将选择集模块的全部符号（包括 namespace、namespaces）平铺到顶层 d3 对象上，这与 package.json 中声明的 d3-selection: ^3.0.0 依赖一致。

d3.namespaces：已注册前缀表及其默认值

d3.namespaces 是一张已注册命名空间前缀的映射表，其初始值为：

{
  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/"
}

各前缀覆盖 Web 平台最常用的命名空间：

前缀	命名空间 URL	典型用途
svg	http://www.w3.org/2000/svg	创建/操作 SVG 图形元素，如 svg:text
xhtml	http://www.w3.org/1999/xhtml	在 foreignObject 内创建 HTML 元素，如 xhtml:div
xlink	http://www.w3.org/1999/xlink	设置 XLink 命名空间属性，如 xlink:href
xml	http://www.w3.org/XML/1998/namespace	操作 xml:lang 等标准 XML 属性
xmlns	http://www.w3.org/2000/xmlns/	处理命名空间声明属性

注册自定义前缀

文档明确指出："Additional prefixes may be assigned as needed to create elements or attributes in other namespaces."——d3.namespaces 就是一个普通对象，你可以按需往里添加条目来创建或使用其他命名空间的元素和属性：

// 注册一个新的命名空间前缀（示例 URL 请以实际资源为准）
d3.namespaces.my = "http://example.com/my-namespace";

// 之后即可使用带前缀的名称
d3.namespace("my:widget");
// {space: "http://example.com/my-namespace", local: "widget"}

注册后即可在所有依赖 d3.namespaces 的 API 中使用该前缀，包括 d3.create、*selection*.append、*selection*.insert 创建元素，以及 *selection*.attr 设置带前缀的属性（修改篇 中 *selection*.attr 一节专门举了 xlink:href 的例子："the href attribute in the XLink namespace"）。

在 API 索引中的位置

在 docs/api.md 的 API 总览中，命名空间工具归入 d3-selection 的 Namespaces 分组，共两条：

• d3.namespace —— 限定带前缀的 XML 名称，如 xlink:href；
• d3.namespaces —— 内置 XML 命名空间表。

它是 d3-selection 文档 七大主题（选择元素、修改元素、数据连接、事件、控制流、局部变量、命名空间）之一。与命名空间相关的姊妹文档还有：joining.md 的数据连接流程（追加/移除元素时的命名空间继承规则在此生效）、modifying.md 的属性与元素修改方法，以及 control-flow.md、locals.md 等。

小结与使用建议

• 日常 HTML 操作：不带前缀即可，命名空间从父元素继承，无需关心 d3.namespaces；
• SVG 内嵌 HTML / 混合文档：显式使用 xhtml: 前缀（如 xhtml:div），这是 foreignObject 场景的标准写法；
• 带前缀属性：使用 xlink:href 这类已注册前缀，attr 方法会通过 setAttributeNS 落到正确的命名空间；
• 第三方命名空间：向 d3.namespaces 对象直接添加"前缀 → URL"条目，d3.namespace 与全部创建/设属性 API 随即识别该前缀。

整套机制的设计目标是：把浏览器 createElementNS/setAttributeNS 的繁琐细节收敛到一张可注册的映射表后面，让你在前缀层面书写代码即可覆盖绝大多数跨命名空间操作。