getting-started.md

title	description	spline	isGettingStarted
TDesign Web Components	TDesign 适配桌面端的组件库，可以在任何前端项目中使用。	explain	true

安装

使用 npm 安装

推荐使用 npm 方式进行开发

npm i tdesign-web-components

浏览器引入（敬请期待）

基础使用

无需额外配置即可实现组件按需引入：

import 'tdesign-web-components/lib/style/index.css'; // 少量公共样式
import 'tdesign-web-components/lib/button';

也可以整体引入

import 'tdesign-web-components/lib/style/index.css'; // 少量公共样式
import 'tdesign-web-components';

然后按照以下写法使用即可

document.body.innerHTML = `<t-button theme="success">按钮</t-button>`;

工程化使用

如果使用vite打包工具，需要在vite.config.ts中添加以下配置，设置vite解析jsx的逻辑：

import { defineConfig } from 'vite'
export default defineConfig({
+   esbuild: {
+     jsxFactory: 'h',
+     jsxFragment: 'h.f',
+   },
})

注意：在vite >= 5.x 版本中，需要使用下面的vite插件，其它版本可跳过

import lessCompilerPlugin from 'tdesign-web-components/plugins/vite-plugin-less-compiler';

// vite.config.ts
export default defineConfig({
  plugins: [lessCompilerPlugin({
    lessOptions: {} // less 相关参数
  })]
})

如果使用webpack打包工具，需要在babel中设置jsx的解析逻辑：

{
  "presets": [
    ...
+   [
+     "@babel/preset-react",
+     {
+       "pragma": "h",
+       "pragmaFrag": "h.f"
+     }
+   ]
+  ],
   ...
}

更改主题

由于原始样式基于 less 编写，需要自行处理 less 文件的编译（例如安装 less、less-loader）

更多 less 变量定义 查看这里

import 'tdesign-web-components/esm/button'
import 'tdesign-web-components/esm/style/index.js' // 少量公共样式

在 vite 中定制主题

// vite.config.js
export default {
  css: {
    preprocessorOptions: {
      less: {
        modifyVars: {
          '@btn-height-default': '40px',
        },
      },
    },
  },
};

在 webpack 中定制主题

// webpack.config.js
module.exports = {
  rules: [{
    test: /\.less$/,
    use: [{
      loader: 'css-loader',
      options: {
+       exportType: 'string', // translates CSS into string
      },
    }, {
      loader: 'less-loader', // compiles Less to CSS
+     options: {
+       lessOptions: { // 如果使用less-loader@5，请移除 lessOptions 这一级直接配置选项。
+         modifyVars: {
+           '@btn-height-default': '40px',
+         },
+         javascriptEnabled: true,
+       },
+     },
    }],
+   include: /node_modules\/tdesign-web-components/, // 建议对组件库中的less单独处理
  }],
}

更改样式

有些业务场景需要更改组件的样式，但是shadowDOM具有天然样式隔离的特点，组件外部的样式影响不到组件内部，为此 TDesign Web Components 提供了几种方式来对样式进行更改：

通过设置css属性，来修改样式（推荐）

目前每一个组件，都默认有一个css的属性，设置该值时会在shadowDOM内部创建style标签：

<t-button css="button.t-button {color: red}">填充按钮</t-button>

会在组件内部，创建style标签，改变内部样式：

<!-- DOM结构 -->
<t-button
  #shadow-root
    <button>...</button>
    <style>
      button.t-button {
        color: red;
      }
    </style>
</t-button>

通过设置style、innerStyle来改变样式

任意组件，均可设置style和innerStyle，约定style只在最外层标签上起作用：

<!-- 设置style -->
<t-button style={{ color: 'red' }}>填充按钮</t-button>

<!-- DOM结构 -->
<t-button style="color: red">
  #shadow-root
    <button>...</button>
</t-button>

约定innerStyle只在shadowDOM内部第一层标签上起作用：

<!-- 设置innerStyle -->
<t-button innerStyle={{ color: 'red' }}>填充按钮</t-button>

<!-- 对应DOM结构 -->
<t-button>
  #shadow-root
    <button style="color: red">...</button>
</t-button>

通过设置class、innerClass来改变样式（可以和css属性搭配使用）

任意组件，均可设置class和innerClass，约定class只在最外层标签上起作用：

<!-- 设置class -->
<t-button class="customClass">填充按钮</t-button>

<!-- 对应DOM结构 -->
<t-button class="customClass">
  #shadow-root
    <button>...</button>
</t-button>

约定innerClass只在shadowDOM内部第一层标签上起作用：

<!-- 设置innerStyle -->
<t-button innerClass="customClass">填充按钮</t-button>

<!-- 对应DOM结构 -->
<t-button>
  #shadow-root
    <button class="customClass">...</button>
</t-button>

后续会推出基于打包工具的样式注入插件，敬请期待...

浏览器兼容性

IE / Edge	Firefox	Chrome	Safari
Edge >=84	Firefox >=83	Chrome >=84	Safari >=14.1

FAQ

Q: 是否内置 reset 样式统一页面元素的默认样式 ？

A: 我们不引入 reset.less