LitElement

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

參數

name

string

_old

null | string

value

null | string

詳細資訊

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

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

註冊 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');

當元件新增至文件的 DOM 時叫用。

詳細資訊

在 connectedCallback() 中，您應該設定僅在元件連接至文件時才會發生的任務。其中最常見的是將事件監聽器新增至元件外部的節點，例如新增至視窗的 keydown 事件處理常式。

connectedCallback() {
  super.connectedCallback();
  addEventListener('keydown', this._handleKeydown);
}

通常，在 connectedCallback() 中完成的任何操作都應該在元件斷線時於 disconnectedCallback() 中復原。

當元件從文件的 DOM 中移除時叫用。

詳細資訊

此回呼是元件可能不再使用的主要信號。disconnectedCallback() 應該確保沒有任何項目持有對元件的參照 (例如新增至元件外部節點的事件監聽器)，以便可以進行垃圾回收。

disconnectedCallback() {
  super.disconnectedCallback();
  window.removeEventListener('keydown', this._handleKeydown);
}

元件可能會在斷線後重新連接。

將初始化函式新增至在實例建構期間呼叫的類別。

參數

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。

確保此類別被標記為 finalized，作為一種優化，確保它不會不必要地嘗試 finalize。

詳細資訊

請注意，此屬性名稱是一個字串，以防止破壞 Closure JS 編譯器的優化。請參閱 @lit/reactive-element 以取得更多資訊。

如果元素原型上不存在屬性訪問器，則建立一個，並為具有給定選項的屬性儲存一個 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 選項的私有屬性。在需要時，可以透過公用屬性初始化狀態屬性，以促進複雜的互動。

在每次更新時呼叫，以執行呈現任務。此方法可能會傳回 lit-html 的 ChildPart 可呈現的任何值 - 通常是 TemplateResult。在此方法內設定屬性將不會觸發元素更新。

應將元素 DOM 呈現到其中的節點或 ShadowRoot。預設為開啟的 shadowRoot。

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

詳細資訊

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

所有元素樣式的記憶列表。在最終確定類別時，在使用者子類別上惰性建立。

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

參數

styles?

CSSResultGroup

詳細資訊

樣式會進行重複資料刪除，並保留列表中最後一個實例。這是一種效能最佳化，可避免重複的樣式，這種情況在透過子類別組合時尤其容易發生。保留最後一個項目是為了嘗試保留層疊順序，並假設最後加入的樣式會覆蓋先前的樣式，這一點最為重要。

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

詳細資訊

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

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

請注意，此方法應視為最終方法，且不應覆寫。它會使用觸發第一次更新的函式在元素執行個體上覆寫。

參數

_requestedUpdate

布林值

在元素第一次更新時叫用。實作以便在更新後對元素執行一次性工作。

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有舊值的變更屬性對應

詳細資訊

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

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

updateComplete Promise 的覆寫點。

詳細資訊

由於 TypeScript 中的限制，直接覆寫 updateComplete getter 並不安全，這表示當目標語言為 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() 以同步處理更新變得困難。

要求以非同步方式處理的更新。當元素應根據設定反應屬性時未觸發的某些狀態進行更新時，應呼叫此函式。在此情況下，請勿傳遞任何引數。當手動實作屬性設定程式時，也應呼叫此函式。在此情況下，請傳遞屬性 name 和 oldValue，以確保任何已設定的屬性選項都受到尊重。

參數

name?

PropertyKey

要求屬性的名稱

oldValue?

未知

要求屬性的舊值

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>

具有舊值的變更屬性對應

更新元素。此方法會將屬性值反映到屬性，並呼叫 render 以透過 lit-html 轉譯 DOM。在此方法內設定屬性將不會觸發另一個更新。

參數

changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有舊值的變更屬性對應

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

詳細資訊

若要等待其他非同步工作，請覆寫 getUpdateComplete 方法。例如，在滿足此 Promise 之前，等待轉譯元素有時很有用。若要執行此操作，請先等待 super.getUpdateComplete()，然後等待任何後續狀態。

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

參數

_changedProperties

Map<PropertyKey, unknown> | PropertyValueMap<any>

具有舊值的變更屬性對應

詳細資訊

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

在 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}`;
}

用於複製範本的節點（將在此節點上呼叫 importNode）。這會控制轉譯 DOM 的 ownerDocument，以及任何繼承的內容。預設為全域 document。

要用作事件接聽程式的 this 值的物件。通常將此值設定為轉譯範本的主機元件會很有用。

呈現最上層部分的初始連線狀態。如果沒有設定 isConnected 選項，AsyncDirective 預設會連線。如果初始呈現發生在未連線的樹狀結構中，且 AsyncDirective 在其初始呈現時應看到 isConnected === false，則設為 false。初始呈現後，必須使用 part.setConnected() 方法來變更部分的連線狀態。

在容器中呈現內容之前的 DOM 節點。