آموزش مقدماتی توسعه اپلیکیشن ری اکت توسط Ant Design

با سلام خدمت کاربران گرامی آکادمی راهکارینو، با آموزش پیاده سازی اپلیکیشن react توسط ant-design همراه شما هستیم. بدون شک یکی از بهترین و محبوب ترین کتابخانه رابط کاربری (UI Library) برای ری اکت، کتابخانه Ant Design می باشد. این کتابخانه در گیتهاب بیش از 76 هزار ستاره از کاربران دریافت کرده است.

Ant Design یا به اختصار antd یک کتابخانه رابط کاربری یا UI Library است که برای پیاده سازی اپلیکیشن های reactjs بکار می رود. لایبرری AntD شامل مجموعه ای کامپوننت های زیبا و باکیفیت است که به توسعه دهنده ریکت کمک می کند اپلیکیشن هایی با رابط کاربری جذاب و قدرتمند تولید کند.

ویژگی های کتابخانه Ant Design:

• شامل تعداد زیادی کامپوننت با کیفیت و منحصربفرد
• ارائه شده با هر دو زبان برنامه نویسی javascript و typescript
• پشتیبانی از زبان ها و ملیت های مختلف
• ارائه سمپل کد و دمو برای تمام کامپوننت ها
• امکان سفارشی سازی جز به جز تمپلیت اپلیکیشن
• و…

پشتیبانی Ant Design از موارد زیر:

• قابل استفاده در تمام مرورگرهای مدرن و internet explorer 11 به بعد
• رندر شدن سمت سرور (SSR: Server-Side Rendering)
• الکترون (Electron)

نسخه فعلی لایبرری انت دیزاین در زمان نگارش مقاله (مرداد ماه 1400) 4.16.10 است.

نحوه نصب کتابخانه Ant Design:

پیشنهاد می شود برای نصب لایبرری antd از دستورات npm یا yarn استفاده شود. زیرا علاوه بر اینکه توسعه اپلیکیشن را ساده تر می کند، همچنین می توان از ابزارهای کمکی جاوا اسکریپت استفاده کرد.

نصب ant design توسط npm:

npm install antd

نصب ant design توسط yarn:

yarn add antd

اما در صورتیکه نمی خواهید از دستورات npm یا yarn برای نصب antd استفاده کنید، می توانید فایل های استایل و اسکریپت کتابخانه antdesign را از سایت cdnjs دانلود کرده و در پروژه خود import کنید. دو فایل غیر فشرده antd.js و antd.css یا دو فایل فشرده antd.min.js و antd.min.css (واقع در فولدر antd/dist) را می توانید در پروژه خود استفاده کنید.

نحوه استفاده (Usage):

برای استفاده از لایبرری انت دیزاین، کافیست کامپوننت موردنظر را از کتابخانه antd ایمپورت کنید:

import { DatePicker } from 'antd';

ReactDOM.render(<DatePicker />, mountNode);

و سپس استایل شیت را بصورت دستی import کنید:

import 'antd/dist/antd.css'; // or 'antd/dist/antd.less'

لینک های مفید در زمینه یادگیری کتابخانه Ant Design:

• Mobile UI
• Ant Design Icons
• Ant Design Colors
• Dark Theme
• Landing Pages
• Motions
• Customize Theme

شرکت هایی که از Ant Design استفاده می کنند:

• Alibaba
• Tencent
• Baidu
• Koubei
• Meituan
• Didi
• Eleme

برای شروع توسعه اپلیکیشن ریکت توسط Ant Design دو روش کلی در پیش روی شماست:

1. کدنویسی پروژه در محیط codesandbox
2. توسعه اپلیکیشن به وسیله دستور create-react-app
3. توسعه اپلیکیشن با زبان برنامه نویسی تایپ اسکریپت

ابتدا می خواهیم روش اول را آموزش دهیم.

توسعه ری‌اکت با Ant Design در CodeSandBox:

پیش از شروع آموزش کتابخانه antd شدیدا توصیه می کنیم ابتدا زبان برنامه نویسی ES2015 را یاد بگیرید و سپس کتابخانه ReactJS را آموزش ببینید و در نهایت به سراغ یادگیری ant design بیایید.

برای شروع کار اگر node را روی سیستم عامل خود نصب ندارید، ابتدا node.js را نصب کنید (نسخه 8 به بالا).

بنابراین در این آموزش فرض شده است که شما با HTML-CSS-JS حداقل در سطح متوسط آشنا هستید.

قدم اول: ایجاد یک codesandbox

ابتدا به لینک http://u.ant.design/codesandbox-repro مراجعه کنید. در صورتیکه قبلا در این سایت ثبت نام نکرده اید، sign up را انجام دهید. زیرا وقتی در codesandbox لاگین کنید، این امکان را خواهید داشت که پروژه خود را save کنید و در هر جا و هر سیستمی قادر خواهید بود روی پروژه خود کار کنید و همچنین می توانید در سایر پروژه ها مشارکت (collaborate) داشته باشید.

قدم دوم: استفاده و تغییر کامپوننت AntD

قطعه کد زیر را جایگزین کد index.js در محیط توسعه codesandbox کنید. همانطور که مشاهده می کنید، ساختار کامپوننت های AntD دقیقا مشابه کامپوننت های ریکت است:

import React, { useState } from 'react';
import { render } from 'react-dom';
import { DatePicker, message } from 'antd';
import 'antd/dist/antd.css';
import './index.css';

const App = () => {
  const [date, setDate] = useState(null);
  const handleChange = value => {
    message.info(`Selected Date: ${value ? value.format('YYYY-MM-DD') : 'None'}`);
    setDate(value);
  };
  return (
    <div style={{ width: 400, margin: '100px auto' }}>
      <DatePicker onChange={handleChange} />
      <div style={{ marginTop: 16 }}>
        Selected Date: {date ? date.format('YYYY-MM-DD') : 'None'}
      </div>
    </div>
  );
};

render(<App />, document.getElementById('root'));

قدم سوم: استفاده از کامپوننت های دیگر AntD

شما می توانید لیست کامل کامپوننت های AntDesign را در صفحه components مشاهده کنید. مانند کامپوننت Alert. برای هر کامپوننت، سمپل کدها و نمونه های زیادی وجود دارد که می توانید براحتی از آنها استفاده کنید.

همانطور که در تصویر زیر مشخص است، برای هر قطعه کد در کامپوننت ها، چند لینک موجود است که با کلیک روی آیکون <> می توان سورس کد آن کامپوننت را مشاهده کرد، به همین ترتیب می توان سورس کد را در محیط های توسعه codesandbox و codepen و stackblitz مشاهده و ویرایش کرد.

در ادامه می خواهیم از کامپوننت Alert در پروژه خود استفاده کنیم. پس نیاز است آن را ابتدا import کنیم:

import { DatePicker, message, Alert } from 'antd';

سپس کد زیر را در تابع render فایل index.js تعریف کنید:

<DatePicker onChange={value => this.handleChange(value)} />
<div style={{ marginTop: 20 }}
 <Alert message="Selected Date" description={date ? date.format('YYYY-MM-DD') : 'None'} />
</div>

اکنون اگر یک تاریخ را از کامپوننت date-picker انتخاب کنید، تاریخ انتخابی شما در باکس alert نمایش خواهد یافت:

حالا شما با نحوه کارکرد کامپوننت های انت دیزاین تا حدی آشنا شدید و می توانید از کامپوننت های دیگر به همین ترتیب استفاده کنید.

قدم چهارم: تست توسط Jest

اگر می خواهید پروژه خود را به وسیله JEST تست کنید، باید کد زیر را به فایل کانفیگ jest خود اضافه کنید:

"transform": { "^.+\\.(ts|tsx|js|jsx)?$": "ts-jest" }

نکته: اگر می خواهید جریان کاری یا workflow پروژه خود را سفارشی سازی کنید و تغییر دهید، پیشنهاد می شود از ابزار وب پک (WebPack) استفاده کنید. با مراجعه به این لینک می توانید کتاب آموزشی وب پک به زبان فارسی را تهیه کنید.

توسعه ری‌اکت با Ant Design در Create React App:

برای راه اندازی یک پروژه ریکت، یکی از بهترین روش ها، استفاده از دستور create-react-app می باشد. ما در این آموزش می خواهیم از لایبرری antd و ابزار webpack استفاده کنیم.

نحوه نصب و راه اندازی اولیه:

اگر می خواهید از ابزار yarn برای نصب پکیج های پروژه استفاده کنید، نیاز است ابتدا خود yarn را توسط npm نصب کنید. سپس به یکی از روش های زیر، کتابخانه ant-design را روی پروژه خود نصب کنید:

$ yarn create react-app antd-demo

# or

$ npx create-react-app antd-demo

با اجرای این دستور، یک اپلیکیشن جدید ریکت به همراه تمام وابستگی ها (dependencies) ایجاد می شود. اگر در حین اجرای دستور create-react-app با خطا مواجه شدید، می توانید پراکسی را چک کنید و یا vpn خود را روشن کنید و مجددا تست کنید.

سپس وارد فولدر پروژه یعنی antd-demo می شویم و دستور yarn start را اجرا می کنیم:

$ cd antd-demo
$ yarn start

مرورگر بطور خودکار باز می شود و در آدرس http://localhost:3000 قابل مشاهده خواهد بود.

ساختار پیش فرض فولدربندی پروژه ریکت به شکل زیر است:

├── README.md
├── package.json
├── public
│   ├── favicon.ico
│   └── index.html
├── src
│   ├── App.css
│   ├── App.js
│   ├── App.test.js
│   ├── index.css
│   ├── index.js
│   └── logo.svg
└── yarn.lock

نصب کتابخانه AntD:

اکنون نوبت به نصب کتابخانه AntDesign می رسد. توسط yarn یا npm:

$ yarn add antd
# or
$ npm install antd

فایل app.js را باز کرده و آن را مطابق کد زیر تغییر دهید (نمایش یک دکمه ant):

import React from 'react';
import { Button } from 'antd';
import './App.css';

const App = () => (
  <div className="App">
    <Button type="primary">Button</Button>
  </div>
);

export default App;

ایمپورت کردن استایل های antd:

برای استفاده از استایل های انت دیزاین، کافیست فایل antd.css را به شکل زیر در فایل App.css ایمپورت کنید:

@import '~antd/dist/antd.css';

اکنون می توانید یک دکمه آبی رنگ را در آدرس localhost:3000 مشاهده کنید. به همین ترتیب می توان سورس کد سایر کامپوننت های AntD را کپی پیست کنید و خروجی را مشاهده کنید یا آنها را مطابق نیاز پروژه خود تغییر دهید.

تست پروژه توسط Jest:

با نصب اپلیکیشن توسط دستور create-react-app ، امکان تست برنامه بوسیله jest بطور پیش فرض فراهم خواهد بود.

به منظور تست اپلیکیشن ریکت و antd با jest، نیاز است قطعه کد زیر را به فایل package.json پروژه خود اضافه کنید:

"jest": {
  "transformIgnorePatterns": [
    "/node_modules/(?!antd|@ant-design|rc-.+?|@babel/runtime).+(js|jsx)$"
  ]
}

نحوه کانفیگ webpack:

در پروژه های واقعی، نیاز داریم وب پک را با توجه به نیازهای پروژه ویرایش و سفارشی سازی کنیم. به این منظور، از craco (که بطور پیش فرض با دستور create-react-app همراه است) استفاده می شود. برای نصب craco دستور زیر را اجرا کنید:

$ yarn add @craco/craco
# or
$ npm install @craco/craco

سپس باید فیلد scripts را در فایل package.json به شکل زیر آپدیت کنید:

"scripts": {
-   "start": "react-scripts start",
-   "build": "react-scripts build",
-   "test": "react-scripts test",
+   "start": "craco start",
+   "build": "craco build",
+   "test": "craco test",
}

سپس یک فایل بنام craco.config.js در مسیر اصلی پروژه ایجاد کنید و کد زیر را در آن تعریف کنید:

module.exports = {
  // ...
};

استفاده از پیش پردازنده Less:

به منظور استفاده از پیش پردازنده های CSS مانند LESS یا SASS در پروژه React+AntD مجددا می توان از craco استفاده کرد. در این بخش می خواهیم از less استفاده کنیم. بنابراین ابتدا پکیج craco-less را نصب کنید:

$ yarn add craco-less
# or
$ npm install craco-less

سپس فایل craco.config.js را به صورت زیر تغییر دهید:

const CracoLessPlugin = require('craco-less');

module.exports = {
  plugins: [
    {
      plugin: CracoLessPlugin,
      options: {
        lessLoaderOptions: {
          lessOptions: {
            modifyVars: { '@primary-color': '#1DA57A' },
            javascriptEnabled: true,
          },
        },
      },
    },
  ],
};

اکنون باید فایل src/App.css را به src/App.less تغییر نام دهید:

/* src/App.js */
- import './App.css';
+ import './App.less';

و فایل استایل انت دیزاین را با فرمت less ایمپورت کنید:

/* src/App.less */
- @import '~antd/dist/antd.css';
+ @import '~antd/dist/antd.less';

توسعه ری‌اکت با Ant Design و TypeScript:

در این بخش می خواهیم یک اپلیکیشن react را با استفاده از زبان برنامه نویسی تایپ اسکریپت و کتابخانه Ant Design توسعه دهیم.

نحوه نصب و راه اندازی اولیه پروژه:

ابتدا مطمئن شوید که روی سیستم عامل‌تان آخرین نسخه node.js و yarn و npm نصب شده باشد. سپس با دستور زیر، یک اپلیکیشن ری اکت را با زبان typescript تعریف می کنیم:

توسط yarn:

$ yarn create react-app antd-demo-ts --template typescript

توسط npm:

$ npx create-react-app antd-demo-ts --template typescript

در مرحله بعد وارد پوشه پروژه می شویم و آن را اجرا می کنیم:

$ cd antd-demo-ts
$ yarn start

آدرس http://localhost:3000 بطور اتوماتیک در مرورگر باز می شود و پیغام Welcome to React قابل مشاهده خواهد بود.

ایمپورت کردن antd:

توسط yarn:

$ yarn add antd

توسط npm:

$ npm install antd

حالا نوبت تغییر نام فایل src/App.js به App.tsx می رسد. سپس کامپوننت Button را از antd ایمپورت کنید:

import React, { FC } from 'react';
import { Button } from 'antd';
import './App.css';

const App: FC = () => (
  <div className="App">
    <Button type="primary">Button</Button>
  </div>
);

export default App;

در فایل App.css باید فایل antd.css را به شکل زیر import کنید:

@import '~antd/dist/antd.css';

اکنون اگر دستور yarn start را اجرا کنید، در صفحه مرورگر، یک دکمه آبی رنگ مشاهده خواهید کرد. خوشبختانه کتابخانه Ant Design با هر دو زبان javascript و typescript کار می کند و مانند تصویر زیر، امکان property suggestion نیز دارد.

نحوه انجام تنظیمات وب پک:

در پروژه های واقعی، معمولا نیاز داریم تا کانفیگ ابزار وب پک (webpack) را شخصی سازی کنیم و تغییر دهیم. اینکار را با استفاده از craco (Create React App Configuration Override) انجام می دهیم.

برای نصب craco دستور زیر را اجرا کنید:

توسط yarn:

$ yarn add @craco/craco

توسط npm:

$ npm install @craco/craco

سپس باید فیلد scripts را در فایل package.json تغییر دهید:

/* package.json */
"scripts": {
-   "start": "react-scripts start",
-   "build": "react-scripts build",
-   "test": "react-scripts test",
+   "start": "craco start",
+   "build": "craco build",
+   "test": "craco test",
}

سپس در روت پروژه، فایلی بنام craco.config.js بسازید و فعلا کد زیر را برای آن تعریف کنید:

/* craco.config.js */
module.exports = {
  // ...
};

استفاده از پیش پردازنده LESS:

برای اینکه در پروژه های واقعی و مقیاس بزرگ راحت تر بتوانیم قالب اپلیکیشن را طراحی کنیم، بهتر است از یکی از پیش پردازنده های CSS مانند SASS یا LESS استفاده کنیم. در این بخش می خواهیم نحوه کار با فایل های LESS را در Ant Design و React توسط craco-less آموزش دهیم.

ابتدا فایل src/App.css را به src/App.less تغییر نام دهید و بجای فایل css که در بالا ایمپورت کردیم، فایل less را به شکل زیر import کنید:

/* src/App.ts */
- import './App.css';
+ import './App.less';

/* src/App.less */
- @import '~antd/dist/antd.css';
+ @import '~antd/dist/antd.less';

سپس باید craco-less را با دستور زیر نصب کنید:

$ yarn add craco-less
# or
$ npm install craco-less

و فایل craco.config را به صورت زیر آپدیت کنید:

const CracoLessPlugin = require('craco-less');

module.exports = {
  plugins: [
    {
      plugin: CracoLessPlugin,
      options: {
        lessLoaderOptions: {
          lessOptions: {
            modifyVars: { '@primary-color': '#1DA57A' },
            javascriptEnabled: true,
          },
        },
      },
    },
  ],
};

شخصی سازی قالب Ant Design:

کتابخانه قدرتمند Ant Design به توسعه دهندگان این امکان را می دهد تا قالب اپلیکیشن ریکتی خود را طبق رنگ سازمانی موردنظر، یا سلیقه شخصی خود تغییر دهند. مانند رنگ اولیه قالب (primary color)، رنگ border و button و…

متغیرهای LESS در Ant Design:

تیم توسعه دهنده Ant Design زبان LESS را بعنوان زبان استایل نویسی این لایبرری انتخاب کرده اند. مجموعه ای متغیرهای Less بطور پیش فرض در Ant تعریف شده اند که توسعه دهنده می تواند بر اساس نیازهای پروژه خود، آنها را تغییر دهد.

در بخش زیر، چند مورد از متغیرهای مهم و اساسی را مشاهده می کنید.

برای بررسی لیست کامل متغیرهای less در ant design به Default Variables مراجعه شود.

@primary-color: #1890ff; // primary color for all components
@link-color: #1890ff; // link color
@success-color: #52c41a; // success state color
@warning-color: #faad14; // warning state color
@error-color: #f5222d; // error state color
@font-size-base: 14px; // major text font size
@heading-color: rgba(0, 0, 0, 0.85); // heading text color
@text-color: rgba(0, 0, 0, 0.65); // major text color
@text-color-secondary: rgba(0, 0, 0, 0.45); // secondary text color
@disabled-color: rgba(0, 0, 0, 0.25); // disable state color
@border-radius-base: 2px; // major border radius
@border-color-base: #d9d9d9; // major border color
@box-shadow-base: 0 3px 6px -4px rgba(0, 0, 0, 0.12), 0 6px 16px 0 rgba(0, 0, 0, 0.08),
  0 9px 28px 8px rgba(0, 0, 0, 0.05); // major shadow for layers

چگونه قالب Ant را شخصی سازی کنیم؟

ما از modifyVars (که در less.js موجود است) برای جایگزین شدن متغیرهای دلخواه ما با متغیرهای پیش فرض LESS استفاده خواهیم کرد. برای تمرین می توانید این مثال را در گیتهاب چک کنید.

انجام تنظیمات webpack:

ما در این بخش برای کانفیگ less loader در وب پک از فایل webpack.config.js استفاده می کنیم. بنابراین محتوای این فایل را مطابق کد زیر تعریف کنید:

// webpack.config.js
module.exports = {
  rules: [{
    test: /\.less$/,
    use: [{
      loader: 'style-loader',
    }, {
      loader: 'css-loader', // translates CSS into CommonJS
    }, {
      loader: 'less-loader', // compiles Less to CSS
+     options: {
+       lessOptions: { // If you are using less-loader@5 please spread the lessOptions to options directly
+         modifyVars: {
+           'primary-color': '#1DA57A',
+           'link-color': '#1DA57A',
+           'border-radius-base': '2px',
+         },
+         javascriptEnabled: true,
+       },
+     },
    }],
    // ...other rules
  }],
  // ...other config
}

نکات:

• وقتی از less loader استفاده می کنید، مسیر node_modules/antd را exclude نکنید.
• lessOptions در ورژن less-loader@6.0.0 به بعد پشتیبانی می شود.

شخصی سازی در فایل less:

روش دیگر برای سفارشی سازی قالب انت، ایجاد یک فایل با فرمت less است که باعث می شود جایگزین فایل antd.less شود:

@import '~antd/lib/style/themes/default.less';
@import '~antd/dist/antd.less'; // Import Ant Design styles by less entry
@import 'your-theme-file.less'; // variables to override above

قالب های رسمی انت دیزاین (Ant Design Official Themes):

تیم توسعه دهنده کتابخانه AntDesign سه تم متنوع در اختیار کاربران قرار می دهد:

• قالب تیره (Dark Theme): در نسخه های 4.0.0 به بالا پشتیبانی می شود.
• قالب فشرده (Compact Theme): در نسخه های 4.1.0 به بالا پشتیبانی می شود.
• قالب Aliyun: نسخه بتا (Beta Version) منتشر شده است.

فعال سازی قالب تیره (Dark):

به دو روش زیر می توان قالب تیره یا dark را در Ant Design فعال کرد و مورد استفاده قرار داد:

روش اول:

import کردن فایل antd/dist/antd.dark.less در فایل استایل قالب:

@import '~antd/dist/antd.dark.less'; // Introduce the official dark less style entry file

نکته: اگر در پروژه خود از less استفاده نمی کنید، باید فایل antd.dark.css را import کنید:

@import '~antd/dist/antd.dark.css';

روش دوم:

استفاده از less-loader در فایل کانفیگ وب پک. فایل webpack.config.js را باز کرده و به شکل زیر آن را آپدیت کنید:

const { getThemeVariables } = require('antd/dist/theme');

// webpack.config.js
module.exports = {
  rules: [{
    test: /\.less$/,
    use: [{
      loader: 'style-loader',
    }, {
      loader: 'css-loader', // translates CSS into CommonJS
    }, {
      loader: 'less-loader', // compiles Less to CSS
+     options: {
+       lessOptions: { // If you are using less-loader@5 please spread the lessOptions to options directly
+         modifyVars: getThemeVariables({
+           dark: true, // Enable dark mode
+         }),
+         javascriptEnabled: true,
+       },
+     },
    }],
  }],
};

فعال سازی قالب فشرده (Compact):

به دو روش زیر می توان قالب فشرده یا compact را در Ant Design فعال کرد و مورد استفاده قرار داد:

روش اول:

import کردن فایل antd/dist/antd.compact.less در فایل استایل قالب:

@import '~antd/dist/antd.compact.less'; // Introduce the official compact less style entry file

نکته: اگر در پروژه خود از less استفاده نمی کنید، باید فایل antd/dist/antd.compact.css را import کنید:

@import '~antd/dist/antd.compact.css';

روش دوم:

استفاده از less-loader در فایل کانفیگ وب پک. فایل webpack.config.js را باز کرده و به شکل زیر آن را آپدیت کنید:

const { getThemeVariables } = require('antd/dist/theme');

// webpack.config.js
module.exports = {
  rules: [{
    test: /\.less$/,
    use: [{
      loader: 'style-loader',
    }, {
      loader: 'css-loader', // translates CSS into CommonJS
    }, {
      loader: 'less-loader', // compiles Less to CSS
+     options: {
+       lessOptions: { // If you are using less-loader@5 please spread the lessOptions to options directly
+         modifyVars: getThemeVariables({
+           compact: true, // Enable compact mode
+         }),
+         javascriptEnabled: true,
+       },
+     },
    }],
  }],
};

چند زبانه شدن قالب اپلیکیشن:

در حال حاضر زبان پیش فرض قالب Ant Design انگلیسی است و طراحی آن بر اساس چپ به راست (LTR) می باشد اما اگر می خواهید زبان پیش فرض را تغییر دهید، به بخش زیر توجه کنید:

استفاده از کامپوننت ConfigProvider:

تیم توسعه دهنده antd یک کامپوننت معرفی کرده بنام ConfigProvider. این کامپوننت می توان قابلیت پشتیبانی از زبان های مختلف را فراهم کند. فقط کافیست از آن در فایل Index اپلیکیشن خود استفاده کنید:

import { ConfigProvider } from 'antd';
import faIR from 'antd/lib/locale/fa_IR';

return (
  <ConfigProvider locale={faIR}>
    <App />
  </ConfigProvider>
);

در قطعه کد بالا گفتیم که زبان پیش فرض قالب اپلیکیشن فارسی (fa_IR) و از راست به چپ باشد.

نکته: برای تنظیمات بیشتر کامپوننت ConfigProvider کلیک کنید.

در حال حاضر از زبان های جدول زیر پشتیبانی می شود: