ReactiveElement

當特性變更時，同步屬性值。

參數

name

string

_old

null | string

value

null | string

詳細資訊

具體來說，當設定特性時，會設定對應的屬性。您很少需要實作此回呼。如果覆寫此方法，則必須呼叫 super.attributeChangedCallback(name, _old, value)。請參閱 MDN 上關於 attributeChangedCallback 的使用生命週期回呼以取得更多資訊。

傳回對應於已註冊屬性的特性清單。

註冊一個 ReactiveController 以參與元件的響應式更新週期。元件會在生命週期回呼期間自動呼叫任何已註冊的控制器。

參數

controller

ReactiveController

詳細資訊

如果在呼叫 addController() 時元件已連線，則會立即呼叫控制器的 hostConnected() 回呼。

從元件中移除 ReactiveController。

參數

controller

ReactiveController

針對此類別停用指定的警告類別。

詳細資訊

此方法僅存在於開發組建中，因此應該使用保護措施來存取，例如

// Disable for all ReactiveElement subclasses
ReactiveElement.disableWarning?.('migration');
// Disable for only MyElement and subclasses
MyElement.disableWarning?.('migration');

讀取或設定此類別的所有已啟用警告類別。

詳細資訊

此屬性僅在開發組建中使用。

針對此類別啟用指定的警告類別。

詳細資訊

此方法僅存在於開發組建中，因此應該使用保護措施來存取，例如

// Enable for all ReactiveElement subclasses
ReactiveElement.enableWarning?.('migration');
// Enable for only MyElement and subclasses
MyElement.enableWarning?.('migration');

在第一次連線時，建立元件的 renderRoot、設定元件樣式，並啟用更新。

允許擴充中的 super.disconnectedCallback()，同時保留未來在斷線時進行非破壞性功能新增的可能性。

將一個初始化函數新增到類別，該函數會在實例建構期間呼叫。

參數

initializer

Initializer

詳細資訊

這對於針對 ReactiveElement 子類別執行的程式碼很有用，例如裝飾器，需要在每個實例執行工作，例如設定 ReactiveController。

const myDecorator = (target: typeof ReactiveElement, key: string) => {
  target.addInitializer((instance: ReactiveElement) => {
    // This is run during construction of the element
    new MyController(instance);
  });
}

然後，裝飾欄位會導致每個實例執行一個初始化程式，以新增控制器

class MyElement extends LitElement {
  @myDecorator foo;
}

初始化程式會儲存在每個建構函式中。將初始化程式新增到子類別不會將其新增到父類別。由於初始化程式在建構函式中執行，因此初始化程式會按照類別階層順序執行，從父類別開始，然後進展到實例的類別。

為已註冊的屬性建立屬性存取器、設定元件樣式，並確保任何父類別也都已完成。如果元件已完成，則傳回 true。

將類別標記為已完成建立屬性。

如果元件原型上不存在屬性存取器，則建立該存取器，並儲存具有指定選項的屬性的 PropertyDeclaration。屬性設定器會呼叫屬性的 hasChanged 屬性選項，或使用嚴格的相等性檢查來判斷是否要求更新。

參數

name

PropertyKey

options?

PropertyDeclaration<unknown, unknown>

詳細資訊

這個方法可以被覆寫以自訂屬性；然而，當這樣做時，重要的是要呼叫 super.createProperty 以確保屬性被正確設定。這個方法內部會呼叫 getPropertyDescriptor 來取得要安裝的描述符。若要自訂屬性在被讀取或設定時的行為，請覆寫 getPropertyDescriptor。若要自訂屬性的選項，請像這樣實作 createProperty

static createProperty(name, options) {
  options = Object.assign(options, {myOption: true});
  super.createProperty(name, options);
}

所有元素屬性的記憶化清單，包括任何超類別屬性。在使用者子類別完成類別時，會延遲建立。

傳回要定義在給定名稱屬性上的屬性描述符。如果沒有傳回描述符，則該屬性將不會變成存取器。例如，

參數

name

PropertyKey

key

string | symbol

options

PropertyDeclaration<unknown, unknown>

詳細資訊

class MyElement extends LitElement {
  static getPropertyDescriptor(name, key, options) {
    const defaultDescriptor =
        super.getPropertyDescriptor(name, key, options);
    const setter = defaultDescriptor.set;
    return {
      get: defaultDescriptor.get,
      set(value) {
        setter.call(this, value);
        // custom action.
      },
      configurable: true,
      enumerable: true
    }
  }
}

傳回與給定屬性相關聯的屬性選項。這些選項是透過 properties 物件或 @property 裝飾器，使用 PropertyDeclaration 定義，並在 createProperty(...) 中註冊。

參數

name

PropertyKey

詳細資訊

請注意，這個方法應該被視為「最終」且不應被覆寫。若要自訂給定屬性的選項，請覆寫 createProperty。

使用者提供的物件，將屬性名稱對應到包含配置響應式屬性選項的 PropertyDeclaration 物件。當設定響應式屬性時，元素將會更新並渲染。

詳細資訊

預設情況下，屬性是公開欄位，因此應被視為主要由元素使用者透過屬性或屬性本身設定。通常，由元素變更的屬性應為私有或受保護的欄位，並應使用 state: true 選項。標記為 state 的屬性不會從對應的屬性反映出來。然而，有時元素程式碼確實需要設定一個公開屬性。這通常只應在回應使用者互動時完成，並應觸發一個事件通知使用者；例如，一個核取方塊在被點擊時會設定其 checked 屬性，並觸發一個 changed 事件。對於非原始（物件或陣列）屬性，通常不應變更公開屬性。在其他元素需要管理狀態的情況下，應使用設定為 state: true 選項的私有屬性。在需要時，可以透過公開屬性初始化狀態屬性，以方便複雜的互動。

傳回元素應渲染到的節點，預設會建立並傳回一個開放的 shadowRoot。實作此方法以自訂元素 DOM 的渲染位置。例如，若要渲染到元素的 childNodes 中，請傳回 this。

元素 DOM 應渲染到的節點或 ShadowRoot。預設為開放的 shadowRoot。

呼叫 attachShadow 時使用的選項。設定此屬性以自訂 shadowRoot 的選項；例如，若要建立關閉的 shadowRoot：{mode: 'closed'}。

詳細資訊

請注意，這些選項在 createRenderRoot 中使用。如果自訂此方法，應盡可能尊重選項。

所有元素樣式的記憶化清單。在使用者子類別完成類別時，會延遲建立。

採用使用者透過 static styles 屬性提供的樣式，並傳回要應用於元素的樣式陣列。覆寫此方法以整合到樣式管理系統中。

參數

styles?

CSSResultGroup

詳細資訊

樣式會進行重複資料刪除，保留清單中最後一個實例。這是一種效能優化，可避免重複的樣式，這種情況尤其在透過子類別撰寫時可能發生。保留最後一個項目是為了嘗試保留階層順序，並假設最後新增的樣式覆寫先前的樣式最為重要。

要應用於元素的樣式陣列。這些樣式應使用 css 標籤函式、透過可建構樣式表或從原生 CSS 模組腳本匯入來定義。

詳細資訊

關於內容安全策略的注意事項：當瀏覽器不支援採用的樣式表時，元素樣式會使用 <style> 標籤實作。若要將此類 <style> 標籤與 style-src CSP 指令一起使用，style-src 值必須包含 'unsafe-inline' 或 nonce-<base64-value>，其中 <base64-value> 會被伺服器產生的 nonce 取代。若要在產生的 <style> 元素上提供要使用的 nonce，請在載入應用程式程式碼之前，在您頁面的 HTML 中將 window.litNonce 設定為伺服器產生的 nonce

<script>
  // Generated and unique per request:
  window.litNonce = 'a1b2c3d4';
</script>

請注意，這個方法應該被視為最終且不應被覆寫。它會在元素實例上被一個觸發第一次更新的函式覆寫。

參數

_requestedUpdate

boolean

在元素第一次更新時呼叫。實作此方法以在更新後對元素執行一次性的工作。

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

包含變更屬性及其舊值的 Map

詳細資訊

firstUpdated() {
  this.renderRoot.getElementById('my-text-area').focus();
}

在此方法內設定屬性將會在此更新週期完成後再次觸發元素的更新。

updateComplete Promise 的覆寫點。

詳細資訊

直接覆寫 updateComplete getter 並不安全，因為 TypeScript 的限制，這表示當目標語言為 ES5 時，無法呼叫超類別 getter (例如 super.updateComplete.then(...)) (https://github.com/microsoft/TypeScript/issues/338)。應改為覆寫此方法。例如

class MyElement extends LitElement {
  override async getUpdateComplete() {
    const result = await super.getUpdateComplete();
    await this._myChild.updateComplete;
    return result;
  }
}

在第一次更新後設定為 true。元素程式碼不能假設在元素 hasUpdated 之前就存在 renderRoot。

如果因為呼叫 requestUpdate() 而有待處理的更新，則為 True。應該只讀取此值。

執行元素更新。請注意，如果在更新期間擲出例外，將不會呼叫 firstUpdated 和 updated。

詳細資訊

呼叫 performUpdate() 以立即處理待處理的更新。這通常不需要，但在您需要同步更新的極少數情況下可以這樣做。注意：為了確保 performUpdate() 同步完成待處理的更新，不應覆寫此方法。在 LitElement 2.x 中，建議覆寫 performUpdate() 以自訂更新排程。相反地，您現在應該覆寫 scheduleUpdate()。為了與 LitElement 2.x 回溯相容，透過 performUpdate() 排程更新仍然有效，但也會使得呼叫 performUpdate() 來同步處理更新變得困難。

請求以非同步方式處理的更新。當元素應根據某些未透過設定反應屬性觸發的狀態進行更新時，應該呼叫此方法。在這種情況下，請勿傳遞任何引數。當手動實作屬性 setter 時，也應呼叫此方法。在這種情況下，傳遞屬性 name 和 oldValue，以確保任何已設定的屬性選項都會被採用。

參數

name?

PropertyKey

請求屬性的名稱

oldValue?

unknown

請求屬性的舊值

options?

PropertyDeclaration<unknown, unknown>

要使用而非先前設定的選項的屬性選項

排程元素更新。您可以覆寫此方法，透過傳回 Promise 來變更更新的時機。更新將會等待傳回的 Promise，您應該解析 Promise 以允許更新繼續進行。如果覆寫此方法，則必須呼叫 super.scheduleUpdate()。

詳細資訊

例如，若要排程更新在下一個影格之前發生

override protected async scheduleUpdate(): Promise<unknown> {
  await new Promise((resolve) => requestAnimationFrame(() => resolve()));
  super.scheduleUpdate();
}

控制當元素請求更新時是否應呼叫 update()。預設情況下，此方法永遠傳回 true，但可以自訂以控制何時更新。

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

包含變更屬性及其舊值的 Map

更新元素。此方法會將屬性值反映到屬性。可以覆寫此方法以呈現並保持更新的元素 DOM。在此方法內設定屬性將 *不會* 觸發另一個更新。

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

包含變更屬性及其舊值的 Map

傳回當元素完成更新時解析的 Promise。Promise 值是一個布林值，如果元素在未觸發另一個更新的情況下完成更新，則為 true。如果屬性是在 updated() 內設定的，則 Promise 結果為 false。如果 Promise 被拒絕，則表示在更新期間擲出例外。

詳細資訊

若要等待額外的非同步工作，請覆寫 getUpdateComplete 方法。例如，在實現此 Promise 之前等待呈現的元素有時會很有用。若要執行此操作，請先等待 super.getUpdateComplete()，然後等待任何後續狀態。

每當元素更新時叫用。實作以透過 DOM API 執行更新後的工作，例如，聚焦元素。

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

包含變更屬性及其舊值的 Map

詳細資訊

在此方法內設定屬性將會在此更新週期完成後再次觸發元素的更新。

在 update() 之前叫用，以計算更新期間所需的值。

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

詳細資訊

實作 willUpdate 來計算依賴其他屬性且在更新程序的其餘部分使用的屬性值。

willUpdate(changedProperties) {
  // only need to check changed properties for an expensive computation.
  if (changedProperties.has('firstName') || changedProperties.has('lastName')) {
    this.sha = computeSHA(`${this.firstName} ${this.lastName}`);
  }
}
render() {
  return html`SHA: ${this.sha}`;
}

呼叫以將屬性值轉換為屬性值。

參數

value

null | string

type?

TypeHint

呼叫以將屬性值轉換為屬性值。

參數

value

類型

type?

TypeHint

詳細資訊

它會傳回 unknown 而不是 string，以便與 https://github.com/WICG/trusted-types (以及類似的努力) 相容。

指出屬性如何以及是否變成觀察的屬性。如果值為 false，則不會將屬性新增至 observedAttributes。如果為 true 或不存在，則會觀察到小寫的屬性名稱 (例如，fooBar 變成 foobar)。如果是字串，則會觀察到字串值 (例如，attribute: 'foo-bar')。

指示如何將屬性轉換為/從屬性轉換。如果此值為函式，則會使用它來將屬性值轉換為屬性值。如果它是一個物件，則可以具有 fromAttribute 和 toAttribute 的鍵。如果未提供 toAttribute 函式且 reflect 設定為 true，則會將屬性值直接設定為屬性。如果沒有提供，則會使用預設的 converter；它支援 Boolean、String、Number、Object 和 Array。請注意，當屬性變更且轉換器用於更新屬性時，該屬性永遠不會因為屬性變更而再次更新，反之亦然。

指示是否會為此屬性建立存取子。預設情況下，將會為此屬性產生一個存取子，該存取子會在設定時請求更新。如果此旗標為 true，則不會建立存取子，並且使用者有責任呼叫 this.requestUpdate(propertyName, oldValue) 以在屬性變更時請求更新。

指示屬性是否應反映到屬性。如果為 true，則在設定屬性時，會根據 attribute 屬性選項的規則以及使用 converter 屬性選項的規則轉換的屬性值來設定屬性。

設定為 true 時，表示該屬性是內部私有狀態。使用者不應設定該屬性。使用 TypeScript 時，此屬性應標記為 private 或 protected，並且也常見在名稱中使用前導 _。該屬性不會新增至 observedAttributes。

指示屬性的類型。這僅用作 converter 的提示，以確定如何將屬性轉換為/從屬性。

一個函式，指示在設定屬性時是否應將其視為已變更。如果應請求更新，則該函式應接受 newValue 和 oldValue 並返回 true。

參數

value

類型

oldValue

類型