dart:html

使用 dart:html 程式庫來程式設計瀏覽器、操作 DOM 中的物件和元素，並存取 HTML5 API。DOM 代表文件物件模型，它描述了 HTML 頁面的階層結構。

dart:html 的其他常見用途包括操作樣式 (CSS)、使用 HTTP 請求取得資料，以及使用 WebSockets 交換資料。HTML5（和 dart:html）還有許多本節未涵蓋的其他 API。只有 Web 應用程式可以使用 dart:html，命令列應用程式則不行。

若要在 Web 應用程式中使用 HTML 程式庫，請匯入 dart:html

import 'dart:html';

若要使用 DOM，您需要了解視窗、文件、元素和節點。

Window 物件代表 Web 瀏覽器的實際視窗。每個 Window 都有一個 Document 物件，它指向目前載入的文件。Window 物件還可以存取各種 API，例如 IndexedDB（用於儲存資料）、requestAnimationFrame（用於動畫）等等。在分頁瀏覽器中，每個分頁都有自己的 Window 物件。

使用 Document 物件，您可以在文件中建立和操作 Element 物件。請注意，文件本身也是一個元素，可以進行操作。

DOM 會對 節點樹狀結構進行建模。這些節點通常是元素，但也可能是屬性、文字、註解和其他 DOM 類型。除了沒有父節點的根節點之外，DOM 中的每個節點都有一個父節點，並且可能有許多子節點。

若要操作元素，您首先需要一個代表它的物件。您可以使用查詢來取得此物件。

使用頂層函式 querySelector() 和 querySelectorAll() 尋找一個或多個元素。您可以依 ID、類別、標籤、名稱或這些的任何組合來查詢。CSS 選取器規格指南定義了選取器的格式，例如使用 # 字首來指定 ID，以及使用句點 (.) 來指定類別。

querySelector() 函式會傳回第一個符合選取器的元素，而 querySelectorAll() 則會傳回符合選取器的元素集合。

// Find an element by id (an-id).
Element idElement = querySelector('#an-id')!;

// Find an element by class (a-class).
Element classElement = querySelector('.a-class')!;

// Find all elements by tag (<div>).
List<Element> divElements = querySelectorAll('div');

// Find all text inputs.
List<Element> textInputElements = querySelectorAll(
  'input[type="text"]',
);

// Find all elements with the CSS class 'class'
// inside of a <p> that is inside an element with
// the ID 'id'.
List<Element> specialParagraphElements = querySelectorAll('#id p.class');

您可以使用屬性來變更元素的狀態。Node 及其子類型 Element 定義了所有元素都擁有的屬性。例如，所有元素都具有 classes、hidden、id、style 和 title 屬性，可用於設定狀態。Element 的子類別定義了其他屬性，例如 AnchorElement 的 href 屬性。

請考慮以下在 HTML 中指定錨點元素的範例

<a id="example" href="/another/example">link text</a>

此 <a> 標籤指定了一個具有 href 屬性和文字節點（可透過 text 屬性存取）的元素，其中包含字串「連結文字」。若要變更連結前往的 URL，您可以使用 AnchorElement 的 href 屬性

var anchor = querySelector('#example') as AnchorElement;
anchor.href = 'https://dart.dev.org.tw';

通常您需要在多個元素上設定屬性。例如，下列程式碼會設定所有具有「mac」、「win」或「linux」類別的元素的 hidden 屬性。將 hidden 屬性設定為 true 的效果與將 display: none 新增至 CSS 相同。

<!-- In HTML: -->
<p>
  <span class="linux">Words for Linux</span>
  <span class="macos">Words for Mac</span>
  <span class="windows">Words for Windows</span>
</p>

// In Dart:
const osList = ['macos', 'windows', 'linux'];
final userOs = determineUserOs();

// For each possible OS...
for (final os in osList) {
  // Matches user OS?
  bool shouldShow = (os == userOs);

  // Find all elements with class=os. For example, if
  // os == 'windows', call querySelectorAll('.windows')
  // to find all elements with the class "windows".
  // Note that '.$os' uses string interpolation.
  for (final elem in querySelectorAll('.$os')) {
    elem.hidden = !shouldShow; // Show or hide.
  }
}

當正確的屬性不可用或不方便時，您可以使用 Element 的 attributes 屬性。此屬性是一個 Map<String, String>，其中鍵是屬性名稱。如需屬性名稱及其含義的清單，請參閱MDN 屬性頁面。以下是設定屬性值的範例

elem.attributes['someAttribute'] = 'someValue';

您可以透過建立新元素並將其附加到 DOM 來新增到現有的 HTML 頁面。以下是建立段落 (<p>) 元素的範例

var elem = ParagraphElement();
elem.text = 'Creating is easy!';

您也可以透過剖析 HTML 文字來建立元素。任何子元素也會被剖析和建立。

var elem2 = Element.html(
  '<p>Creating <em>is</em> easy!</p>',
);

請注意，在前面的範例中，elem2 是一個 ParagraphElement。

透過將父節點指派給元素，將新建立的元素附加到文件中。您可以將元素新增至任何現有元素的子元素。在下列範例中，body 是一個元素，並且可以從 children 屬性存取其子元素（作為 List<Element>）。

document.body!.children.add(elem2);

回想一下，元素只是一種節點。您可以使用 Node 的 nodes 屬性找到節點的所有子節點，該屬性會傳回 List<Node>（與省略非 Element 節點的 children 不同）。取得此清單後，您可以使用常用的 List 方法和運算子來操作節點的子節點。

若要將節點新增為其父節點的最後一個子節點，請使用 List add() 方法

querySelector('#inputs')!.nodes.add(elem);

若要取代節點，請使用 Node replaceWith() 方法

querySelector('#status')!.replaceWith(elem);

若要移除節點，請使用 Node remove() 方法

// Find a node by ID, and remove it from the DOM if it is found.
querySelector('#expendable')?.remove();

CSS 或串接樣式表，定義了 DOM 元素的呈現樣式。您可以透過將 ID 和類別屬性附加到元素來變更元素的外觀。

每個元素都有一個 classes 欄位，它是一個清單。只需從此集合中新增和移除字串，即可新增和移除 CSS 類別。例如，下列範例會將 warning 類別新增至元素

var elem = querySelector('#message')!;
elem.classes.add('warning');

依 ID 尋找元素通常非常有效率。您可以使用 id 屬性動態設定元素 ID

var message = DivElement();
message.id = 'message2';
message.text = 'Please subscribe to the Dart mailing list.';

您可以使用方法串接來減少此範例中重複的文字

var message = DivElement()
  ..id = 'message2'
  ..text = 'Please subscribe to the Dart mailing list.';

雖然使用 ID 和類別將元素與一組樣式關聯是最佳實踐，但有時您會希望直接將特定樣式附加到元素。

message.style
  ..fontWeight = 'bold'
  ..fontSize = '3em';

若要回應外部事件，例如點擊、焦點變更和選取，請新增事件監聽器。您可以將事件監聽器新增至頁面上的任何元素。事件分派和傳播是一個複雜的主題；如果您是 Web 程式設計新手，請研究詳細資訊。

使用 element.onEvent.listen(function) 新增事件處理常式，其中 Event 是事件名稱，而 function 是事件處理常式。

例如，以下說明如何處理按鈕上的點擊事件

// Find a button by ID and add an event handler.
querySelector('#submitInfo')!.onClick.listen((e) {
  // When the button is clicked, it runs this code.
  submitData();
});

事件可以在 DOM 樹狀結構中向上和向下傳播。若要找出最初觸發事件的元素，請使用 e.target。

document.body!.onClick.listen((e) {
  final clickedElem = e.target;
  // ...
});

若要查看您可以註冊事件監聽器的所有事件，請在 Element 及其子類別的 API 文件中尋找「onEventType」屬性。一些常見的事件包括：

• change (變更)
• blur (失去焦點)
• keyDown (按下按鍵)
• keyUp (放開按鍵)
• mouseDown (按下滑鼠按鍵)
• mouseUp (放開滑鼠按鍵)

您應該避免直接使用 dart:html 發出 HTTP 請求。 dart:html 中的 HttpRequest 類別與平台相關，並與單一實作綁定。 請改用更高等級的程式庫，例如 package:http。

從網際網路擷取資料 教學課程說明如何使用 package:http 發出 HTTP 請求。

WebSocket 可讓您的 Web 應用程式與伺服器互動式交換資料，而無需輪詢。 伺服器會建立 WebSocket 並監聽以 ws:// 開頭的 URL 上的請求，例如 ws://127.0.0.1:1337/ws。透過 WebSocket 傳輸的資料可以是字串或 blob。通常，資料是 JSON 格式的字串。

若要在您的 Web 應用程式中使用 WebSocket，請先建立 WebSocket 物件，並將 WebSocket URL 作為引數傳遞。

var ws = WebSocket('ws://echo.websocket.org');

若要在 WebSocket 上傳送字串資料，請使用 send() 方法。

ws.send('Hello from Dart!');

若要在 WebSocket 上接收資料，請註冊訊息事件的監聽器。

ws.onMessage.listen((MessageEvent e) {
  print('Received message: ${e.data}');
});

訊息事件處理常式會收到一個 MessageEvent 物件。此物件的 data 欄位具有來自伺服器的資料。

您的應用程式可以處理下列 WebSocket 事件：open、close、error 和（如先前所示）message。以下是一個建立 WebSocket 物件並註冊 open、close、error 和 message 事件處理常式的方法範例。

void initWebSocket([int retrySeconds = 1]) {
  var reconnectScheduled = false;

  print('Connecting to websocket');

  void scheduleReconnect() {
    if (!reconnectScheduled) {
      Timer(Duration(seconds: retrySeconds),
          () => initWebSocket(retrySeconds * 2));
    }
    reconnectScheduled = true;
  }

  ws.onOpen.listen((e) {
    print('Connected');
    ws.send('Hello from Dart!');
  });

  ws.onClose.listen((e) {
    print('Websocket closed, retrying in $retrySeconds seconds');
    scheduleReconnect();
  });

  ws.onError.listen((e) {
    print('Error connecting to ws');
    scheduleReconnect();
  });

  ws.onMessage.listen((MessageEvent e) {
    print('Received message: ${e.data}');
  });
}

本節僅淺談使用 dart:html 程式庫的皮毛。如需更多資訊，請參閱 dart:html 的文件。 Dart 有其他程式庫可用於更專業的 Web API，例如 Web 音訊、IndexedDB 和 WebGL。

如需有關 Dart Web 程式庫的更多資訊，請參閱 Web 程式庫概觀。

除非另有說明，否則本網站上的文件反映的是 Dart 3.6.0。 頁面最後更新時間：2024-11-17。 檢視原始碼 或 回報問題。