---
name: "getBoundingClientRect"
mode: "api"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "getBoundingClientRect - 获取节点的坐标信息"
---

## getBoundingClientRect

> [VERSION] @ray-js/ray >= 0.5.10

### 描述

获取节点的坐标信息

### 参数

`Params`

| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `ref` | `NodesRef` | 是 | 通过 getElementById 获取的节点引用 |

### 返回值

类型: `Promise<Rect>`

包含节点坐标和尺寸信息的 Rect 对象，节点不存在时返回 null

##### Rect

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `right` | `number` | 节点右边界坐标 |
| `left` | `number` | 节点左边界坐标 |
| `top` | `number` | 节点上边界坐标 |
| `bottom` | `number` | 节点下边界坐标 |
| `width` | `number` | 节点宽度 |
| `height` | `number` | 节点高度 |

### 引用对象

##### `interface` NodesRef

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `boundingClientRect` | `(callback: (result: BoundingClientRectResult) => void) => SelectorQueryChain` | 获取节点布局位置（left, right, top, bottom, width, height） |
| `scrollOffset` | `(callback: (result: ScrollOffsetResult) => void) => SelectorQueryChain` | 获取节点滚动位置（scrollLeft, scrollTop） |
| `fields` | `(fields: Record<string, boolean>, callback: (result: Record<string, unknown>) => void) => SelectorQueryChain` | 获取节点指定字段信息 |

##### `interface` BoundingClientRectResult

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 节点 id |
| `dataset` | `Record<string, unknown>` | 节点 dataset |
| `left` | `number` | 左边界坐标 |
| `right` | `number` | 右边界坐标 |
| `top` | `number` | 上边界坐标 |
| `bottom` | `number` | 下边界坐标 |
| `width` | `number` | 节点宽度 |
| `height` | `number` | 节点高度 |

##### `interface` SelectorQueryChain

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `exec` | `(callback: (results: unknown[]) => void) => void` | 执行查询 |

##### `interface` ScrollOffsetResult

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `id` | `string` | 节点 id |
| `dataset` | `Record<string, unknown>` | 节点 dataset |
| `scrollLeft` | `number` | 横向滚动位置 |
| `scrollTop` | `number` | 纵向滚动位置 |


### 示例代码

#### 基础用法

```tsx
import React, { useState } from 'react';
import { View, Button, Text, getBoundingClientRect, getElementById } from '@ray-js/ray';

export default function Demo() {
  const [info, setInfo] = useState('');

  const handleGetRect = async () => {
    const element = await getElementById('targetBox');
    if (element) {
      const rect = await getBoundingClientRect(element);
      if (rect) {
        setInfo(`宽:${rect.width} 高:${rect.height} 左:${rect.left} 上:${rect.top}`);
      }
    }
  };

  return (
    <View style={{ padding: 20 }}>
      <View
        id="targetBox"
        style={{
          width: 200,
          height: 100,
          backgroundColor: '#1890ff',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <Text style={{ color: '#fff' }}>目标区域</Text>
      </View>
      <Button style={{ marginTop: 10 }} onClick={handleGetRect}>
        获取坐标信息
      </Button>
      {info && <Text style={{ marginTop: 10 }}>{info}</Text>}
    </View>
  );
}
```