# @carbon-labs/wc-resizer 中文文档

规范地址：https://npmcn.com/package/%40carbon-labs/wc-resizer/

版本：0\.5\.0
npm 元数据更新时间：2026-08-21T15:34:50.480Z
中文译文更新时间：2026-11-09T04:45:22.924Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40carbon-labs/wc-resizer
原文对照：https://npmcn.com/package/%40carbon-labs/wc-resizer/?lang=original
项目主页：https://github.com/carbon-design-system/carbon-labs#readme
源码仓库：https://github.com/carbon-design-system/carbon-labs

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

- 包体积（解压后）：178 kB，87 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-05-12T11:15:56.217Z
- 最新版本发布：2026-07-15T17:45:49.445Z
- 近 30 天下载量：13051（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

碳实验室 - 用于创建可扩展面板的Resizer网络组件

## 安装

```sh
npm install @carbon-labs/wc-resizer
```

也可以使用：`pnpm add @carbon-labs/wc-resizer`、`yarn add @carbon-labs/wc-resizer`、`bun add @carbon-labs/wc-resizer`

## README

# Resizer Web 组件

一套网络组件,用于创建支持两者的可扩展面板 声明式(零设置)和方案式(可组合)使用模式.

## 构成部分

-   `clabs-resizer-grid` - 大型面板集装箱
-   `clabs-resizer-panel` - 个人可调整面板
-   `clabs-resizer-handle` - 在面板之间调整大小
-   `clabs-resizer-handle-pivot` - 先进再大小的角中枢

## 特征

### 零定用法( 声明式)

启用没有 JavaScript 设置的组件的直接使用 。 用户可以 完全通过HTML来作曲布局,并重新调整了出箱工作的大小.

### 可编译用法( 程序)

允许 `clabs-resizer-handle` 财务报告和审定财务报表 `clabs-resizer-handle-pivot` 用作 释放拖动事件和三角洲值的独立组件。 消费者(例如, react等框架可以通过JavaScript处理再大小逻辑.

## 使用量

### 声明模式( Zero- Setup)

#### 基本水平布局

```html
<clabs-resizer-grid axis="x">
  <clabs-resizer-panel slot="left"> Left panel content </clabs-resizer-panel>

  <clabs-resizer-handle slot="handle-horizontal"></clabs-resizer-handle>

  <clabs-resizer-panel slot="right"> Right panel content </clabs-resizer-panel>
</clabs-resizer-grid>
```

#### 基本垂直布局

```html
<clabs-resizer-grid axis="y">
  <clabs-resizer-panel slot="top"> Top panel content </clabs-resizer-panel>

  <clabs-resizer-handle slot="handle-vertical"></clabs-resizer-handle>

  <clabs-resizer-panel slot="bottom">
    Bottom panel content
  </clabs-resizer-panel>
</clabs-resizer-grid>
```

#### 与关键处理

```html
<clabs-resizer-grid axis="x">
  <clabs-resizer-panel slot="left">
    Left panel content
    <clabs-resizer-handle slot="handle-horizontal">
      <clabs-resizer-handle-pivot></clabs-resizer-handle-pivot>
    </clabs-resizer-handle>
  </clabs-resizer-panel>

  <clabs-resizer-panel slot="right"> Right panel content </clabs-resizer-panel>
</clabs-resizer-grid>
```

### 程序模式 (Event- Driven)

换接器柄可以独立使用,不用网格容器 听取其活动:

#### 活动

-   `resize-start` - 拖曳开始时被炒了
    
    -   `detail.axis` - 调整轴("x"或"y")
    -   `detail.startPosition` - 开始位置{x,y}
-   `resize-drag` - 拖行时被放火
    
    -   `detail.axis` - 调整轴("x"或"y")
    -   `detail.delta` - 三角地移动像素
    -   `detail.position` - 当前位置{x,y}
-   `resize-end` - 拖曳结束时被解除
    
    -   `detail.axis` - 调整轴("x"或"y")
    -   `detail.delta` - 三角地总移动像素
    -   `detail.position` - 最终位置{x,y}
-   `resize-reset` - 双塔/双击起火
    

#### 单一面板示例

```html
<div class="container">
  <div class="panel" id="myPanel">Panel content</div>
  <clabs-resizer-handle></clabs-resizer-handle>
</div>

<script>
  const handle = document.querySelector('clabs-resizer-handle');
  const panel = document.getElementById('myPanel');
  let initialHeight = 0;

  handle.addEventListener('resize-start', (e) => {
    initialHeight = panel.offsetHeight;
  });

  handle.addEventListener('resize-drag', (e) => {
    const newHeight = initialHeight + e.detail.delta;
    panel.style.height = `${Math.max(48, newHeight)}px`;
  });
</script>
```

#### 边框调整大小示例

```html
<div class="container" style="height: 400px">
  <div class="panel" id="boundedPanel">Panel content</div>
  <clabs-resizer-handle></clabs-resizer-handle>
</div>

<script>
  const handle = document.querySelector('clabs-resizer-handle');
  const panel = document.getElementById('boundedPanel');
  const container = document.querySelector('.container');
  let initialHeight = 0;

  handle.addEventListener('resize-start', (e) => {
    initialHeight = panel.offsetHeight;
  });

  handle.addEventListener('resize-drag', (e) => {
    const containerHeight = container.offsetHeight;
    const newHeight = initialHeight + e.detail.delta;

    // Constrain between min and max
    const constrainedHeight = Math.max(
      48,
      Math.min(newHeight, containerHeight - 20)
    );

    panel.style.height = `${constrainedHeight}px`;
  });
</script>
```

## CSS 自定义属性

-   `--resizer-thickness` - 增压器柄的厚度( 默认: 4px)
-   `--resizer-grab-thickness` - 其他抓取区域厚度(默认:0px)
-   `--resizer-grab-color` - 抓取区域的颜色( 默认: 透明)
-   `--start-element-size` - 启动面板的大小( 默认:1fr)
-   `--end-element-size` - 端面板的大小( 默认:1fr)

## 无障碍

### 键盘导航

更新器手柄支持键盘导航 :

-   **箭头键**: 以 5px 递增方式移动更新器手柄
    -   `ArrowUp`编号 :`ArrowDown` 用于水平手柄(y-轴)
    -   `ArrowLeft`编号 :`ArrowRight` 用于垂直手柄(x轴)
-   **移动 + 箭头键**: 以25px增量移动,以更快地调整大小
-   **内容**: 将启动面板折叠到最小大小( 仅网格模式)
-   **结束**: 将启动面板扩展至最大大小(仅网格模式)
-   **双击/双打**: 将面板重置为默认大小

### ARIA 属性

#### 基于网格的使用(自动)

使用时 `clabs-resizer-handle` 内 `clabs-resizer-grid`, ARIA 属性 自动管理 :

-   `role="separator"` - 确定元素为分离器
-   `aria-orientation` - 设定为基于轴的"垂直"或"横向"
-   `aria-valuenow` - 现行拆分百分比(0-100)
-   `aria-valuemin="0"` - 最低价值
-   `aria-valuemax="100"` - 最大价值
-   `aria-valuetext` - 人可读分拆比率(例如“60%/40%”)
-   `aria-live="assertive"` - 向屏幕阅读器宣布更改

#### 独立使用(手册)

使用时 `clabs-resizer-handle` 没有网格(程序模式),您就是 负责管理ARIA属性,以确保无障碍:

```html
<div class="container">
  <div class="panel" id="myPanel">Panel content</div>
  <clabs-resizer-handle
    aria-valuenow="50"
    aria-valuemin="0"
    aria-valuemax="100"
    aria-valuetext="Panel height: 200px"></clabs-resizer-handle>
</div>

<script>
  const handle = document.querySelector('clabs-resizer-handle');
  const panel = document.getElementById('myPanel');
  let initialHeight = 0;

  handle.addEventListener('resize-start', (e) => {
    initialHeight = panel.offsetHeight;
  });

  handle.addEventListener('resize-drag', (e) => {
    const newHeight = initialHeight + e.detail.delta;
    const constrainedHeight = Math.max(48, newHeight);
    panel.style.height = `${constrainedHeight}px`;

    // Update ARIA attributes for accessibility
    const percentage = Math.round((constrainedHeight / 400) * 100);
    handle.setAttribute('aria-valuenow', percentage.toString());
    handle.setAttribute(
      'aria-valuetext',
      `Panel height: ${constrainedHeight}px`
    );
  });
</script>
```

**说明**编号: `role="separator"` 属性需要 `aria-valuenow` 将会是 为适当遵守无障碍规定而提供。 当使用独立的手柄时, 在调整操作大小时总是更新这些属性 .

## 浏览器支持

有 Web 组件支持的现代浏览器( Chrome, Firefox, Safari, Edge)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @carbon-labs/wc-resizer 是什么？

碳实验室 - 用于创建可扩展面板的Resizer网络组件

### 如何安装 @carbon-labs/wc-resizer？

在项目目录运行 npm install @carbon-labs/wc-resizer，或使用 pnpm add / yarn add / bun add。

### @carbon-labs/wc-resizer 支持 TypeScript 吗？

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

### @carbon-labs/wc-resizer 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @carbon-labs/wc-resizer 可以商用吗？

@carbon-labs/wc-resizer 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @carbon-labs/wc-resizer 的下载量有多少？

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

### @carbon-labs/wc-resizer 还在维护吗？

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