Methodox Wiki
产品文档
简体中文
English 简体中文 繁體中文
Methodox 首页

数据源

Data Source（数据源）是保存在文档中的命名查询，其结果始终是一张表格：来自 Web API、SQLite 数据库文件或任何通过 ODBC 访问的数据库的行。你在一个边输入边显示表格的编辑器中构建它，文档会在任何可以放置表格的位置显示它：溢出到工作簿的单元格中，或作为 Impulse 文档中或 Expo 幻灯片上的智能表格。刷新它，表格就会随数据源更新，同时保留你为每一列设置的格式。

Data Source 是数据，而不是代码：它不需要等待 Enable，但在你允许它访问之前，它无法访问任何内容（参见信任）。

创建 Data Source

应用程序 创建 编辑
Formula Data ▸ New Data Source… 选中其表格中的某个单元格后使用 Data ▸ Edit Data Source…；Properties 面板中的 Edit Data Source… 会在 Data Sources 选项卡中打开它
Impulse Insert ▸ Data Source… 把它作为智能表格放在插入点处 References ▸ Edit Data Source…，或表格的右键菜单
Expo Insert ▸ Data Source… 把它作为智能表格放在幻灯片上 表格的右键菜单

在 Formula 中，Data Source 是一个公式 =DATASOURCE("Sales")，它会像任何动态数组一样，从单元格溢出其表格。

Data Sources 示例上方的 Data Source 编辑器：左侧是针对 Sales.db、读取 Region 参数的 SQLite 查询，右侧是它返回的八行，下方是每一列的显示名称、数字格式和宽度

编辑器

  • Name：文档对它的称呼，例如 =DATASOURCE("Sales") 中的名称。
  • Reads from：Web API、SQLite file 或 ODBC。
    • Web API：一个返回 JSON 的 URL，其查询参数每行一个（region = {param.Region}），其请求头每行一个（Authorization: Bearer {credential.secret}），以及 Rows，即指向行数组的 JSON 路径，例如 $.data.items（留空时为整个响应）。只发出 GET 请求。
    • SQLite file：数据库文件，可以是文档旁边的路径（Sales.db），也可以是完整路径；它以只读方式打开。
    • ODBC：一个连接字符串，例如 DSN=Sales。
  • Query（用于数据库）：一条 SELECT（或 WITH … SELECT）语句；不接受任何写入操作。SQL 中的 param.Region 读取文档的 Region 参数，并作为值发送，绝不会被拼接进语句中，因此参数无法改变查询的行为。
  • Credential：保存在你计算机上（绝不保存在文档中）的用户名和密钥，连接字符串、URL 或请求头以 {credential.user} 和 {credential.secret} 读取它们。旁边的锁形按钮会把新凭据保存到 Windows 凭据管理器中，名称为 MethodoxOffice:<name>。文档只保存凭据的名称，因此每个打开它的人都使用自己的凭据。
  • Refresh：Manually、When the document opens 或 Every few minutes（除非你更改，否则每 15 分钟一次）。当数据源读取的参数发生变化时，它总会刷新。

右侧的表格是数据源的结果，每次更改后片刻就会重新读取，因此你看到的就是你正在构建的表格；当数据源需要文档尚未获得的访问权限时，旁边会出现一个 Allow 按钮。一旦读取得到结果，其下方就会出现 Columns，列出数据源返回的内容（在此之前没有可列出的内容，因此不会显示）：取消勾选某列可将其排除，在 Shown as 下重命名，设置其初始的数字格式和宽度，以及上移或下移。OK 会将 Data Source 作为一次可撤消的更改保存在文档中。一个 Data Source 最多返回 100,000 行。

Data Sources 选项卡

Formula 中的 Data ▸ Data Sources，或 Impulse 和 Expo 中的 Tools ▸ Data Sources，会在底部托盘中打开一个选项卡，在一处列出文档的所有 Data Source：其名称、Kind（Web API、SQLite 或 ODBC）、Reads（读取的内容）、Shown In（表格显示的位置）、上次刷新时间、Status 和上一个错误、Rows，以及是否拥有所需的 Access。数据源右键菜单中的 Show in Data Sources 项，以及它在 Smart Objects 选项卡中的行，都会在该数据源处打开此选项卡。

  • New Data Source… 和 Edit Data Source… 会打开编辑器。
  • Refresh 刷新所选的数据源，Refresh All 刷新所有数据源。
  • Rename… 重命名数据源，并在同一个撤消步骤中改写所有调用它的 =DATASOURCE("…") 公式，同时保留其上次的结果，因此任何显示它的地方都不会变成错误。
  • Duplicate 创建一个副本以供修改；Delete 在询问后删除数据源，并说明它仍在何处显示。
  • Go To（或双击该行）会转到它所填充的表格；Insert at Selection 会把它放在单元格或插入点处：在 Formula 中作为溢出的 =DATASOURCE()，在 Impulse 和 Expo 中作为智能表格。
  • Allow 授予数据源所需的权限，与文档上方的栏作用相同。

Data Sources 示例下方的 Data Sources 选项卡：来自 SQLite 文件的 Sales 和来自 Web API 的 Forecast，以及各自读取的内容、显示位置、上次刷新时间、行数和仍需的访问权限

刷新

  • Formula： Data ▸ Refresh Data（Ctrl+Shift+F5）刷新工作簿中的所有 Data Source 和数据源 Function。
  • Impulse 和 Expo： Data Source 是一个智能对象，通过 Refresh All（Ctrl+Shift+F9）与其他智能对象一起刷新，或从其右键菜单刷新。
  • 自动刷新：按照每个数据源的 Refresh 设置进行，以及在其读取的参数发生变化时进行。

在两次刷新之间，以及在离线打开的文档中，表格显示上次刷新获取的内容，这些内容随文档一起保存。Data Sources 选项卡列出所有 Data Source 及其上次刷新时间和结果；上次刷新的时间随文档一起保存。Smart Objects 选项卡也在 Data sources 下列出了它们。

信任与访问

读取 Data Source 会访问文档之外的内容，因此必须允许文档这样做：

  • Web API 需要对其网站的 GET 权限，例如 Needs GET api.open-meteo.com；
  • 数据库需要对其文件或连接的 Connect 权限，例如 Needs Connect Sales.db。

文档上方的栏或编辑器的预览会通过 Allow 按钮发出请求。每项授权都会针对该文档记录在你的信任存储中，并与决定数据源连接到何处以及查询什么的内容相关联；因此在其他地方编辑数据源的连接或查询会再次询问，而你在编辑器中所做的编辑会保留文档的授权。数据源表格的外观不计入其中。

按列名设置表格格式

Data Source 或任何智能表格在每次刷新时都会被重写，其列可能以另一种顺序返回，或者多一列、少一列。因此你可以像对待任何表格一样为它设置格式，而格式属于列的名称，而非其位置：每次刷新后，每一列都会按其标题恢复外观、宽度和数字格式。

  • Formula： 溢出的表格会保留每一列的单元格格式、宽度以及其中的条件格式。
  • Impulse： 智能表格会保留每一列的单元格格式、文本格式及其宽度。表格右键菜单中的 Column Number Format… 用于设置某列数字的写法。
  • Expo： 列的外观由其标题单元格和第一个正文单元格决定，并应用到每一行。选中表格或其中某个单元格，用文本格式栏设置格式；Column Number Format… 位于右键菜单中。

Data Source，或在 Lua 中通过 host.table(rows, formats) 的脚本，可以为新列建议数字格式、宽度和对齐方式。你自己的格式始终优先于建议。在同一会话中消失后又重新出现的列会恢复原样，而新的数字列会右对齐。

试一试

Examples\Formula\Data Sources.xlsx 包含两个由 =DATASOURCE() 溢出的 Data Source：Sales 是工作簿旁边的 SQLite 数据库 Sales.db，按 Region 参数读取；Forecast 是 Open-Meteo 在 Latitude 和 Longitude 参数所指位置的一周预报。在被询问时分别允许它们，然后在 Parameters 面板中更改某个参数：表格会重新获取数据，而每一列都保留其格式。

另请参阅