TDesign Vue 2.x UI Library

Common errors

• [Vue warn]: Unknown custom element: <t-button> - did you register the component correctly?

  cause TDesign components were not properly registered with the Vue application, or styles were not imported, leading to rendering issues.
  fix Ensure you have `import Vue from 'vue'; import TDesign from 'tdesign-vue'; import 'tdesign-vue/es/style/index.css'; Vue.use(TDesign);` in your main application entry file (e.g., `main.js`). If using individual imports, make sure each component is imported and registered (either globally or in the component's `components` option).

• Module not found: Error: Can't resolve 'tdesign-vue/es/style/index.css'

  cause The main CSS file for TDesign Vue is missing or the import path is incorrect. This can happen if the package is not installed correctly or the build tool cannot locate the stylesheet.
  fix Verify that `tdesign-vue` is correctly installed (`npm install tdesign-vue`) and ensure the import path `import 'tdesign-vue/es/style/index.css';` is correct in your main application entry point. Also, check your build configuration (e.g., Webpack, Vite) for CSS loading.

• Property 'alert' does not exist on type 'Vue'.

  cause This TypeScript error occurs when a TDesign plugin method, like `$alert`, is accessed on the Vue instance (`this`) but the TypeScript compiler does not know about it. This is usually due to missing or incorrect global type declarations.
  fix Ensure that TDesign's global type declarations are included in your TypeScript configuration. For `tdesign-vue`, you might need to add `node_modules/tdesign-vue/global.d.ts` to your `tsconfig.json`'s `include` array or create a custom `d.ts` file to augment the `Vue` interface if auto-detection fails.

Warnings

• breaking The `tdesign-icons-vue` dependency, which provides icons for `tdesign-vue`, underwent significant changes in version 0.4.x (released with `tdesign-vue` 1.14.0). Several icons, specifically `video-camera-3`, `video-camera-3-filled`, and `list`, were removed.
  Fix: Review your application for usage of the removed icons. Update your icon references to available alternatives or remove them. Consult the `tdesign-icons-vue` documentation for the latest icon set.
• breaking The `ColorPicker` component in `tdesign-vue` 1.12.0 introduced changes to its gradient mode and removed the `HSB` format. Businesses relying on the `ColorPicker`'s gradient functionality or the `HSB` color format should be aware of these breaking changes.
  Fix: For `ColorPicker` users, verify your implementation if using gradient mode or the `HSB` format. Adjust your color format conversions to `HEX8` or other supported formats as necessary. Refer to the `ColorPicker` documentation for updated API details.
• deprecated The `Alert` component's `close` API was deprecated in favor of `closeBtn` in version 1.13.0. The `close` prop will be removed in a future major version.
  Fix: Migrate your `Alert` component usage from the `close` prop to `closeBtn` to ensure future compatibility. For example, change `<t-alert close />` to `<t-alert closeBtn />`.
• gotcha This library (`tdesign-vue`) is specifically built for Vue 2.x. It is not directly compatible with Vue 3.x applications. Attempting to use it in a Vue 3 project will lead to runtime errors or unexpected behavior, as `tdesign-vue-next` is the dedicated Vue 3 version.
  Fix: Ensure your project is running Vue 2.x. If you are developing for Vue 3.x, use `tdesign-vue-next` instead. If migrating a Vue 2 project using `tdesign-vue` to Vue 3, a full migration to `tdesign-vue-next` or careful use of Vue 3's compatibility build (`@vue/compat`) would be required, though direct `tdesign-vue` integration with `@vue/compat` is not officially supported by TDesign.

Install

• npm install tdesign-vue npm
• yarn add tdesign-vue yarn
• pnpm add tdesign-vue pnpm

Imports

• TDesign
  wrong:

  const TDesign = require('tdesign-vue');

  correct:

  import Vue from 'vue';
  import TDesign from 'tdesign-vue';
  import 'tdesign-vue/es/style/index.css';
  
  Vue.use(TDesign);

  Imports and globally registers all TDesign components and global styles for Vue 2 applications. This is a common setup for full library usage.
• Button
  wrong:

  import Button from 'tdesign-vue/lib/button';

  correct:

  import { Button } from 'tdesign-vue';

  For tree-shaking and on-demand component loading, import individual components as named exports directly from 'tdesign-vue'. This is the recommended approach for specific component usage.
• TButtonProps

  import type { ButtonProps as TButtonProps } from 'tdesign-vue';

  The library ships with TypeScript types. Use type imports for component props or other utility types for enhanced type safety in TypeScript projects.

Quickstart

This quickstart demonstrates how to globally import and register TDesign Vue components and styles, then use a `TButton` and `TDatePicker` in a basic Vue 2 application.

import Vue from 'vue';
import TDesign from 'tdesign-vue';
import 'tdesign-vue/es/style/index.css';

// Import specific component styles if needed, or rely on global styles
// import 'tdesign-vue/es/button/style/index.css';

Vue.use(TDesign);

new Vue({
  el: '#app',
  template: `
    <div id="app">
      <t-space direction="vertical">
        <h1>TDesign Vue Quickstart</h1>
        <t-button theme="primary" @click="handleClick">Hello TDesign!</t-button>
        <t-date-picker />
      </t-space>
    </div>
  `,
  methods: {
    handleClick() {
      this.$alert('Button Clicked!', 'Info');
    }
  }
});