adoptStyles / adoptSheetText

CSS را به یک Shadow DOM تزریق می‌کند و Constructable Stylesheets را ترجیح می‌دهد: یک CSS تنها یک بار تجزیه می‌شود و سپس با ارجاع میان همهٔ نمونه‌های مؤلفه به اشتراک می‌رود، پس هزار نمونه هم تنها یک نتیجهٔ تجزیه‌شده در دست دارند. آنجا که پشتیبانی نشود، هر دو به تزریق تگ <style> پناه می‌برند.

هر دو در SSR امن‌اند (وقتی document نباشد بی‌درنگ بازمی‌گردند) و چندبار فراخواندنشان نتیجه را عوض نمی‌کند.

کاربرد

import css from './index.less?inline';
import { adoptStyles } from 'ranuts/utils';

class MyElement extends HTMLElement {
  constructor() {
    super();
    const root = this.shadowRoot || this.attachShadow({ mode: 'closed' });
    adoptStyles(root, css);
  }
}

API

adoptStyles

برای سبک‌های ایستای یک مؤلفه. مسیر جایگزین، تکرار را به‌ازای هر ریشه می‌گیرد: هر shadow root دقیقاً یک <style> نشان‌دار نگه می‌دارد و نخستین نویسنده برنده است. سبک‌های ایستای یک مؤلفه باید در هر ریشه یک بار باشند، پس فراخوانی دوم یعنی فراخواننده اشتباه کرده است.

پارامترها

پارامتر	توضیح	نوع	پیش‌فرض
shadowRoot	shadow root مقصد	ShadowRoot	الزامی
cssText	متن سبک	string	الزامی
marker	ویژگی نشانه روی <style> جایگزین	string	'data-adopted-style'

بازگشت

بدون مقدار بازگشتی (void)

adoptSheetText

برای سبک‌های پویا که در زمان اجرا داده می‌شوند (مثلاً ویژگی sheet یک مؤلفه). تنها فرقش با adoptStyles این است که مسیر جایگزین تکرار را بر چه پایه‌ای می‌گیرد: اینجا بر پایهٔ cssText، پس یک ریشه می‌تواند چند شیوه‌نامهٔ پویای متفاوت را روی هم بچیند، حال آنکه شیوه‌نامهٔ یکسان تنها یک بار تزریق می‌شود.

پارامترها

پارامتر	توضیح	نوع	پیش‌فرض
shadowRoot	shadow root مقصد	ShadowRoot	الزامی
cssText	متن سبک	string	الزامی
marker	ویژگی نشانه روی <style> جایگزین	string	'data-adopted-sheet'

بازگشت

بدون مقدار بازگشتی (void)

ثابت‌ها

نام	مقدار	معنا
ADOPTED_STYLE_MARKER	'data-adopted-style'	نشانهٔ پیش‌فرض تگ جایگزینِ adoptStyles
ADOPTED_SHEET_MARKER	'data-adopted-sheet'	نشانهٔ پیش‌فرض تگ جایگزینِ adoptSheetText

آرگومان marker از آن روست که یک کتابخانه بتواند سبک‌هایی را که تزریق می‌کند نشان بگذارد و بعدها بازشان بیابد. برای نمونه، ranui مقدارهای data-ranui و data-ranui-sheet را می‌دهد.