Benutzerdefinierten Gutenberg-Block erstellen – Teil 4: Attribute

In diesem Teil sehen wir uns an, wie Attribute definiert, ihre Werte abgerufen und aktualisiert werden. Mit Attributen können wir Eingaben vom Editor akzeptieren, speichern und nach Belieben ausgeben. Im vorherigen Schritt haben wir uns WordPress-Komponenten angesehen, wo sie zu finden sind und wie sie implementiert werden. In diesem Beitrag fügen wir Requisiten hinzu, um die Verbindung zu Attributen herzustellen – den gespeicherten Daten.

Attribute definieren

attributesAttribute werden der Eigenschaft in als Objekte in einem Array hinzugefügt registerBlockType(). Der Schlüssel jedes Attributs ist der Attributname, und Sie müssen typemindestens die Eigenschaft haben.

Die typeEigenschaft kann eine der folgenden sein; null, boolean, object, array, number, string, oder integer.

Optional können Sie die Eigenschaft defaultangeben, um den Startwert Ihres Attributs zu definieren. Wenn Sie keinen Standardwert angeben, wird das Attribut standardmäßig auf null.

Eine weitere Attribut-Eigenschaft ist sourcedie, die mit der selectorEigenschaft zusammenarbeitet, aber das sind knifflige Dinge, die wir uns weiter unten im Detail ansehen werden.

Zum Beispiel zwei Attribute definieren; exampleTextals String und postIdsals Array würde so aussehen:

const { registerBlockType } = wp.blocks;
registerBlockType('awp/firstblock', {
    title: 'My first block',
    category: 'common',
    attributes: {
        exampleText: {
            type: 'string',
            default: ''
        },
        postIds: {
            type: 'array'
            default: []
        }
    },
    edit: (props) => { 
    ...

Alles, was Sie für Ihren Block speichern müssen (Eingaben des Benutzers/Editors), erfordert ein Attribut. Es liegt an Ihnen, wie Sie Ihre Daten strukturieren, indem Sie für jeden einzelne Attribute definieren oder sie alle in einem Objekt bündeln. Es wird nur ein Unterschied darin sein, wie Sie ihre Daten abrufen und wie Sie sie aktualisieren.

Attributwerte abrufen

Attribute sind als Requisiten für Ihre Blöcke editund saveFunktionen verfügbar. Wenn Sie dieser Serie vom vorherigen Schritt gefolgt sind, denken Sie daran, dass wir die Funktionen aktualisiert haben, um Requisiten als Parameter zu übergeben.

Es ist üblich, Attribute aus Requisiten zu destrukturieren, wie Sie sie normalerweise oft verwenden würden. Die Ausgabe eines aufgerufenen Attributs exampleTextwürde beispielsweise so aussehen:

edit: (props) => { 
    const { attributes } = props;
    return <div>{attributes.exampleText}</div>
},

Aktualisieren von Attributwerten

Um Attribute zu aktualisieren, haben wir in Requisiten eine Methode namens setAttributes(). Diese Funktion akzeptiert ein Objekt, dem Sie jedes Attribut hinzufügen können, das Sie aktualisieren möchten. Sie können nur ein Attribut, mehrere oder alle gleichzeitig aktualisieren. Wenn Sie mehrere Attribute definiert haben und setAttributes()nur eines davon aktualisieren möchten, werden die anderen nicht berührt.

Wenn Sie Erfahrung mit React haben, werden Sie wahrscheinlich sofort Ähnlichkeiten zwischen setAttributes()und erkennen setState(). Sie funktionieren genau gleich, aber der Unterschied besteht darin, dass der Zustand in React nur etwas ist, das lokal in dieser Komponente gespeichert wird, und Attribute tatsächlich als Daten außerhalb der Komponente gespeichert werden.

Um ein Attribut zu aktualisieren, würden Sie normalerweise die Funktion von Requisiten zerstören und sie so nennen: Unten aktualisieren wir exampleTextdas Attribut auf „Hi”.

const { setAttributes } = props;
setAttributes({ exampleText: 'Hi' });

Natürlich würden Sie das setAttributes()innerhalb einer Aktion ausführen. Ein gängiges Beispiel ist innerhalb der onChangeRequisite eine Art Eingabefeld, das zum Speichern des exampleTextAttributwerts verwendet wird.

Achten Sie darauf, Attribute in dem Typ zu speichern, den Sie für das Attribut definiert haben. Sie werden zum Beispiel kein Glück haben, wenn Sie versuchen, Objekte in einem String-Attribut zu speichern.

Probieren wir es in der Praxis aus! Initiiere npm run start, falls du es noch nicht getan hast.

Anzeigen eines Attributs in einer benutzerdefinierten Texteingabe und Aktualisieren des Attributwerts

Im vorherigen Schritt haben wir einige Komponenten in hinzugefügt edit, zB eine Texteingabe, aber es wurde nichts gespeichert. Lassen Sie uns in unserem Block ein Attribut und eine Texteingabe dafür hinzufügen. Wir werden beide sicherstellen, dass die Texteingabe den aktuellen Wert anzeigt, und jedes Mal, wenn die Eingabe geändert wird, aktualisieren wir das Attribut.

Hinzufügen der Texteingabe und ihrer onChangeRequisite

const { registerBlockType } = wp.blocks;
const { TextControl } = wp.components;
 
registerBlockType('awp/firstblock', {
    title: 'My first block',
    category: 'common',
    attributes: {
        exampleText: {
            type: 'string',
            default: ''
        }
    },
    edit: (props) => { 
        const { attributes, setAttributes } = props;
        return (<div>
                <TextControl 
                    value={attributes.exampleText}
                    onChange={(newtext) => setAttributes({ exampleText: newtext })}
                /> 
            </div>
        );
    },
    save:() => { 
        return <div>:)</div> 
    }
});

Wir destrukturieren attributesund setAttributesaus props, da wir beide verwenden werden. Dann verwenden wir eine TextControlKomponente aus dem WordPress- wp.componentsPaket. Wir geben zwei Requisiten daran weiter; valuesetzt den Wert der Eingabe (sowohl zu Beginn als auch während der Eingabe) und eine Aktion für das Ereignis der Eingabe onChange.

In valuesetzen wir es auf den Wert unseres Attributs; attributes.exampleText. Für den onChangeFall, dass wir eine Funktion ausführen und den eingegebenen Wert unserer Eingabe als Parameter übergeben newtext(der Eingabewert ist eine Stütze, die von der Komponente zurückgegeben wird). In dieser Funktion rufen wir setAttributes()das Attribut auf und aktualisieren exampleTextes entsprechend der Eingabe.

Das ist grundlegendes React – abgesehen davon, dass wir mit Attributen und nicht mit Zuständen arbeiten. Wenn Sie das oben Verwirrte verwirrt, empfehle ich Ihnen, sich ein kurzes Tutorial in React anzusehen, da diese diesen Weg wahrscheinlich besser erklären als ich!

Aktualisieren Sie Ihren Editor und sehen Sie, wie der Block funktioniert! Sie sollten eine Standardtexteingabe erhalten, um Dinge einzugeben, und sie wird gespeichert, wenn Sie in der Nachbearbeitung auf Speichern/Aktualisieren klicken.

Das Ergebnis im Frontend und in der Datenbank

Wenn Sie Ihren Beitrag im Frontend anzeigen, sollte er immer noch ein div mit „:)” widerspiegeln, da wir das immer noch in unserer saveFunktion haben. Aber hinter den Kulissen ist etwas passiert! Der Kommentarblock unseres Blocks enthält jetzt den Wert unseres Attributs in JSON.

Sie können die Kommentarblöcke in einer Vorlage, die einen normalen the_content()Aufruf ausführt, nicht sehen. Um die Kommentarblöcke zu sehen, haben Sie zwei Möglichkeiten. Schauen Sie sich entweder die post_contentTabelle in der Posts-Datenbank an. Oder fügen Sie echo get_the_content()die Vorlage hinzu und sehen Sie sie sich im Inspektions-/Debugging-Tool an.

Offensichtlich haben wir auch Zugriff auf die Attribute in save, von Requisiten.

Anzeige des Eingangswertes insave

Lassen Sie uns den Wert des Attributs innerhalb eines div in unserer saveFunktion anzeigen:

save: (props) => { 
    const { attributes } = props;
    return <div>{attributes.exampleText}</div>
}

Hinweis: Nachdem Sie diese Änderung vorgenommen haben, erhalten Sie einen defekten Block in dem Beitrag, zu dem Sie diesen Block bereits hinzugefügt haben. Dies geschieht, weil der Editor auf eine andere Ausgabe von stößt saveals die, die wir jetzt definiert haben. Entfernen Sie den Block und fügen Sie ihn erneut hinzu. Geben Sie etwas in Ihre Texteingabe ein, aktualisieren Sie den Beitrag und sehen Sie ihn im Frontend an.

Und das ist eigentlich der Kern davon. Sie entscheiden, welche Attribute Sie benötigen, um in Ihrem Block zu speichern, was Sie wollen. In editrendern Sie Eingabemöglichkeiten für den Benutzer und achten darauf, dass die aktuellen Werte angezeigt und aktualisiert werden, wenn sie sich ändern. Und saveSie extrahieren die gespeicherten Attribute und rendern die Ausgabe wie Sie möchten.

Wir werden im Laufe dieser Tutorial-Serie noch viel mehr verschiedene Komponenten und Attribute ansprechen. Aber schauen wir uns eine andere Komponente in diesem Beitrag an, um zu sehen, worum es bei der Attributeigenschaft sourcegeht.

RichText und die Attributeigenschaftsource

Die WordPress- RichTextKomponente bietet Ihnen einen „randlosen” Textbereich mit Textformatierungsunterstützung. Vielleicht ziehen Sie es vor, dies anstelle einer (hässlichen?) Standard-Texteingabe oder eines Textbereichs zu verwenden. Denken Sie jedoch daran, dass RichTextdies etwas anders gehandhabt werden muss, da es mehrere Requisiten gibt, die Sie beachten müssen, und es einen Unterschied gibt, wie wir den Wert in unserer saveFunktion erfassen.

Hinzufügen einer RichTextKomponente

Die einfachste Form von RichTextist die Implementierung wie bei einer Texteingabe:

const { registerBlockType } = wp.blocks;
const { RichText } = wp.blockEditor;
 
registerBlockType('awp/firstblock', {
    ...
    attributes: {
        myRichText: {
            type: 'string',
            default: ''
        }
    },
    edit: (props) => { 
        const { attributes, setAttributes } = props;
        return (<div>
                <RichText 
                    value={attributes.myRichText}
                    onChange={(newtext) => setAttributes({ myRichText: newtext })}
                /> 
            </div>
        );
    },
    ...

Wir destrukturieren die RichTextKomponente aus dem wp.blockEditorPaket, aber ansonsten ist das Obige identisch mit dem, was wir mit der Standardtexteingabe gemacht haben.

Umgang savemitRichText

In der saveFunktion müssen Sie die RichTextKomponente jedoch erneut verwenden, um den Wert des Attributs zu erhalten. Wir rufen auf RichText.Contentund setzen die Stütze valueauf unser Attribut:

save: (props) => { 
    const { attributes } = props;
    return (<div>
            <RichText.Content 
                value={attributes.myRichText}
            />
        </div>
    );
}

Dadurch wird das, was im Editor eingegeben wurde RichText, direkt ohne HTML-Umbruch ausgegeben.

Wenn Sie mit arbeiten RichText, möchten Sie höchstwahrscheinlich den HTML-Wrapper um den Text steuern, z. B. a <p>oder a <h2>, sowohl im Frontend als auch im Editor. Dafür können wir ein Prop namens verwenden tagName.

Die Komponente RichTexterlaubt auch mehrere andere Requisiten. placeholderMit der Requisite können Sie einen Platzhaltertext definieren, der angezeigt (ausgeblendet) wird, wenn er leer ist. Mit der Komponente können Sie auch steuern, welche Formatierungsoptionen das Feld zulässt (welche Schaltflächen es in der Symbolleiste anzeigt).

RichTextmittagName

Mit dem Prop tagNamekönnen Sie vordefinieren, in welches HTML-Tag seine Ausgabe eingeschlossen wird. Wenn Sie verwenden tagName, sollten Sie in und dasselbe tagNameProp und denselben Wert editverwenden save.

Angenommen, Sie möchten Ihren Attributwert in ein <h2>einfügen, wodurch im Editor jede Eingabe gezwungen wird, ein h2 zu sein. In editkönnen Sie Folgendes tun:

<RichText 
    tagName="h2"
    placeholder="Write your heading here"
    value={attributes.myRichText}
    onChange={(newtext) => setAttributes({ myRichText: newtext })}
/>

Und darin save:

<RichText.Content 
    tagName="h2"
    value={attributes.myRichText}
/>

Das Obige gibt nun aus, was auch immer in den RichTextBereich innerhalb eines <h2>Tags eingegeben wurde.

Verwendensource

Natürlich können Sie mehrere Richtexte für einen Block kombinieren, zum Beispiel einen für Überschrift und einen für einen Absatz. Denken Sie daran, dass jeder sein eigenes Attribut benötigt. Zum Beispiel:

attributes: {
    myRichHeading: {
        type: 'string'
    },
    myRichText: {
        type: 'string'
    }
},
edit: (props) => { 
    const { attributes, setAttributes } = props;
    return (<div>
            <RichText 
                tagName="h2"
                placeholder="Write your heading here"
                value={attributes.myRichHeading}
                onChange={(newtext) => setAttributes({ myRichHeading: newtext })}
            />
            <RichText
                tagName="p"
                placeholder="Write your paragraph here"
                value={attributes.myRichText}
                onChange={(newtext) => setAttributes({ myRichText: newtext })}
            />
        </div>
    );
},
save: (props) => { 
    const { attributes } = props;
    return (<div>
            <RichText.Content 
                tagName="h2"
                value={attributes.myRichHeading}
            />
            <RichText.Content 
                tagName="p"
                value={attributes.myRichText}
            />
        </div>
    );
}

Allerdings werden Sie jetzt auf einige Probleme stoßen. Auch wenn Sie Text im Editor formatieren können, wird nichts (oder einige) Ihrer Formatierung nicht gespeichert. Wenn Sie den Beitrag im Frontend anzeigen, wird er einfach als h2und pangezeigt, ohne dass Sie eine Formatierung vorgenommen haben (kursiv, fett, Link). Nicht einmal der Kommentarblock für Ihren Block enthält die Formatierung. Das ist das knifflige an RichText. Um dies zu lösen, müssen wir mit dem Attribut property arbeiten source.

Die sourceEigenschaft, die es WordPress ermöglicht, den Inhalt direkt aus dem Inhalt des Beitrags zu extrahieren und zu interpretieren. Wenn ein Attribut nicht sourcegesetzt ist, wird es im HTML-Kommentarblock gespeichert und daraus extrahiert.

Wenn wir mit arbeiten RichText, setzen wir normalerweise sourceauf html, das die Bibliothek von WordPress verwendet, um HTML-Markup zu analysieren. Die Eigenschaft sourcearbeitet mit einer anderen Attribut-Eigenschaft zusammen; selectordie definiert, aus welchem ​​HTML-Tag es extrahiert werden soll.

Als Beispiel setzen wir sourceas htmlin unserem Absatz RichTextund setzen selectoras p(andernfalls ist es standardmäßig die Wurzel des Blocks).

attributes: {
    ...
    myRichText: {
        type: 'string',
        source: 'html',
        selector: 'p'
    }
},

Jetzt sollte unsere zweite RichTexterfolgreich alle Textformatierungen speichern. Sie werden auch feststellen, dass der Kommentarblock das myRichHeadingAttribut jetzt nur noch in JSON anzeigt. Das Attribut myRichTextist komplett aus dem Kommentarblock verschwunden. Das liegt daran, dass bei sourceWordPress nun der Beitragsinhalt anstatt des Kommentarblocks nach dem Attributwert geparst wird.

Um ganz ehrlich zu sein, habe ich überhaupt nicht so viel mit dem sourceAttribut gearbeitet und würde empfehlen, es zu vermeiden, wenn Sie können. Die WordPress-Dokumentation erklärt etwas mehr über Quelle und Attribute, wenn Sie es selbst überprüfen möchten.

In diesem Beitrag haben wir die Grundlagen über Attribute gelernt; wie man sie definiert, aktualisiert und ihre Werte ausgibt. In den nächsten Schritten sehen wir uns weitere verschiedene Komponenten an und wie man Einstellungen außerhalb des Blockinhalts selbst hinzufügt; in der Symbolleiste und der Seitenleiste des Editors (genannt Inspector).