В этой части мы рассмотрим, как определять атрибуты, извлекать их значения и обновлять их. С помощью атрибутов мы можем принимать ввод из редактора, сохранять его и выводить по своему усмотрению. На предыдущем шаге мы рассмотрели компоненты WordPress, где их найти и как реализовать. В этом посте мы добавим пропсы для подключения к атрибутам — сохраненным данным.
Определение атрибутов
Атрибуты добавляются как объекты в массиве к attributes
свойству в registerBlockType()
. Ключ каждого атрибута — это имя атрибута, и у вас должно быть type
как минимум это свойство.
Свойство type
может быть любым из следующих; null
, boolean
, object
, array
, number
, string
или integer
.
Вы можете дополнительно указать свойство default
, чтобы определить начальное значение вашего атрибута. Если вы не укажете значение по умолчанию, атрибут по умолчанию будет иметь значение null
.
Еще одно свойство атрибута source
работает вместе с этим selector
свойством, но это тонкие вещи, которые мы подробно рассмотрим ниже.
Например, определение двух атрибутов; exampleText
как строка и postIds
как массив, будет выглядеть так:
Все, что вам нужно сохранить для вашего блока (ввод от пользователя/редактора), требует атрибута. Вам решать, как вы структурируете свои данные, определяя отдельные атрибуты для каждого или объединяя их все в объект. Это будет просто разница в том, как вы извлекаете их данные и как вы их обновляете.
Получение значений атрибутов
Атрибуты доступны в качестве реквизита для вашего блока edit
и save
функций. Если вы следовали этой серии с предыдущего шага, помните, что мы обновили функции, чтобы передавать свойства в качестве параметра.
Общепринято деструктурировать атрибуты из реквизита, поскольку вы обычно часто к ним обращаетесь. Например, вывод вызываемого атрибута exampleText
будет выглядеть так:
Обновление значений атрибутов
Для обновления атрибутов у нас есть метод, доступный в свойствах, который называется setAttributes()
. Эта функция принимает объект, в который вы можете добавить любой атрибут, который хотите обновить. Вы можете обновить только один атрибут, несколько или все сразу. Если у вас определено несколько атрибутов и вы вызываете setAttributes()
обновление только одного из них, остальные не затрагиваются.
Если у вас есть опыт работы с React, вы, вероятно, сразу заметите сходство между setAttributes()
и setState()
. Они работают точно так же, но разница в том, что состояние в React — это просто то, что хранится локально в этом компоненте, а атрибуты фактически сохраняются как данные вне компонента.
Для обновления атрибута вы обычно удаляете функцию из реквизита и вызываете ее так: Ниже мы обновляем exampleText
атрибут, чтобы он был «Привет».
const { setAttributes } = props;
setAttributes({ exampleText: 'Hi' });
Естественно, вы бы запускали setAttributes()
изнутри какое-то действие. Обычный пример находится внутри onChange
реквизита в каком-то поле ввода, которое используется для хранения значения exampleText
атрибута.
Обязательно сохраните атрибуты в том типе, который вы определили для атрибута. Например, вам не повезет, если вы попытаетесь сохранить объекты в строковый атрибут.
Попробуем на практике! Инициируйте npm run start
, если вы еще этого не сделали.
Отображение атрибута в пользовательском вводе текста и обновление значения атрибута
На предыдущем шаге мы добавили в, некоторые компоненты edit
, например ввод текста, но ничего не сохранилось. Добавим атрибут и один текстовый ввод для него в наш блок. Мы оба будем следить за тем, чтобы ввод текста отображал текущее значение, и всякий раз, когда ввод изменяется, мы обновляем атрибут.
Добавление ввода текста и его onChange
реквизита
Мы деструктурируем attributes
и setAttributes
из props
того, как мы будем использовать оба. Затем мы используем TextControl
компонент из wp.components
пакета WordPress. Передаем ему два реквизита; value
установит значение ввода (как изначально, так и во время ввода) и действие на событие ввода onChange
.
В value
мы устанавливаем его на значение нашего атрибута; attributes.exampleText
. В onChange
случае, если мы запускаем функцию, передавая типизированное значение нашего ввода в качестве параметра newtext
(входное значение — это свойство, возвращаемое компонентом). В этой функции мы вызываем setAttributes()
и обновляем атрибут exampleText
до того, что было введено на входе.
Это базовый React — за исключением того, что мы работаем с атрибутами, а не с состоянием. Если вышеизложенное смутило вас, я рекомендую посмотреть краткий учебник по React, так как он, вероятно, объяснит это лучше, чем я!
Обновите свой редактор и посмотрите, как работает блок! Вы должны получить стандартный текстовый ввод для ввода данных, и он будет сохранен всякий раз, когда вы нажмете «Сохранить/Обновить» в редактировании сообщения.
Результат во фронтенде и в БД
Если вы просматриваете свой пост во внешнем интерфейсе, он все равно должен отображать div с «:)», потому что это то, что у нас все еще есть в нашей save
функции. Но что-то произошло за кулисами! Блок комментариев нашего блока теперь содержит значение нашего атрибута в формате JSON.
Вы не можете видеть блоки комментариев в шаблоне, который выполняет обычный the_content()
вызов. Чтобы увидеть блоки комментариев, у вас есть два варианта. Либо посмотрите в post_content
таблице базы данных сообщений. Или добавьте echo get_the_content()
шаблон и просмотрите его в инструменте проверки/отладки.
Очевидно, у нас также есть доступ к атрибутам save
из реквизита.
Отображение значения ввода вsave
Давайте отобразим значение атрибута внутри div в нашей save
функции:
Примечание. После внесения этого изменения вы получите сломанный блок в сообщении, к которому вы уже добавили этот блок. Это происходит потому, что редактор сталкивается с выводом, отличным от save
того, что мы определили сейчас. Удалите блок и снова добавьте его. Введите что-нибудь в текстовый ввод, обновите сообщение и просмотрите его в интерфейсе.
И в этом собственно суть. Вы сами решаете, какие атрибуты вам нужны, чтобы сохранить то, что вы хотите в своем блоке. В edit
вы отобразите способы ввода пользователем, позаботившись о том, чтобы текущие значения отображались и обновлялись при каждом изменении. И save
вы извлекаете сохраненные атрибуты и визуализируете вывод так, как хотите.
Мы коснемся гораздо большего количества различных компонентов и атрибутов в этой серии руководств. Но давайте посмотрим на еще один компонент в этом посте, чтобы понять, что такое свойство атрибута source
.
RichText и свойство атрибутаsource
Компонент WordPress RichText
предоставляет вам текстовую область без полей с поддержкой форматирования текста. Вы можете предпочесть использовать это вместо (уродливого?) стандартного ввода текста или текстовой области. Но имейте в виду, что это RichText
должно обрабатываться немного по-другому, так как есть несколько реквизитов, о которых вам нужно знать, и есть разница в том, как мы получаем значение в нашей save
функции.
Добавление RichText
компонента
Самая простая форма RichText
— это реализовать его, как если бы вы вводили текст:
Мы деструктурируем RichText
компонент из wp.blockEditor
пакета, но в остальном вышеописанное идентично тому, что мы сделали со стандартным вводом текста.
Обращение save
сRichText
Однако в save
функции вам нужно снова использовать RichText
компонент, чтобы получить значение атрибута. Мы вызываем RichText.Content
и устанавливаем value
свойство для нашего атрибута:
Это выведет все, что было введено в RichText
редакторе, напрямую, без какого-либо HTML-обертывания.
Когда вы работаете с RichText
ним, вы, скорее всего, захотите управлять HTML-оболочкой вокруг текста, например a <p>
или a <h2>
, как во внешнем интерфейсе, так и в редакторе. Для этого мы можем использовать реквизит под названием tagName
.
Компонент RichText
также допускает несколько других реквизитов. Вы можете определить текст-заполнитель, который отображается (исчезает), когда он пуст, с placeholder
опорой. Компонент также позволяет вам контролировать, какие параметры форматирования разрешает поле (какие кнопки отображаются на панели инструментов).
RichText
сtagName
С помощью свойства tagName
вы можете заранее определить, в какой HTML-тег будет заключен его вывод. При использовании tagName
вы должны использовать одно и то же tagName
свойство и значение в обоих edit
и save
.
Скажем, вы хотите поместить значение атрибута в a <h2>
, что в редакторе заставит любой ввод быть h2. В edit
вы можете сделать:
И в save
:
Приведенное выше теперь будет выводить все, что было введено в RichText
области внутри <h2>
тега.
С использованиемsource
Очевидно, вы можете комбинировать несколько форматированных текстов для блока, например, один для заголовка и один для абзаца. Только помните, что для каждого понадобится свой атрибут. Например:
Однако к настоящему времени вы начнете сталкиваться с некоторыми проблемами. Несмотря на то, что вы можете форматировать текст в редакторе, ничего (или часть) вашего форматирования не будет сохранено. Когда вы просматриваете сообщение во внешнем интерфейсе, оно просто отображается как h2
и p
без какого-либо форматирования, которое вы сделали (курсив, полужирный шрифт, ссылка). Даже блок комментариев для вашего блока не содержит форматирования. Это сложная вещь с RichText
. Чтобы решить эту проблему, нам нужно работать со свойством атрибута source
.
Свойство source
, позволяющее WordPress извлекать и интерпретировать контент непосредственно из контента публикации. Если атрибут не source
установлен, он будет сохранен и извлечен из блока комментариев HTML.
При работе RichText
мы обычно устанавливаем source
значение html
, которое использует библиотеку WordPress для разбора HTML-разметки. Свойство source
работает вместе с другим свойством атрибута; selector
который определяет, из какого тега HTML он должен извлекаться.
В качестве примера мы устанавливаем source
as html
для нашего абзаца RichText
и устанавливаем selector
as p
(в противном случае по умолчанию используется корень блока блока).
attributes: {
...
myRichText: {
type: 'string',
source: 'html',
selector: 'p'
}
},
Теперь наш второй RichText
файл должен успешно сохранить все форматирование текста. Вы также заметите, что блок комментариев теперь отображает myRichHeading
атрибут только в формате JSON. Атрибут myRichText
полностью исчез из блока комментариев. Это связано с тем, что source
WordPress теперь анализирует содержимое сообщения вместо блока комментариев для значения атрибута.
Если быть совершенно честным, я вообще не работал с этим source
атрибутом и рекомендовал бы избегать его, если вы можете. Документация WordPress объясняет несколько больше об источнике и атрибутах, которые вы хотите проверить сами.
В этом посте мы узнали основы атрибутов; как их определить, обновить и вывести их значения. На следующих шагах мы рассмотрим другие компоненты и способы добавления настроек вне самого содержимого блока; на панели инструментов и боковой панели редактора (называемой Инспектор).