Bootstrap Utilities API: $utilities Map'i ile Yardımcı Sınıf Ekleme, Değiştirme, Silme

$utilities map'i ve seçenekleri

Bütün yardımcı sınıf grupları _utilities.scss içindeki $utilities değişkeninde durur. Map'in her anahtarı bir grubun adıdır ("width", "margin-start", "shadow" gibi), değeri de o grubu tanımlayan iç içe bir map'tir. Belgedeki seçenek tablosunu Türkçe özetleyelim:

Kaynakta gerçek bir grup şöyle görünür. Genişlik yardımcıları width özelliğini, w önekini ve beş değerlik bir map kullanır:

// scss/_utilities.scss (v5.0.2)
"width": (
  property: width,
  class: w,
  values: (
    25: 25%,
    50: 50%,
    75: 75%,
    100: 100%,
    auto: auto
  )
),

Bootstrap 5.0.2 derlenmiş CSS dosyasında bu grubun ilk sınıfı şöyle tanımlıdır: .w-25 { width: 25% !important; }. Sınıf eki map anahtarından (25), değer de map değerinden (25%) gelir.

Sınıf adı nasıl oluşur?

API'yi rahat kullanmanın anahtarı, generate-utility mixin'inin sınıf adını nasıl kurduğunu bilmektir. v5.0.2 kaynağına göre ad üç parçanın birleşimidir: önek, kırılma noktası eki ve değer eki. Önek class seçeneğidir, yoksa property listesinin ilk öğesidir. Kırılma noktası eki taban (xs) için boştur, diğerleri için -md gibidir. Değer eki ise map anahtarının önüne tire konmuş hâlidir.

• values bir liste ise mixin listeyi kendisiyle eşleştirip map'e çevirir; sınıf eki değerin kendisi olur. overflow grubu auto hidden visible scroll listesini kullanır, bu yüzden .overflow-hidden oluşur.
• Map anahtarı null ise ek yazılmaz. shadow grubunda null: $box-shadow satırı yalın .shadow sınıfını, sm anahtarı .shadow-sm sınıfını üretir; border grubunun yalın .border sınıfı da böyle oluşur.
• class null ise önek boş kalır ve sınıf adı yalnızca değer ekinden oluşur. visibility grubu bu yüzden .visible ve .invisible sınıflarını üretir.
• Değer null ise o satır için hiç kural yazılmaz. Negatif margin grupları, $enable-negative-margins kapalıyken değerleri null olduğu için boş kalır.
• Birden fazla property verilirse aynı değer hepsine yazılır. word-wrap grubu word-wrap ve word-break özelliklerini birlikte ayarlayan .text-break sınıfını üretir.

Belgenin seçenek tablosu null anahtarlı satırların derlenmediğini söyler; ancak v5.0.2'deki mixin kodu ve derlenmiş .shadow sınıfı, null anahtarın eksiz bir sınıf ürettiğini gösterir. Bu yazıdaki açıklamalar kaynak koda dayanır.

Duyarlı, yazdırma ve RFS çıktıları

responsive: true olan bir grup için utilities/api dosyası $grid-breakpoints map'indeki her kırılma noktasında media-breakpoint-up sorgusu açar ve sınıfları ekli adla yeniden üretir. float grubu duyarlıdır, bu yüzden stok CSS'te .float-md-start vardır; overflow grubu duyarlı değildir, bu yüzden .overflow-md-hidden yoktur. print: true olan gruplar ek olarak @media print içinde -print ekli sınıflar alır: display grubu bu seçeneği taşıdığı için .d-print-none vardır. rfs: true olan gruplarda ise taban değer akışkan hesaplanır, RFS kırılma noktasının (varsayılan 1200px) üzerinde sabit değer yazılır. Bootstrap 5.0.2 derlenmiş CSS dosyasında .fs-1 önce calc(1.375rem + 1.5vw), 1200px ve üzerinde 2.5rem olarak tanımlıdır.

State ve RTL

state seçeneği sözde sınıf varyantları üretir. Kaynaktaki kalıba göre her sınıfın yanına, adının sonuna sözde sınıfın adı eklenmiş ikinci bir seçici yazılır; örneğin state: hover verilen bir grupta değer ekinden sonra -hover gelir ve seçici :hover ile biter. Birden fazla durum için state: hover focus gibi boşlukla ayrılmış liste verilir. rtl: false ise sınıfı /* rtl:begin:remove */ ve /* rtl:end:remove */ yorumları arasına alır; RTLCSS aracı sağdan sola çıktı üretirken bu bloğu atar. Stok CSS'te .text-break böyle sarılıdır. Kaynakta margin-start grubunun özelliği margin-left'tir; sağdan sola dosyada bu yönü RTLCSS çevirir.

!important ve önem sırası

API'nin ürettiği bütün yardımcı sınıflar !important taşır. Belgeye göre amaç, yardımcı sınıfların bileşen ve değiştirici sınıflarını gerektiği gibi ezebilmesidir: class="btn btn-primary w-100" yazdığınızda genişlik butonun kendi kuralına takılmaz. Bu davranış $enable-important-utilities değişkeniyle (varsayılan true) genel olarak açılıp kapatılır. Bunun ters yüzü de vardır: kendi CSS dosyanızdaki bir kural bir yardımcı sınıfı ezemez. Örneğin d-none taşıyan bir öğeyi kendi kuralınızla göstermeye çalışırsanız kazanan yine yardımcı sınıf olur; sınıfı HTML'den kaldırmak ya da duyarlı bir display sınıfı kullanmak gerekir.

Import sırası: API nereye yazılır?

Belgedeki örneklerin hepsi aynı üç satırla başlar: functions, variables ve utilities. $utilities map'i utilities dosyasında tanımlandığı için ona map-merge ile dokunmak bu dosyadan sonra mümkündür. Sınıfları üreten döngü ise utilities/api dosyasındadır ve bootstrap.scss'te olduğu gibi en sona gelir. Tam bir dosyada sıra şöyle olur:

@import "../node_modules/bootstrap/scss/functions";
// (değişken ezmeleri)
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/utilities";

// $utilities değişiklikleriniz burada

@import "../node_modules/bootstrap/scss/root";
@import "../node_modules/bootstrap/scss/reboot";
// ... diğer bileşenler
@import "../node_modules/bootstrap/scss/helpers";
@import "../node_modules/bootstrap/scss/utilities/api";

Kaynakta ikinci bir yol daha vardır. _utilities.scss önce $utilities: () !default; der, ardından varsayılan grupları sizin $utilities map'inizle birleştirir. Yani utilities import'undan önce kendi $utilities map'inizi tanımlarsanız, aynı anahtarlı gruplar sizinkilerle değiştirilir. Belgedeki "Changing utilities" örneği bu yolu kullanır. Birleştirme sığ olduğu için bu durumda grubu bütün seçenekleriyle yeniden yazmanız gerekir.

API ile yapabilecekleriniz

Yeni bir yardımcı eklemek

Belgenin örneği, üç değerli ve duyarlı bir cursor yardımcısı ekler. Kaynakta varsayılan olarak böyle bir grup yoktur:

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    )
  )
);

Sınıf adı kuralına göre bu tanım .cursor-auto, .cursor-pointer, .cursor-grab ve kırılma noktalı .cursor-md-pointer gibi sınıflar üretir. Derlediğiniz dosyada şöyle kullanırsınız:

<div class="card">
  <div class="card-body cursor-pointer">
    <h3 class="card-title h5">Dosyayı sürükleyin</h3>
    <p class="card-text cursor-grab">Bu alanı tutup taşıyabilirsiniz.</p>
  </div>
</div>

Parça bir ayrıştırıcıyla denetlendi; cursor-pointer ve cursor-grab stok CSS'te olmadığı için ancak yukarıdaki Sass ile derlediğiniz dosyada çalışır, diğer sınıflar v5.0.2 CSS'inde tanımlıdır.

Mevcut bir grubu değiştirmek

Bir gruba değer eklemek için iç içe map-get ve map-merge kullanılır. Belgedeki örnek genişlik yardımcılarına %10 değerini ekler; en dıştaki birleştirme $utilities'i, ortadaki "width" grubunu, en içteki de o grubun values map'ini genişletir:

$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

Sonuçta mevcut beş sınıf korunur ve yanlarına .w-10 eklenir. Ortadaki map-merge adımını atlayıp "width": (values: ...) yazsaydınız grubun property ve class seçenekleri kaybolurdu.

Duyarlı hâle getirmek ve yeniden adlandırmak

Aynı kalıpla tek bir seçeneği değiştirebilirsiniz. border grubuna responsive: true eklemek .border-md ve .border-md-0 gibi sınıflar üretir; margin-start grubunun class değerini ml yapmak ise v4'ten alışık olduğunuz .ml-* adlarını geri getirir. Belge bu ikinci örneği, eski adlandırmaya alışkın olanlar için açıkça gösterir. Ancak takım içinde v5 belgeleriyle çalışan biri ms-* arayacağı için bu kararı belgelemenizi öneririz; v4'ten geçiş ayrıntıları geçiş rehberinde.

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Bir grubu kaldırmak

Kullanmadığınız bir grubu çıktıdan atmak için anahtarını null yaparsınız. API döngüsü yalnızca map olan grupları işlediği için bu grup hiç üretilmez ve derlenen dosya küçülür:

$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

RTL çıktısından çıkarmak

Belge, Arapçadaki satır kırma gibi bazı durumlarda sağdan sola stillerin zorlaştığını ve böyle grupların rtl: false ile RTL çıktısından çıkarılabileceğini anlatır. v5.0.2'de word-wrap grubu tam olarak bu seçeneği taşır. Sağdan sola dosyanın nasıl yükleneceği kurulum yazısında anlatılıyor.

Hazır alt kümeler: map-get-multiple

Kaynak klasöründeki bootstrap-grid.scss API'nin başka bir kullanımını gösterir: dosya utilities import'undan sonra $utilities map'ini map-get-multiple() fonksiyonuyla süzer ve yalnızca display, order, flex, justify-content, align-items, margin ve padding gibi yerleşim gruplarını bırakır. Kendi projenizde de aynı yöntemle yalnızca kullandığınız grupları tutabilirsiniz. bootstrap-utilities.scss ise yardımcıların tamamını ve helpers dosyasını derler; geçiş belgesine göre v5'te derlenmiş bootstrap-utilities.css dosyası helpers sınıflarını da içerir.

Uygulamalı örnek: bir projenin yardımcı katmanı

Bir yönetim paneli için şu ihtiyaçlar olsun: sürüklenebilir kartlar için imleç sınıfları, tablo hücrelerinde dar ekranda kaldırılan çerçeveler için duyarlı border sınıfları ve hiç kullanılmayan max-height ile viewport-height gruplarının çıkarılması. Hepsi tek bir birleştirmede yazılabilir:

@import "../node_modules/bootstrap/scss/functions";
@import "../node_modules/bootstrap/scss/variables";
@import "../node_modules/bootstrap/scss/mixins";
@import "../node_modules/bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    ),
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
    "max-height": null,
    "viewport-height": null,
  )
);

// ... bileşenler
@import "../node_modules/bootstrap/scss/helpers";
@import "../node_modules/bootstrap/scss/utilities/api";

Bu dosya belgedeki örneklerin birleşimidir ve burada derlenmedi; grup adları (border, max-height, viewport-height) v5.0.2'deki _utilities.scss dosyasında mevcuttur. Derlenen CSS'te .mh-100 ve .vh-100 sınıflarının artık bulunmadığını, .border-md-0 gibi sınıfların eklendiğini kontrol etmek için çıktıda bu adları aramanız yeterlidir.

Sık yapılan hatalar

• map-merge satırını utilities import'undan önce yazmak: $utilities henüz tanımlı değildir. Önceden yazacaksanız kendi map'inizi tanımlayın, birleştirmeyi Bootstrap yapsın.
• utilities/api dosyasını import etmemek: map değişir ama hiçbir sınıf üretilmez.
• Bir grubu yalnızca values ile yeniden tanımlamak: birleştirme sığdır, property ve class kaybolur.
• Yeni sınıfın stok CDN dosyasında çalışmasını beklemek: API yalnızca kendi derlediğiniz CSS'i etkiler.
• Kendi CSS kuralınızla bir yardımcı sınıfı ezmeye çalışmak: yardımcılar !important taşır.
• Liste ile map'i karıştırmak: sınıf ekini değerden farklı istiyorsanız (ör. start: left) map kullanın.

Sık Sorulan Sorular

Utilities API olmadan yardımcı sınıf yazamaz mıyım?

Yazabilirsiniz; sıradan bir CSS sınıfı da iş görür. API'nin farkı, duyarlı, yazdırma ve durum varyantlarını Bootstrap'in kırılma noktaları ve adlandırmasıyla tutarlı biçimde tek tanımdan üretmesidir.

Hangi grupların duyarlı olduğunu nereden anlarım?

scss/_utilities.scss dosyasında grubun içinde responsive: true satırı olup olmadığına bakın. Örneğin display, float, margin ve padding grupları duyarlıdır; overflow ve border varsayılan olarak değildir.

Bir grubu kaldırmak dosya boyutunu gerçekten küçültür mü?

Evet; anahtarı null olan grup API döngüsünde atlanır ve o gruba ait hiçbir kural derlenen dosyaya yazılmaz. Ne kadar küçüleceği grubun büyüklüğüne bağlıdır; duyarlı gruplar her kırılma noktası için tekrarlandığı için daha fazla yer tutar.

Yardımcı sınıfları !important olmadan üretebilir miyim?

Evet, $enable-important-utilities: false; ile. Bu durumda yardımcı sınıfların bileşen kurallarını ezmesi CSS'in olağan özgüllük ve sıra kurallarına kalır; ayrıntı seçenekler yazısında.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Bootstrap öğrenme rehberi · Sass ile özelleştirme · Seçenekler ve CSS değişkenleri · Margin ve padding sınıfları · Display sınıfları · CSS öğrenme rehberi