Document.createProcessingInstruction() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createProcessingInstruction(target, data)

Beschreibung

createProcessingInstruction() erzeugt einen Knoten vom Typ ProcessingInstruction (nodeType 7). Eine Verarbeitungsanweisung ist eine Anweisung an die verarbeitende Anwendung und wird als <?ziel daten?> geschrieben. Das bekannteste Beispiel ist <?xml-stylesheet href="style.xsl" type="text/xsl"?>. Damit bindet man ein Stylesheet an ein XML-Dokument.

Die Methode braucht man vor allem, wenn man XML-Dokumente per Programmcode aufbaut oder verändert. Typische Fälle sind Dokumente aus document.implementation.createDocument() oder XML, das mit DOMParser eingelesen wurde. Wie bei createElement() oder createComment() ist der neue Knoten zunächst nicht im Dokument eingehängt. Das geschieht erst mit insertBefore(), appendChild(), prepend() oder ähnlichen Methoden.

Zwei Regeln werden geprüft: Das Ziel (target) muss ein gültiger XML-Name sein. Die Daten (data) dürfen die Zeichenfolge ?> nicht enthalten, denn sie würde die Anweisung vorzeitig beenden. Ist eine der beiden Regeln verletzt, wird eine DOMException vom Typ InvalidCharacterError ausgelöst.

Wichtig: Die XML-Deklaration <?xml version="1.0"?> ist im DOM keine Verarbeitungsanweisung. Mit dieser Methode lässt sie sich daher nicht sinnvoll erzeugen.

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	string		Ziel der Verarbeitungsanweisung, also der Teil direkt nach `<?`, z. B. `"xml-stylesheet"`. Muss ein gültiger XML-Name sein und steht später in `pi.target` und `pi.nodeName`.
$data Pflicht	string		Inhalt der Anweisung nach dem Ziel, z. B. `'href="style.css" type="text/css"'`. Darf `?>` nicht enthalten. Steht später in `pi.data`.

Rückgabewert

Typ

ProcessingInstruction

Beschreibung

Der neu erzeugte, noch nicht eingehängte ProcessingInstruction-Knoten. Sein ownerDocument ist das Dokument, auf dem die Methode aufgerufen wurde.

Beispiele

XML-Dokument mit Stylesheet-Anweisung erzeugen

// Neues XML-Dokument mit Wurzelelement <rezepte>
const doc = document.implementation.createDocument(null, 'rezepte', null);

// Verarbeitungsanweisung erzeugen und vor dem Wurzelelement einfügen
const pi = doc.createProcessingInstruction(
  'xml-stylesheet',
  'href="rezepte.xsl" type="text/xsl"'
);
doc.insertBefore(pi, doc.documentElement);

console.log(new XMLSerializer().serializeToString(doc));

<?xml-stylesheet href="rezepte.xsl" type="text/xsl"?><rezepte/>

Eigenschaften des Knotens auslesen und ändern

const doc = new DOMParser().parseFromString('<config/>', 'application/xml');
const pi = doc.createProcessingInstruction('app-hinweis', 'modus="debug"');

console.log(pi.nodeType === Node.PROCESSING_INSTRUCTION_NODE); // 7
console.log(pi.target, pi.nodeName); // Ziel = Knotenname
console.log(pi.data);

// Daten lassen sich nachträglich ändern (target nicht)
pi.data = 'modus="produktion"';
doc.prepend(pi);
console.log(new XMLSerializer().serializeToString(doc));

true app-hinweis app-hinweis modus="debug" <?app-hinweis modus="produktion"?><config/>

Ungültige Eingaben abfangen

const doc = document.implementation.createDocument(null, 'daten', null);

const sicherErzeugen = (target, data) => {
  try {
    return doc.createProcessingInstruction(target, data);
  } catch (err) {
    console.log(`${err.name}: target="${target}"`);
    return null;
  }
};

sicherErzeugen('1ziel', 'x');       // Ziel ist kein gültiger XML-Name
sicherErzeugen('ziel', 'a ?> b');   // Daten enthalten "?>"
console.log(sicherErzeugen('ziel', 'ok') !== null);

InvalidCharacterError: target="1ziel" InvalidCharacterError: target="ziel" true

// Wichtig · Fallstricke

Ausnahmen: Ein InvalidCharacterError wird ausgelöst, wenn target kein gültiger XML-Name ist oder data die Folge ?> enthält. Daten aus Benutzereingaben sollte man vorher prüfen oder den Aufruf in try…catch kapseln.
HTML-Dokumente: Nach aktuellem DOM-Standard funktioniert die Methode auch in HTML-Dokumenten. Ältere Browser, etwa ältere Firefox-Versionen, warfen dort einen NotSupportedError. Außerdem kennt der HTML-Parser keine Verarbeitungsanweisungen: Beim erneuten Einlesen, z. B. über innerHTML, wird aus <?…?> ein Kommentar. Sinnvoll ist die Methode daher praktisch nur in XML-Dokumenten.
Keine XML-Deklaration: <?xml version="1.0"?> ist keine Verarbeitungsanweisung. XMLSerializer gibt sie nicht aus. Wer sie braucht, setzt sie als Zeichenkette vor die serialisierte Ausgabe.
Keine Wirkung auf die Darstellung: Wird eine xml-stylesheet-Anweisung nachträglich per Code eingefügt, rendert der Browser das angezeigte Dokument nicht automatisch neu. Sie wirkt erst, wenn das serialisierte XML erneut geladen wird.
target ist nach dem Erzeugen schreibgeschützt. Nur data lässt sich über die Eigenschaften von CharacterData ändern.

Siehe auch

new ProcessingInstruction() Document.createCDATASection() Document.createExpression() Document.createNodeIterator() Document.createDocumentFragment()