数据可视化【免费下载链接】vegaA visualization grammar.项目地址https://gitcode.com/gh_mirrors/ve/vega点击查看免费下载本文是 Vega 可视化语法规范vega 仓库中docs/docs/types.md的深度技术指南系统梳理 Vega 规范中所有通用参数类型的定义、适用场景与写法约定。无论你是在编写 mark/encode 编码、scale 映射、transform 变换还是 legend/title 配置掌握这套类型体系都能帮助你写出合法、可预测的 Vega 规范并理解运行时如 vega-parser、vega-schema是如何解析与验证这些值的。读完本文你将能准确区分 Literal 值与 Value Reference、Signal 与 Expr、Field 与 FieldValue 等易混淆概念并能直接写出渐变、多字段排序、按 datum 求值表达式等高级配置。Vega 规范中的参数按用途可归为三大类字面量类型Literal Values、数据与信号类型Data and Signal Types、以及用于视觉编码的Value Reference 类型Value、ColorValue、FieldValue、GradientValue。这些类型定义不仅出现在文档中也直接对应着 packages/vega-schema/src 中生成的 JSON Schema 定义以及 packages/vega-parser/src/parsers/encode/entry.js 中的实际解析逻辑。Parameter Type Reference 总览docs/docs/types.md提供了一份完整的参数类型索引Literal Values字面量Any、Array、Boolean、Color、Date、Gradient、Number、Object、String、URLData and Signal Types数据与信号Data、Field、Signal、Compare、ExprValue References值引用Value、ColorValue、FieldValue、GradientValue格式相关TimeMultiFormat在 packages/vega-schema/src/util.js 中这些基础类型被定义为一组可直接复用的 Schema 原子例如anyType、arrayType、booleanType、numberType、objectType、stringType、nullType并通过orSignal(obj)与signalRef组合出某类型或 signal 引用的联合类型这正是 Vega 规范几乎所有参数都可以是动态信号的设计基石。Literal Values 字面量类型Any*接受任意字面量值包括字符串、数字、布尔值或null。Array数组接受数组值例如[]、[1, 2, 3]、[foo, bar]。如果数组中的每个元素必须符合特定类型则使用括号记法表示元素类型如Number[]或String[]。在多数情况下数组元素也可以是 signal 引用例如[{signal: width}, {signal: height}]在 packages/vega-schema/src/util.js 中array(items, props)会生成{type: array, items: ...}的 Schemaitems参数即用于约束元素类型而对 encode 值而言数组还可以是带条件的 rule 数组见下文 Value 中的 rule 说明对应 encode.js 的valueSchema。Boolean布尔接受布尔值例如true、false。Color颜色接受合法的 CSS 颜色字符串例如#f304d3、#ccc、rgb(253, 12, 134)、steelblue。在 Schema 层面encode.jscolorValue被定义为null、字符串或 colorValue 引用即baseColorValue的联合类型——注意null是显式允许的用于表示不绘制的语义。Date日期接受合法的 JavaScriptDate对象或时间戳。由于 JSON 本身不支持日期值在 Vega 规范中日期时间值可以通过以下两种方式之一表达数值时间戳自 UNIX 纪元以来的毫秒数即Date.getTime()的返回值信号表达式例如{signal: datetime(2001, 2, 3)}。日期时间值通常配合 scale 的domain、scale.domain以及数据过滤使用相关表达式能力见 expressions 文档。Gradient渐变— Vega 5.4接受一个用于指定渐变颜色模式的对象。如果要基于颜色 scale 的 range来定义线性渐变请改用 GradientValue。直接定义渐变的示例如下{ gradient: linear, stops: [ {offset: 0.0, color: red}, {offset: 0.5, color: white}, {offset: 1.0, color: blue} ] }Gradient 类型在 packages/vega-schema/src/encode.js 中被拆分为linearGradient与radialGradient两个 Schema二者共享gradientStops一个由offsetcolor组成的对象数组。在 packages/vega-scenegraph 渲染层线性渐变会被绘制为沿直线的颜色插值径向渐变则绘制为两圆之间的颜色插值。Linear Gradient 线性渐变线性渐变沿一条直线、从起始点向终止点插值颜色。默认情况下线性渐变水平运行从左到右。可通过x1、y1、x2、y2属性配置渐变方向。所有坐标均定义在归一化的 [0, 1] 坐标空间中相对于被着色元素的包围盒。名称类型描述gradientString必填。渐变类型线性渐变使用linear。x1Number线性渐变起始 x 坐标归一化 [0, 1]默认 0。y1Number线性渐变起始 y 坐标归一化 [0, 1]默认 0。x2Number线性渐变终止 x 坐标归一化 [0, 1]默认 1。y2Number线性渐变终止 y 坐标归一化 [0, 1]默认 0。stopsGradientStop[]必填。定义渐变颜色序列的渐变停止点数组。对应 Schema 见 encode.js 中 linearGradient 定义其中gradient属性被enums([linear])约束只允许linear一个取值。Radial Gradient 径向渐变径向渐变在两个圆之间插值颜色从内圆边界到外圆边界。默认情况下径向渐变从坐标系中心点半径为零的内圆向外延伸到最大范围半径为 0.5 的外圆。可通过x1、y1、x2、y2配置内外圆圆心通过r1、r2配置圆的半径。所有坐标均定义在归一化 [0, 1] 坐标空间中相对于被着色元素的包围盒值 1 对应包围盒的最大范围宽和高中的较大者。名称类型描述gradientString必填。渐变类型径向渐变使用radial。x1Number内圆圆心 x 坐标归一化 [0, 1]默认 0.5。y1Number内圆圆心 y 坐标归一化 [0, 1]默认 0.5。r1Number内圆半径归一化 [0, 1]默认 0。x2Number外圆圆心 x 坐标归一化 [0, 1]默认 0.5。y2Number外圆圆心 y 坐标归一化 [0, 1]默认 0.5。r2Number外圆半径归一化 [0, 1]默认 0.5。stopsGradientStop[]必填。定义渐变颜色序列的渐变停止点数组。Gradient Stop 渐变停止点一个渐变停止点由一个 Color 值和一个offset进度分数组成名称类型描述offsetNumber必填。颜色停止点的偏移分数指示其在渐变中的位置。colorColor必填。渐变在该点的颜色值。Number数字接受数值例如1、3.14、1e5。Object对象接受对象字面量例如{left:5, right:30, top:5, bottom:50}。合法的对象属性名与类型因参数而异需阅读具体参数的描述。Schema 层面util.js 的object()辅助函数默认采用additionalProperties: false严格校验属性名用下划线包裹如_value_表示必填。String字符串接受字符串值例如bold、step-before、。URL接受指向外部站点或资源的合法 URL 字符串例如data/stocks.csv、images/logo.png。URL 常用于数据加载见 data 文档、image mark 的url编码通道以及background配置。Data and Signal Types 数据与信号类型Data接受指示数据集名称的字符串例如table、nodes。Data 类型广泛用于 transform 的from/lookup参数以及信号事件流的数据引用。Field字段接受指示数据字段名称的字符串例如amount、source.x、target[x]。也可以接受一个带字符串值field属性的对象例如{field: amount}、{field: source.x}。此外as参数可用于为字段指定不同的输出名称例如{field: inputName, as: outputName}。字段解析遵循 JavaScript 对象访问路径规则使用点.或括号foo[bar]记法的合法访问路径会被转换为对嵌套对象的查找如果字段名包含点号但并非嵌套查找则需要转义内联的点my\\.field或将字段名括在方括号中[my.field]。在源码层面packages/vega-util/src/splitAccessPath.ts 实现了访问路径拆分它会把a.b、a[b]之类的路径解析为字符串数组同时正确处理转义\\.与括号保护[my.field]。而 packages/vega-parser/src/parsers/encode/entry.js 中的resolveField则进一步将字段引用编译为运行时表达式例如datum[amount]这样的访问链。Signal信号接受一个引用信号值或表达式的对象。对象的signal属性必须是合法的信号名称字符串或指示派生值的表达式字符串。例如{signal: width} {signal: width / 2}Signal 引用是 Vega 实现响应式reactive可视化的核心机制当信号值变化时所有依赖它的参数都会自动重新求值。在 packages/vega-schema/src/util.js 中signalRef def(signalRef)被定义为一个全局可复用的引用并通过orSignal(obj)便捷地包裹任意参数定义。Compare比较器接受一个提供排序比较器定义的对象。比较器对象可以有两个属性——field和order——分别指示要排序的数据字段和每个字段的期望排序方向。每个属性既可以取单个字符串值按一个字段排序也可以取字符串数组按多个字段排序。order属性是可选的。如果定义order值必须是ascending从低到高或descending从高到低之一。如果order未定义或order条目数少于field条目数则默认使用升序。单字段比较器{field: amount, order: ascending}多字段比较器{ field: [amount, date], order: [descending, ascending] }比较器不能通过单个 signal 实例来指定但field和order属性本身可以各自使用 signal{ field: {signal: sortField}, order: {signal: sortOrder} }如果某个排序字段为null该字段及其对应的order条目将被忽略如同该条目不存在。Compare 类型是 sort/collect/window/stack 等 transform 的sort参数基础具体可参考 transforms 文档。Expr表达式接受一个定义对每个数据对象求值的表达式的对象。某些 transform例如 wordcloud transform的参数可以取静态字符串/数字值或对每条 datum 执行查找操作。Expr 类型有两种合法形式field 引用和expr 引用。field 引用执行字段查找与 Field 类型参数完全相同{ type: wordcloud, rotate: {field: angle} // 对每条 datum 查找 angle 字段 }expr 引用提供一个表达式字符串该表达式将对每条 datum 求值一次{ type: wordcloud, rotate: {expr: datum.minAngle round(90*random() - 45)} // 对每条 datum 求值一次 }与每次参数求值一次的 signal 引用不同expr 引用的行为类似于匿名函数lambda 函数对每个数据对象独立求值。需要注意的是signal 引用与 expr 引用在上游依赖发生变化时都会重新运行。field 与 expr 引用都可以包含as属性用于指定输出的字段名。Value References 值引用Value接受一个定义value reference值引用的对象通常用于视觉编码。一个值引用由基础值base value、可选的scale 变换scale transform与值修饰modification组成。在 packages/vega-parser/src/parsers/encode/entry.js 中entry函数完整实现了这一解析流程先确定基础值再套用 scale最后依次应用 exponent/mult/offset/round 修饰。基础值Base Value基础值必须通过以下属性之一指定名称类型描述signalString一个 signal 名称或表达式。colorColorValue使用每个颜色通道的值引用来指定颜色见 color value 文档。fieldFieldValue数据字段名或描述符见 field value 文档。valueAny常量值。合法值包括数字、布尔值、字符串、颜色和渐变。这些属性按优先级顺序列出例如如果定义了signal则任何color、field或value属性都会被忽略。此外在某些scale值的情况下或为了表示null值基础值可以留空不定义。这一优先级在源码中得到精确体现entry.js 中entry()的取值顺序为enc.signal→enc.color→enc.field ! null→enc.value ! undefined与文档中的优先级顺序完全一致。Scale 变换Scale Transforms基础值确定后可以执行 scale 查找。可用的 scale 相关属性如下名称类型描述scaleString|FieldValue要应用的 scale 变换名称。如果此参数是对象则表示一个 field value用于动态查找 scale 名称。例如{datum: s}使用当前数据对象上s字段的值作为 scale 名称而{parent: t}使用父 group 数据对象上t字段的值作为 scale 名称。bandNumber若指定返回 scale 的带宽乘以给定数字。此参数仅适用于 band scales。例如{band: 1}表示完整带宽{band: 0.5}表示一半带宽。如果定义了基础值则乘后的带宽会加到 scale 变换的输出上。例如{field: a, scale: s, band: 0.5}等价于scale(datum.a) 0.5 * scale.bandwidth()。在 entry.js 的scale()函数中可以看到具体实现_scale(scale, value)将基础值送入 scale_bandwidth(scale)获取 band scale 带宽并乘以band系数若基础值存在则用拼接即band 加在 scale 输出之上否则单独返回带宽。Schema 端encode.js的numberModifiers中还额外定义了extra布尔属性用于处理超出范围的额外元素与range属性从 scale 的 range 中按比例lerp取值属于 schema 支持但文档未展开的进阶能力。值修饰Value Modifiersscale 变换应用之后还可以通过以下属性进一步修饰结果值。值引用的基本公式为pow(scale(baseValue), exponent) * mult offset。值修饰符仅适用于数值。名称类型描述exponentNumber|Value将值提升到给定指数等价于pow(value, exponent)。若指定指数运算在 scale 变换之后立即应用。multNumber|Value值的乘数等价于mult * value。乘数在 scale 变换或指数运算之后应用。offsetNumber|Value最终值的加性偏移等价于value offset。偏移在 scale 变换、指数运算或乘法之后添加。roundBoolean指示是否对最终值取整默认false。取整在所有其他修饰之后执行。若为 true等价于round(value)。这一先 scale、再 exponent、再 mult、最后 offset/round的顺序同样在 entry.js 中逐行体现pow(...)包裹 scale 输出随后拼接*mult、offset最后用round(...)包裹整体。示例{value: 5}— 常量值5。{field: price}— 当前 datum 的price值。{field: index, mult: 20}— 当前 datum 的index值乘以 20。{scale: x, value: 0}— 将值0通过名为x的 scale 运行的结果。{scale: y, field: price}— 将当前 datum 的price通过名为y的 scale 运行的结果。{scale: x, band: 1}— band scalex的范围带宽。注意 scale 类型必须是 band{scale: x, band: 1, offset: -1}— band scalex的范围带宽减去负偏移1 像素。此外encode 的值还支持rule条件数组形式valueSchemaencode.js允许值本身或数组中的元素带上test条件表达式用于实现条件编码例如根据datum属性切换颜色这与 expressions 文档 中test谓词的用法一致。ColorValue接受一个对象该对象使用所选颜色空间中每个颜色通道的值引用来定义自定义颜色。颜色空间根据使用的通道名称自动推断。通常颜色值被指定为表示 RGB 颜色的单个值。但有时设计者可能希望针对特定颜色字段或使用不同的颜色空间。在下面的示例中我们将 RGB 颜色的红、蓝通道设置为常量而绿色通道则由 scale 变换确定{ fill: { color: { r: {value: 255}, g: {scale: green, field: g}, b: {value: 0} } } }Vega 支持以下颜色空间名称描述RGB红、绿、蓝通道分别使用属性r、g、b。HSL色相、饱和度、亮度通道分别使用属性h、s、l。LAB亮度、A绿-红对比度、B蓝-黄对比度通道分别使用属性l、a、b。LAB 是感知颜色空间距离基于人类颜色判断。HCL色相、色度、亮度通道分别使用属性h、c、l。HCL 颜色空间是 LAB 的简单变换AB 平面使用极坐标表示。在 packages/vega-schema/src/encode.js 中四个颜色空间被分别定义为colorRGB、colorHSL、colorLAB、colorHCL每个通道都是numberValueRef数字或值引用。而解析侧entry.js的color()函数则根据通道出现情况自动推断空间有c用 hcl有h/s用 hsl有l/a用 lab有r/g/b用 rgb并将其编译为rgb(...)、hsl(...)、lab(...)、hcl(...)表达式。FieldValue接受一个字符串或对象用于指示数据字段值。如果是字符串则直接使用给定的数据字段名。如果是对象则可以使用以下属性属性类型描述signalString求值 signal 名称或表达式并将结果用作要查找的字段名。datumFieldValue使用给定字段名对当前数据对象执行查找。这类似于直接提供字符串值。groupFieldValue使用包围 group mark 实例的属性作为值例如field: {group: width}或field: {group: height}。parentFieldValue使用包围 group mark 数据对象的字段作为值例如field: {parent: fieldInParentData}。这些属性可以任意嵌套以执行间接字段查找。例如{parent: {datum: f}}将首先检索当前 mark 数据对象上f字段的值然后将该值用作在包围父 group mark 数据对象上查找的属性名。此外group和parent引用可以包含可选的level属性用于访问祖父及更上层的祖先。例如{parent: f, level: 2}将使用祖父 datum 上f字段的值。默认level 1表示紧邻的父作用域。在源码实现中entry.js 的 resolveField() 正是围绕这几种情况展开signal分支使用datum[...]动态字段名group/parent分支通过level循环拼接item.mark.group链每层访问父 group再分别落到 group 属性或父 datum 字段datum分支直接映射到当前数据对象字段。这也解释了为什么{group: width}能读取 group 的宽度属性——它被编译为对item.mark.group链上的width属性访问。GradientValue定义一个基于 scale range的线性渐变用于确定fill或stroke编码通道的颜色。若要直接定义渐变而不引用 scale则可将 Gradient 定义赋给编码的value属性。属性类型描述gradientString|FieldValue必填。一个 scale 的名称其 range 是连续颜色方案。startNumber[]渐变的起始坐标为归一化 [0, 1] 坐标系中的 [x, y] 数组。该坐标相对于被着色元素的边界。默认为[0, 0]。stopNumber[]渐变的终止坐标为归一化 [0, 1] 坐标系中的 [x, y] 数组。该坐标相对于被着色元素的边界。默认为[1, 0]即横跨元素完整边界的水平渐变。countNumber从颜色 scale 采样的建议目标采样点数。示例{ encode: { fill: { gradient: colorScale, start: [0, 1], stop: [0, 0], count: 10 } } }解析时entry.js 的 gradient() 函数 会将其编译为运行时表达式gradient(scaleName, start, stop, count)尾部的 null 参数会被裁剪其中gradient属性若为字符串则直接引用 scale 名若为对象则复用 field value 的动态解析逻辑。Schema 端对应 encode.js 中 baseColorValue 的 gradient 分支start/stop被约束为恰好两个数字的数组minItems: 2, maxItems: 2。此外GradientValue 也常被 Vega 内部的 legend 渐变、以及 vega-scenegraph 的 gradient 场景 所使用。TimeMultiFormat时间多格式一个定义日期时间值自定义多格式规格的对象。该对象必须是 timeFormat API 方法 的合法输入对象键必须是合法的时间单位例如year、month等对象值必须是合法的 d3-time-format 格式说明符字符串。这些值将结合未指定单位的默认值用于创建一个动态格式化函数该函数根据输入日期的粒度例如日期落在年、月、日、小时等边界上使用不同的格式。在源码层面packages/vega-format/src/time.js 的timeMultiFormat()完整实现了这一逻辑它按milliseconds、seconds、minutes、hours、date/day、week、month、quarter、year划分粒度每个粒度都有默认格式如.%L、:%S、%I:%M、%I %p、%a %d、%b %d、%B、%Y用户可在 spec 对象中按时间单位键覆盖对应粒度。返回的格式化函数运行时会从最高精度向下探测——例如某日期落在秒边界内就用L格式落在小时边界内就用M格式落在年边界内就用y格式——从而在同一图表中自适应地呈现不同时间粒度的标签。该函数通过timeFormat(spec)传入对象形式而非字符串时被触发time.jsUTC 模式同理使用utcInterval。总结如何选择正确的参数类型静态配置常量、固定颜色、固定 URL→ 使用 Literal ValuesAny/Number/String/Color/URL 等响应式动态值随交互、窗口大小变化→ 使用 Signal 引用或带signal属性的 Value按数据行变化的计算→ 使用 Exprper-datum 求值或 Field视觉编码encode→ 使用 Value 及其子类型 ColorValue、FieldValue、GradientValue按需组合 scale/band/exponent/mult/offset/round排序→ 使用 Compare支持单字段与多字段、升序与降序时间轴标签→ 使用 TimeMultiFormat 提供按粒度自适应的格式。需要校验规范合法性时可直接参考 packages/vega-schema 生成的 JSON Schemadocs/vega-schema.json 为构建产物其中每个类型的约束都能找到对应的定义运行时行为则可在 packages/vega-parser 的 encode 解析代码中逐一印证。赞分享数据可视化【免费下载链接】vegaA visualization grammar.项目地址https://gitcode.com/gh_mirrors/ve/vega点击查看免费下载相关推荐Click 参数类型Parameter Types全解析从内置类型到自定义 ParamTypeClick 参数类型Parameter Types全解析从内置类型到自定义 ParamType 本指南基于 Click 官方文档《Parameter Ty开发工具Flow 官方 React 工具类型Utility Types完整参考指南Flow 官方 React 工具类型Utility Types完整参考指南 Flow 从 react 模块导出一系列内置工具类型用于描述组件内容chil开发工具静态分析代码质量Apache Maven 4 依赖类型Dependency Types与 Legacy Artifact Handlers 完整参考Apache Maven 4 依赖类型Dependency Types与 Legacy Artifact Handlers 完整参考 导读 本文围绕 imp构建工具CLI上一篇ACE-Step UI模型下载加速解决资源获取慢的问题下一篇anomalib 仓库 AI Agent 安全审计指南工具白名单中的 Subshell 展开绕过Vector F创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考