跳转到正文

元素抓取器

使用 AI 编码助手时,你通常需要告诉它们页面上的特定元素由哪个模板文件渲染。元素抓取器提供十字准星样式的元素选择器,只需一个操作即可将丰富的元素上下文复制到剪贴板。

启用

元素抓取器由查询参数控制。将?blockstudio-devtools附加到任意前端URL即可启用:

代码
https://example.com/?blockstudio-devtools
https://example.com/?p=123&blockstudio-devtools

不带查询参数时,不会加载脚本或数据属性。

设置

在主题的blockstudio.json中启用元素抓取器:

JSON
{
  "dev": {
    "grab": {
      "enabled": true
    }
  }
}
属性 类型 默认值 说明
enabled boolean false 启用元素抓取器。

也可以通过过滤器设置此项:

PHP
add_filter('blockstudio/settings/dev/grab/enabled', '__return_true');

用法

  1. 登录后,访问任意带有?blockstudio-devtools的前端页面;登录用户必须具有edit_posts权限。
  2. 按住 Cmd+C(Mac)或 Ctrl+C(Windows)100毫秒,即可激活抓取器。
  3. 十字准星选择器会启动,并显示画布叠加层;悬停时,叠加层会突出显示Blockstudio区块。
  4. 会显示两个标签:一个显示区块的模板文件路径,另一个显示HTML元素标记名称。
  5. 点击元素,将其上下文复制到剪贴板。
  6. 将结果粘贴到你的 AI 编码工具中。

再次按 Escape 或 Cmd+C 可在不复制的情况下停用。若在100毫秒前松开 Cmd+C,则会保留正常的复制行为。

剪贴板格式

点击元素会复制一段为 AI 编码助手设计的丰富上下文字符串:

代码
@<div>

<div class="my-block">
  Hello world
</div>
  in theme-name/blockstudio/blocks/my-block/index.php

其中包含元素标记名称、带属性和内容的HTML预览,以及模板文件路径。

内部机制

Blockstudio 会为前端使用 useBlockProps 的每个区块包装元素添加 data-blockstudio-path 属性。此属性包含用于渲染该区块的模板文件的绝对路径。

前端会为已登录的编辑者加载一个轻量级原生 TypeScript 模块(无 React,无 WordPress 依赖)。它使用 document.elementsFromPoint() 检测光标下的特定 HTML 元素及其父级 Blockstudio 区块,并分别高亮显示。

安全

只有满足以下所有条件时,才会渲染 data-blockstudio-path 属性和抓取器脚本:

  • 存在 ?blockstudio-devtools 查询参数。
  • dev.grab.enabled 设置为 true。
  • 当前用户具有 edit_posts 权限。

访客永远不会看到文件路径或抓取器脚本。