MDC-112 Web: MDC'yi Web Çerçeveleriyle Entegre Etme

1. Giriş

Material Bileşenleri (MDC), geliştiricilerin Material Design'u uygulamalarına yardımcı olur. Google'daki bir mühendis ve kullanıcı deneyimi tasarımcısı ekibi tarafından oluşturulan MDC, onlarca güzel ve işlevsel kullanıcı arayüzü bileşenine sahiptir ve Android, iOS, web ve Flutter'da kullanılabilir.material.io/develop

MDC Web, Materyal Tasarım ilkelerini korurken herhangi bir kullanıcı arabirimi çerçevesine entegre edilecek şekilde tasarlanmıştır. Aşağıdaki codelab'de, temel olarak MDC Web kullanan bir React bileşeni oluşturma konusunda size yol gösterilmektedir. Bu kod laboratuvarındaki ilkeler herhangi bir JavaScript çerçevesine uygulanabilir.

MDC Web nasıl oluşturulur?

MDC Web'in JavaScript katmanı, bileşen başına üç sınıftan oluşur: Bileşen, Temel ve Uyumlulayıcı. Bu kalıp, MDC Web'e ön uç çerçeveleriyle entegrasyon esnekliği sağlar.

Temel, Materyal Tasarım'ı uygulayan iş mantığını içerir. Vakıf, herhangi bir HTML öğesine atıfta bulunmaz. Bu sayede HTML etkileşim mantığını adaptöre soyutlayabiliriz. Foundation'da bir adaptör bulunur.

Adaptör bir arayüzdür. Materyal Tasarım iş mantığını uygulamak için Foundation, Adaptör arayüzüne başvurur. Uyumlatıcı'yı Angular veya React gibi farklı çerçevelerde uygulayabilirsiniz. Bir adaptör uygulaması, DOM yapısıyla etkileşim kurar.

Bileşen bir Temele sahiptir ve görevi

1. Çerçeve dışı JavaScript kullanarak Bağdaştırıcı'yı uygulayın ve
2. Foundation'daki yöntemlere proxy yapan herkese açık yöntemler sağlayın.

MDC Web'in sunduğu özellikler

MDC Web'deki her pakette bir bileşen, temel ve adaptör bulunur. Bir Bileşen örneğini oluşturmak için kök öğeyi Bileşenin kurucu yöntemine iletmeniz gerekir. Bileşen, DOM ve HTML öğeleriyle etkileşime giren bir Bağdaştırıcı uygular. Ardından Bileşen, Uyumlulaştırma yöntemlerini çağıran Temel sınıfını oluşturur.

MDC Web'i bir çerçeveye entegre etmek için ilgili çerçevenin dilinde/sentaksında kendi bileşeninizi oluşturmanız gerekir. Bileşen çerçevesi, MDC Web'in Bağdaştırıcısı'nı uygular ve MDC Web'in Temeli'ni kullanır.

Oluşturacağınız uygulama

Bu codelab'de, Material Design React bileşeni oluşturmak için Foundation mantığını kullanmak üzere özel bir Adaptor'un nasıl oluşturulacağı gösterilmektedir. Çerçevelere Entegre Etme başlıklı makaledeki ileri düzey konuları kapsar. Bu kod laboratuvarında örnek çerçeve olarak React kullanılmıştır ancak bu yaklaşım diğer tüm çerçevelere uygulanabilir.

Bu codelab'de, üst uygulama çubuğunu oluşturacak ve üst uygulama çubuğu demo sayfasını yeniden oluşturacaksınız. Demo sayfası düzeni, üst uygulama çubuğu üzerinde çalışmaya başlayabilmeniz için önceden ayarlanmıştır. Üst uygulama çubuğunda şunlar yer alır:

• Gezinme simgesi
• İşlem öğeleri
• 4 varyant mevcuttur: Kısa, her zaman daraltılmış, sabit ve belirgin varyantlar

İhtiyacınız olanlar:

• Node.js'nin yeni bir sürümü (JavaScript paket yöneticisi olan npm ile birlikte gelir)
• Örnek kod (sonraki adımda indirilecek)
• HTML, CSS, JavaScript ve React hakkında temel düzeyde bilgi

Web geliştirme konusundaki deneyiminizi nasıl değerlendirirsiniz?

Acemi Orta Seviye Uzman

2. Geliştirme ortamını ayarlama

Başlangıç Codelab uygulamasını indirin

Başlangıç uygulamasını indirin

Başlatıcı uygulama, material-components-web-codelabs-master/mdc-112/starter dizininde bulunur.

Kök dizinin adındaki -master son ekini not edin. Başlatıcı uygulamayı yukarıdaki düğmeden indiriyorsanız bu codelab'in geri kalanında kök dizine her referans verildiğinde lütfen -master son ekini ekleyin.

...veya GitHub'dan kopyalayın

Bu kod laboratuvarını GitHub'dan kopyalamak için aşağıdaki komutları çalıştırın:

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

Daha fazla yardım için: GitHub'dan depo klonlama

Proje bağımlılıklarını yükleme

material-components-web-codelabs/mdc-112/starter adlı başlangıç dizininde şu komutu çalıştırın:

npm install

Çok fazla etkinlik göreceksiniz ve son olarak terminalinizde başarılı bir yükleme işlemi gösterilecektir:

MDC Web, Sass adlı bir CSS önişleyici kullanır. Farklı bir CSS ön işlemcisi kullanıyorsanız (veya hiç ön işlemcisi kullanıyorsanız sorun değil) sass CLI'yi yükleyerek veya derleme araç zincirinizde bir eklenti (örneğin, Webpack için sass-loader, Gulp için gulp-sass veya Grunt için grunt-sass) kullanarak Sass'ı mevcut önişleyicinizle birlikte kullanabilirsiniz.

Kodumuzun IE 11 gibi eski tarayıcılarda çalışması için MDC Web'in ES2015 JavaScript söz dizimini ES5 JavaScript söz dizimine aktarmak üzere Babel adlı bir aktarıcı kullanırız.

Dosyalarımızı paketlemek ve sitemizi yerel olarak yayınlamak için webpack'ı kullanacağız. Bu projenin webpack yapılandırması, webpack.config.js dosyasında sizin için zaten ayarlanmıştır. Nasıl yapılandırıldığı hakkında daha fazla bilgi için Başlangıç kılavuzuna göz atın.

Başlatıcı uygulamayı çalıştırma

Aynı dizinde şu komutu çalıştırın:

npm start

webpack-dev-server başlar. Sayfayı görmek için tarayıcınızı http://localhost:8080/ adresine yönlendirin.

npm install veya npm start'i başarıyla çalıştıramadığınızda geliştirici ortamınızda sorun giderin.

Başarıyla gerçekleştirildi. Üst Uygulama Çubuğu React Demo sayfasının başlangıç kodu tarayıcınızda çalışıyor olmalıdır. lorem ipsum metninden oluşan bir duvar, Denetimler kutusu (sağ alt) ve tamamlanmamış bir Üst Uygulama Çubuğu görürsünüz:

Kodu ve projeyi inceleyin

Kod düzenleyicinizi açarsanız proje dizini aşağıdaki gibi görünür:

App.js dosyasını açın ve <TopAppBar> bileşenini içeren render yöntemine bakın:

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>
    );
  }

Bu, uygulamadaki TopAppBar için giriş noktasıdır.

yalın bir React Component sınıfı olan TopAppBar.js dosyasını render yöntemiyle açın:

TopAppBar.js

import React from 'react';

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

3. Bileşenin bileşimi

React'te render yöntemi, bileşenin HTML'sini döndürür. Üst uygulama çubuğu bileşeni, bir <header /> etiketi oluşturur ve 2 ana bölümden oluşur:

1. Gezinme simgesi ve başlık bölümü
2. İşlem simgeleri bölümü

Üst uygulama çubuğunu oluşturan öğelerle ilgili sorularınız varsa GitHub'daki dokümanları ziyaret edin.

TopAppBar.js içerisindeki render() yöntemini şu şekilde görünecek şekilde değiştirin:

  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>
    );
  }

Bu HTML'de iki bölüm öğesi vardır. İlkinde bir gezinme simgesi ve başlık bulunur. İkincisi, işlem simgelerini içerir.

Sonra, renderActionItems yöntemini ekleyin:

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>
  );
}

Geliştirici, TopAppBar öğesini React uygulamasına aktarır ve işlem simgelerini TopAppBar öğesine iletir. App.js bölgesinde TopAppBar işlemini başlatan örnek kodu görebilirsiniz.

render yönteminde kullanılan getMergedStyles yöntemi eksik. Lütfen TopAppBar sınıfına aşağıdaki JavaScript yöntemini ekleyin:

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

this.classes, render yönteminde de eksiktir ancak daha sonraki bir bölümde ele alınacaktır. Eksik this.classes alıcı yönteminin yanı sıra, üst uygulama çubuğunun doğru şekilde oluşturulabilmesi için TopAppBar'un uygulamanız gereken başka parçaları da vardır.

React bileşeninin üst uygulama çubuğunda hâlâ eksik olan parçaları şunlardır:

• Hazır bir temel
• Temele aktarılacak adaptör yöntemleri
• JSX işaretleme
• Varyant yönetimi (sabit, kısa, her zaman daraltılmış, belirgin)

Yaklaşımı

1. Bağdaştırıcı yöntemlerini uygulayın.
2. componentDidMount içinde Temel'i başlatın.
3. componentWillUnmount içinde Foundation.destroy yöntemini çağırın.
4. Uygun sınıf adlarını birleştiren bir alıcı yöntemi aracılığıyla varyant yönetimi oluşturun.

4. Adaptör yöntemlerini uygulama

Çerçeve dışı JS TopAppBar Bileşeni aşağıdaki Uyumlatıcı yöntemlerini uygular (burada ayrıntılı olarak listelenmiştir):

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

React sentetik etkinliklere ve farklı en iyi kodlama uygulamalarına ve kalıplarına sahip olduğundan Bağdaştırıcısı yöntemlerinin yeniden uygulanması gerekir.

Adaptör Getter Yöntemi

TopAppBar.js dosyasında TopAppBar öğesine aşağıdaki JavaScript yöntemini ekleyin:

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,
  };
}

React'te kaydırma veya yeniden boyutlandırma için sentetik etkinlik olmadığı ve yerel DOM etkinlik sistemine devredildiği için kaydırma ve yeniden boyutlandırma etkinliği kaydı için bağdaştırıcı API'leri, çerçeve dışı JS sürümüne benzer şekilde uygulanır. getViewPortScrollY, React'in API'sinde bulunmayan window nesnesinde bir işlev olduğundan yerel DOM'a da yönlendirilmelidir. Adaptör uygulamaları her çerçeve için farklı olacaktır.

Uygulanmayan 3 yöntem vardır:

• registerNavigationIconInteractionHandler()
• deregisterNavigationIconInteractionHandler()
• notifyNavigationIconClicked()

Bu 3 yöntem React'te kötü bir uygulama olan DOM etkinliklerine özel olarak tasarlandığı için bu bilerek yapılmıştır. Bunun yerine sentetik etkinlik sistemini kullanın ve etkinlik işleyiciyi simge öğesine ekleyin.

get adapter yöntemi tarafından çağrılan this.setStyle öğesinin eksik olduğunu fark edebilirsiniz. TopAppBar.js dosyasında, eksik JavaScript yöntemini TopAppBar sınıfına ekleyin:

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

Adaptörü uyguladınız. Tam uygulama henüz tamamlanmadığı için bu aşamada konsolunuzda hata görebilirsiniz. Sonraki bölümde CSS sınıflarını ekleme ve kaldırma işlemleri açıklanmaktadır.

5. Bileşen yöntemlerini uygulama

Varyantları ve Sınıfları Yönetme

React'te sınıfları yönetmek için bir API yoktur. Yerel JavaScript'in CSS ekleme/kaldırma sınıf yöntemlerini taklit etmek için classList durum değişkenini ekleyin. TopAppBar dosyasında CSS sınıflarıyla etkileşimde bulunan üç kod parçası vardır:

1. className bileşenini className öğesi aracılığıyla ekleyin.<TopAppBar />
2. addClass veya removeClass aracılığıyla Bağdaştırıcı yöntemi.
3. <TopAppBar /> React bileşeninde sabit kodlanmıştır.

Öncelikle aşağıdaki içe aktarmayı TopAppBar.js üst kısmına, mevcut içe aktarma işlemlerinin altına ekleyin:

import classnames from 'classnames';

Ardından, TopAppBar bileşeninin sınıf beyanının içine aşağıdaki kodu ekleyin:

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 adresine giderseniz Kontroller onay kutuları artık DOM'daki sınıf adlarını etkinleştirip devre dışı bırakacaktır.

Bu kod, TopAppBar'ü birçok geliştirici tarafından kullanılabilir hale getirir. Geliştiriciler, CSS sınıflarının uygulama ayrıntılarıyla ilgili endişe duymadan TopAppBar API ile etkileşimde bulunabilir.

Notlar:

Bu kod 3 işlev ekler:

1. Üst Uygulama Çubuğu DOM Düğümüne bir referans.
2. classList durum nesnesini bir küme olarak başlatma.
3. Sınıf dizesini hesaplayan sınıflar için bir alıcı yöntemi oluşturma.

Adaptörü başarıyla uyguladınız. Bir sonraki bölümde, Foundation örneği oluşturma işleminde size yol gösterilecektir.

Bileşeni Montaj ve Ayrıştırma

Foundation örneği, componentDidMount yönteminde oluşturulur.

Foundation'ın bir DOM öğesine ihtiyacı olduğu için TopAppBar, componentWillMount yerine componentDidMount yöntemini uygular.

Öncelikle, TopAppBar.js içindeki mevcut içe aktarma işlemlerinden sonra aşağıdaki içe aktarma işlemini ekleyerek MDC Üst Uygulama Çubuğu temellerini içe aktarın:

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

Ardından, TopAppBar sınıfına aşağıdaki JavaScript kodunu ekleyin:

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 kodlamayla ilgili iyi bir uygulama, propTypes ve defaultProps'u tanımlamaktır. TopAppBar.js'deki mevcut içe aktarma işlemlerinden sonra aşağıdaki içe aktarma işlemini ekleyin:

import PropTypes from 'prop-types';

Ardından, TopAppBar.js dosyasının alt kısmına (Component sınıfından sonra) aşağıdaki kodu ekleyin:

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,
};

Üst uygulama çubuğu React bileşenini başarıyla uyguladınız. http://localhost:8080 adresine giderseniz demo sayfasını oynayabilirsiniz. Demo sayfası, MDC Web'in demo sayfasıyla aynı şekilde çalışır. Demo sayfası aşağıdaki gibi görünmelidir:

6. Son adım

Bu eğiticide, MDC Web'in Temel bölümünün React uygulamasında kullanılmak üzere nasıl sarmalanacağını ele aldık. Github ve npm'de, Çerçevelere entegrasyon bölümünde açıklandığı şekilde MDC Web Bileşenlerini sarmalayan birkaç kitaplık vardır. Buradaki listeyi kullanmanızı öneririz. Bu listede React dışında Angular ve Vue gibi diğer çerçeveler de yer alır.

Bu eğitimde, MDC Web kodunu Foundation (Temel), Adapter (Bağdaştırıcılar) ve Component (Bileşen) olmak üzere 3 bölüme ayırma kararımız vurgulanmaktadır. Bu mimari, bileşenlerin tüm çerçevelerle çalışırken ortak kod paylaşmasına olanak tanır. Material Components React'i denediğiniz için teşekkürler. Lütfen yeni kitaplığımız MDC React'e göz atın. Bu codelab'den memnun kaldığınızı umuyoruz.

Bu codelab'i makul bir zaman ve çabayla tamamlayabildim

Kesinlikle katılıyorum Katılıyorum Ne katılıyorum ne katılmıyorum Katılmıyorum Kesinlikle katılmıyorum

Gelecekte Material Components'i kullanmaya devam etmek istiyorum

Kesinlikle katılıyorum Katılıyorum Ne katılıyorum ne katılmıyorum Katılmıyorum Kesinlikle katılmıyorum