@actinc/dls 中文文档教程

Question

Design Language System (DLS)

ACT 前端项目的设计语言系统。 查看 UI 组件 此处。

Project Setup

Installation

为了使用 DLS，您必须将其与 Material UI 版本 4.x 和 React 版本 16.x 或 17.x。

npm install --save @actinc/dls@latest @material-ui/core@4 react@17 react-dom@17

Choosing a Theme

这个 DLS 建立在 主题引擎 来自 Material UI，并附带两个开箱即用的主题：

1. "ACT": for ACT's "traditional" look and feel
2. "ACT_ET": for ACT's "Emerging Technology" look and feel
3. "ENCOURA_DATALAB": for Encoura's "Datalab" look and feel

要将这些主题之一应用到您的组件，只需包装您的应用程序 在 ThemeProvider 组件中指定一个主题！

import { ThemeProvider } from '@actinc/dls/components';

...

const MyApp = () => (
  // specify a theme here!
  <ThemeProvider theme="ACT_ET">
    <App />
  </ThemeProvider>
);

Extending Themes

您可以使用扩展核心 DLS 主题 createTheme 来自 Material UI 的生成器：

import { createTheme } from '@material-ui/core/styles';
import { merge } from 'lodash';
import { THEME_ACT } from '@actinc/dls/styles/themeAct';
import { ThemeProvider } from '@actinc/dls/components';

const myExtendedTheme = createTheme(merge(THEME_ACT_ET, {
  // theme customizations go here!
}));

const MyApp = () => (
  <ThemeProvider theme={myExtendedTheme}>
    <App />
  </ThemeProvider>
);

Custom Themes

或者，您可以使用 createTheme 来自 Material UI

import { createTheme } from '@material-ui/core/styles';
import { ThemeProvider } from '@actinc/dls/components';

const myCustomTheme = createTheme({
  // build your theme here!
});

const MyApp = () => (
  <ThemeProvider theme={myCustomTheme}>
    <App />
  </ThemeProvider>
);

Load Fonts

Montserrat

的生成器：ACT 和 ACT_ET 主题假定 Montserrat 字体可用于 浏览器。 因此，建议您包括以下字体 在 React 应用程序

<link
  href="https://fonts.googleapis.com/css?family=Montserrat:300,400,500,600,700&display=swap"
  rel="stylesheet"
/>

Museo

的 head 中引用：ENCOURA_DATALAB 主题假定 Museo 字体 在浏览器中可用。 因此，建议您包括 在 React 应用程序的 head 中引用以下字体：

<style type="text/css">
  @font-face {
    font-family: 'Museo';
    src: url('path/to/Museo300.otf');
    font-style: normal;
    font-weight: 300;
  }
  @font-face {
    font-family: 'Museo';
    src: url('path/to/Museo500.otf');
    font-style: normal;
    font-weight: 500;
  }
  @font-face {
    font-family: 'Museo';
    src: url('path/to/Museo700.otf');
    font-style: normal;
    font-weight: 700;
  }
</style>

CSS Baseline

建议从 Material UI 附近注入 CssBaseline 组件 组件树的根，以便重置和规范化浏览器样式 对于你的项目：

import { CssBaseline } from '@material-ui/core';

...

const MyApp = () => (
  ...
  <CssBaseline />
  ...
);

Server-Side Rendering

如果你的项目的 React 框架支持 SSR，你可以配置 DLS 使用 ServerStyleSheets 导出的服务器端渲染组件 来自 Material UI。

例如，在 Next.js 项目中，您可以添加 以下是您的 pages/_document.tsx 文件：

import { ServerStyleSheets } from '@material-ui/core/styles';

...

class Document extends DocumentImport<Props> {
  static async getInitialProps(ctx: Context): Promise<Props> {
    ...

    const sheets = new ServerStyleSheets();
    const originalRenderPage = ctx.renderPage;

    ctx.renderPage = (): void =>
      originalRenderPage({
        enhanceApp: (App: any): any => (props: any): any =>
          sheets.collect(<App {...props} />),
      });

    ...

    return {
      ...
      styles: sheets.getStyleElement(),
      ...
    }
  }

  ...
}

Icons

DLS 重新导出由 mdi-material-ui 包。

您可以搜索要使用的特定图标 materialdesignicons.com。 一旦你找到 完美的图标，你可以像这样在你的项目中使用它：

import { PollBox } from '@actinc/dls/icons';

...

const MyComponent = () => (
  ...
  <PollBox />
  ...
);

Minimizing Bundle Size

如果你使用命名导入从 ACT DLS 导入模块，更多代码可能是 加载到内存中比你需要的。 为了在保持使用命名导入的同时 您的包大小尽可能小，我们建议配置 babel-plugin-transform-imports Babel 的插件。

npm install --save-dev babel-plugin-transform-imports

然后将以下内容添加到您的 Babel 配置文件（例如 .babelrc.js）：

module.exports = {
  plugins: [
    ...
    [
      'babel-plugin-transform-imports',
      {
        '@material-ui/core': {
          preventFullImport: true,
          transform: '@material-ui/core/${member}',
        },
        '@material-ui/core/colors': {
          preventFullImport: true,
          transform: '@material-ui/core/colors/${member}',
        },
        '@actinc/dls/components': {
          transform: '@actinc/dls/components/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/constants': {
          transform: '@actinc/dls/constants/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/context': {
          transform: '@actinc/dls/context/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/helpers': {
          transform: '@actinc/dls/helpers/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/helpers': {
          transform: '@actinc/dls/hooks/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/icons': {
          transform: '@actinc/dls/icons/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/styles': {
          transform: '@actinc/dls/styles/${member}',
          preventFullImport: true,
        },
        '@actinc/dls/types': {
          transform: '@actinc/dls/types/${member}',
          preventFullImport: true,
        },
      },
    ],
    ...
  ],
  presets: [...],
}

Import Stuff

就是这样！ 您已准备好使用 DLS。 只需导入颜色、组件、 您需要的常量、助手、图标、样式和类型：

// components
import { Alert } from '@actinc/dls/components';
// constants
import { sortDirectionTypes as SORT_DIRECTION_TYPES } from '@actinc/dls/constants';
// context
import { AlertContext } from '@actinc/dls/context';
// helpers
import { search } from '@actinc/dls/helpers';
// hooks
import { useLocalStorage } from '@actinc/dls/hooks';
// icons
import { ChevronDown } from '@actinc/dls/icons';
// styles & themes
import { THEME_ACT } from '@actinc/dls/styles/themeAct';
// types
import { SortObject } from '@actinc/dls/types';

Local Development

查看开发人员指南以了解如何构建 对 DLS 有效。

在本地运行 DLS：

1. Install node modules: npm install
2. Start the Storybook component visualizer: npm start

npm Scripts

在本地开发过程中有很多 npm 脚本供您使用。 以下是一些更重要的：

Script	Description
npm run build	Transpile DLS from TypeScript (./src) into ES5 (./dist).
npm run build-storybook	Create a static website for deployment (./storybook-static).
npm start	Start the Storybook component visualizer.
npm test	Run all tests.
npm run release	Publish a new release of the DLS.

Pinned Packages

一些 npm 包由于特定原因被固定到非当前版本：

Package	Version	Reason
color	3.2.1	Version 4.x cannot be run in Storybook due to this issue.
np	7.4.0	Version 7.5.0 is broken.