tdesign-create-component
This skill should be used when creating a new TDesign React component. It provides a complete SOP for scaffolding components in the packages/components or packages/pro-components directories, including file structure, code patterns, and registration steps.
ソース情報
- リポジトリ
- Tencent/tdesign-react
- ソースの最終更新活動
- 2026年3月16日 07:15
- 検出された SKILL.md の言語
- 中国語
- スター
- 968
- フォーク
- 377
インストール方法
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
ソースファイルを確認
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
ファイルエクスプローラー
2 ファイルSKILL.md を表示中
SKILL.md
ソースの指示 · 読み取り専用プレビュー- name
- tdesign-create-component
- description
- This skill should be used when creating a new TDesign React component. It provides a complete SOP for scaffolding components in the packages/components or packages/pro-components directories, including file structure, code patterns, and registration steps.
# TDesign 组件创建脚手架
本技能提供 TDesign React 新组件开发的完整 SOP 流程。
## 触发条件
当用户需要执行以下任务时使用此技能：
- 创建新的 TDesign 组件
- 初始化组件脚手架
- 添加新的基础组件或高阶组件
## SOP 流程
### Step 1: 确定组件类型和目标目录
根据组件性质选择目标位置：
| 组件类型 | 目录 | 说明 |
|---------|------|------|
| 基础组件 | `packages/components/` | 通用 UI 组件（button, input, select 等） |
| 高阶组件 | `packages/pro-components/` | 业务/AIGC 组件（chat, copilot 等） |
### Step 2: 创建组件目录结构
以组件名 `example-component`（PascalCase: `ExampleComponent`）为例：
```
packages/components/example-component/
├── index.ts # 组件入口
├── ExampleComponent.tsx # 组件主文件
├── type.ts # 类型定义（由 API 平台生成）
├── defaultProps.ts # 默认属性（由 API 平台生成）
├── example-component.md # 中文文档
├── example-component.en-US.md # 英文文档
├── style/
│ ├── index.js # Less 样式入口
│ └── css.js # CSS 样式入口
├── _example/
│ └── base.tsx # 基础示例
├── _usage/ # Live Demo 配置（可选）
│ └── props.json
└── __tests__/
└── vitest-example-component.test.tsx
```
### Step 3: 编写组件入口文件 (index.ts)
```typescript
import _ExampleComponent from './ExampleComponent';
import './style/index.js';
export type { ExampleComponentProps } from './ExampleComponent';
export * from './type';
export const ExampleComponent = _ExampleComponent;
export default ExampleComponent;
```
### Step 4: 编写组件主文件（标准模式）
使用 `forwardRef` + `useDefaultProps` 标准模式：
```typescript
import React, { forwardRef } from 'react';
import classNames from 'classnames';
import useConfig from '../hooks/useConfig';
import useDefaultProps from '../hooks/useDefaultProps';
import { TdExampleComponentProps } from './type';
import { exampleComponentDefaultProps } from './defaultProps';
export interface ExampleComponentProps extends TdExampleComponentProps {
// 扩展属性（如原生 HTML 属性）
}
const ExampleComponent = forwardRef<HTMLDivElement, ExampleComponentProps>(
(originProps, ref) => {
// 1. 合并默认属性
const props = useDefaultProps(originProps, exampleComponentDefaultProps);
const { className, style, ...restProps } = props;
// 2. 获取前缀配置
const { classPrefix } = useConfig();
const componentClass = `${classPrefix}-example-component`;
// 3. 计算类名
const rootClassName = classNames(componentClass, className);
// 4. 渲染
return (
<div ref={ref} className={rootClassName} style={style}>
{/* 组件内容 */}
</div>
);
}
);
ExampleComponent.displayName = 'ExampleComponent';
export default ExampleComponent;
```
### Step 5: 编写类型定义文件 (type.ts)
⚠️ **重要**：此文件由 API 平台生成，不应手动编辑。
临时开发时可以先写一个简化版本，后续由 API 平台覆盖：
```typescript
/* eslint-disable */
/**
* 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
* */
import { TNode, StyledProps } from '../common';
export interface TdExampleComponentProps extends StyledProps {
/**
* 组件内容
*/
children?: TNode;
/**
* 是否禁用
* @default false
*/
disabled?: boolean;
}
```
### Step 6: 编写默认属性文件 (defaultProps.ts)
⚠️ **重要**：此文件由 API 平台生成，不应手动编辑。
```typescript
/**
* 该文件为脚本自动生成文件，请勿随意修改。如需修改请联系 PMC
* */
import { TdExampleComponentProps } from './type';
export const exampleComponentDefaultProps: TdExampleComponentProps = {
disabled: false,
};
```
### Step 7: 编写样式入口文件
**style/index.js**（引用 Less 源文件）：
```javascript
import '../../_common/style/web/components/example-component/index.less';
```
**style/css.js**（引用编译后 CSS）：
```javascript
import '../../_common/style/web/components/example-component/index.css';
```
### Step 8: 编写基础示例 (_example/base.tsx)
```tsx
import React from 'react';
import { ExampleComponent } from 'tdesign-react';
export default function ExampleComponentBase() {
return <ExampleComponent>基础用法</ExampleComponent>;
}
```
### Step 9: 编写测试文件
位置: `__tests__/vitest-example-component.test.tsx`
```tsx
import { render } from '@testing-library/react';
import ExampleComponent from '../ExampleComponent';
describe('ExampleComponent', () => {
it('renders correctly', () => {
const { container } = render(<ExampleComponent />);
expect(container.firstChild).toHaveClass('t-example-component');
});
it('supports disabled state', () => {
const { container } = render(<ExampleComponent disabled />);
expect(container.firstChild).toHaveClass('t-is-disabled');
});
});
```
### Step 10: 注册组件到导出入口
编辑 `packages/components/index.ts`，添加导出：
```typescript
// 在文件末尾添加
export * from './example-component';
```
### Step 11: 注册组件到站点配置
编辑 `packages/tdesign-react/site/site.config.mjs`：
```javascript
{
title: '基础组件',
type: 'component',
children: [
// ... 其他组件
{
title: 'ExampleComponent 示例组件',
name: 'example-component',
path: '/react/components/example-component',
component: () => import('tdesign-react/example-component/example-component.md'),
},
],
}
```
### Step 12: 编写组件文档 (example-component.md)
组件文档采用 **Markdown + `{{ xxx }}` 占位符** 机制，占位符会在站点构建时自动解析为 `_example/xxx.tsx` 中导出的 React 组件。
**基础组件** 使用双层拼接：
- **文档主体**（跨框架通用）：`packages/common/docs/web/api/<component>.md` — 包含使用说明文本和 `{{ xxx }}` 示例占位符，这是文档的核心内容
- **框架入口**（React 特有）：`packages/components/<component>/<component>.md` — 以 `:: BASE_DOC ::` 开头自动引入上层文档主体，后面追加 React 特有的 API 表格
> ⚠️ 当 `<component>.md` 以 `:: BASE_DOC ::` 开头时，文档的使用说明和示例占位符**不在这个文件中**，而是在 `packages/common/docs/web/api/<component>.md` 里。
**映射规则**：每个 `{{ xxx }}` 对应 `_example/xxx.tsx`，文件必须默认导出一个 React 组件。
```markdown
---
title: ExampleComponent 示例组件
description: 组件的一句话描述。
isComponent: true
usage: { title: '', description: '' }
spline: base
---
:: BASE_DOC ::
## API
{{ api }}
```
> ⚠️ 新增示例时，必须同时：
> 1. 在 `_example/` 下创建对应的 `.tsx` 文件
> 2. 在 Markdown 中添加对应的 `{{ xxx }}` 占位符
> 占位符名称必须与文件名（不含扩展名）**完全一致**。
## 关键规范引用
执行时应参考以下规范：
1. **CSS 命名**: 参考 `.codebuddy/specs/css-naming-spec.md`
- 前缀使用 `t-`
- BEM 命名：`t-[component]__[element]--[modifier]`
- 状态类：`t-is-*`
2. **API 设计**: 参考 `.codebuddy/specs/api-design-spec.md`
- 使用 `TNode` 类型定义可定制内容
- 事件命名使用 `on` 前缀
- `size` 属性固定三档：`small/medium/large`
3. **构建产物**: 参考 `.codebuddy/specs/build-output-spec.md`
- 确保 style/ 目录正确配置
## 常见模式
### 受控/非受控模式
```typescript
import useControlled from '../hooks/useControlled';
const [value, onChange] = useControlled(props, 'value', props.onChange);
```
### TNode 渲染
```typescript
import parseTNode from '../_util/parseTNode';
// 在 JSX 中
{parseTNode(props.content)}
```
### 静态方法组件（如 Message）
使用 `forwardRefWithStatics` 挂载静态方法：
```typescript
import { forwardRefWithStatics } from '../_util/forwardRefWithStatics';
const ComponentWithStatics = forwardRefWithStatics(Component, {
info: MessagePlugin.info,
success: MessagePlugin.success,
});
```
## 检查清单
创建完成后，请确认：
- [ ] 组件目录结构完整
- [ ] 使用 forwardRef + useDefaultProps 标准模式
- [ ] 使用 useConfig() 获取前缀，未硬编码 `t-`
- [ ] type.ts 和 defaultProps.ts 标记为自动生成
- [ ] 已注册到 index.ts 和 site.config.mjs
- [ ] 基础示例可正常运行
- [ ] 测试文件可通过
GitHubで見る