库

概述

通常情况下，您会使用以下三种类型的库与 OJS 一起使用：

Observable 核心库在每个文档中自动可用。
来自 npm 和 ObservableHQ 的第三方 JavaScript 库。
您和/或您的同事创建的自定义库

在本文件中，我们将提供核心库的高层次概述，并展示一些使用第三方库的示例（D3 和 Arquero）。创建您自己的库在关于代码重用的文章中有所介绍。

标准库

Observable 标准库提供了渲染内容和加载代码及数据的核心功能。标准库中一些特别重要的组件包括：

组件	描述
DOM	动态创建 DOM 元素
FileAttachments	读取各种格式的文件
require	从 NPM 和 GitHub 导入第三方模块

您可以在 https://github.com/observablehq/stdlib 找到标准库的完整文档。

Note

Quarto 总是嵌入 ObservableHQ 运行时的特定版本，这意味着 Quarto 可能比 ObservableHQ 网站上的最新版本稍旧。如果您需要使用最新版本的 Plot（或其他核心库），您可以使用 import 函数直接从 CDN 导入最新版本。例如：

Plot = import("https://cdn.jsdelivr.net/npm/@observablehq/plot/+esm")

输入

Observable 输入库提供了可以通过 viewof 关键字绑定到响应式表达式的微件。一些特别有用的输入包括：

组件	描述
Radio	从互斥选项集中选择
Checkbox	从一个列表中选择一个或多个选项
Range	用于连续数值的滑块
Select	下拉选择框
Table	从表格中选择一行或多行

您可以在 https://github.com/observablehq/inputs 找到所有输入的完整文档。

Plot

Observable Plot 是一个用于探索性数据可视化的 JavaScript 库。Plot 构建在一组核心概念（Marks、Scales、Transforms 和 Facets）之上，可以组合在一起创建自定义可视化。

以下是一个使用 Plot 创建的奥运运动员体重直方图的示例：

```{ojs}
athletes = FileAttachment("athletes.csv").csv({typed: true})

Plot.plot({
  grid: true,
  facet: {
    data: athletes,
    y: "sex"
  },
  marks: [
    Plot.rectY(
      athletes, 
      Plot.binX({y: "count"}, {x: "weight", fill: "sex"})
    ),
    Plot.ruleY([0])
  ]
})
```

您可以在 https://github.com/observablehq/plot 找到 Observable Plot 的完整文档。

D3

D3.js 是一个基于数据操作文档的 JavaScript 库。D3 几乎可以创建您能想象到的任何交互式图形！

以下是一个使用 D3 创建的“可缩放旭日图”（最初发布于：https://observablehq.com/@d3/zoomable-sunburst）。每次只显示两个层次的层次结构。点击一个节点以放大，或点击中心以缩小。

sunburst = {
  const root = partition(flareData);

  root.each(d => d.current = d);

  const svg = d3.create("svg")
      .attr("viewBox", [0, 0, width, width])
      .style("font", "15px sans-serif");

  const g = svg.append("g")
      .attr("transform", `translate(${width / 2},${width / 2})`);

  const path = g.append("g")
    .selectAll("path")
    .data(root.descendants().slice(1))
    .join("path")
      .attr("fill", d => { while (d.depth > 1) d = d.parent; return color(d.data.name); })
      .attr("fill-opacity", d => arcVisible(d.current) ? (d.children ? 0.6 : 0.4) : 0)
      .attr("d", d => arc(d.current));

  path.filter(d => d.children)
      .style("cursor", "pointer")
      .on("click", clicked);

  path.append("title")
      .text(d => `${d.ancestors().map(d => d.data.name).reverse().join("/")}\n${format(d.value)}`);

  const label = g.append("g")
      .attr("pointer-events", "none")
      .attr("text-anchor", "middle")
      .style("user-select", "none")
    .selectAll("text")
    .data(root.descendants().slice(1))
    .join("text")
      .attr("dy", "0.35em")
      .attr("fill-opacity", d => +labelVisible(d.current))
      .attr("transform", d => labelTransform(d.current))
      .text(d => d.data.name);

  const parent = g.append("circle")
      .datum(root)
      .attr("r", radius)
      .attr("fill", "none")
      .attr("pointer-events", "all")
      .on("click", clicked);

  function clicked(event, p) {
    parent.datum(p.parent || root);

    root.each(d => d.target = {
      x0: Math.max(0, Math.min(1, (d.x0 - p.x0) / (p.x1 - p.x0))) * 2 * Math.PI,
      x1: Math.max(0, Math.min(1, (d.x1 - p.x0) / (p.x1 - p.x0))) * 2 * Math.PI,
      y0: Math.max(0, d.y0 - p.depth),
      y1: Math.max(0, d.y1 - p.depth)
    });

    const t = g.transition().duration(750);

    // 对所有弧形的数据进行过渡，即使是那些不可见的，
    // 以便如果此过渡被中断，进入的弧形将从所需位置开始下一次过渡。
    path.transition(t)
        .tween("data", d => {
          const i = d3.interpolate(d.current, d.target);
          return t => d.current = i(t);
        })
      .filter(function(d) {
        return +this.getAttribute("fill-opacity") || arcVisible(d.target);
      })
        .attr("fill-opacity", d => arcVisible(d.target) ? (d.children ? 0.6 : 0.4) : 0)
        .attrTween("d", d => () => arc(d.current));

    label.filter(function(d) {
        return +this.getAttribute("fill-opacity") || labelVisible(d.target);
      }).transition(t)
        .attr("fill-opacity", d => +labelVisible(d.target))
        .attrTween("transform", d => () => labelTransform(d.current));
  }
  
  function arcVisible(d) {
    return d.y1 <= 3 && d.y0 >= 1 && d.x1 > d.x0;
  }

  function labelVisible(d) {
    return d.y1 <= 3 && d.y0 >= 1 && (d.y1 - d.y0) * (d.x1 - d.x0) > 0.03;
  }

  function labelTransform(d) {
    const x = (d.x0 + d.x1) / 2 * 180 / Math.PI;
    const y = (d.y0 + d.y1) / 2 * radius;
    return `rotate(${x - 90}) translate(${y},0) rotate(${x < 180 ? 0 : 180})`;
  }

  return svg.node();
}

要在 {ojs} 单元格中使用 D3，首先使用 require 函数导入它（该函数加载托管在 jsDelivr 上的模块）：

```{ojs}
d3 = require("d3@7")
```

然后，根据需要使用 d3 来创建你的可视化。例如，以下是创建上述可视化的单元格的前几行代码：

```{ojs}
sunburst = {
  const root = partition(flareData);
  root.each(d => d.current = d);
  const svg = d3.create("svg")
      .attr("viewBox", [0, 0, width, width])
      .style("font", "15px sans-serif");

  // ...剩余的实现部分
  
  return svg.node();
}
```

查看 Sunburst 示例以获取完整的源代码。要了解更多关于 D3 的信息，请访问 https://d3js.org/。

Arquero

Arquero 是一个用于查询处理和数组支持的数据表转换的 JavaScript 库。遵循关系代数并受 dplyr 设计启发，Arquero 提供了一个流畅的 API 来操作面向列的数据框。

在这里，我们将导入 Arquero (aq) 和一个 Arquero 操作的别名 (op)，读取一个数据集，然后过滤、聚合并查看数据：

```{ojs}
import { aq, op } from '@uwdata/arquero'
penguins = aq.loadCSV("palmer-penguins.csv")
penguins
  .groupby('species')
  .filter(p => p.body_mass_g > 0)
  .rollup({
    count: op.count(),
    avg_mass: op.average('body_mass_g')
   })
  .view()
```

查看 Arquero 示例以获取完整的源代码。要了解更多关于使用 Arquero 的信息，请参阅 Introducing Arquero 教程。

模块

NPM

标准库中的 require 函数可以用来导入 npm 模块（这些模块由 jsDelivr CDN 提供服务）：

```{ojs}
d3 = require("d3")
topojson = require("topojson")
```

模块可以选择性地包含一个带有版本的 @ 符号。例如：

```{ojs}
d3 = require("d3@7")
```

查看 jsDelivr 文档以获取更多详细信息。请注意，require 函数在解析导入时会自动添加前缀 https://cdn.jsdelivr.net/npm/，因此当 jsDelivr 文档提到使用此 URL 时：

https://cdn.jsdelivr.net/npm/package@version/file

你只需将此传递给 require：

package@version/file

ObservableHQ

发布在 http://observablehq.com 上的笔记本也可以编译并下载为 JavaScript 模块。

虽然笔记本通常有自己的嵌入式数据集，但当你导入它们时，实际上可以用你自己的数据替换这些数据！回到上面的旭日图示例，这里我们 import 一个笔记本，并使用 with 关键字为 data 提供我们自己的值：

```{ojs}
pdata = FileAttachment("population.json").json()
import { chart } with { pdata as data } from "@d3/zoomable-sunburst"
chart
```

需要注意的一个重要限制是，并非所有发布在 ObservableHQ 上的笔记本都具有开源许可证。笔记本需要明确标记许可证，以表明可以在 ObservableHQ 之外使用它们。

你可以在笔记本的标题区域查看其许可证。例如，此笔记本带有 ISC 许可证：

在导入 ObservableHQ 笔记本之前，你应该检查其许可证。查看笔记本许可证的文档以获取有关如何执行此操作的更多详细信息。

```{ojs}
flareData = FileAttachment("examples/flare-2.json").json()
```

```{ojs}
partition = flareData => {
  const root = d3.hierarchy(flareData)
      .sum(d => d.value)
      .sort((a, b) => b.value - a.value);
  return d3.partition()
      .size([2 * Math.PI, root.height + 1])
    (root);
}
```

```{ojs}
color = d3.scaleOrdinal(d3.quantize(d3.interpolateRainbow, flareData.children.length + 1))
```

```{ojs}
format = d3.format(",d")
```

```{ojs}
width = 932
```

```{ojs}
radius = width / 6
```

```{ojs}
arc = d3.arc()
    .startAngle(d => d.x0)
    .endAngle(d => d.x1)
    .padAngle(d => Math.min((d.x1 - d.x0) / 2, 0.005))
    .padRadius(radius * 1.5)
    .innerRadius(d => d.y0 * radius)
    .outerRadius(d => Math.max(d.y0 * radius, d.y1 * radius - 1))
```

```{ojs}
d3 = require("d3@7")
```

概述

标准库

输入

Plot

D3

Arquero

模块

NPM

ObservableHQ

附录