TDesign 快速上手实用指南

TDesign 作为企业级设计系统，提供了组件化开发解决方案，帮助开发者快速构建一致、高质量的用户界面。本文将通过五阶段递进式结构，带你从零开始掌握 TDesign 的基础使用流程。

准备：开发环境配置

环境要求清单

软件/工具	最低版本要求	推荐版本
Node.js	14.0.0	16.0.0+
包管理工具	npm 6.0.0 / yarn 1.22.0 / pnpm 5.0.0	npm 8.0.0+ / pnpm 7.0.0+
Git	2.20.0	2.30.0+

环境检查方法

打开终端执行以下命令，验证环境是否满足要求：

# 检查 Node.js 版本
node -v

# 检查 npm 版本
npm -v

# 检查 Git 版本
git --version

📌 知识拓展：Node.js 版本过低可能导致依赖安装失败，建议使用 nvm 或 n 等版本管理工具切换到推荐版本。

获取：项目源码与依赖

通过版本控制工具获取源码

使用 Git 将项目代码克隆到本地：

git clone https://gitcode.com/gh_mirrors/tde/tdesign
cd tdesign

安装项目依赖

进入项目目录后，使用包管理工具安装依赖：

# 使用 npm
npm install

# 或使用 pnpm (推荐)
pnpm install

🔧 操作提示：依赖安装过程可能需要几分钟时间，取决于网络状况和计算机性能。

配置：开发环境启动

启动开发服务器

执行以下命令启动本地开发服务器：

# npm 方式
npm run dev

# pnpm 方式
pnpm dev

启动成功后，终端会显示访问地址，通常为 http://localhost:3000。在浏览器中打开该地址，即可看到 TDesign 的演示站点。

开发环境验证

访问开发服务器后，确认以下内容正常显示：

• 导航菜单可以正常展开/收起
• 组件展示区域能正确加载
• 页面响应式布局在不同窗口大小下正常显示

📝 注意事项：如果启动失败，检查终端错误信息，通常是端口占用或依赖缺失导致。可尝试使用 npm run dev -- --port 3001 更换端口。

实践：组件使用与页面构建

基础组件使用示例

以下是一个简单的页面布局示例，展示如何使用 TDesign 组件构建页面结构：

// 导入必要的组件和样式
import { TdDocLayout, TdHeader, TdDocAside, TdDocContent } from "@tdesign/site-components";
import "@tdesign/site-components/lib/styles/style.css";

// 页面组件结构
function App() {
  return (
    <TdDocLayout>
      {/* 页头区域 */}
      <TdHeader slot="header" />
      
      {/* 侧边导航 */}
      <TdDocAside slot="doc-aside" title="组件文档" />
      
      {/* 主内容区域 */}
      <TdDocContent slot="doc-content">
        <h1>组件使用示例</h1>
        <p>这是一个使用 TDesign 组件构建的页面示例</p>
        
        {/* 组件演示区域 */}
        <TdDocDemo>
          {/* 这里放置具体组件示例 */}
        </TdDocDemo>
      </TdDocContent>
    </TdDocLayout>
  );
}

布局组件效果展示

TDesign 提供了多种预设布局，帮助快速搭建页面结构：

🔍 组件探索：在开发服务器中浏览 /components 路径，查看所有可用组件的演示和代码示例。

拓展：构建部署与进阶学习

构建生产版本

开发完成后，执行以下命令构建生产版本：

# npm 方式
npm run build

# pnpm 方式
pnpm build

构建产物将输出到项目的 dist 目录，可直接部署到 Web 服务器。

官方资源导航

入门级资源

• 快速开始指南：docs/introduce.md
• 组件基础示例：packages/site-components/src/components/

进阶级资源

• 设计规范文档：docs/design/
• 主题定制指南：packages/theme-generator/

专家级资源

• 源码贡献指南：docs/contributing.md
• 组件开发文档：docs/new-component.md

🚀 学习路径：建议从组件使用开始，熟悉基础后尝试主题定制，最后深入源码了解实现原理。

通过以上五个阶段的学习，你已经掌握了 TDesign 的基本使用方法。继续探索更多组件和高级功能，打造专业的企业级用户界面吧！