val.h¶

Die Embind C++ Klasse emscripten::val (definiert in val.h) wird verwendet, um JavaScript-Code nach C++ zu transliterieren.

Anleitungsmaterial für diese Klasse finden Sie unter Verwenden von val zur Transliteration von JavaScript nach C++.

class emscripten::val¶

Diese Klasse ist ein C++-Datentyp, der verwendet werden kann, um jedes JavaScript-Objekt darzustellen (und bequemen Zugriff darauf zu ermöglichen). Sie können damit ein JavaScript-Objekt aufrufen, dessen Eigenschaften lesen und schreiben oder es in einen C++-Wert wie einen bool, int oder std::string umwandeln.

Zum Beispiel zeigt der folgende Code ein einfaches JavaScript zum Erstellen einer XHR-Anfrage an einer URL

var xhr = new XMLHttpRequest;
xhr.open("GET", "http://url");

Derselbe Code kann in C++ geschrieben werden, indem global() verwendet wird, um das Symbol für das globale XMLHttpRequest-Objekt zu erhalten und es dann zum Öffnen einer URL zu verwenden.

val xhr = val::global("XMLHttpRequest").new_();
xhr.call<void>("open", std::string("GET"), std::string("http://url"));

Sie können überprüfen, ob der Aufruf der Methode open erfolgreich war, indem Sie operator[]() verwenden, um eine Objekteigenschaft zu lesen, und dann as(), um den Typ zu erzwingen

const char* state;
switch (xhr["readyState"].as<int>()) {
case 0:
  state = "UNSENT"; break;
case 1:
  state = "OPENED"; break;
default:
  state = "etc";
}

Weitere Beispiele finden Sie unter Verwenden von val zur Transliteration von JavaScript nach C++.

Warnung

JavaScript-Werte können nicht über Threads hinweg gemeinsam genutzt werden, und daher auch keine val-Instanzen, die sie binden.

Wenn Sie beispielsweise eine JavaScript-Globale als val cachen möchten, müssen Sie separate Instanzen dieser Globalen unter ihrem Namen in jedem Thread abrufen und binden. Der einfachste Weg dazu ist eine thread_local-Deklaration

thread_local const val Uint8Array = val::global("Uint8Array");

static val array()¶: Erstellt und gibt ein neues Array zurück.

static val object()¶: Erstellt und gibt ein neues Object zurück.

static val u8string(const char *s)¶: Erstellt einen val aus einem String-Literal in UTF-8-Codierung.

static val u16string(const char16_t *s)¶: Erstellt einen val aus einem String-Literal in UTF-16-Codierung.

static val undefined()¶: Erstellt einen val, der undefined darstellt.

static val null()¶: Erstellt einen val, der null darstellt.

EM_VAL as_handle() const¶

Gibt ein Roh-Handle zurück, das diesen val darstellt. Dies kann verwendet werden, um Rohwert-Handles an JavaScript zu übergeben und die Werte auf der anderen Seite über die Funktion Emval.toValue abzurufen. Beispiel

EM_JS(void, log_value, (EM_VAL val_handle), {
  var value = Emval.toValue(val_handle);
  console.log(value); // 42
});

val foo(42);
log_value(foo.as_handle());

static val take_ownership(EM_VAL e)¶

Erstellt einen val aus einem rohen Handle. Dies kann verwendet werden, um Werte von JavaScript abzurufen, wobei die JavaScript-Seite einen Wert mit Emval.toHandle umschließen, an C++ übergeben und C++ dann take_ownership verwenden kann, um ihn in eine val-Instanz umzuwandeln. Beispiel

EM_ASYNC_JS(EM_VAL, fetch_json_from_url, (const char *url), {
  var url = UTF8ToString(url);
  var response = await fetch(url);
  var json = await response.json();
  return Emval.toHandle(json);
});

val obj = val::take_ownership(fetch_json_from_url("https://httpbin.org/json"));
std::string author = obj["slideshow"]["author"].as<std::string>();

static val global(const char *name)¶: Sucht einen globalen Wert anhand des angegebenen name.

static val module_property(const char *name)¶: Sucht einen Wert anhand des angegebenen name im Emscripten Modulobjekt.

explicit val(T &&value)¶

Konstruktor.

Erstellt einen val durch Konvertierung von einem beliebigen Embind-kompatiblen C++-Typ. Zum Beispiel val(true) oder val(std::string("foo")).

explicit val(const char *v)¶: Konstruiert eine val-Instanz aus einem String-Literal.

val(val &&v)¶: Verschiebt den Besitz eines Wertes auf eine neue val-Instanz.

val(const val &v)¶: Erstellt eine weitere Referenz auf denselben Wert hinter der bereitgestellten val-Instanz.

~val()¶: Entfernt den aktuell gebundenen Wert, indem dessen Referenzzähler verringert wird.

val &operator=(val &&v)¶: Entfernt eine Referenz auf den aktuell gebundenen Wert und übernimmt den bereitgestellten Wert.

val &operator=(const val &v)¶: Entfernt eine Referenz auf den aktuell gebundenen Wert und erstellt eine weitere Referenz auf den Wert hinter der bereitgestellten val-Instanz.

bool hasOwnProperty(const char *key) const¶: Prüft, ob das JavaScript-Objekt eine eigene (nicht geerbte) Eigenschaft mit dem angegebenen Namen besitzt.

val new_(Args&&... args) const¶: Geht davon aus, dass der aktuelle Wert ein Konstruktor ist und erstellt eine Instanz davon. Entspricht einem JavaScript-Ausdruck new currentValue(…).

val operator[](const T &key) const¶: Ruft die angegebene (key) Eigenschaft eines JavaScript-Objekts ab.

void set(const K &key, const val &v)¶: Setzt die angegebene (key) Eigenschaft eines JavaScript-Objekts (über einen val zugänglich) mit dem Wert v.

val operator()(Args&&... args) const¶: Geht davon aus, dass der aktuelle Wert eine Funktion ist und ruft diese mit den bereitgestellten Argumenten auf.

ReturnValue call(const char *name, Args&&... args) const¶: Ruft die angegebene Methode (name) auf dem aktuellen Objekt mit den bereitgestellten Argumenten auf.

T as() const¶: Konvertiert den aktuellen Wert in den angegebenen C++-Typ.

val typeof() const¶: Gibt das Ergebnis eines JavaScript-Operators typeof zurück, der auf den aktuellen Wert angewendet wird.

std::vector<T> vecFromJSArray(const val &v)¶

Kopiert ein JavaScript-Array in ein std::vector<T>, wobei jedes Element über .as<T>() konvertiert wird. Für eine effizientere, aber unsichere Version, die mit Zahlen arbeitet, siehe convertJSArrayToNumberVector.

Parameter: val v – Das zu kopierende JavaScript-Array
Gibt zurück: Ein aus dem JavaScript-Array erstelltes std::vector<T>

std::vector<T> convertJSArrayToNumberVector(const val &v)¶

Konvertiert ein JavaScript-Array effizient in ein std::vector<T>, als ob die JavaScript-Funktion Number() auf jedes Element angewendet würde. Dies ist bei Arrays mit mehr als 2 Werten wesentlich effizienter als vecFromJSArray, eignet sich aber nicht für Arrays mit nicht-numerischen Werten. Es wird keine Typprüfung durchgeführt, daher wird jeder ungültige Array-Eintrag stillschweigend durch einen NaN-Wert (oder 0 für ganzzahlige Typen) ersetzt.

Parameter: val v – Das zu kopierende JavaScript-(typisierte) Array
Gibt zurück: Ein std::vector<T> aus dem Javascript-Array

val await() const¶

Pausiert C++, um das Promise / Thenable await zu stellen.

Gibt zurück

Der erfüllte Wert.

Hinweis

Diese Methode erfordert, dass ASYNCIFY aktiviert ist.

val operator co_await() const¶

Der co_await-Operator ermöglicht das Warten auf JavaScript-Promises, die durch val dargestellt werden.

Es ist mit allen C++20-Koroutinen kompatibel, sollte aber normalerweise innerhalb einer val-zurückgebenden Koroutine verwendet werden, die ebenfalls zu einem Promise wird.

Zum Beispiel ermöglicht es Ihnen, das Äquivalent dieser JavaScript-Funktion async/await zu implementieren

async function foo() {
  const response = await fetch("http://url");
  const json = await response.json();
  return json;
}

export { foo };

als C++-Koroutine

val foo() {
  val response = co_await val::global("fetch")(std::string("http://url"));
  val json = co_await response.call<val>("json");
  return json;
}

EMSCRIPTEN_BINDINGS(module) {
  function("foo", &foo);
}

Im Gegensatz zur Methode await() benötigt sie Asyncify nicht, da sie die native C++-Koroutinen-Transformation verwendet.

Gibt zurück: Ein val, der den erfüllten Wert dieses Promises darstellt.