# @blockle/blocks-react 中文文档

规范地址：https://npmcn.com/package/%40blockle/blocks-react/

版本：3\.5\.0
npm 元数据更新时间：2026-11-07T23:39:38.378Z
中文译文更新时间：2026-11-08T07:19:30.697Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40blockle/blocks-react
原文对照：https://npmcn.com/package/%40blockle/blocks-react/?lang=original
项目主页：https://github.com/Blockle/blocks#readme
源码仓库：https://github.com/Blockle/blocks

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

- 包体积（解压后）：241 kB，301 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=19\.1\.0，react-dom \>=19\.1\.0，@blockle/blocks-core \>=3\.4\.x，@vanilla-extract/css ^1\.18\.0，@blockle/blocks-react-slot \>=1\.2\.x
- 首次发布：2025-03-27T19:17:33.429Z
- 最新版本发布：2026-11-07T23:39:38.060Z
- 近 30 天下载量：2737（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 33 个）

## 中文简介

Blockle 的反应钩和组件

## 安装

```sh
npm install @blockle/blocks-react
```

也可以使用：`pnpm add @blockle/blocks-react`、`yarn add @blockle/blocks-react`、`bun add @blockle/blocks-react`

## README

# @ blockle/ blocks- react

## 测试

`Dialog` 财务报告和审定财务报表 `Drawer` 打开方式 `HTMLDialogElement.showModal()` 关闭 `close()`. jsdom 不执行这些, 因此在 jsdom 测试中打开 `Dialog` 保持关闭 `<dialog>`,而测试库无法从角色中找到它或其中的任何内容.

将此多填充添加到您的 Vest 或 Jest 设置文件中 。 它只定义了jsdom缺失的方法:

```ts
const DialogPrototype = HTMLDialogElement.prototype;

if (!DialogPrototype.showModal) {
  DialogPrototype.showModal = function showModal() {
    this.setAttribute('open', '');
  };
}

if (!DialogPrototype.show) {
  DialogPrototype.show = function show() {
    this.setAttribute('open', '');
  };
}

if (!DialogPrototype.close) {
  DialogPrototype.close = function close() {
    if (!this.hasAttribute('open')) {
      return;
    }

    this.removeAttribute('open');
    this.dispatchEvent(new Event('close'));
  };
}
```

用它可以找到一个打开的对话框 `getByRole('dialog')`数字 :

```tsx
render(
  <Dialog open onRequestClose={() => {}} aria-label="Settings">
    <button type="button">Save</button>
  </Dialog>,
);

screen.getByRole('dialog', { name: 'Settings' });
screen.getByRole('button', { name: 'Save' });
```

在多填充下,对话框是开放的,但不是模式的:它不是在上层,它以外的任何东西都不是惰性的,所以它后面的内容仍然可以被询问和点击. 测试模式行为,在真实浏览器中聚焦并点击外部,例如使用Vitest浏览器模式或Playwright.

### 过量

`Popover` 以 `showPopover()` 关闭 `hidePopover()`. jsdom 不执行 Popover API,其默认样式表隐藏每个 `[popover]` 未打开的元素, 因此测试库将打开的 popover 内容视为隐藏 `getByRole` 里面什么都没有.

将此多填充添加到测试设置中 。 它只定义了 jsdom 缺少的方法, 并标记一个开放的弹出式 `data-popover-open` 测试样式表显示的属性 :

```ts
const PopoverPrototype = HTMLElement.prototype;

if (!PopoverPrototype.showPopover) {
  PopoverPrototype.showPopover = function showPopover() {
    this.setAttribute('data-popover-open', '');
  };
}

if (!PopoverPrototype.hidePopover) {
  PopoverPrototype.hidePopover = function hidePopover() {
    this.removeAttribute('data-popover-open');
  };
}

if (!PopoverPrototype.togglePopover) {
  PopoverPrototype.togglePopover = function togglePopover(force?: boolean) {
    return this.toggleAttribute('data-popover-open', force);
  };
}

const popoverStyle = document.createElement('style');
popoverStyle.textContent = '[popover][data-popover-open] { display: block; }';
document.head.append(popoverStyle);
```

藉由它,一个开放的流行乐内容可以通过角色找到:

```tsx
render(
  <Popover open anchorElement={anchorRef} onRequestClose={() => {}}>
    <button type="button">Inside</button>
  </Popover>,
);

screen.getByRole('button', { name: 'Inside' });
```

其他图书馆可查询 `showPopover` 并且一旦存在,行为就不同;例如,dnd-kit拖动方式不同。 如果全局多填充器中断了这种试验,则仅在下列条件下进行: `describe` 打开弹出器,然后删除它之后添加的内容:

```ts
import { afterAll, beforeAll, describe } from 'vitest';

describe('with a popover open', () => {
  const polyfills: Record<string, (this: HTMLElement, force?: boolean) => unknown> = {
    showPopover() {
      this.setAttribute('data-popover-open', '');
    },
    hidePopover() {
      this.removeAttribute('data-popover-open');
    },
    togglePopover(force?: boolean) {
      return this.toggleAttribute('data-popover-open', force);
    },
  };
  const added: string[] = [];
  const popoverStyle = document.createElement('style');

  beforeAll(() => {
    for (const [method, polyfill] of Object.entries(polyfills)) {
      if (!(method in HTMLElement.prototype)) {
        Reflect.set(HTMLElement.prototype, method, polyfill);
        added.push(method);
      }
    }

    popoverStyle.textContent = '[popover][data-popover-open] { display: block; }';
    document.head.append(popoverStyle);
  });

  afterAll(() => {
    for (const method of added) {
      Reflect.deleteProperty(HTMLElement.prototype, method);
    }

    popoverStyle.remove();
  });

  // Tests that open a popover
});
```

如果缺少了 Popover API 而未应用多填充, `Popover` 警告它打开或关闭时,不要投掷。 其内容随后会隐藏在jsdom的默认样式下. 测试定位,顶层并用真实的浏览器点击外部.

## 常见问题

### @blockle/blocks-react 是什么？

Blockle 的反应钩和组件

### 如何安装 @blockle/blocks-react？

在项目目录运行 npm install @blockle/blocks-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.1\.0）、react-dom（\>=19\.1\.0）、@blockle/blocks-core（\>=3\.4\.x）、@vanilla-extract/css（^1\.18\.0）、@blockle/blocks-react-slot（\>=1\.2\.x）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blockle/blocks-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @blockle/blocks-react 支持 ESM 还是 CommonJS？

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

### @blockle/blocks-react 可以商用吗？

@blockle/blocks-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blockle/blocks-react 的下载量有多少？

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

### @blockle/blocks-react 还在维护吗？

最新版本 3\.5\.0 发布于 2026/11/08（今天）；至今共发布 51 个版本，其中过去 12 个月发布了 33 个；首次发布于 2025/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。