快速开始

at 是基于 Teambition 设计体系的 React UI 组件库,主要用于研发企业级中前台产品。

支持环境

  • 现代浏览器和 IE9 及以上(IE需要 polyfills)。

  • 支持服务端渲染。

安装

使用 npm 安装

我们推荐使用 npm 的方式进行开发,不仅可在开发环境轻松调试,也可放心地在生产环境打包部署使用,享受整个生态圈和工具链带来的诸多好处。

$ npm i @txdfe/at --save

浏览器引入

也可以在浏览器中使用 scriptlink 标签直接引入 CDN 资源,同时会导出全局变量 AT

  • 通过 引入当前组件库最新资源:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@txdfe/at/build/teambition.min.css" />
<script src="https://cdn.jsdelivr.net/npm/@txdfe/at/build/at.min.js"></script>
  • 引入指定版本的组件库资源:
<link rel="stylesheet" href="https://g.alicdn.com/aisc/at/{{version}}/teambition.min.css" />
<script src="https://g.alicdn.com/aisc/at/{{version}}/at.min.js"></script>

其中 version 代表组件库版本号,当前最新版本为 npm package

注意:引入 at.min.js 前你需要自行引入 reactmoment 。@txdfe/at 基于 react@16 开发,目前并不兼容 react@15 及其以下的版本,且将 react/react-dom 作为 peerDependencies,需要用户手动提前安装或引入。采用 CDN 形式引入时,需要在 webpack 配置中 externals 掉@txdfe/at,通用配置如下。否则使用的是 npm 包,CDN 版本无效。

// webpack config
externals: {
  '@txdfe/at': {
    root: 'AT',
    amd: '@txdfe/at',
    commonjs: '@txdfe/at',
    commonjs2: '@txdfe/at',
  },
}

示例

import { Button } from '@txdfe/at';
ReactDOM.render(<Button />, mountNode);

如果没有通过浏览器引入样式资源的话,可以在工程中引入全量样式文件:

import "@txdfe/at/build/teambition.min.css";

第一个例子

这是一个最简单的 at 组件的在线演示。

按需加载

注意:@txdfe/at 默认支持基于 ES module 的 tree shaking。对于 js 部分,直接引入import Button from '@txdfe/at'也会有按需加载的效果。对于 css 部分,首先需要通过 sass-loader 将 scss 变量注入到样式文件中,具体代码如下:

// webpack config
{
	loader: 'sass-loader',
    options: {
      data: '@import "~@txdfe/at-theme/teambition/scss/index.scss";\n',
	  // prependData: '@import "~@txdfe/at-theme/teambition/scss/index.scss";\n',
    },
},
// 如果sass-loader的版本为8.x,请使用prependData

然后可以通过以下的写法来按需加载组件:

  • 手动引入
import Button from '@txdfe/at/es/button'; // 加载 JS
import '@txdfe/at/es/button/style'; // 加载 CSS
  • 使用 babel-plugin-import
import { Button } from '@txdfe/at';

通过 babel-plugin-import 插件,可以将上述代码转化为类似下面的代码:

import Button from '@txdfe/at/es/button'; // 加载 JS
import '@txdfe/at/es/button/style'; // 加载 CSS

babel配置:

// webpack babel loader option or babel.config.js
{
  // ...
  plugins: [
    ['babel-plugin-import', {
    libraryName: '@txdfe/at',
    style: (name) => {
      if (name === '@txdfe/at/es/field') {
        return false;
      }
      return `${name}/style`;
    }}]
  ]
}

更换主题

不同的应用有不同的主题色。为了保证设计的一致性并节省用户的识别成本,主题包支持 7 级色阶定制。

TB 所有应用使用同一个主题包。每个应用仅内对 7 级主题色变量重新赋值 css var。

主题变量定义方式,在页面模板 head 标签内,在AT组件库样式资源前:

<style>
 :root {
   --highlight-brand: #edf7ff;
   --bright-brand: #cce7ff;
   --border-brand: #70b8ff;
   --primary-brand: #006cfa;
   --hover-brand: #0054d8;
   --click-brand: #0042b2;
   --heavy-brand: #003194;
 }
</style>
<!-- AT 组件库 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@txdfe/at/build/teambition.min.css" />

获取当前使用版本

@txdfe/at导出一个属性version,可通过该属性获取当前使用的版本信息。

import { version } from '@txdfe/at';
console.log(version);

注意事项

减小应用中 webpack 打包 moment 体积

AT 中将 moment 作为自己的 devDependencies 而非 dependencies,所以用户需要自己在应用中引入 moment 的 cdn 文件 moment-with-locales.js 或者本地安装 moment 打包进自己的应用。对于后者,由于 moment 在引入 locale 文件时存在这样的代码:require('./locale/' + name),如果用 webpack 构建,会打包进所有的 locale 文件,增加构建后文件的体积,目前社区比较主流的解决方案有以下两种:

const webpack = require('webpack');
module.exports = {
  // ...
  plugins: [
    // 打包指定需要的语言文件
    new webpack.ContextReplacementPlugin(/moment[\/\\]locale$/, /zh-cn|ja/),
    // 只打包有过引用的语言文件,应用中需要添加如:`import 'moment/locale/zh-cn';`
    // new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/)
  ],
};