# @flourish/info-popup 中文文档

规范地址：https://npmcn.com/package/%40flourish/info-popup/

版本：8\.3\.3
npm 元数据更新时间：2026-09-01T12:49:50.462Z
中文译文更新时间：2026-11-15T00:15:46.902Z
软件包许可：LicenseRef-LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flourish/info-popup
原文对照：https://npmcn.com/package/%40flourish/info-popup/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：425 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：9 个
- 首次发布：2020-07-29T15:35:18.106Z
- 最新版本发布：2026-09-01T12:49:50.263Z
- 近 30 天下载量：4142（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 4 个）

## 中文简介

用数据插入弹出

## 安装

```sh
npm install @flourish/info-popup
```

也可以使用：`pnpm add @flourish/info-popup`、`yarn add @flourish/info-popup`、`bun add @flourish/info-popup`

## README

# 面粉信息弹出

将由数据驱动的弹出(tooltips)和面板添加到任何面粉模板中,带有样式设置.

使用该模块通常有七个步骤:

### 1\. 安装

```
npm install @flourish/info-popup
```

### 2 - 为模块添加状态属性, 以对象为值

```javascript
const state = {
    popup: {} // Add any properties to this object to override the default settings
}
```

### 3 - 将设置导入到您的 `template.yml` 文件

```yaml
  - Popups & panels
  - property: popup
    import: "@flourish/info-popup"
```

### 4 - 弹出初始化

初始化弹出, 在国有属性和可选的容器中通过, 决定弹出和面板的位置

```javascript
import initialisePopup from "@flourish/info-popup";

const popup = initialisePopup(state.popup, panel_container, popup_container);
```

如果您想要面板填充整页( 即覆盖页眉和页脚), 请忽略 `panel_container` 财务报告和审定财务报表 `popup_container` 参数.

### 5 - 数据附加基于事件的方法

**与本模块理解的重要内容是,模板传递用户触发事件的信息(如点击,鼠标over等),然后由模块决定该事件的结果.** 这是因为根据所选择的设置,弹出和面板对用户事件的反应有多种不同的方式. 举例来说,这里有一些不同的设想情景 `mouseover` 事件:

-   在弹出模式下:弹出在数据点上显示
-   在弹出模式下, 有粘滞内容: 无所事事
-   在面板模式下时:无所事事
-   当小组模式下, `Always show` 打开: 面板中的内容负荷
-   当小组模式下, `Always show` 打开,内容粘稠:什么都没有发生
-   当两个模式中:带有预览内容的弹出在数据点上显示时

因此为了一致性,这个逻辑是从模板中抽象出来的. 这就是为什么没有办法 行动,例如打开弹出,因为我们叫 `popup.mouseover()` 并且让模块查看所有不同的设置,并决定该事件的结果.

列出所有基于事件的方法 [下级](https://npmcn.com/package/%40flourish/info-popup/#readme-methods) 在方法一节中,但共同执行将看起来是这样的:

```javascript
import { popup } from "./popup";

function updateGraphic() {
    d3.selectAll(...) // datapoints
        .on("mouseover", function() {
            const el = this;
            popup.mouseover(el, el.__data__);
        })
        .on("mouseout", function() {
            popup.mouseout();
        })
        .on("click", function() {
            const el = this;
            const data = el.__data__
            const locked_id = data.id
            popup.click(el, data, locked_id); // See step 8 for more information on locked_id
        });
}
```

### 6 - 确保弹出显示正确、格式化的数据 `.setColumnNames()` 财务报告和审定财务报表 `.setFormatters()`

对于每次弹出,我们想要确保我们显示正确的标签和数据格式化值. 这项工作有两个部分:

#### 第一部分 - 数据传递

数据传送到 `popup.click`, (中文(简体) ), `popup.mouseover` 或者说 `popup.touch`。您通过与您交互的节点相连的数据。 如果您有下列数据绑定: `binding_one`, (中文(简体) ),`binding_two`, (中文(简体) ), `binding_three` 财务报告和审定财务报表 `binding_four` 每个数据点的数据(以及您将传递到弹出模块的数据)将看起来像这样:

```javascript
{
    binding_one: "Joe Biden",
    binding_two: "President",
    binding_three: "https://public.flourish.studio/uploads/ff3f9984-470c-4ed9-beb8-2a86bb7019ea.jpg",
    binding_four: "Democrat"
}
```

#### 编 二 - 设置列名

目前弹出已被传递了一组与数据绑定相关的数值,我们现在必须为我们希望在弹出中出现的每个绑定数据设置一列名称:

```javascript
popup
    .setColumnNames({
        binding_one: "Name",
        binding_two: "Job title",
        binding_four: "Party"
    })
    .update()
```

**数据只有在我们为数据绑定设置了列名时才会显示 .** 我们没有为 `binding_three` 因此在弹出时显示的信息将是:

```
Name: Joe Biden
Job title: President
Party: Democrat
```

如果没有任何柱子你想排除,你可以通过 `column_names` 来自面粉数据集的对象 :

```javascript
popup
    .setColumnNames(data.data.column_names)
    .update()
```

如果有列您想要用于自定义内容, 但不希望在默认弹出内容或面板内容中显示( 如长序列数据), 您可以将其排除在外 `.hideColumnNames()`。这需要一系列具有约束力的名称。 在上述例子中 `.hideColumnNames(["binding_four"])` 将不会在默认弹出或面板中显示缔约方信息.

#### 编 三 -- 设置格式

可选的,也可以为每个数据绑定设置格式. 这些必须匹配所传递的数据 `.setColumnNames()` 但是,你不需要为装订物提供垫子.

格式化有两种形式:

-   函数带值并返回字符串。 任意格式化器由 `initNumberFormatter` 内 [@flourish/格式化器](https://github.com/kiln/flourish-formatters) 设置面板中格式化的更改应在弹出中反映出来.
-   含有 `output_format_id` \[@flourish/interpreter\] 模块中使用的字符串属性 。 这是传递给 [@flourish/格式化器](https://github.com/kiln/flourish-formatters) 生成 formatter 函数.

对于多列绑定,您可以通过一个格式化阵列(其中每个格式是一个函数或包含 `output_format_id`) (中文(简体) ).

```javascript
popup
    .setColumnNames({
        binding_one: "Name",
        binding_two: "Cost",
        binding_three: "Sold", 
        binding_four: "Released"
    })
    .setFormatters({
        binding_two: d => `£${d}`,
        binding_three: { output_format_id: "number$comma_point" } 
        binding_four: { output_format_id: "datetime$%d/%m/%Y" },
    })
    .update()
```

如果以下数据被传送到弹出点:

```javascript
{
    binding_one: "Pain au chocolat",
    binding_two: 2,
    binding_three: 1235000,
    binding_four: new Date("2022-05-12T03:24:00")
}
```

由此产生的信息将在弹出中显示:

```
Name: Pain au chocolat
Cost: £2
Sold: 1,235,000
Released: 05/12/2022
```

如果您不想通过任何自定义的事务函数, 您可以通过通过 `metadata` 用于数据集的对象。 此对象包括带有 `output_format_id` 每个绑定的字符串属性(这些可以由用户在数据面板中设置).

```javascript
popup
    .setColumnNames(data.data.column_names)
    .setFormatters(data.data.metadata)
    .update()
```

### 7 - 更新弹出 `.update()`

为了确保弹出是使用最新的设置,根据通过 `.setColumnNames()`我们需要打电话 `popup.update()` 模板内 `update()` 循环.

### 8 - 设置锁定功能( 可选)

被锁定的功能是在开放状态下"锁定"弹出的能力. 锁定的弹出会一直打开直到 `clickout` 被触发,在锁定时,它会启用 CSS 指针事件,以便端取景器可以例如点击弹出内的一个链接.

要设置锁定功能, 您需要定义 `getLockedPosition` 函数。 如果有一个被锁定的弹出功能,此功能会重新调整被锁定项目的被锁定节点或协调信息,以及与之相关的数据. 它返回一个数组 : `[node_or_coordinate, data]`

此功能只需在弹出状态关闭后直接调用一次即可,但也可以作为更新功能的一部分调用.

```javascript
popup.getLockedPosition(getLockedPositionCallback)

function getLockedPositionCallback(locked_id) {
    // get the node that relates to this id (this is just one common way you might do this)
    const el_node = select(`#${locked_id}`).node();

    // if there is no locked popup, or there is currently no element on the screen
    // corresponding to the stored locked popup return null
    if (!el_node) return null;

    // get the data from that node
    const datum = el_node && el_node.__data__;

    // return node and data
    return [el_node, datum];
}
```

## 方法

### 基于事件的方法

-   `popup.click(coords_or_node, data, locked_id, callback)` 查看器点击数据点时使用 . `coords_or_node` 可以是坐标数组(\[x,y\])或DOM元素. `data` 是要显示的数据(通常是您正在点击的元素所附带的数据). `locked_id` 是被点击的数据点的标识符。 若为 `locked_id` 未定义它不会被锁定, 如果它被定义, 数值将被存储为已锁定的 id并传递到 `getLockedPositionCallback` 函数.
    
-   `popup.mouseover(coords_or_node, data, callback)` 查看器鼠标覆盖一个数据点时使用 。 (注:这不代表 `locked_id` 参数,因为你永远无法通过在数据点上摩擦来锁定弹出。)
    
-   `popup.touch(coords_or_node, data, locked_id, callback)` 当取景器在触摸设备上并触及到数据点时使用. 它与鼠标翻转具有相同的行为,除了在"Both"模式中,它可以一次触摸来打开弹出,再触碰弹出来打开面板. (因此它需要锁定的 id参数,因为第二次触摸会锁住面板。)
    
-   `popup.mouseout()` 查看器鼠标离开数据点时使用. 它关闭或重置弹出或面板,除非它被锁定.
    
-   `popup.clickout()` 当查看器点击不属于数据点的物体时使用. 它如果被锁定会关闭弹出;通常在点击处理器中用于背景(例如SVG或画布元素). **注:这种方法可以使代码看起来相当反直观,例如:**
    
    ```javascript
          document.body.onclick = function() { popups.clickout(); };
    ```
    
    这是因为你对浏览器 **单击** 但对于弹出你 **点击出** (因为你正在点击一些不是数据点的东西).
    

### 设置标题和字幕

可以指定数据中的某些密钥代表弹出或面板的标题和字幕. 这些出现在弹出片头部分,与弹出片后的其他部分风格不同.

-   `popup.titleKey(data_binding_name)`
-   `popup.subtitleKey(data_binding_name)`

### 指定默认模板

您可以为弹出或面板内容指定不同的模板, 例如, 如果您想要添加一个 `<img>` 标记或内容需要以特定的顺序显示。 初始化时进行:

-   `popup.popupDefaultTemplate(template_string)`
-   `popup.panelDefaultTemplate(template_string)`

这个 `template_string` 可包含卷括号之间的数据绑定键,例如 `<h1>{{name}}</h1>` 地点 `name` 您的数据绑定 .

### 定位方法

-   `popup.popupDirections(directions)` - 获得或设置弹出方向.
-   `popup.margins()` – 获得可视化边缘上的空间用于面板. 这在您不希望面板覆盖内容时有用 .

### 隐藏方法

-   `popup.hidePopup()` 将隐藏弹出而不重置 `locked_id`。 。 。 .
-   `popup.hidePanel()` 将隐藏面板而不重置 `locked_id`。 。 。 .

### 获取方法

-   `popup.locked()` - 获得当前 `locked_id` 从弹出状态。 回返 `null` 如果当前没有弹出“ 已锁定” 打开.
-   `popup.mode()` - 获得当前 `mode` 从弹出状态.

### 杂项方法

-   `popup.onPanelClose(fn)` 当面板关闭时会开火

### 调整自定义内容设置中要显示的绑定数据

默认情况下,所有数据绑定都被用作自定义内容设置下的小按钮. 您可以通过添加设置覆盖来更改 :

```yaml
overrides:
      - property: [ popup_custom_main, popup_custom_header ]
        editor:
          style: true
          url: true
          flourish_embed: true
          bindings: [ dataset_name.databinding_name_1, dataset_name.databinding_name_2 ]
```

## 参考模板

使用模板 `info-popups` 以相当直截了当的方式劝阻:

-   [模板/卡片](https://github.com/kiln/template-cards)
-   [模板/任务](https://github.com/kiln/template-gantt)

使用模板 `info-popups` 和画布包括:

-   [模板/散开](https://github.com/kiln/template-scatter)

#### 对于有多个数据表的模板

如果模板有多个数据表,您需要以信息弹出绑定相关的数据表名称通过。 如果在测试中没有通过,将使用第一个数据表 `column_names` 对象.

## 常见问题

### @flourish/info-popup 是什么？

用数据插入弹出

### 如何安装 @flourish/info-popup？

在项目目录运行 npm install @flourish/info-popup，或使用 pnpm add / yarn add / bun add。

### @flourish/info-popup 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flourish\_\_info-popup 是否存在。

### @flourish/info-popup 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @flourish/info-popup 可以商用吗？

@flourish/info-popup 使用 LicenseRef-LICENSE 许可。声明的许可为 LicenseRef-LICENSE，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @flourish/info-popup 的下载量有多少？

根据 npm 官方下载统计，@flourish/info-popup 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,142 次，日均约 138 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flourish/info-popup 还在维护吗？

最新版本 8\.3\.3 发布于 2026/09/01（2 个月前）；至今共发布 52 个版本，其中过去 12 个月发布了 4 个；首次发布于 2020/07/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。