This skill provides the complete SOP process for developing new TDesign React components.
Trigger conditions
Use this skill when the user needs to perform the following tasks:
- Create a new TDesign component
- Initialize the component scaffold
- Add a new basic component or higher-order component
SOP process
Step 1: Determine the component type and target directory
Select the target location based on the nature of the component:
| Component type | Directory | Description |
|---|---|---|
| Basic component | packages/components/ |
General UI components (button, input, select, etc.) |
| Higher-order component | packages/pro-components/ |
Business/AIGC components (chat, copilot, etc.) |
Step 2: Create the component directory structure
Using the component name example-component(PascalCase: ExampleComponent) as an example:
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: Write the component entry file (index.ts)
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: Write the component main file (standard mode)
Use the forwardRef + useDefaultProps standard mode:
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: Write the type definition file (type.ts)
⚠️ Important: This file is generated by the API platform and should not be edited manually.
During temporary development, you can first write a simplified version, which will later be overwritten by the API platform:
/* eslint-disable */
/**
* 该文件为脚本自动生成文件,请勿随意修改。如需修改请联系 PMC
* */
import { TNode, StyledProps } from '../common';
export interface TdExampleComponentProps extends StyledProps {
/**
* 组件内容
*/
children?: TNode;
/**
* 是否禁用
* @default false
*/
disabled?: boolean;
}
Step 6: Write the default props file (defaultProps.ts)
⚠️ Important: This file is generated by the API platform and should not be edited manually.
/**
* 该文件为脚本自动生成文件,请勿随意修改。如需修改请联系 PMC
* */
import { TdExampleComponentProps } from './type';
export const exampleComponentDefaultProps: TdExampleComponentProps = {
disabled: false,
};
Step 7: Write the style entry file
style/index.js(reference the Less source file):
import '../../_common/style/web/components/example-component/index.less';
style/css.js(reference the compiled CSS):
import '../../_common/style/web/components/example-component/index.css';
Step 8: Write a basic example (_example/base.tsx)
import React from 'react';
import { ExampleComponent } from 'tdesign-react';
export default function ExampleComponentBase() {
return <ExampleComponent>基础用法</ExampleComponent>;
}
Step 9: Write the test file
Location: __tests__/vitest-example-component.test.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: Register the component in the export entry
Edit packages/components/index.ts, add the export:
// 在文件末尾添加
export * from './example-component';
Step 11: Register the component in the site configuration
Edit packages/tdesign-react/site/site.config.mjs:
{
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: Write the component documentation (example-component.md)
Component documentation uses the Markdown + {{ xxx }} placeholder mechanism; placeholders are automatically resolved at site build time to the React components exported from _example/xxx.tsx .
Basic component uses double-layer assembly:
- Documentation body(cross-framework common):
packages/common/docs/web/api/<component>.md— contains the usage description text and{{ xxx }}example placeholders, which are the core content of the documentation - Framework entry(React-specific):
packages/components/<component>/<component>.md— starts with:: BASE_DOC ::to automatically import the upper-layer documentation body, followed by the React-specific API table
⚠️ When
<component>.mdstarts with:: BASE_DOC ::, the documentation's usage description and example placeholdersare not in this file, but inpackages/common/docs/web/api/<component>.md.
Mapping rule: each {{ xxx }} corresponds to _example/xxx.tsx, and the file must default-export a React component.
---
title: ExampleComponent 示例组件
description: 组件的一句话描述。
isComponent: true
usage: { title: '', description: '' }
spline: base
---
:: BASE_DOC ::
## API
{{ api }}
⚠️ When adding a new example, you must simultaneously:
- Create the corresponding
_example/file under.tsxFile- Add the corresponding
{{ xxx }}placeholder in the Markdown The placeholder name must exactly match the file name (without extension)Fully consistent。
Key specification references
During execution, refer to the following specifications:
-
CSS Naming: Reference
.codebuddy/specs/css-naming-spec.md- Use prefix
t- - BEM naming:
t-[component]__[element]--[modifier] - State classes:
t-is-*
- Use prefix
-
API Design: Reference
.codebuddy/specs/api-design-spec.md- Use
TNodetype definitions for customizable content - Event naming uses the
onprefix sizeproperties are fixed at three levels:small/medium/large
- Use
-
Build Output: Reference
.codebuddy/specs/build-output-spec.md- Ensure the style/ directory is correctly configured
Common Patterns
Controlled/Uncontrolled mode
import useControlled from '../hooks/useControlled';
const [value, onChange] = useControlled(props, 'value', props.onChange);
TNode rendering
import parseTNode from '../_util/parseTNode';
// 在 JSX 中
{parseTNode(props.content)}
Static method components (e.g., Message)
Use forwardRefWithStatics to mount static methods:
import { forwardRefWithStatics } from '../_util/forwardRefWithStatics';
const ComponentWithStatics = forwardRefWithStatics(Component, {
info: MessagePlugin.info,
success: MessagePlugin.success,
});
Checklist
After creation is complete, please confirm:
- Component directory structure is complete
- Uses the forwardRef + useDefaultProps standard pattern
- Uses useConfig() to get the prefix, without hardcoding
t- - type.ts and defaultProps.ts are marked as auto-generated
- Registered in index.ts and site.config.mjs
- Basic example runs properly
- Test files pass