Eidos 表格 View

如果你想把一张 Eidos 表格展示成看板、图表或卡片列表，可以提供表格 View。它绑定用户当前选择的表格，使用同一份字段和记录。

本篇先做一个 Inspector：在表格中显示字段信息和前 20 条记录，便于确认数据如何到达插件。之后再把这个输出替换成自己的界面。

1. 声明表格 View

创建 plugin.json 和 src/main.ts：

{
  "apiVersion": 1,
  "id": "example.table-inspector",
  "name": "Table Inspector",
  "version": "0.1.0",
  "requires": {
    "pluginApi": "3.0.0"
  },
  "views": [
    {
      "id": "inspect",
      "title": "Inspector",
      "kind": "file",
      "entry": "./src/main.ts",
      "capabilities": ["eidos/table"]
    }
  ],
  "placements": [
    {
      "location": "table/view",
      "view": "inspect"
    }
  ]
}

这里使用 kind: "file"，因为数据来自 Eidos 文件。eidos/table 提供当前表格接口，table/view 让它出现在表格的 View 选择流程中。这个只读示例不需要 access: "write"。

2. 读取结构和记录

在 src/main.ts 中填写：

import type { Mount } from "@eidos.space/plugin-sdk"

const mount: Mount = async (ctx, root) => {
  const table = ctx.capabilities.eidos?.table
  if (!table) throw new Error("Open this View inside an Eidos table")
  const output = document.createElement("pre")
  const status = document.createElement("p")
  root.append(output, status)
  let revision = 0
  const refresh = async () => {
    const current = ++revision
    try {
      const context = await table.readContext()
      const page = await table.readRows({ offset: 0, limit: 20 })
      if (ctx.signal.aborted || current !== revision) return
      output.textContent = JSON.stringify(
        { fields: context.fields, page },
        null,
        2
      )
      status.textContent = ""
    } catch (error) {
      if (!ctx.signal.aborted && current === revision)
        status.textContent = String(error)
    }
  }
  ctx.subscriptions.add(table.watch(() => void refresh()))
  await refresh()
}
export default mount

readContext 返回字段和视图信息，readRows 分页读取当前表格。示例用 JSON 展示它们，是为了让你先看清真实数据结构。实现卡片或图表时，用字段 ID 读取记录值，不要假定显示名称永远不变。

watch 是“数据可能变化”的通知，不包含完整数据，也不发送初始值。收到通知后重新读取；页面关闭后订阅会释放。示例会忽略迟到的请求，保留最后一次成功显示的内容。

3. 在表格中检查结果

在 Lite 加载并启用插件，打开包含记录的 .eidos 文件。在表格中添加或选择插件提供的 Inspector View，应看到字段与最多 20 条记录。修改表格内容，输出应更新。

这个接口始终针对绑定表格。要继续读下一页，增加 offset；要打开某条记录，调用 table.openRecord(rowId)；要计算汇总，使用 table.aggregate。具体数据类型见 Eidos API。

保存展示配置

例如，看板需要记住“紧凑显示”选项。先在 View 中加入 eidos/config，并设置 access: "write"。然后在用户改变选项的处理函数中：

const { table, config } = ctx.capabilities.eidos ?? {}
if (!table || !config) throw new Error("Table and config required")
const current = await config.read(table.tableId)
await config.write(table.tableId, {
  value: { ...current.value, compact: true },
  expectedVersion: current.version,
})

这份配置保存在 Eidos 文件中，并且隔离到当前插件。写入使用刚读取的版本；如果版本过期，重新读取并合并用户选择，不要直接覆盖。用 config.watch(tableId, listener) 监听配置失效，再主动读取新值。

如果只需要保存当前 View 的展示配置，也可以使用 table.setViewConfig。它完整替换配置，调用前应合并需要保留的键。

需要浏览整个文件时

加入 eidos/schema 后，可以用 schema.listTables() 列出文件内的表，再用 schema.readTable(tableId) 查看字段。它适合文件结构浏览器；若要直接打开整个 .eidos 文件，还需要匹配该扩展名的 file/open 入口。

三个能力分别声明，不会因为有 table 就自动获得 schema 或 config。Lite 支持这三个接口；CLI Serve 提供 eidos/table。需要支持 Serve 时，先用 check --target cli 检查兼容性。