D3 本地变量详解：d3.local 与 DOM 作用域状态的读写、继承与移除

D3 本地变量详解d3.local 与 DOM 作用域状态的读写、继承与移除【免费下载链接】d3Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:项目地址: https://gitcode.com/GitHub_Trending/d3/d3D3 locals本地变量是 d3-selection 提供的一种把状态挂载到 DOM 元素上的机制它让状态的定义完全独立于数据绑定并支持沿祖先链自动继承。本文基于仓库中 locals 文档 的完整 API 内容展开并结合 package.json、src/index.js 与 api.md 等仓库证据说明local()、local.set、local.get、local.remove、local.toString五个 API 的用法、行为边界以及与其他状态存储方式的取舍。什么是 D3 locals适合什么场景D3 locals 允许定义独立于数据data的本地状态。典型场景是渲染时间序列数据的 small multiples小倍图你可能希望所有小图共享同一个 x 轴比例尺但每张图拥有各自独立的 y 轴比例尺以便对比各指标的相对表现。locals 的作用域规则以 DOM 元素为单位set 时值被存储在指定的元素上get 时值从指定元素读取若该元素未定义此 local则沿祖先链向上查找返回最近的定义了该 local 的祖先上的值若没有任何祖先定义则返回undefined。原文档给出了一条明确的官方提示值得原样保留CAUTIONLocals 很少被使用你往往会发现把需要的状态存储在 selection 的 data 中更简单。也就是说locals 的定位是“锦上添花”的细粒度控制手段而不是日常首选。local()声明一个新的本地变量const foo d3.local();local()用于声明一个新的本地变量。可以把它理解为 JS 的var的 DOM 化版本与var相同每个 local 都是一个独立的符号引用与var不同每个 local 的取值还按 DOM 作用域划分即同名 local 在不同元素上可以有不同取值。在完整打包的 d3 中local与整个 d3-selection 模块一起导出。从 src/index.js 可以看到umbrella 包通过export * from d3-selectionsrc/index.js#L24一次性暴露了d3.local在内的全部 selection API而 package.json 声明的依赖版本为d3-selection: ^3.0.0package.json#L61当前 umbrella 包版本为7.9.0。这意味着d3.local在 d3 v7 及 d3-selection v3 及以上版本中均可直接使用。local.set(node, value)向元素写入值selection.each(function(d) { foo.set(this, d.value); });local.set(node, value)把指定node上该 local 的值设置为value并返回被设置的value这一返回值使得 set 可以内嵌在表达式中使用。由于 set/get 的入参是具体的 DOM 节点而非 selection惯用写法是借助 selection.each 遍历选区在回调里用this引用当前元素。如果只是想给元素存储一个变量原文档建议直接考虑更简单的 selection.propertyselection.property(foo, (d) d.value);这里foo作为 local 变量对象传入会被用作属性名的字符串标识等价于以foo.toString()的标识为属性名调用 property。这一写法能成立的原因正是下一个小节要讲的 toString 机制。local.get(node)按祖先链回退的读取selection.each(function() { const value foo.get(this); });local.get(node)返回指定node上该 local 的值其查找规则是整个 locals 机制中最有特色的部分若node自身定义了该 local直接返回自身上的值若node未定义则返回最近的定义了该 local 的祖先的值若整条祖先链上都没有定义返回undefined。这种“就近继承”语义使得 small multiples 场景中的分工变得自然把共享的 x 比例尺 set 在图表容器的公共外层节点上把各自的 y 比例尺 set 在每个小图节点上小图内部的所有子元素坐标轴、网格线、文字等调用get(this)时x 比例尺从外层继承y 比例尺则命中所在小图自身的定义。祖先继承也意味着修改某个内层元素上的 local 不影响外层而删除内层定义后读取会回退到外层值见下文 remove。local.remove(node)删除元素上的定义selection.each(function() { foo.remove(this); });local.remove(node)删除指定node上该 local 的值其返回值为布尔型若删除前node自身定义了该 local返回true否则返回false。需要注意继承语义在删除后依然生效若祖先上也定义了该 local这些祖先定义不受影响因此 local.get 仍然会返回继承自祖先的值。换言之remove只清除“本节点自己的定义”让查找自然回退到祖先链而不是把值置空。local.toString()取回本地属性标识符local.toString()返回该 local 自动生成的标识符。这个标识符的实质意义是它正是用来在元素上存储该 local 值的属性名。因此除了 set/get/remove 之外你还可以通过原生属性访问读写同一个值element[local]—— 用 local 对象作为计算属性名直接读写底层属性local.toString()会在计算属性名时被自动调用selection.property —— 例如selection.property(foo, (d) d.value)即把foo.toString()的结果当作属性名。这一点把 locals 与 d3-selection 的其余修改类 API 打通了同一个 local 既可以用 locals API 管理也可以作为property的属性名使用两条路径读写的是元素上同一个位置的值。在 d3 项目中的位置与证据从仓库结构可以确认 locals 在 d3 生态中的归属与地位API 索引api.md 的 d3-selection 章节将 “Local variables” 列为 selection 的六大主题之一与 Selecting、Modifying、Joining、Events、Control flow 并列并逐条索引了d3.local、local.set、local.get、local.remove、local.toString五个条目api.md#L1096-L1102与本文覆盖范围一致。模块归属locals 属于 d3-selection 子模块umbrella 包通过 src/index.js 的 re-export 汇总暴露各 API 的实现源码位于 d3-selection 子仓库的src/local.js官方文档在每条 API 条目下均标注了对应的 Source 链接实现细节以该子模块为准。历史沿革CHANGES.md 记录了d3.local的引入动机CHANGES.md#L1208“提供定义本地变量的机制状态绑定到 DOM 元素并可供任何后代元素使用是使用 selection.each 或把状态存进 data 的便捷替代。” 这与本文开头描述的用途一致。locals 与 data、property 的取舍locals 是 d3 中三种“把值挂到元素上”的方式之一选择时可以从以下维度对照方式存储位置作用域/继承适用情形selection 的 datadata join与元素的 datum 绑定无祖先继承按数据索引取用状态与数据一一对应时的默认选择selection.property元素上的原生属性无祖先继承表单控件的value/checked等特殊属性或单变量存储d3.local元素上以自动生成标识符为名的属性有祖先继承get 沿祖先链回退状态需要跨层级共享、且不想混入数据绑定时的细粒度场景官方对 locals 的定位是克制而明确的它“很少被使用”。日常开发中优先把状态放进 selection 的 data 或用property存储只有当状态天然是“挂在 DOM 树某一层级、供整棵子树读取”的形态如 small multiples 中的共享比例尺、子组件间传递的渲染上下文时locals 的祖先继承语义才会体现出独特价值。小结d3.local()声明一个按 DOM 元素划分的本地变量是var的 DOM 作用域版本local.set(node, value)将值写入指定元素并返回该值通常配合selection.each使用单变量场景可退化为selection.property(foo, fn)local.get(node)读取值时沿祖先链回退未命中任何定义则返回undefined这是 locals 支持“公共配置挂外层、私有配置挂内层”模式的关键local.remove(node)仅删除本节点的定义并返回布尔值祖先定义不受影响删除后 get 会回退到继承值local.toString()暴露底层存储所用的属性名使element[local]与selection.property成为与 locals API 等价的读写路径。【免费下载链接】d3Bring data to life with SVG, Canvas and HTML. :bar_chart::chart_with_upwards_trend::tada:项目地址: https://gitcode.com/GitHub_Trending/d3/d3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考