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

1. Giriş

Material Components (MDC), geliştiricilerin Materyal Tasarım'ı uygulamasına yardımcı olur. Google'daki bir mühendis ve kullanıcı deneyimi tasarımcısı ekibi tarafından oluşturulan MDC, düzinelerce güzel ve işlevsel kullanıcı arayüzü bileşeni içerir. Android, iOS, web ve Flutter.material.io/develop için kullanılabilir.

MDC Web, Materyal Tasarım'ın ilkelerini korurken herhangi bir kullanıcı arabirimi çerçevesine entegre olacak şekilde tasarlanmıştır. Aşağıdaki codelab'de, temel olarak MDC Web'i kullanan bir React bileşeni oluşturma işlemi adım adım açıklanır. Bu codelab'de öğrenilen 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: Component, Foundation ve Adapter. Bu kalıp, MDC Web'in ön uç çerçeveleriyle entegre olabilmesi için esneklik sağlar.

Foundation, Materyal Tasarım'ı uygulayan iş mantığını içerir. Foundation, herhangi bir HTML öğesine referans vermez. Bu sayede, HTML etkileşim mantığını Adapter'da soyutlayabiliriz. Foundation'ın Adapter'ı var.

Adaptör bir arayüzdür. Adapter arayüzü, Materyal Tasarım işletme mantığını uygulamak için Foundation tarafından referans alınır. Adaptörü Angular veya React gibi farklı çerçevelerde uygulayabilirsiniz. Bir bağdaştırıcı uygulaması, DOM yapısıyla etkileşimde bulunur.

Bileşen, Temel'e sahiptir ve rolü

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

MDC Web'in sunduğu özellikler

MDC Web'deki her pakette Component (Bileşen), Foundation (Temel) ve Adapter (Adaptör) bulunur. Bir bileşen örneklendirmek için kök öğeyi bileşenin oluşturucu yöntemine iletmeniz gerekir. Bileşen, DOM ve HTML öğeleriyle etkileşim kuran bir Uyarlayıcı uygular. Ardından Bileşen, Adapter yöntemlerini çağıran Foundation'ı başlatır.

MDC Web'i bir çerçeveye entegre etmek için bu çerçevenin dilinde/söz diziminde kendi Component öğenizi oluşturmanız gerekir. Component çerçevesi, MDC Web'in Adapter'ını uygular ve MDC Web'in Foundation'ını kullanır.

Ne oluşturacaksınız?

Bu codelab'de, Materyal Tasarım React bileşeni elde etmek için Foundation mantığını kullanmak üzere özel bir Adapter'ın nasıl oluşturulacağı gösterilmektedir. Framework'lere Entegrasyon bölümünde yer alan ileri düzey konuları kapsar. Bu codelab'de örnek çerçeve olarak React kullanılmaktadı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 sayfa düzeni önceden ayarlandığı için üst uygulama çubuğu üzerinde çalışmaya başlayabilirsiniz. Üst uygulama çubuğunda şunlar yer alır:

• Gezinme simgesi
• Action items
• 4 varyant vardır: Kısa, her zaman daraltılmış, sabit ve belirgin varyantlar

Gerekenler:

• Node.js'nin son 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 bilgi

Web geliştirme alanındaki deneyim seviyenizi nasıl değerlendirirsiniz?

Başlangıç Orta İleri

2. Geliştirme ortamını ayarlama

Başlangıç Codelab uygulamasını indirin

Başlangıç uygulamasını indirin

Başlangıç uygulaması, material-components-web-codelabs-master/mdc-112/starter dizininde bulunur.

Kök dizinin adındaki -master sonekini not edin. Başlangıç uygulamasını yukarıdaki düğmeden indiriyorsanız lütfen bu codelab'in geri kalanında kök dizine her başvurulduğunda -master sonekini ekleyin.

...veya GitHub'dan klonlayın

Bu codelab'i GitHub'dan klonlamak 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 kopyalama

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

Başlangıç dizininden material-components-web-codelabs/mdc-112/starter şunu çalıştırın:

npm install

Çok sayıda etkinlik görürsünüz ve sonunda terminalinizde başarılı bir yükleme gösterilir:

MDC Web, Sass adlı bir CSS ön işlemcisi kullanır. Farklı bir CSS ön işlemcisi (veya hiçbiri) kullanıyorsanız sorun yok. sass KSA'yı yükleyerek veya derleme araç zincirinizde bir eklenti (örneğin, Webpack için sass-loader, Gulp için gulp-sass ya da Grunt için grunt-sass) kullanarak Sass'ı mevcut ön işlemcinizle 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 çevirmek üzere Babel adlı bir programlama dili çeviricisi kullanıyoruz.

Dosyalarımızı paketlemek ve sitemizi yerel olarak sunmak için webpack'i kullanacağız. Bu projenin webpack yapılandırması, webpack.config.js dosyasında sizin için önceden ayarlanmıştır. Yapılandırma hakkında daha fazla bilgi için Başlangıç Kılavuzu'na bakın.

Başlangıç uygulamasını ç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 komutlarını başarıyla çalıştıramadıysanız durdurun ve geliştirme ortamınızda sorun giderme işlemi yapın.

Başarılı aktarım Üst uygulama çubuğu React demo sayfası için başlangıç kodu tarayıcınızda çalışıyor olmalıdır. Lorem ipsum metninden oluşan bir duvar, Denetimler kutusu (sağ altta) ve tamamlanmamış bir üst uygulama çubuğu görürsünüz:

Koda ve projeye göz atma

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.

TopAppBar.js dosyasını açın. Bu dosya, render yöntemi olan basit bir React Component sınıfıdır:

TopAppBar.js

import React from 'react';

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

3. Bileşenin yapısı

React'te render yöntemi, bileşenin HTML'sini verir. Ü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 öğeler hakkında sorularınız varsa GitHub'daki dokümanları inceleyin.

TopAppBar.js içindeki render() yöntemini aşağıdaki gibi 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 var. Birincisinde gezinme simgesi ve başlığı bulunur. İkincisinde işlem simgeleri bulunur.

Ardından, 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>
  );
}

Bir geliştirici, TopAppBar öğesini React uygulamasına aktarır ve işlem simgelerini TopAppBar öğesine iletir. TopAppBar öğesini App.js içinde 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 eksik ancak bu konu sonraki bir bölümde ele alınacaktır. Eksik alıcı yöntemin (this.classes) yanı sıra, üst uygulama çubuğunun doğru şekilde oluşturulabilmesi için TopAppBar öğesinin bazı bölümlerini uygulamanız gerekir.

Üst uygulama çubuğunda hâlâ eksik olan React bileşenleri şunlardır:

• Başlatılmış bir temel
• Temele aktarılacak bağdaştırıcı yöntemleri
• JSX işaretleme
• Varyant yönetimi (sabit, kısa, her zaman daraltılmış, belirgin)

Yaklaşımı

1. Adapter yöntemlerini uygulayın.
2. componentDidMount içinde Foundation'ı başlatın.
3. componentWillUnmount içinde Foundation.destroy yöntemini çağırın.
4. Uygun sınıf adlarını birleştiren bir getter yöntemiyle varyant yönetimi oluşturun.

4. Adaptör yöntemlerini uygulama

Çerçeve dışı JS TopAppBar Component, aşağıdaki Adapter yöntemlerini uygular (ayrıntılı olarak burada listelenmiştir):

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

React'te yapay etkinlikler ve farklı en iyi kodlama uygulamaları ve kalıpları olduğundan Adapter yöntemlerinin yeniden uygulanması gerekir.

Adapter Getter Method

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 herhangi bir yapay etkinlik olmadığından ve yerel DOM etkinlik sistemine başvurulduğundan, 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üyle aynı şekilde uygulanır. getViewPortScrollY, React'in API'sinde bulunmayan window nesnesindeki bir işlev olduğundan yerel DOM'a da başvurmalıdır. Adaptör uygulamaları her çerçeve için farklı olacaktır.

Uygulanmayan 3 yöntem vardır:

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

Bu durum, söz konusu 3 yöntemin DOM etkinlikleri etrafında tasarlanmış olmasından kaynaklanmaktadır. Bu, React'te kötü bir uygulamadır. Bunun yerine, sentetik etkinlik sistemini kullanın ve etkinlik işleyiciyi simge öğesine ekleyin.

this.setStyle öğesinin eksik olduğunu fark edebilirsiniz. Bu öğe, get adapter yöntemiyle çağrılır. 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ü yeni uyguladınız. Tam uygulama henüz tamamlanmadığı için bu noktada konsolunuzda hatalar görebileceğinizi unutmayın. Bir sonraki bölümde, CSS sınıflarını ekleme ve kaldırma konusunda size yol gösterilecektir.

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 sınıfı ekleme/kaldırma yöntemlerini taklit etmek için classList durum değişkenini ekleyin. TopAppBar içinde CSS sınıflarıyla etkileşimde bulunan üç kod parçası vardır:

1. className özelliği aracılığıyla <TopAppBar /> bileşeni.
2. addClass veya removeClass üzerinden bağdaştırıcı yöntemi.
3. <TopAppBar /> React bileşeninde sabit kodlanmış.

Öncelikle TopAppBar.js dosyasının en üstüne, mevcut içe aktarma işlemlerinin altına aşağıdaki içe aktarma işlemini ekleyin:

import classnames from 'classnames';

Ardından, TopAppBar Component sınıf bildiriminin 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ı açıp kapatabilir.

Bu kod, TopAppBar'nın birçok geliştirici tarafından kullanılabilmesini sağlar. Geliştiriciler, CSS sınıflarının uygulama ayrıntıları konusunda endişelenmeden TopAppBar API ile etkileşimde bulunabilir.

Notlar:

Bu kod 3 işlev ekler:

1. Üst uygulama çubuğu DOM düğümüne referans.
2. classList durum nesnesini bir Set 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 oluşturma işlemi adım adım açıklanacaktır.

Bileşeni takma ve çıkarma

Foundation başlatma işlemi componentDidMount yönteminde gerçekleşir.

TopAppBar, Foundation bir DOM öğesine ihtiyaç duyduğundan 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 Top App Bar temellerini içe aktarın:

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

Ardından, aşağıdaki JavaScript kodunu TopAppBar sınıfına 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();
  }
 
  ... 

}

propTypes ve defaultProps'u tanımlamak, iyi bir React kodlama uygulamasıdı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, aşağıdaki kodu TopAppBar.js dosyasının en altına (Component sınıfından sonra) 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 giderek demo sayfasıyla oynayabilirsiniz. Demo sayfası, MDC Web'in demo sayfası ile aynı şekilde çalışır. Demo sayfası aşağıdaki gibi görünmelidir:

6. Özet

Bu eğitimde, React uygulamasında kullanılmak üzere MDC Web'in Foundation'ını nasıl sarmalayacağımızı ele aldık. Github ve npm'de, Çerçevelere Entegrasyon bölümünde açıklandığı gibi MDC Web Bileşenlerini sarmalayan birkaç kitaplık vardır. Burada bulunan listeyi kullanmanızı öneririz. Bu listede React'in yanı sıra Angular ve Vue gibi diğer çerçeveler de yer alır.

Bu eğitimde, MDC Web kodunu Foundation, Adapter ve Component olmak üzere 3 bölüme ayırma kararımız vurgulanmaktadır. Bu mimari, bileşenlerin tüm çerçevelerle çalışırken ortak kodu paylaşmasına olanak tanır. Material Components React'i denediğiniz için teşekkür ederiz. Lütfen yeni kitaplığımız MDC React'i inceleyin. Bu codelab'i beğendiğinizi umuyoruz.

Bu codelab'i makul bir süre 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'ı 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