# @clutch-creator/toolkit 中文文档

规范地址：https://npmcn.com/package/%40clutch-creator/toolkit/

版本：3\.3\.1
npm 元数据更新时间：2026-01-23T18:05:48.703Z
中文译文更新时间：2026-11-10T04:03:50.150Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40clutch-creator/toolkit
原文对照：https://npmcn.com/package/%40clutch-creator/toolkit/?lang=original

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

- 包体积（解压后）：306 kB，116 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：next ^16\.0\.1，react ^19\.0\.0
- 首次发布：2025-07-23T10:03:38.509Z
- 最新版本发布：2025-11-27T00:32:10.616Z
- 近 30 天下载量：2746（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 3 个）

## 中文简介

离合器项目中使用的工具包组件和提法

## 安装

```sh
npm install @clutch-creator/toolkit
```

也可以使用：`pnpm add @clutch-creator/toolkit`、`yarn add @clutch-creator/toolkit`、`bun add @clutch-creator/toolkit`

## README

# Clutch 工具包

[![npm version](https://badge.fury.io/js/@clutch-creator%2Ftoolkit.svg)](https://badge.fury.io/js/@clutch-creator%2Ftoolkit) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![React](https://img.shields.io/badge/React-19.0.0-blue.svg)](https://reactjs.org/) [![Next.js](https://img.shields.io/badge/Next.js-15.3.3-black.svg)](https://nextjs.org/) [![Build Status](https://github.com/clutch-creator/toolkit/workflows/Checks/badge.svg)](https://github.com/clutch-creator/toolkit/actions)

为Next.js应用程序提供反应组件、公用事业和州管理解决方案的综合工具包.

## 安装

```bash
npm install @clutch-creator/toolkit
# or
yarn add @clutch-creator/toolkit
# or
bun add @clutch-creator/toolkit
```

## 概览

Clutch工具包旨在为开发者提供一套可再用组件和公用设施,与Next.js应用程序无缝地融合. 它包括国家管理,SIO优化,图像处理,以及各种公用功能.

## API 参考

### 国家管理钩

#### `useRegisterState(name, value)`

在离合器中注册一个全球可约束的状态.

**类型签名 :**

```typescript
useRegisterState<T>(name: string, value: T): (newValue: T) => void
```

**示例**

```typescript
import { useRegisterState } from '@clutch-creator/toolkit';
import { useState } from 'react';

function Counter() {
  const [counter, setCounter] = useState(0);

  // Register the state so it can be accessed globally in Clutch
  useRegisterState<number>('count', counter);

  const increment = () => setCounter(prev => prev + 1);
  const reset = () => setCounter(0);

  return (
    <div>
      <button onClick={increment}>Increment</button>
      <button onClick={reset}>Reset</button>
    </div>
  );
}
```

#### `useRegisterAction(options)`

注册事件可触发的组件的行动.

**类型签名 :**

```typescript
useRegisterAction<T extends (...args: unknown[]) => unknown>(
  options: TRegisterActionOptions<T>
): void

interface TRegisterActionOptions<T> {
  name: string;
  action: T;
  props?: Record<string, unknown>;
  wrapper?: React.FunctionComponent<{
    children: React.ReactNode;
    [key: string]: unknown;
  }>;
  styleSelectors?: TStyleSelector[];
}

interface TStyleSelector {
  name: string;
  value: string;
}
```

**示例**

```typescript
import { useRegisterAction } from '@clutch-creator/toolkit';
import { useState } from 'react';

type TSetToggled = (toggled: boolean) => void;

function TodoItem({ id, text, completed }) {
  const [toggled, setToggled] = useState(false);

  useRegisterAction<TSetToggled>({
    name: 'setToggled',
    action: (newValue) => {
      setToggled((value) => newValue);
    },
    props: {
      'data-toggled': toggled
    },
    styleSelectors: [
      { name: 'Toggled', value: '&:[data-toggled=true]' }
    ]
  });

  return <div className={completed ? 'completed' : ''}>{text}</div>;
}
```

#### `useRegisterSelect(setVisibility, activeTrail)`

在离合器中选择元素时,注册一个要调用的处理器.

**类型签名 :**

```typescript
useRegisterSelect(
  setVisibility: (shouldBeVisible: boolean) => void,
  activeTrail?: boolean
): null
```

**示例**

```typescript
import { useRegisterSelect } from '@clutch-creator/toolkit';
import { useState } from 'react';

function ConditionalContent({ children }) {
  const [isVisible, setIsVisible] = useState(true);

  useRegisterSelect(
    (shouldBeVisible) => setIsVisible(shouldBeVisible),
    true // activeTrail - whether it should be called when a child is selected
  );

  if (!isVisible) return null;

  return <div className="conditional-content">{children}</div>;
}
```

### 公用事业

#### `updateUrlSearchParams(newParams, router)`

更新 URL 搜索参数,同时保留已有的参数。 用于通过 URL 过滤、 pagination 和状态管理 .

**类型签名 :**

```typescript
updateUrlSearchParams(
  newParams: Record<string, unknown>,
  router: NextRouter
): Record<string, unknown>
```

**示例**

```typescript
import { updateUrlSearchParams } from '@clutch-creator/toolkit';
import { useRouter } from 'next/router';

function ProductFilters() {
  const router = useRouter();

  const handleCategoryFilter = (category: string) => {
    updateUrlSearchParams({ category, page: 1 }, router);
    // URL: /products?category=electronics&page=1
  };

  const handlePriceRange = (min: number, max: number) => {
    updateUrlSearchParams({
      priceMin: min.toString(),
      priceMax: max.toString()
    }, router);
    // URL: /products?category=electronics&page=1&priceMin=100&priceMax=500
  };

  const clearFilters = () => {
    updateUrlSearchParams({
      category: null,
      priceMin: null,
      priceMax: null
    }, router);
    // URL: /products
  };

  return (
    <div>
      <button onClick={() => handleCategoryFilter('electronics')}>
        Electronics
      </button>
      <button onClick={() => handlePriceRange(100, 500)}>
        $100-$500
      </button>
      <button onClick={clearFilters}>Clear Filters</button>
    </div>
  );
}
```

#### `clutchElementConfig(element, config)`

用于可选配置的 Clutch 视觉编辑器的 React 组件 .

**类型签名 :**

```typescript
clutchElementConfig(
  element: React.FunctionComponent,
  config: {
    icon?: string;
    styleSelectors?: { name?: string; value: string }[];
  }
): void
```

**示例**

```typescript
import { clutchElementConfig } from '@clutch-creator/toolkit';

const Button = ({ children, variant = 'primary', ...props }) => (
  <button className={`btn btn-${variant}`} {...props}>
    {children}
  </button>
);

const Card = ({ title, children, ...props }) => (
  <div className="card" {...props}>
    <h3 className="card-title">{title}</h3>
    <div className="card-content">{children}</div>
  </div>
);

// Register components with Clutch editor
clutchElementConfig(Button, {
  icon: '🔘',
  styleSelectors: [
    { name: 'Hover', value: '&:hover' },
    { name: 'Disabled', value: '&:disabled' },
  ]
});

clutchElementConfig(Card, {
  icon: '🃏',
  styleSelectors: [
    { name: 'Card Hover', value: '&:hover' },
  ]
});
```

#### `logger`

有条件的日志功能,具有不同的开发与调试方法.

**类型签名 :**

```typescript
logger: {
  log(...args: unknown[]): void;      // Only in development
  debug(...args: unknown[]): void;    // Only when window.CLUTCH_DEBUG = true
  warn(...args: unknown[]): void;     // In development or server
  error(...args: unknown[]): void;    // In development or server
}
```

**示例**

```typescript
import { logger } from '@clutch-creator/toolkit';

function DataProcessor({ data }) {
  // Always logs in development
  logger.log('Processing data:', data);

  // Only logs when window.CLUTCH_DEBUG = true
  logger.debug('Debug info:', data);

  try {
    const processed = processData(data);
    logger.log('Data processed successfully:', processed);
    return processed;
  } catch (error) {
    logger.error('Error processing data:', error);
    logger.warn('Falling back to default data');
    return getDefaultData();
  }
}

// In browser console to enable debug logging:
// window.CLUTCH_DEBUG = true;
```

#### `cloneChildren(children, props)`

克隆反应儿童,并将给定道具应用于每个儿童元素. 过滤出与调试相关的道具,并同时处理独生子和数组子.

**类型签名 :**

```typescript
cloneChildren(
  children: React.ReactNode,
  props: Record<string, unknown>
): React.ReactNode
```

**示例**

```typescript
import { cloneChildren } from '@clutch-creator/toolkit';

function WrapperComponent({ children, className, onClick }) {
  // Clone children and add common props
  const clonedChildren = cloneChildren(children, {
    className: `child-element ${className}`,
    onClick: onClick,
    'data-wrapper': true
  });

  return <div className="wrapper">{clonedChildren}</div>;
}

// Usage
function App() {
  return (
    <WrapperComponent className="highlighted" onClick={() => console.log('clicked')}>
      <button>Button 1</button>
      <button>Button 2</button>
    </WrapperComponent>
  );
}
// Both buttons will receive className="child-element highlighted" and onClick handler
```

### 错误分类

#### `MissingEnvVariableError`

缺少所需环境变量时抛出 .

**类型签名 :**

```typescript
class MissingEnvVariableError extends Error {
  constructor(envName: string);
}
```

**示例**

```typescript
import { MissingEnvVariableError } from '@clutch-creator/toolkit';

function initializeApp() {
  const apiKey = process.env.NEXT_PUBLIC_API_KEY;
  const dbUrl = process.env.DATABASE_URL;

  if (!apiKey) {
    throw new MissingEnvVariableError('NEXT_PUBLIC_API_KEY');
  }

  if (!dbUrl) {
    throw new MissingEnvVariableError('DATABASE_URL');
  }

  // Initialize app with environment variables
  return { apiKey, dbUrl };
}

// Usage with error handling
try {
  const config = initializeApp();
} catch (error) {
  if (error instanceof MissingEnvVariableError) {
    console.error('Configuration error:', error.message);
    // Handle missing environment variable
  }
}
```

#### `InvalidEnvVariableError`

当环境变量有无效值时抛出 .

**类型签名 :**

```typescript
class InvalidEnvVariableError extends Error {
  constructor(envName: string);
}
```

**示例**

```typescript
import { InvalidEnvVariableError } from '@clutch-creator/toolkit';

function validateConfig() {
  const port = process.env.PORT;
  const nodeEnv = process.env.NODE_ENV;

  if (port && isNaN(parseInt(port))) {
    throw new InvalidEnvVariableError('PORT');
  }

  if (nodeEnv && !['development', 'production', 'test'].includes(nodeEnv)) {
    throw new InvalidEnvVariableError('NODE_ENV');
  }

  return {
    port: port ? parseInt(port) : 3000,
    nodeEnv: nodeEnv || 'development',
  };
}

// Usage
try {
  const config = validateConfig();
} catch (error) {
  if (error instanceof InvalidEnvVariableError) {
    console.error('Invalid configuration:', error.message);
    process.exit(1);
  }
}
```

### 控制类型

工具包用于 Clutch 编辑器中所使用的各种控制类型,导出全面的 TypeScript 类型 :

```typescript
import type { Controls } from '@clutch-creator/toolkit';

// Available control types:
// Array, Checkbox, Code, Color, Combobox, Component, File, Input,
// Json, Media, Number, Object, RichText, Select, Styles, Svg,
// TextArea, Url, Action
```

**示例**

```typescript
import type { Controls } from '@clutch-creator/toolkit';

type TSomeComponentProps = {
  // props.image will use a media control
  image: Controls["Media"],
  /**
   * You can also annotate a prop to set a control
   * @control CustomControl
   */
  anotherProp: string
}

export function SomeComponent = (props: TSomeComponentProps) {
  // ...
}
```

## 软件包导出

该工具包分为模块出口,用于特定用途:

### 构成部分

```typescript
// Individual component imports
import { Image } from '@clutch-creator/toolkit/components/Image';
import { ClientImage } from '@clutch-creator/toolkit/components/ClientImage';
import { Link } from '@clutch-creator/toolkit/components/Link';
import { Seo } from '@clutch-creator/toolkit/components/Seo';
import { RichText } from '@clutch-creator/toolkit/components/RichText';
import { Svg } from '@clutch-creator/toolkit/components/Svg';
import { ApplyHooks } from '@clutch-creator/toolkit/components/ApplyHooks';
import { NotFoundRedirect } from '@clutch-creator/toolkit/components/NotFoundRedirect';
import { Slot } from '@clutch-creator/toolkit/components/Slot';
```

-   **`Image`**ưμ㼯A 有自动占位符生成和优化的图像包
-   **`ClientImage`**: 用于动态图像加载的客户端图像组件
-   **`Link`**: 增强的下一个.js 链接组件,支持复杂的 URL 参数管理
-   **`Seo`**: 支持OpenGraph、Twitter卡和结构化数据的SEO综合组件
-   **`RichText`**: 支持字符串和JSX内容的灵活丰富的文本渲染器
-   **`Svg`**: SVG 组件包装器,用于动态 SVG 渲染
-   **`ApplyHooks`**: 对儿童适用多钩组件的组件
-   **`NotFoundRedirect`**: 处理404再定向的组件
-   **`Slot`**: 向儿童传递道具的功能部分(使用) `cloneChildren` 内部)

### 发展 工作流量

1.  叉子存储器
2.  创建特性分支 : `git checkout -b feature/amazing-feature`
3.  做你的改变
4.  运行测试 : `bun run test`
5.  运行林入 : `bun run lint`
6.  **创建更改列表**数字 : `bun run changeset` (如果您的更改会触发释放)
7.  提交更改 : `git commit -m 'feat: add amazing feature'`
8.  推到你的树枝: `git push origin feature/amazing-feature`
9.  创建拉动请求

在离合器项目中本地运行工具包,创建工具包的连锁:

```bash
bun link
```

然后在项目目录上:

```bash
bun link @clutch-creator/toolkit
```

您还需要在下一个配置中添加一些配置, 确保根路径足够返回到它嵌入工具包位置的地方 :

```js
const nextConfig: NextConfig = withClutch({
  transpilePackages: ['@clutch-creator/toolkit'],
  turbo: {
    root: path.join(__dirname, '../../../../..'),
  },
  outputFileTracingRoot: path.join(__dirname, '../../../../..'),
});
```

## 部署

这个项目使用 [更改](https://github.com/changesets/changesets) 用于自动版本和出版:

1.  创建更改列表 : `bun run changeset`
2.  将更改推到 `main` 分支
3.  GitHub 动作将自动 :
    -   创建带有版本更新的“ 释放 PR ”
    -   合并后,发布国家防范机制软件包并创建 GitHub 版本

## 许可证

麻省理工学院

## 捐款

这个工具包由克勒克团队维护. 关于问题和专题报道,请访问 [GitHub 仓库](https://github.com/clutch-creator/toolkit)。 。 。 .

## ++ 辅助

-   📚 [文档](https://docs.clutch.io/)
-   🐛 [报告问题](https://github.com/clutch-creator/toolkit/issues)
-   💬 [社区讨论](https://discord.gg/j4bnupeese)
-   🌐 [官方网站](https://clutch.io/)

* * *

由美国制造 [Clutch 团队](https://clutch.io/)

Clutch是下一代视觉构建者,赋予创作专业人士完全设计自由,高级功能,并具有顶级性能的能力. 学习更多 [离合器 io](https://clutch.io/)。 。 。 .

## 常见问题

### @clutch-creator/toolkit 是什么？

离合器项目中使用的工具包组件和提法

### 如何安装 @clutch-creator/toolkit？

在项目目录运行 npm install @clutch-creator/toolkit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：next（^16\.0\.1）、react（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clutch-creator/toolkit 支持 TypeScript 吗？

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

### @clutch-creator/toolkit 支持 ESM 还是 CommonJS？

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

### @clutch-creator/toolkit 可以商用吗？

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

### @clutch-creator/toolkit 的下载量有多少？

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

### @clutch-creator/toolkit 还在维护吗？

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