vega-util

Vega 的 JavaScript 实用程序。提供一组在整个 Vega 模块中使用的辅助方法，包括函数生成器、类型检查器、日志消息以及用于对象、数组和字符串值的附加实用程序。

API 参考

• 职能
• 类型检查器
• 类型强制
• 对象
• 数组
• 日期
• 日志记录
• 错误

职能

用于访问和比较值的函数和函数生成器。

#
维加。访问器（函数[，字段，名称]）
<>

用依赖数据字段的字符串数组和字符串名称注释函数实例，并返回输入函数。假设输入函数接受一个对象（数据元组）作为输入，字段数组中的字符串对应于函数访问的对象属性。一旦被注释，如果函数用作访问器，Vega 数据流可以跟踪数据字段依赖性并生成适当的输出名称（例如，在计算聚合时）。

在内部，此方法将字段数组分配给fields输入函数的属性，并将名称分配给fname属性。为了面向未来，客户端不应直接访问这些属性。相反，使用accessorFields和accessorName方法。

#
维加。访问器字段（访问器）
<>

返回给定访问器函数的依赖字段名称数组。如果未设置字段名称，则返回 null。

#
维加。访问者名称（访问者）
<>

返回给定访问器函数的名称字符串。如果未设置名称，则返回 null。

#
维加。升序( a , b )
<>

用于按升序对原始值和日期值进行排序的比较器函数。

#
维加。比较（字段[，订单]）
<>

根据给定的字段集和可选的排序顺序生成用于对数据值进行排序的比较器函数。的字段参数必须是一个字符串，一个访问器功能，或二者之一的一个阵列。字符串按优先顺序指示要作为排序依据的对象属性的名称。字段字符串可能包括嵌套的属性（例如，foo.bar.baz）。所述订单参数必须是一个字符串或字符串的阵列; 有效的字符串值为'ascending'（对应字段的升序）或'descending'（对应字段的降序）。如果订单参数被省略，比字段数组短，或者包含除 'ascending'或'descending'，对应字段将默认为升序。

#
维加。常量（值）
<>

给定一个输入值，返回一个简单返回该值的函数。如果输入值本身是一个函数，则直接返回该函数。

#
维加。去抖动（延迟，函数）
<>

生成一个“debounced”函数，该函数将调用func延迟到自上次调用 debounced 函数以来经过延迟毫秒之后。调用最多将一个参数从去抖动函数传递给func并且不保留this上下文。

#
维加。字段（字段[，名称]）
<>

生成用于检索指定字段值的访问器函数。输入字段字符串可以包括嵌套属性（例如，foo.bar.baz）。一个可选的名称参数表示生成函数的访问器名称；如果排除，则字段字符串将用作名称（有关更多详细信息，请参阅访问器方法）。

var fooField = vega.field('foo');
fooField({foo: 5}); // 5
vega.accessorName(fooField); // 'foo'
vega.accessorFields(fooField); // ['foo']

var pathField = vega.field('foo.bar', 'path');
pathField({foo: {bar: 'vega'}}); // 'vega'
pathField({foo: 5}); // undefined
vega.accessorName(pathField); // 'path'
vega.accessorFields(pathField); // ['foo.bar']

#
维加。id（对象）
<>

一个访问器函数，它返回id输入对象的属性值。

#
维加。身份（值）
<>

一个简单地返回其值参数的访问器函数。

#
维加。键（字段[，平面]）
<>

生成一个访问器函数，该函数返回一组对象字段的键字符串（适合用作对象属性名称）。的字段参数必须是字符串或字符串数组，其中每个条目指示将被用来产生代表键值的输入对象的属性。生成的键函数是一个具有访问器名称的访问器实例'key'。可选的flat参数是一个布尔标志，指示是否应将字段名称视为平面属性名称，通常由点或括号表示法指示的侧步嵌套字段查找。默认情况下，平坦的是false并进行嵌套属性查找。

var keyf = vega.key(['foo', 'bar']);
keyf({foo:'hi', bar:5}); // 'hi|5'
vega.accessorName(keyf); // 'key'
vega.accessorFields(keyf); // ['foo', 'bar']

#
维加。一()
<>

一个简单地返回值一 ( 1)的访问器函数。

#
维加。零()
<>

一个简单地返回值零 ( 0)的访问器函数。

#
维加。真实()
<>

一个简单地返回布尔true值的访问器函数。

#
维加。假()
<>

一个简单地返回布尔false值的访问器函数。

类型检查器

用于检查 JavaScript 值类型的函数。

#
维加。isArray (值)
<>

true如果输入值是 Array 实例，false则返回，否则返回。

#
维加。isBoolean (值)
<>

true如果输入值是布尔实例，false则返回，否则返回。

#
维加。isDate (值)
<>

true如果输入值是 Date 实例，false则返回，否则返回。

#
维加。isFunction (值)
<>

true如果输入值是 Function 实例，false则返回，否则返回。

#
维加。isIterable (值)
<>

true如果输入值支持可迭代协议，false则返回，否则返回。

#
维加。isNumber (值)
<>

true如果输入值是 Number 实例，false则返回，否则返回。

#
维加。isObject (值)
<>

true如果输入值是 Object 实例，false则返回，否则返回。

#
维加。isRegExp (值)
<>

true如果输入值是 RegExp 实例，false则返回，否则返回。

#
维加。isString (值)
<>

true如果输入值是 String 实例，false则返回，否则返回。

类型强制

将值强制为所需类型的函数。

#
维加。toBoolean (值)
<>

将输入值强制为布尔值。字符串"true"和"1"映射到true; 字符串"false"并"0"映射到false. 空值和空字符串映射到null.

#
维加。toDate ( value [, parser ])
<>

将输入值强制为日期时间戳。空值和空字符串映射到null. 日期对象不变地通过。如果提供了可选的解析器函数，则用于执行日期解析。默认情况下，数字（时间戳）不变地通过，否则Date.parse使用。请注意，Date.parse跨浏览器有不同的实现！

#
维加。toNumber (值)
<>

将输入值强制转换为数字。空值和空字符串映射到null.

#
维加。toString (值)
<>

将输入值强制为字符串。空值和空字符串映射到null.

对象

用于操作 JavaScript 对象值的函数。

#
维加。扩展（目标[，源1，源2，…]）
<>

通过复制（按顺序）输入源对象的所有可枚举属性来扩展目标对象。

#
维加。继承（孩子，父母[，成员]）
<>

一种设置面向对象继承的便捷方法。分配prototype输入的属性子功能，使得孩子继承的财产父通过原型继承函数的原型。可选的members参数是一个包含要添加到新子原型的方法或属性的对象。返回新的子原型对象。

#
维加。lruCache ([ maxsize ])
<>

提供以字符串为键的键/值缓存，用于逐出最近最少使用 (LRU) 条目。支持has、get、set和clear方法。可选的maxsize参数（默认为 10,000）确定在项目被驱逐之前可以添加的最大元素数。

在内部实现中使用了两个缓存：当前缓存和先前缓存。当当前缓存填满时，它成为以前的缓存并创建一个新的、空的当前缓存。后续的get调用会将先前缓存中的元素提升到当前缓存。当前缓存填满后，缓存将再次翻转，所有仍驻留在前一个缓存中的 LRU 项都将被删除。

var cache = vega.lruCache(1); // use 1-element cache to demonstrate
cache.set('a', 1); // current cache has a->1
cache.set('b', 2); // current cache has b->2, previous cache has a->1
cache.get('a');    // -> 1 (a now in current cache, b in previous cache)
cache.set('c', 3); // current cache has c->3, previous cache has a->1
cache.has('c');    // -> true  (c is in the current cache)
cache.has('b');    // -> false (b has been evicted)
cache.has('a');    // -> true  (a is in the previous cache)
cache.get('c');    // -> 3
cache.clear();

#
维加。fastmap ([对象])
<>

提供以字符串为键的键/值映射数据结构。支持ES6 Map API 的一个子集，包括has、get、set、delete和clear方法以及一个size属性。如果提供了可选的对象参数，则输入对象上的所有键/值都将添加到新的地图实例中。

var map = vega.fastmap({foo:1, bar:2});
map.has('foo'); // -> true
map.get('foo'); // -> 1
map.delete('bar');
map.has('bar'); // -> false
map.set('baz', 0);
map.get('baz'); // -> 0
map.size; // -> 2
map.empty; // -> 1 (number of empty entries)
map.clean(); // invoke garbage collection, clears empty entries

通过使用基本的 JavaScript 对象来散列值并避免调用内置的 JavaScriptdelete运算符，fastmaps 提供了良好的性能。然而，这种速度是以一些对象膨胀为代价的，在多次删除的情况下需要定期进行垃圾收集。fastmap 对象为请求对空映射条目进行垃圾收集提供了一种干净的方法。该测试方法是用于提供应垃圾收集过程中除去一个可选的布尔值函数，其指示其他对象（从删除的键不只是空条目）的吸气剂/调节器。

#
维加。hasOwnProperty（对象，属性）
<>

返回true如果输入对象有一个名为性质上定义，否则false。此方法仅涉及输入对象，忽略在原型链上定义的属性。该方法等效于Object.hasOwnProperty，但通过防止重写的 Object 原型内置函数来提高安全性。

#
维加。mergeConfig ( …config )
<>

将 Vega 配置对象的集合合并为单个组合对象。参数列表中索引位置较高的配置对象具有较高的优先级，因此可能会覆盖较早对象提供的设置。

#
维加。writeConfig ( config , key , value [, recurse ])
<>

将值写入 Vega 配置对象。给定一个配置对象和一个配置属性key和value，适当地将值分配给配置对象。该递归如果递归合并（而不是重写）进行参数控制：如果false或未定义，不进行递归; 如果true执行一级递归合并；如果递归是对象值的，则对递归对象映射到真值的键执行一级递归合并。此方法是在mergeConfig 中使用的辅助方法。

数组

用于操作 JavaScript 数组值的函数。

#
维加。数组（值）
<>

确保输入值是一个 Array 实例。如果是，则简单地返回该值。如果不是，则该值包含在一个新的单元素数组中，返回[value].

#
维加。钳位范围（范围，最小值，最大值）
<>

跨度保持范围夹。如果输入范围的跨度小于 ( max – min ) 并且端点超过最小值或最大值，则转换范围以保留跨度并且一个端点接触最小/最大范围的边界。如果跨度超过 ( max – min )，则返回范围[min, max]。

#
维加。范围（数组[，访问器]）
<>

返回与输入的最小值和最大值的阵列排列，在形式[min, max]。忽略 null、undefined 和 NaN 值。可选的访问器参数提供了一个函数，该函数在比较之前首先应用于每个数组值。

#
维加。范围索引（数组[，访问器]）
<>

根据自然顺序返回输入数组（作为[minIndex, maxIndex]数组）中最小值和最大值的数组索引。可选的访问器参数提供了一个函数，该函数在比较之前首先应用于每个数组值。

vega.extentIndex([1,5,3,0,4,2]); // [3, 1]
vega.extentIndex([
  {a: 3, b:2},
  {a: 2, b:1},
  {a: 1, b:3}
], vega.field('b')); // [1, 2]

#
维加。齐平（范围、值、阈值、左、右、中心）
<>

如果提供的值与输入数字范围齐平，则在潜在的返回值中进行选择。如果 *value在range的最小元素的阈值距离内，则返回left。返回右如果*值是内阈值的的最大元素的距离范围。否则，返回center。

#
维加。INRANGE（值，范围[，左，右]）
<>

返回true输入值是否在给定范围数组的范围内。在左和右布尔标志控制使用含（真）或排他性（假）的比较; 如果未指定，则使用包容性测试。

#
维加。lerp（数组，分数）
<>

返回数组中第一个和最后一个条目之间的线性内插值，用于提供的内插分数（通常在 0 和 1 之间）。例如，lerp([0, 50], 0.5)返回 25。

#
维加。合并（比较，ARRAY1，数组2 [，输出]）
<>

将两个已排序的数组合并为一个已排序的数组。输入比较函数是对元素进行排序的比较器，应该对应array1和array2源数组的预排序顺序。合并的数组内容将写入输出数组（如果提供）。如果未指定输出，则生成并返回一个新数组。

#
维加。panLinear ( domain , delta )
<>

给定一个输入数值域（按升序排序），返回一个新的域数组，该数组使用线性变换将域转换为增量。的增量值表示为当前域跨度的一小部分，并且可以是正的或负指示平移方向。返回值是一个二元素数组，指示翻译（平移）域的起始值和结束值。

#
维加。panLog ( domain , delta )
<>

给定一个输入数值域（按升序排序），返回一个新的域数组，该数组使用对数变换将域转换为增量。的增量值表示为当前域跨度的一小部分，并且可以是正的或负指示平移方向。返回值是一个二元素数组，指示翻译（平移）域的起始值和结束值。

#
维加。panPow ( domain , delta , exponent )
<>

给定一个输入数值域（按升序排序），返回一个新的域数组，该数组使用由提供的exponent参数化的幂标度变换将域转换为增量。的增量值表示为当前域跨度的一小部分，并且可以是正的或负指示平移方向。返回值是一个二元素数组，指示翻译（平移）域的起始值和结束值。

#
维加。panSymlog ( domain , delta , constant )
<>

给定一个输入数值域（按升序排序），返回一个新的域数组，该数组使用由提供的常量参数化的符号对数（对称对数）比例变换将域转换为增量。的增量值表示为当前域跨度的一小部分，并且可以是正的或负指示平移方向。返回值是一个二元素数组，指示翻译（平移）域的起始值和结束值。

#
维加。窥视（数组）
<>

返回输入数组中的最后一个元素。类似于内置Array.pop方法，只是它不删除最后一个元素。此方法是 的方便简写array[array.length - 1]。

#
维加。跨度（数组）
<>

返回输入数组的数值范围：最后一个值和第一个值之间的差值。

#
维加。toSet（数组）
<>

给定一个输入值数组，返回一个新的 Object 实例，其属性键是array中的值，每个值都分配了一个属性值1。数组中的每个值都被强制转换为一个字符串值，因此应该映射到一个合理的字符串键值。

vega.toSet([1, 2, 3]); // {'1':1, '2':1, '3':1}

#
维加。访问数组（数组，[过滤器，]访问者）
<>

Vists在输入值阵列，调用访客对于经过一个可选的每个数组值函数滤波器。如果指定，则使用每个单独的数组值调用过滤器函数。如果过滤器函数的返回值为真，则返回值将作为输入传递给访问者函数。因此，过滤器不仅执行过滤，还可以充当值转换器。如果未指定过滤器函数，则数组中的所有值都将传递给访问者函数。类似于内置Array.forEach方法，访问者函数被调用与三个参数：值到访问，当前索引到源阵列，并以索里的参考阵列。

// console output: 1 0; 3 2
vega.visitArray([0, -1, 2],
  function(x) { return x + 1; },
  function(v, i, array) { console.log(v, i); });

#
维加。zoomLinear ( domain , anchor , scale )
<>

给定一个输入数字域（按升序排序），返回一个新的域数组，该数组使用线性变换按比例因子缩放（缩放）域，以给定的锚值为中心。如果锚是null，则使用域的中点。返回值是一个二元素数组，指示缩放（缩放）域的起始值和结束值。

#
维加。zoomLog ( domain , anchor , scale )
<>

给定一个输入数字域（按升序排序），返回一个新的域数组，该数组使用对数变换按比例因子缩放（缩放）域，以给定的锚值为中心。如果锚是null，则使用域的中点。返回值是一个二元素数组，指示缩放（缩放）域的起始值和结束值。

#
维加。zoomPow ( domain , anchor , scale , exponent )
<>

给定一个输入数值域（按升序排序），返回一个新的域数组，该数组使用由提供的exponent参数化的幂比例变换按比例因子缩放（缩放）域，以给定的锚值为中心。如果锚是，则使用域的中点。返回值是一个二元素数组，指示缩放（缩放）域的起始值和结束值。null

#
维加。zoomSymlog ( domain , anchor , scale , constant )
<>

给定一个输入数字域（按升序排序），返回一个新的域数组，该数组使用由提供的常量参数化的符号对数（对称对数）比例变换按比例因子缩放（缩放）域，以给定的锚值为中心。如果锚是，则使用域的中点。返回值是一个二元素数组，指示缩放（缩放）域的起始值和结束值。null

日期

用于操作 JavaScript 日期值的函数。

#
维加。季度（日期）
<>

为本地时区的输入日期对象或时间戳返回一年中的季度（1 到 4 之间的整数）。

#
维加。UTC季度（日期）
<>

为输入日期对象或协调世界时 (UTC) 的时间戳返回一年中的季度（1 到 4 之间的整数）。

字符串

用于生成和操作 JavaScript 字符串值的函数。

#
维加。填充（字符串，长度[，字符，对齐]）
<>

用一个字符的重复实例填充一个字符串值，直到指定的长度。如果未指定字符，则使用空格 ( )。默认情况下，填充添加到字符串的末尾。可选的align参数指定是否应将填充添加到输入字符串的（开始）、 或（结束）。' ''left''center''right'

vega.pad('15', 5, '0', 'left'); // '00015'

#
维加。重复（字符串，计数）
<>

给定一个输入字符串，返回一个重复输入计数次数的新字符串。

vega.repeat('0', 5); // '00000'

#
维加。splitAccessPath (路径)
<>

将表示JavaScript 对象属性的访问路径的输入字符串拆分为组成路径元素的数组。

vega.splitAccessPath('foo'); // ['foo']
vega.splitAccessPath('foo.bar'); // ['foo', 'bar']
vega.splitAccessPath('foo["bar"]'); // ['foo', 'bar']
vega.splitAccessPath('foo[0].bar'); // ['foo', '0', 'bar']

#
维加。字符串值（值）
<>

返回符合 JSON 和 JavaScript 的输入值的输出表示。对于 Object 和 String 值，JSON.stringify用于生成输出字符串。Number 或 Boolean 等原始类型按原样返回。此方法可用于生成值，然后可以将这些值包含在运行时编译的代码片段中（例如，通过 Function 构造函数）。

#
维加。截断（字符串，长度[，对齐，省略号]）
<>

将输入字符串截断为目标长度。可选的align参数指示应截断字符串的哪一部分：（'left'开头）'center'、 或'right'（结尾）。默认情况下，'right'字符串的结尾被截断。可选的省略号参数指示用于指示截断内容的字符串；默认情况下使用省略号字符（…，与 相同\u2026）。

日志记录

#
维加。记录器（[级别，方法，处理程序]）
<>

生成一个新的记录器实例，用于有选择地将日志消息写入 JavaScript 控制台。可选的level参数指示要使用的初始日志级别（None、Error、Warn、Info或Debug 之一），如果未指定，则默认为None。

生成的记录器实例提供以下方法：

• level ( value )：设置当前的日志记录级别。只有日志级别小于或等于value 的消息才会写入控制台。
• 误差（MESSAGE1 [，消息2，…]）：记录错误消息。console.error如果当前日志级别为Error或更高，消息将使用该方法写入控制台。
• 警告（MESSAGE1 [，消息2，…]）：记录的警告消息。console.warn如果当前日志级别为Warn或更高，消息将使用该方法写入控制台。
• 信息（MESSAGE1 [，消息2，…]）：日志信息性消息。console.log如果当前日志级别为Info或更高，消息将使用该方法写入控制台。
• 调试（MESSAGE1 [，消息2，…]）：记录一个调试消息。console.log如果当前日志级别为Debug或更高，消息将使用该方法写入控制台。

要覆盖控制台方法的选择调用（console.log，console.warn，或console.error），使用可选的方法参数（中的一个"log"，"warn"或"error"通过相同的方法）来路由所有日志消息。

为记录提供自定义的处理函数，使用可选的处理程序参数提供三个参数的函数：方法字符串（之一"log"，"warn"或"error"），日志级别，和值记录的数组。

#
维加。无
<>

指示“无”日志级别的常量值。如果设置为记录器实例的日志级别，则所有日志消息都将被抑制。

#
维加。错误
<>

指示“错误”日志级别的常量值。如果设置为记录器实例的日志级别，则只会显示错误消息。

#
维加。警告
<>

指示“警告”日志级别的常量值。如果设置为记录器实例的日志级别，则会显示错误和警告消息。

#
维加。信息
<>

指示“信息”日志级别的常量值。如果设置为记录器实例的日志级别，将显示错误、警告和信息消息。

#
维加。调试
<>

指示“调试”日志级别的常量值。如果设置为记录器实例的日志级别，将显示所有日志消息（错误、警告、信息和调试）。

错误

#
维加。错误（消息）
<>

使用提供的错误消息引发新错误。这是一种方便的方法，为错误处理添加了一个间接层，例如允许将错误条件包含在表达式链中。

vega.error('Uh oh'); // equivalent to: throw Error('Uh oh')

// embed error in an expression
return isOk ? returnValue : vega.error('Not OK');