وب MDC-112: ادغام MDC با Web Frameworks

وب MDC-112:
ادغام MDC با Web Frameworks

درباره این codelab

subjectآخرین به‌روزرسانی: اکتبر ۱۱, ۲۰۲۰
account_circleنویسنده: Liz Mitchell, Abhinay Omkar

1. مقدمه

logo_components_color_2x_web_96dp.png

Material Components (MDC) به توسعه دهندگان کمک می کند طراحی مواد را پیاده سازی کنند. MDC که توسط تیمی از مهندسان و طراحان UX در Google ایجاد شده است، دارای ده‌ها مؤلفه رابط کاربری زیبا و کاربردی است و برای Android، iOS، وب و Flutter.material.io/develop در دسترس است.

MDC Web طوری مهندسی شده است که در هر فریم ورک جلویی و در عین حال رعایت اصول طراحی متریال ادغام شود. کدهای زیر شما را در ساخت یک React Component راهنمایی می کند که از MDC Web به عنوان پایه استفاده می کند. اصول آموخته شده در این کد لبه را می توان در هر چارچوب جاوا اسکریپت اعمال کرد.

چگونه وب MDC ساخته می شود

لایه جاوا اسکریپت MDC Web از سه کلاس در هر جزء تشکیل شده است: Component ، Foundation و Adapter . این الگو به MDC Web انعطاف پذیری برای ادغام با فریم ورک های فرانت اند را می دهد.

بنیاد شامل منطق تجاری است که طراحی متریال را پیاده سازی می کند. بنیاد به هیچ عنصر HTML ارجاع نمی دهد. این به ما امکان می دهد منطق تعامل HTML را در آداپتور انتزاعی کنیم. بنیاد یک آداپتور دارد.

آداپتور یک رابط است. رابط آداپتور توسط بنیاد برای پیاده سازی منطق تجاری طراحی مواد ارجاع داده می شود. شما می توانید آداپتور را در فریمورک های مختلفی مانند Angular یا React پیاده سازی کنید. پیاده سازی یک آداپتور با ساختار DOM تعامل دارد.

مؤلفه یک بنیاد دارد و نقش آن این است که

  1. آداپتور را با استفاده از جاوا اسکریپت غیر چارچوبی و
  2. روش‌های عمومی را ارائه دهید که پروکسی روش‌ها در بنیاد هستند.

آنچه MDC Web ارائه می دهد

هر بسته در MDC Web دارای یک مؤلفه ، پایه و آداپتور است. برای نمونه سازی یک کامپوننت باید عنصر ریشه را به متد سازنده کامپوننت منتقل کنید. کامپوننت یک آداپتور را پیاده سازی می کند که با عناصر DOM و HTML تعامل دارد. سپس مؤلفه بنیادی را که متدهای Adapter را فراخوانی می کند، نمونه سازی می کند.

برای ادغام MDC Web در یک چارچوب، باید Component خود را در زبان/ نحو آن فریمورک ایجاد کنید. کامپوننت چارچوب آداپتور MDC Web را پیاده سازی می کند و از بنیاد MDC Web استفاده می کند.

چیزی که خواهی ساخت

این نرم افزار نشان می دهد که چگونه می توان یک آداپتور سفارشی ساخت تا از منطق بنیادی برای دستیابی به کامپوننت طراحی مواد واکنشی استفاده کند. این موضوعات پیشرفته ای را که در ادغام در چارچوب ها یافت می شود، پوشش می دهد. React در این Codelab به عنوان یک چارچوب مثال استفاده می شود، اما این رویکرد را می توان برای هر چارچوب دیگری اعمال کرد.

در این لبه کد، نوار برنامه برتر را می‌سازید و صفحه نمایشی نوار بالای برنامه را دوباره ایجاد می‌کنید. طرح‌بندی صفحه نمایشی از قبل تنظیم شده است، بنابراین می‌توانید کار را روی نوار برنامه بالا شروع کنید. نوار برنامه برتر شامل:

  • نماد ناوبری
  • آیتم های اقدام
  • 4 نوع موجود است: انواع کوتاه ، همیشه جمع‌شده ، ثابت و برجسته

آنچه شما نیاز دارید:

  • نسخه اخیر Node.js (که همراه با npm ، یک مدیر بسته جاوا اسکریپت)
  • نمونه کد (در مرحله بعد دانلود می شود)
  • دانش اولیه HTML، CSS، جاوا اسکریپت و React

سطح تجربه خود را در زمینه توسعه وب چگونه ارزیابی می کنید؟

2. محیط برنامه نویس را تنظیم کنید

برنامه codelab starter را دانلود کنید

برنامه شروع در دایرکتوری material-components-web-codelabs-master/mdc-112/starter قرار دارد.

... یا آن را از GitHub شبیه سازی کنید

برای شبیه سازی این کد لبه از GitHub، دستورات زیر را اجرا کنید:

git clone https://github.com/material-components/material-components-web-codelabs
cd material
-components-web-codelabs/mdc-112/starter

وابستگی های پروژه را نصب کنید

از دایرکتوری starter material-components-web-codelabs/mdc-112/starter ، اجرا کنید:

npm install

شما فعالیت های زیادی خواهید دید و در پایان، ترمینال شما باید نصب موفقیت آمیز را نشان دهد:

22a33efc2a687408.png

برنامه استارتر را اجرا کنید

در همان دایرکتوری اجرا کنید:

npm start

webpack-dev-server شروع خواهد شد. برای دیدن صفحه، مرورگر خود را به http://localhost:8080/ ببرید.

b55c66dd400cf34f.png

موفقیت! کد شروع صفحه نمایش نمایشی نوار برنامه بالا React باید در مرورگر شما اجرا شود. شما باید یک دیوار از متن lorem ipsum ، یک کادر کنترل (پایین سمت راست) و یک نوار برنامه بالا ناتمام را ببینید:

4ca3cf6d216f9290.png

به کد و پروژه نگاهی بیندازید

اگر ویرایشگر کد خود را باز کنید، دایرکتوری پروژه باید چیزی شبیه به:

e9a3270d6a67c589.png

فایل App.js را باز کنید و به روش render که شامل مولفه <TopAppBar> است نگاه کنید:

App.js

render() {
    const {isFixed, isShort, isRtl, isProminent, isAlwaysCollapsed, shouldReinit} = this.state;

    return (
      <section
        dir={isRtl ? 'rtl' : 'ltr'}
        className='mdc-typography'>
        {
          shouldReinit ? null :
          <TopAppBar
            navIcon={this.renderNavIcon()}
            short={isShort}
            prominent={isProminent}
            fixed={isFixed}
            alwaysCollapsed={isAlwaysCollapsed}
            title='Mountain View, CA'
            actionItems={this.actionItems}
          />
        }
        <div className={classnames('mdc-top-app-bar--fixed-adjust', {
          'mdc-top-app-bar--short-fixed-adjust': isShort || isAlwaysCollapsed,
          'mdc-top-app-bar--prominent-fixed-adjust': isProminent,
        })}>
          {this.renderDemoParagraphs()}
        </div>

        {this.renderControls()}
      </section>
    );
  }

این نقطه ورود TopAppBar در برنامه است.

فایل TopAppBar.js را باز کنید که یک کلاس React Component خالی با متد render است:

TopAppBar.js

import React from 'react';

export default class TopAppBar extends React.Component {
 
render() {
   
return (
     
<header>
       
TOP APP BAR
     
</header>
   
);
 
}
}

3. ترکیب جزء

در React، متد render HTML کامپوننت را خروجی می دهد. مؤلفه نوار برنامه برتر یک تگ <header /> ارائه می دهد و از 2 بخش اصلی تشکیل می شود:

  1. نماد ناوبری و بخش عنوان
  2. بخش آیکون های اکشن

اگر در مورد عناصر تشکیل دهنده نوار برنامه برتر سؤالی دارید، از مستندات موجود در GitHub دیدن کنید.

متد render() را در TopAppBar.js به شکل زیر تغییر دهید:

  render() {
    const {
      title,
      navIcon,
    } = this.props;

    return (
      <header
        className={this.classes}
        style={this.getMergedStyles()}
        ref={this.topAppBarElement}
      >
        <div className='mdc-top-app-bar__row'>
          <section className='mdc-top-app-bar__section mdc-top-app-bar__section--align-start'>
            {navIcon ? navIcon : null}
            <span className="mdc-top-app-bar__title">
              {title}
            </span>
          </section>
          {this.renderActionItems()}
        </div>
      </header>
    );
  }

دو عنصر بخش در این HTML وجود دارد. اولین شامل یک نماد ناوبری و عنوان است. دومی شامل آیکون های عمل است.

سپس متد renderActionItems را اضافه کنید:

renderActionItems() {
  const {actionItems} = this.props;
  if (!actionItems) {
    return;
  }

  return (
    <section className='mdc-top-app-bar__section mdc-top-app-bar__section--align-end' role='toolbar'>
      {/* need to clone element to set key */}
      {actionItems.map((item, key) => React.cloneElement(item, {key}))}
    </section>
  );
}

یک توسعه دهنده TopAppBar به برنامه React خود وارد می کند و نمادهای عمل را به عنصر TopAppBar منتقل می کند. می‌توانید کد نمونه اولیه‌سازی TopAppBar در App.js ببینید.

متد getMergedStyles وجود ندارد که در روش render استفاده می شود. لطفاً متد جاوا اسکریپت زیر را به کلاس TopAppBar اضافه کنید:

getMergedStyles = () => {
  const {style} = this.props;
  const {style: internalStyle} = this.state;
  return Object.assign({}, internalStyle, style);
}

this.classes نیز در روش render وجود ندارد، اما در بخش بعدی پوشش داده خواهد شد. علاوه بر روش دریافت‌کننده گمشده، this.classes ، هنوز قطعاتی از TopAppBar وجود دارد که باید قبل از اینکه Top App Bar بتواند به درستی رندر شود، پیاده‌سازی کنید.

قطعات React Component که هنوز در Top App Bar وجود ندارد عبارتند از:

  • یک پایه اولیه
  • روش های آداپتور برای عبور به فونداسیون
  • نشانه گذاری JSX
  • مدیریت متغیر (ثابت، کوتاه، همیشه فرو ریخته، برجسته)

رویکرد

  1. روش های Adapter را پیاده سازی کنید.
  2. بنیاد را در componentDidMount راه اندازی کنید.
  3. متد Foundation.destroy را در componentWillUnmount فراخوانی کنید.
  4. مدیریت انواع را از طریق یک متد دریافت کننده که نام کلاس های مناسب را ترکیب می کند، ایجاد کنید.

4. پیاده سازی متدهای آداپتور

مؤلفه غیر چارچوبی JS TopAppBar متدهای آداپتور زیر را پیاده سازی می کند (در اینجا به تفصیل فهرست شده است):

  • hasClass()
  • addClass()
  • removeClass()
  • registerNavigationIconInteractionHandler()
  • deregisterNavigationIconInteractionHandler()
  • notifyNavigationIconClicked()
  • setStyle()
  • getTopAppBarHeight()
  • registerScrollHandler()
  • deregisterScrollHandler()
  • registerResizeHandler()
  • deregisterResizeHandler()
  • getViewportScrollY()
  • getTotalActionItems()

از آنجایی که React دارای رویدادهای مصنوعی و بهترین شیوه‌ها و الگوهای کدنویسی است، روش‌های Adapter باید دوباره پیاده‌سازی شوند.

روش آداپتور گیرنده

در فایل TopAppBar.js روش جاوا اسکریپت زیر را به TopAppBar اضافه کنید:

get adapter() {
  const {actionItems} = this.props;

  return {
    hasClass: (className) => this.classes.split(' ').includes(className),
    addClass: (className) => this.setState({classList: this.state.classList.add(className)}),
    removeClass: (className) => {
      const {classList} = this.state;
      classList.delete(className);
      this.setState({classList});
    },
    setStyle: this.setStyle,
    getTopAppBarHeight: () => this.topAppBarElement.current.clientHeight,
    registerScrollHandler: (handler) => window.addEventListener('scroll', handler),
    deregisterScrollHandler: (handler) => window.removeEventListener('scroll', handler),
    registerResizeHandler: (handler) => window.addEventListener('resize', handler),
    deregisterResizeHandler: (handler) => window.removeEventListener('resize', handler),
    getViewportScrollY: () => window.pageYOffset,
    getTotalActionItems: () => actionItems && actionItems.length,
  };
}

APIهای آداپتور برای ثبت رویداد اسکرول و تغییر اندازه به طور یکسان با نسخه JS غیر چارچوبی پیاده‌سازی می‌شوند، زیرا React هیچ رویداد مصنوعی برای پیمایش یا تغییر اندازه ندارد و به سیستم رویداد DOM اصلی موکول می‌شود. getViewPortScrollY همچنین باید به DOM بومی موکول شود زیرا تابعی در شی window است که در API React نیست. پیاده سازی آداپتور برای هر فریم ورک متفاوت خواهد بود.

ممکن است متوجه شوید this.setStyle وجود ندارد که با متد get adapter فراخوانی می شود. در فایل TopAppBar.js ، متد جاوا اسکریپت گم شده را به کلاس TopAppBar اضافه کنید:

setStyle = (varName, value) => {
  const updatedStyle = Object.assign({}, this.state.style);
  updatedStyle[varName] = value;
  this.setState({style: updatedStyle});
}

شما به تازگی آداپتور را پیاده سازی کرده اید! توجه داشته باشید که ممکن است در این مرحله خطاهایی در کنسول خود مشاهده کنید زیرا اجرای کامل هنوز کامل نشده است. بخش بعدی شما را در مورد نحوه افزودن و حذف کلاس های CSS راهنمایی می کند.

5. پیاده سازی روش های کامپوننت

مدیریت انواع و کلاس ها

React یک API برای مدیریت کلاس ها ندارد. برای تقلید از متدهای کلاس CSS افزودن/حذف بومی جاوا اسکریپت، متغیر وضعیت classList را اضافه کنید. سه قطعه کد در TopAppBar وجود دارد که با کلاس های CSS تعامل دارند:

  1. جزء <TopAppBar /> از طریق className prop.
  2. متد Adapter از طریق addClass یا removeClass .
  3. کدگذاری سخت در <TopAppBar /> React Component.

ابتدا وارد کردن زیر را در بالای TopAppBar.js ، زیر واردات موجود اضافه کنید:

import classnames from 'classnames';

سپس کد زیر را در اعلان کلاس کامپوننت TopAppBar اضافه کنید:

export default class TopAppBar extends React.Component {
  constructor(props) {
    super(props);
    this.topAppBarElement = React.createRef();
  }

  state = {
    classList: new Set(),
    style: {},
  };

  get classes() {
    const {classList} = this.state;
    const {
      alwaysCollapsed,
      className,
      short,
      fixed,
      prominent,
    } = this.props;

    return classnames('mdc-top-app-bar', Array.from(classList), className, {
      'mdc-top-app-bar--fixed': fixed,
      'mdc-top-app-bar--short': short,
      'mdc-top-app-bar--short-collapsed': alwaysCollapsed,
      'mdc-top-app-bar--prominent': prominent,
    });
  }

  ...
}

اگر به http://localhost:8080 بروید، چک باکس های Controls اکنون باید نام کلاس ها را از DOM روشن یا خاموش کنند.

این کد TopAppBar برای بسیاری از توسعه دهندگان قابل استفاده می کند. توسعه دهندگان می توانند بدون نگرانی در مورد جزئیات پیاده سازی کلاس های CSS با TopAppBar API تعامل داشته باشند.

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

نصب و جدا کردن کامپوننت

نمونه سازی بنیاد در روش componentDidMount اتفاق می افتد.

ابتدا، پایه های MDC Top App Bar را با افزودن ورودی زیر پس از واردات موجود در TopAppBar.js وارد کنید:

import {MDCTopAppBarFoundation, MDCFixedTopAppBarFoundation, MDCShortTopAppBarFoundation} from '@material/top-app-bar';

سپس کد جاوا اسکریپت زیر را به کلاس TopAppBar اضافه کنید:

export default class TopAppBar extends React.Component {
 
  ...

  foundation_ = null;

  componentDidMount() {
    this.initializeFoundation();
  }

  componentWillUnmount() {
    this.foundation_.destroy();
  }

  initializeFoundation = () => {
    if (this.props.short) {
      this.foundation_ = new MDCShortTopAppBarFoundation(this.adapter);
    } else if (this.props.fixed) {
      this.foundation_ = new MDCFixedTopAppBarFoundation(this.adapter);
    } else {
      this.foundation_ = new MDCTopAppBarFoundation(this.adapter);
    }

    this.foundation_.init();
  }
 
  ...

}

یکی از روش های خوب کدنویسی React، تعریف propType و defaultProps است. وارد کردن زیر را بعد از واردات موجود در TopAppBar.js اضافه کنید:

import PropTypes from 'prop-types';

سپس کد زیر را به پایین TopAppBar.js (بعد از کلاس Component) اضافه کنید:

import PropTypes from 'prop-types';

TopAppBar.propTypes = {
 
alwaysCollapsed: PropTypes.bool,
 
short: PropTypes.bool,
 
fixed: PropTypes.bool,
 
prominent: PropTypes.bool,
 
title: PropTypes.string,
 
actionItems: PropTypes.arrayOf(PropTypes.element),
 
navIcon: PropTypes.element,
};

TopAppBar.defaultProps = {
 
alwaysCollapsed: false,
 
short: false,
 
fixed: false,
 
prominent: false,
 
title: '',
 
actionItems: null,
 
navIcon: null,
};

اکنون با موفقیت کامپوننت Top App Bar React را پیاده سازی کرده اید. اگر به http://localhost:8080 بروید، می توانید با صفحه نمایشی بازی کنید. صفحه نمایشی همانند صفحه نمایشی وب MDC کار خواهد کرد. صفحه دمو باید به شکل زیر باشد:

3d983b98c2092e7a.png

6. جمع کنید

در این آموزش نحوه بسته بندی MDC Web's Foundation برای استفاده در یک برنامه React را توضیح دادیم. چند کتابخانه در Github و npm وجود دارد که MDC Web Components را همانطور که در Integrating into Frameworks توضیح داده شده است. توصیه می کنیم از لیست موجود در اینجا استفاده کنید. این لیست علاوه بر React شامل فریمورک های دیگری مانند Angular و Vue نیز می شود.

این آموزش تصمیم ما را برای تقسیم کد وب MDC به 3 بخش، پایه ، آداپتور و مؤلفه برجسته می کند. این معماری به اجزا اجازه می دهد تا کدهای مشترک را در حین کار با همه فریم ورک ها به اشتراک بگذارند. از اینکه Material Components React را امتحان کردید متشکریم و لطفاً کتابخانه جدید ما MDC React را بررسی کنید. امیدواریم از این کد لبه لذت برده باشید!

من توانستم با صرف زمان و تلاش معقول این کد لبه را تکمیل کنم

من می‌خواهم در آینده از Material Component استفاده کنم