SuperAPI AI Directory

tdesign-create-component

Coding & development

View repository

Updated 10-16 08:24

About this skill

TDesign component creation scaffold

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>.md starts with :: BASE_DOC :: , the documentation's usage description and example placeholdersare not in this file, but in packages/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:

  1. Create the corresponding _example/ file under .tsx File
  2. 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:

  1. CSS Naming: Reference .codebuddy/specs/css-naming-spec.md

    • Use prefix t-
    • BEM naming:t-[component]__[element]--[modifier]
    • State classes:t-is-*
  2. API Design: Reference .codebuddy/specs/api-design-spec.md

    • Use TNode type definitions for customizable content
    • Event naming uses the on prefix
    • size properties are fixed at three levels:small/medium/large
  3. 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