Spec-Zone.ru › OpenJDK 24

Класс HTMLDocument

java.lang.Object
javax.swing.text.AbstractDocument
javax.swing.text.DefaultStyledDocument
javax.swing.text.html.HTMLDocument
Все реализованные интерфейсы:
Serializable, Document, StyledDocument
public class HTMLDocument extends DefaultStyledDocument
Документ, моделирующий HTML. Целью этой модели является поддержка как просмотра, так и редактирования. В результате структура, описываемая документом HTML, не точно дублируется по умолчанию. Структура элемента, которая моделируется по умолчанию, создается классом HTMLDocument.HTMLReader, реализующим протокол HTMLEditorKit.ParserCallback, который ожидает парсер. Чтобы изменить структуру, можно создать подкласс HTMLReader и переопределить метод getReader(int) для возврата новой реализации ридера. Для получения подробностей о созданной по умолчанию структуре следует обратиться к документации HTMLReader. Цель состоит в том, чтобы документ был без потерь (хотя воспроизведение формата HTML может привести к другому формату).

Документ моделирует только HTML и не пытается сохранить атрибуты представления в нём. Элементы идентифицируются атрибутом StyleContext.NameAttribute, который всегда должен иметь значение типа HTML.Tag, определяющее тип элемента. Некоторые элементы (например, комментарии) синтезируются. Класс HTMLFactory использует этот атрибут для определения того, какое представление необходимо создать.

Этот документ поддерживает инкрементальную загрузку. Свойство TokenThreshold управляет тем, какая часть разбора буферизуется перед попыткой обновления структуры элемента документа. Это свойство устанавливается классом EditorKit, чтобы подклассы могли его отключить.

Свойство Base определяет URL, по отношению к которому разрешаются относительные URL-адреса. По умолчанию это будет Document.StreamDescriptionProperty, если значение свойства является URL-адресом. Если встречается тег <BASE>, база станет URL-адресом, указанным в этом теге. Поскольку базовый URL-адрес является свойством, его, конечно, можно задать непосредственно.

Стандартный механизм хранения содержимого для этого документа — буфер с разрывами (GapContent). Альтернативы могут быть предоставлены с помощью конструктора, принимающего реализацию Content.

Изменение HTMLDocument

В дополнение к методам, предоставляемым классом Document и StyledDocument для изменения HTMLDocument, HTMLDocument предоставляет ряд удобных методов. Следующие методы можно использовать для вставки HTML-содержимого в существующий документ.

  • setInnerHTML(Element, String)
  • setOuterHTML(Element, String)
  • insertBeforeStart(Element, String)
  • insertAfterStart(Element, String)
  • insertBeforeEnd(Element, String)
  • insertAfterEnd(Element, String)

Следующие примеры иллюстрируют использование этих методов. Каждый пример предполагает, что документ HTML инициализирован следующим образом:

 JEditorPane p = new JEditorPane();
 p.setContentType("text/html");
 p.setText("..."); // Document text is provided below.
 HTMLDocument d = (HTMLDocument) p.getDocument();
 

С следующим содержимым HTML:

 <html>
   <head>
     <title>An example HTMLDocument</title>
     <style type="text/css">
       div { background-color: silver; }
       ul { color: blue; }
     </style>
   </head>
   <body>
     <div id="BOX">
       <p>Paragraph 1</p>
       <p>Paragraph 2</p>
     </div>
   </body>
 </html>
 

Все методы изменения HTML-документа требуют Element. Элементы можно получить из документа HTML с помощью метода getElement(Element e, Object attribute, Object value). Он возвращает первый дочерний элемент, содержащий указанный атрибут со значением, в порядке обхода в глубину. Например, d.getElement(d.getDefaultRootElement(), StyleConstants.NameAttribute, HTML.Tag.P) возвращает первый элемент абзаца.

Удобным сокращением для поиска элементов является метод getElement(String); возвращает элемент, чей атрибут ID соответствует указанному значению. Например, d.getElement("BOX") возвращает элемент DIV.

Метод getIterator(HTML.Tag t) также можно использовать для поиска всех вхождений указанного HTML-тега в документе.

Вставка элементов

Элементы можно вставить перед или после существующих дочерних элементов любого нелистового элемента, используя методы insertAfterStart и insertBeforeEnd. Например, если e — это элемент DIV, d.insertAfterStart(e, "<ul><li>List Item</li></ul>") вставляет список перед первым абзацем, а d.insertBeforeEnd(e, "<ul><li>List Item</li></ul>") — после последнего абзаца. Блок DIV становится родителем вновь вставленных элементов.

Элементы-сёстры можно вставить перед или после любого элемента, используя методы insertBeforeStart и insertAfterEnd. Например, если e — это элемент DIV, d.insertBeforeStart(e, "<ul><li>List Item</li></ul>") вставляет список перед элементом DIV, а d.insertAfterEnd(e, "<ul><li>List Item</li></ul>") вставляет список после элемента DIV. Вновь вставленные элементы становятся сёстрами элемента DIV.

Замена элементов

Элементы и все их потомки можно заменить, используя методы setInnerHTML и setOuterHTML. Например, если e — это элемент DIV, d.setInnerHTML(e, "<ul><li>List Item</li></ul>") заменяет все дочерние абзацы списком, а d.setOuterHTML(e, "<ul><li>List Item</li></ul>") заменяет сам элемент DIV. В последнем случае родителем списка является элемент BODY.

Резюме

В следующей таблице показан пример документа и результаты различных методов, описанных выше.

Содержимое HTML примерного документа выше
Пример insertAfterStart insertBeforeEnd insertBeforeStart insertAfterEnd setInnerHTML setOuterHTML

Абзац 1

Абзац 2

  • Элемент списка

Абзац 1

Абзац 2

Абзац 1

Абзац 2

  • Элемент списка
  • Элемент списка

Абзац 1

Абзац 2

Абзац 1

Абзац 2

  • Элемент списка
  • Элемент списка
  • Элемент списка

Предупреждение: Сериализованные объекты этого класса не будут совместимы с будущими выпусками Swing. Текущая поддержка сериализации подходит для краткосрочного хранения или RMI между приложениями, использующими одну и ту же версию Swing. Начиная с версии 1.4, поддержка долгосрочного хранения всех JavaBeans была добавлена в пакет java.beans. Обратитесь к XMLEncoder.

Краткое описание вложенных классов

Модификатор и тип Класс Описание
class  HTMLDocument.BlockElement
Элемент, представляющий структурный блок HTML.
class  HTMLDocument.HTMLReader
Читатель HTML для загрузки документа HTML со структурой HTML-элемента.
static class  HTMLDocument.Iterator
Итератор для итерации по определенному типу тега.
class  HTMLDocument.RunElement
Элемент, представляющий фрагмент текста с набором атрибутов уровня символов HTML, присвоенных ему.

Вложенные классы/интерфейсы, объявленные в классе javax.swing.text.DefaultStyledDocument

DefaultStyledDocument.AttributeUndoableEdit, DefaultStyledDocument.ElementBuffer, DefaultStyledDocument.ElementSpec, DefaultStyledDocument.SectionElement

Вложенные классы/интерфейсы, объявленные в классе javax.swing.text.AbstractDocument

AbstractDocument.AbstractElement, AbstractDocument.AttributeContext, AbstractDocument.BranchElement, AbstractDocument.Content, AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractDocument.LeafElement

Краткое описание полей

Модификатор и тип Поле Описание
static final String AdditionalComments
Значение свойства документа.

Поля, объявленные в классе javax.swing.text.DefaultStyledDocument

buffer, BUFFER_SIZE_DEFAULT

Поля, объявленные в классе javax.swing.text.AbstractDocument

BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, listenerList, ParagraphElementName, SectionElementName

Поля, объявленные в интерфейсе javax.swing.text.Document

StreamDescriptionProperty, TitleProperty

Краткое описание конструкторов

Конструктор Описание
HTMLDocument()
Создает документ HTML с использованием буфера по умолчанию и по умолчанию StyleSheet.
HTMLDocument(AbstractDocument.Content c, StyleSheet styles)
Создает документ HTML с заданной реализацией хранения содержимого и заданным механизмом хранения стилей/атрибутов.
HTMLDocument(StyleSheet styles)
Создает документ HTML с реализацией хранения содержимого по умолчанию и указанным механизмом хранения стилей/атрибутов.

Краткое описание методов

Модификатор и тип Метод Описание
protected void create(DefaultStyledDocument.ElementSpec[] data)
Заменяет содержимое документа заданными спецификациями элементов.
protected Element createBranchElement(Element parent, AttributeSet a)
Создает элемент ветви документа, который может содержать другие элементы.
protected AbstractDocument.AbstractElement createDefaultRoot()
Создает корневой элемент, который используется для представления структуры документа по умолчанию.
protected Element createLeafElement(Element parent, AttributeSet a, int p0, int p1)
Создает элемент листа документа, который непосредственно представляет текст (не имеет дочерних элементов).
protected void fireChangedUpdate(DocumentEvent e)
Уведомляет всех слушателей, которые зарегистрировали интерес к уведомлению об этом типе события.
protected void fireUndoableEditUpdate(UndoableEditEvent e)
Уведомляет всех слушателей, которые зарегистрировали интерес к уведомлению об этом типе события.
URL getBase()
Возвращает расположение для разрешения относительных URL-адресов.
Element getElement(String id)
Возвращает элемент с заданным идентификатором Attribute.
Element getElement(Element e, Object attribute, Object value)
Возвращает дочерний элемент e, содержащий атрибут attribute со значением value, или null, если такой элемент не найден.
HTMLDocument.Iterator getIterator(HTML.Tag t)
Извлекает итератор для указанного HTML-тега.
HTMLEditorKit.Parser getParser()
Возвращает анализатор, используемый при вставке HTML в существующий документ.
boolean getPreservesUnknownTags()
Возвращает поведение, которое анализатор наблюдает при обнаружении неизвестных тегов.
HTMLEditorKit.ParserCallback getReader(int pos)
Извлекает читатель для использования анализатором при загрузке документа с HTML.
HTMLEditorKit.ParserCallback getReader(int pos, int popDepth, int pushDepth, HTML.Tag insertTag)
Возвращает читатель для использования анализатором при загрузке документа с HTML.
StyleSheet getStyleSheet()
Извлекает StyleSheet с правилами отображения, специфичными для документа (CSS), которые были указаны в самом HTML-документе.
int getTokenThreshold()
Получает количество токенов для буферизации перед попыткой обновления структуры элементов документов.
protected void insert(int offset, DefaultStyledDocument.ElementSpec[] data)
Вставка новых элементов в блоке.
void insertAfterEnd(Element elem, String htmlText)
Вставляет HTML, указанный в виде строки, после окончания данного элемента.
void insertAfterStart(Element elem, String htmlText)
Вставляет HTML, указанный в виде строки, в начале элемента.
void insertBeforeEnd(Element elem, String htmlText)
Вставляет HTML, указанный в виде строки, в конце элемента.
void insertBeforeStart(Element elem, String htmlText)
Вставляет HTML, указанный в виде строки, перед началом заданного элемента.
protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Обновляет структуру документа в результате вставки текста.
void processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent e)
Обрабатывает HyperlinkEvents, которые генерируются документами в фрейме HTML.
void setBase(URL u)
Устанавливает расположение для разрешения относительных URL-адресов.
void setInnerHTML(Element elem, String htmlText)
Заменяет дочерние элементы заданного элемента содержимым, указанным в виде HTML-строки.
void setOuterHTML(Element elem, String htmlText)
Заменяет заданный элемент в родительском элементе содержимым, указанным в виде HTML-строки.
void setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace)
Устанавливает атрибуты для абзаца.
void setParser(HTMLEditorKit.Parser parser)
Устанавливает анализатор, используемый методами, которые вставляют html в существующий документ, такие как setInnerHTML и setOuterHTML.
void setPreservesUnknownTags(boolean preservesTags)
Определяет, как анализатор обрабатывает неизвестные теги.
void setTokenThreshold(int n)
Устанавливает количество токенов для буферизации перед попыткой обновления структуры элементов документов.

Методы, объявленные в классе javax.swing.text.DefaultStyledDocument

addDocumentListener, addStyle, getBackground, getCharacterElement, getDefaultRootElement, getFont, getForeground, getLogicalStyle, getParagraphElement, getStyle, getStyleNames, removeDocumentListener, removeElement, removeStyle, removeUpdate, setCharacterAttributes, setLogicalStyle, styleChanged

Методы, объявленные в классе javax.swing.text.AbstractDocument

addUndoableEditListener, createPosition, dump, fireInsertUpdate, fireRemoveUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, insertString, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeUndoableEditListener, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Методы, объявленные в интерфейсе javax.swing.text.Document

addUndoableEditListener, createPosition, getEndPosition, getLength, getProperty, getRootElements, getStartPosition, getText, getText, insertString, putProperty, remove, removeUndoableEditListener, render

Подробное описание полей

Дополнительные комментарии

public static final String AdditionalComments
Ключ-значение свойства документа. Значение для ключа будет вектором строк, которые представляют собой комментарии, отсутствующие в теле.
См. также:
  • Значения константных полей

Подробное описание конструкторов

HTMLDocument

public HTMLDocument()
Конструирует документ HTML с использованием размера буфера по умолчанию и по умолчанию StyleSheet. Это метод для удобства использования конструктора HTMLDocument(Content, StyleSheet).

HTMLDocument

public HTMLDocument(StyleSheet styles)
Конструирует документ HTML с реализацией хранения содержимого по умолчанию и указанным механизмом хранения стилей/атрибутов. Это метод для удобства использования конструктора HTMLDocument(Content, StyleSheet).
Параметры:
styles - стили

HTMLDocument

public HTMLDocument(AbstractDocument.Content c, StyleSheet styles)
Конструирует документ HTML с заданной реализацией хранения содержимого и заданным механизмом хранения стилей/атрибутов.
Параметры:
c - контейнер для содержимого
styles - стили

Подробное описание методов

getReader

public HTMLEditorKit.ParserCallback getReader(int pos)
Извлекает ридер для использования парсером при загрузке документа HTML. Этот метод реализован для возврата экземпляра HTMLDocument.HTMLReader. Подклассы могут переопределить этот метод, чтобы изменить структуру документа по своему усмотрению (например, для обработки пользовательских тегов или структурного представления элементов стиля символов).
Параметры:
pos - начальная позиция
Возвращает:
ридер, используемый парсером для загрузки документа

getReader

public HTMLEditorKit.ParserCallback getReader(int pos, int popDepth, int pushDepth, HTML.Tag insertTag)
Возвращает ридер для использования парсером при загрузке документа HTML. Этот метод реализован для возврата экземпляра HTMLDocument.HTMLReader. Подклассы могут переопределить этот метод, чтобы изменить структуру документа по своему усмотрению (например, для обработки пользовательских тегов или структурного представления элементов стиля символов).

Это удобный метод для getReader(int, int, int, HTML.Tag, TRUE).

Параметры:
pos - начальная позиция
popDepth - количество ElementSpec.EndTagTypes для генерации перед вставкой
pushDepth - количество ElementSpec.StartTagTypes с направлением ElementSpec.JoinNextDirection, которые должны быть сгенерированы перед вставкой, но после генерации закрывающих тегов
insertTag - первый тег для начала вставки в документ
Возвращает:
ридер, используемый парсером для загрузки документа

getBase

public URL getBase()
Возвращает расположение для разрешения относительных URL-адресов. По умолчанию это будет URL-адрес документа, если документ загружен из URL-адреса. Если найден тег base и он может быть проанализирован, он будет использован в качестве базового расположения.
Возвращает:
базовое расположение

setBase

public void setBase(URL u)
Устанавливает расположение для разрешения относительных URL-адресов. По умолчанию это будет URL-адрес документа, если документ загружен из URL-адреса. Если найден тег base и он может быть проанализирован, он будет использован в качестве базового расположения.

Это также устанавливает базу StyleSheet в u, а также базу документа.

Параметры:
u - желаемый базовый URL

insert

protected void insert(int offset, DefaultStyledDocument.ElementSpec[] data) throws BadLocationException
Вставляет новые элементы в пакет. Таким образом элементы создаются в документе. Анализ определяет необходимую структуру и создает спецификацию в виде набора токенов, описывающих изменение, оставляя документ свободным от блокировки записи. Этот метод затем может быть вызван группами, чтобы получить блокировку записи на более короткий срок (т. е. в то время, когда документ фактически изменяется).
Переопределяет:
insert в классе DefaultStyledDocument
Параметры:
offset - начальный смещение
data - данные элемента
Исключения:
BadLocationException - если заданная позиция не представляет допустимое местоположение в связанном документе.

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)
Обновляет структуру документа в результате вставки текста. Это произойдет в пределах блокировки записи. Эта реализация просто анализирует вставленное содержимое для определения символов новой строки и строит набор инструкций для буфера элементов.
Переопределяет:
insertUpdate в классе DefaultStyledDocument
Параметры:
chng - описание изменения документа
attr - атрибуты

create

protected void create(DefaultStyledDocument.ElementSpec[] data)
Заменяет содержимое документа заданными спецификациями элементов. Это вызывается перед insert, если загрузка выполняется порциями. Это единственный вызываемый метод, если загрузка документа выполняется целиком в одной порции.
Переопределяет:
create в классе DefaultStyledDocument
Параметры:
data - новое содержимое документа

setParagraphAttributes

public void setParagraphAttributes(int offset, int length, AttributeSet s, boolean replace)
Устанавливает атрибуты для абзаца.

Этот метод потокобезопасен, хотя большинство методов Swing не являются таковыми. Пожалуйста, обратитесь к асинхронности в Swing для получения дополнительной информации.

Определено в:
setParagraphAttributes в интерфейсе StyledDocument
Переопределяет:
setParagraphAttributes в классе DefaultStyledDocument
Параметры:
offset - смещение в абзаце (должно быть не менее 0)
length - количество затронутых символов (должно быть не менее 0)
s - атрибуты
replace - заменять ли существующие атрибуты или объединить их

getStyleSheet

public StyleSheet getStyleSheet()
Извлекает StyleSheet с правилами отображения (CSS), специфичными для документа, которые были указаны в самом документе HTML.
Возвращает:
StyleSheet

getIterator

public HTMLDocument.Iterator getIterator(HTML.Tag t)
Извлекает итератор для указанного тега HTML. Это может быть использовано для таких операций, как итерация по набору анкеров или итерация по элементам ввода.
Параметры:
t - запрашиваемый HTML.Tag
Возвращает:
Iterator для заданного тега HTML
См. также:
  • HTML.Tag

createLeafElement

protected Element createLeafElement(Element parent, AttributeSet a, int p0, int p1)
Создает элемент листа документа, непосредственно представляющий текст (не имеет дочерних элементов). Это реализовано для возврата элемента типа HTMLDocument.RunElement.
Переопределяет:
createLeafElement в классе AbstractDocument
Параметры:
parent - родительский элемент
a - атрибуты для элемента
p0 - начало диапазона (должно быть не менее 0)
p1 - конец диапазона (должно быть не менее p0)
Возвращает:
новый элемент

createBranchElement

protected Element createBranchElement(Element parent, AttributeSet a)
Создает элемент ветви документа, который может содержать другие элементы. Это реализовано для возврата элемента типа HTMLDocument.BlockElement.
Переопределяет:
createBranchElement в классе AbstractDocument
Параметры:
parent - родительский элемент
a - атрибуты
Возвращает:
элемент

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()
Создает корневой элемент, используемый для представления структуры документа по умолчанию.
Переопределяет:
createDefaultRoot в классе DefaultStyledDocument
Возвращает:
базовый элемент

Ограничение по количеству токенов

public void setTokenThreshold(int n)
Устанавливает количество токенов для буферизации перед попыткой обновить структуру элемента документа.
Параметры:
n - количество токенов для буферизации

Получить ограничение по количеству токенов

public int getTokenThreshold()
Возвращает количество токенов для буферизации перед попыткой обновить структуру элемента документа. Значение по умолчанию - Integer.MAX_VALUE.
Возвращает:
количество токенов для буферизации

Установить сохранение неизвестных тегов

public void setPreservesUnknownTags(boolean preservesTags)
Определяет, как неизвестные теги обрабатываются парсером. Если установлено значение true, неизвестные теги добавляются в модель; в противном случае они игнорируются.
Параметры:
preservesTags - true, если неизвестные теги должны быть сохранены в модели; в противном случае теги игнорируются
См. также:
  • HTML.Tag

Получить сохранение неизвестных тегов

public boolean getPreservesUnknownTags()
Возвращает поведение парсера при обнаружении неизвестных тегов.
Возвращает:
true, если неизвестные теги должны сохраняться при парсинге
См. также:
  • HTML.Tag

Обработать событие гиперссылки HTML-фрейма

public void processHTMLFrameHyperlinkEvent(HTMLFrameHyperlinkEvent e)
Обрабатывает события гиперссылок, генерируемые документами в HTML-фрейме. Тип события, как подразумевает параметр, - HTMLFrameHyperlinkEvent. Помимо стандартной информации, содержащейся в HyperlinkEvent, это событие содержит элемент, соответствующий фрейму, в котором произошёл клик (элемент-источник), и имя целевого элемента. Имя целевого элемента может принимать 4 значения:
  • _self
  • _parent
  • _top
  • имя фрейма
Если target - _self, выполняется изменение значения атрибута HTML.Attribute.SRC и генерируется событие ChangedUpdate.

Если target - _parent, удаляется родительский элемент (элемент <FRAMESET>) и вставляется новый элемент <FRAME>, устанавливая атрибут HTML.Attribute.SRC в значение целевого URL и генерируя события RemovedUpdate и InsertUpdate.

Если target - _top, этот метод ничего не делает. Обработка _top выполняется в представлении фрейма, а именно в FrameView. Поскольку _top подразумевает замену всего документа, эту обработку разумнее выполнить вне заменяемого документа.

Если target - имя фрейма, в иерархии элементов ищется элемент с соответствующим именем, его атрибут HTML.Attribute.SRC обновляется, и генерируется событие ChangedUpdate.

Параметры:
e - событие

Установить парсер

public void setParser(HTMLEditorKit.Parser parser)
Устанавливает парсер, используемый методами вставки HTML в существующий документ, такими как setInnerHTML и setOuterHTML.

HTMLEditorKit.createDefaultDocument установит парсер за вас. Если вы создаёте HTMLDocument вручную, убедитесь, что установили парсер должным образом.

Параметры:
parser - парсер для вставки текста
С версии:
1.3

Получить парсер

public HTMLEditorKit.Parser getParser()
Возвращает парсер, используемый при вставке HTML в существующий документ.
Возвращает:
используемый парсер для вставки текста
С версии:
1.3

Установить внутренний HTML

public void setInnerHTML(Element elem, String htmlText) throws BadLocationException, IOException
Заменяет потомков заданного элемента содержимым, указанным в виде строки HTML.

Это будет рассматриваться как по меньшей мере два события: n вставок, за которыми следует удаление.

Рассмотрим следующую структуру (параметр elem - жирный).

     <body>
       |
     <div>
      /  \
    <p>   <p>
 

Вызов setInnerHTML(elem, "<ul><li>") приводит к следующей структуре (новые элементы - синим цветом).

     <body>
       |
     <div>
         \
         <ul>
           \
           <li>
 

Параметр elem не должен быть листом, в противном случае будет выброшено исключение IllegalArgumentException. Если параметр elem или htmlText имеет значение null, изменения в документе не вносятся.

Для корректной работы документ должен иметь установленный HTMLEditorKit.Parser. Это будет так, если документ был создан из HTMLEditorKit с помощью метода createDefaultDocument.

Параметры:
elem - элемент ветвления, потомки которого будут заменены
htmlText - строка, которая будет обработана как HTML и назначена elem
Исключения:
IllegalArgumentException - если elem является листом
IllegalStateException - если парсер HTMLEditorKit.Parser не определён
BadLocationException - если замена невозможна из-за структурной проблемы
IOException - если произошла ошибка ввода-вывода
С версии:
1.3

Установить внешний HTML

public void setOuterHTML(Element elem, String htmlText) throws BadLocationException, IOException
Заменяет указанный элемент в родителе содержимым, указанным в виде строки HTML.

Это будет рассматриваться как по меньшей мере два события: n вставок, за которыми следует удаление.

При замене листа будет сделана попытка убедиться, что присутствует новая строка, если она необходима. В результате может быть вставлен дополнительный элемент. Например, если заменить элемент символа, содержащий новую строку, на <img>, это создаст два элемента: один для изображения и один для новой строки.

Если вы пытаетесь заменить элемент длиной, скорее всего, в результате получится два элемента, например, setOuterHTML(getCharacterElement (getLength()), "blah") приведёт к двум листовым элементам в конце, один для «blah», а другой — для конечного элемента.

Рассмотрим следующую структуру (параметр elem - жирный).

     <body>
       |
     <div>
      /  \
    <p>   <p>
 

Вызов setOuterHTML(elem, "<ul><li>") приведёт к следующей структуре (новые элементы — синим цветом).

    <body>
      |
     <ul>
       \
       <li>
 

Если параметр elem или htmlText имеет значение null, изменения в документе не вносятся.

Для корректной работы документ должен иметь установленный HTMLEditorKit.Parser. Это будет так, если документ был создан из HTMLEditorKit с помощью метода createDefaultDocument.

Параметры:
elem - заменяемый элемент
htmlText - строка, которая будет обработана как HTML и вставлена вместо elem
Исключения:
IllegalStateException - если для HTMLEditorKit.Parser не задано значение
BadLocationException - если замена невозможна из-за структурной проблемы
IOException - если произошла ошибка ввода-вывода
С версии:
1.3

Вставить после начала

public void insertAfterStart(Element elem, String htmlText) throws BadLocationException, IOException
Вставляет HTML, заданный строкой, в начало элемента.

Рассмотрим следующую структуру (параметр elem - жирный).

     <body>
       |
     <div>
      /  \
    <p>   <p>
 

Вызов insertAfterStart(elem, "<ul><li>") приводит к следующей структуре (новые элементы - синим цветом).

        <body>
          |
        <div>
       /  |  \
    <ul> <p> <p>
     /
  <li>
 

В отличие от метода insertBeforeStart, новые элементы становятся потомками указанного элемента, а не его соседями.

Параметр elem не должен быть листом; в противном случае будет выброшено исключение IllegalArgumentException. Если параметр elem или htmlText имеет значение null, изменения в документе не вносятся.

Для корректной работы документ должен иметь установленный HTMLEditorKit.Parser. Это будет так, если документ был создан из HTMLEditorKit с помощью метода createDefaultDocument.

Параметры:
elem - элемент ветвления, который будет корнем для нового текста
htmlText - строка, которая будет обработана как HTML и назначена elem
Исключения:
IllegalArgumentException - если elem является листом
IllegalStateException - если для документа не задан парсер HTMLEditorKit
BadLocationException - если вставка невозможна из-за структурной проблемы
IOException - если произошла ошибка ввода-вывода
С версии:
1.3

insertBeforeEnd

public void insertBeforeEnd(Element elem, String htmlText) throws BadLocationException, IOException
Вставляет HTML, заданный в виде строки, в конец элемента.

Если у elem дочерние элементы являются листьями, и символ в elem.getEndOffset() - 1 — перевод строки, это вставит перед переводом строки, чтобы не было текста после перевода строки.

Рассмотрим следующую структуру (параметр elem выделен жирным шрифтом).

     <body>
       |
     <div>
      /  \
    <p>   <p>
 

Вызов insertBeforeEnd(elem, "<ul><li>") приводит к следующей структуре (новые элементы выделены синим цветом).

        <body>
          |
        <div>
       /  |  \
     <p> <p> <ul>
               \
               <li>
 

В отличие от метода insertAfterEnd, новые элементы становятся дочерними элементами указанного элемента, а не его соседями.

Параметр elem не должен быть листовым элементом, в противном случае будет выброшено исключение IllegalArgumentException. Если любой из параметров elem или htmlText имеет значение null, изменения в документе не производятся.

Для корректной работы документ должен иметь установленный HTMLEditorKit.Parser. Это будет так, если документ был создан из HTMLEditorKit с помощью метода createDefaultDocument.

Parameters:
elem — элемент, являющийся корнем для нового текста
htmlText — строка, которая будет обработана и назначена elem
Throws:
IllegalArgumentException — если elem является листом
IllegalStateException — если для документа не установлен HTMLEditorKit.Parser
BadLocationException — если вставка невозможна из-за структурной проблемы
IOException — если произошла ошибка ввода-вывода
Since:
1.3

insertBeforeStart

public void insertBeforeStart(Element elem, String htmlText) throws BadLocationException, IOException
Вставляет HTML, заданный в виде строки, перед началом заданного элемента.

Рассмотрим следующую структуру (параметр elem выделен жирным шрифтом).

     <body>
       |
     <div>
      /  \
    <p>   <p>
 

Вызов insertBeforeStart(elem, "<ul><li>") приводит к следующей структуре (новые элементы выделены синим цветом).

        <body>
         /  \
      <ul> <div>
       /    /  \
     <li> <p>  <p>
 

В отличие от метода insertAfterStart, новые элементы становятся соседними элементами указанного элемента, а не дочерними.

Если любой из параметров elem или htmlText имеет значение null, изменения в документе не производятся.

Для корректной работы документ должен иметь установленный HTMLEditorKit.Parser. Это будет так, если документ был создан из HTMLEditorKit с помощью метода createDefaultDocument.

Parameters:
elem — элемент, перед которым вставляется содержимое
htmlText — строка, которая будет обработана и вставлена перед elem
Throws:
IllegalStateException — если для документа не установлен HTMLEditorKit.Parser
BadLocationException — если вставка невозможна из-за структурной проблемы
IOException — если произошла ошибка ввода-вывода
Since:
1.3

insertAfterEnd

public void insertAfterEnd(Element elem, String htmlText) throws BadLocationException, IOException
Вставляет HTML, заданный в виде строки, после конца заданного элемента.

Рассмотрим следующую структуру (параметр elem выделен жирным шрифтом).

     <body>
       |
     <div>
      /  \
    <p>   <p>
 

Вызов insertAfterEnd(elem, "<ul><li>") приводит к следующей структуре (новые элементы выделены синим цветом).

        <body>
         /  \
      <div> <ul>
       / \    \
     <p> <p>  <li>
 

В отличие от метода insertBeforeEnd, новые элементы становятся соседними элементами указанного элемента, а не дочерними.

Если любой из параметров elem или htmlText имеет значение null, изменения в документе не производятся.

Для корректной работы документ должен иметь установленный HTMLEditorKit.Parser. Это будет так, если документ был создан из HTMLEditorKit с помощью метода createDefaultDocument.

Parameters:
elem — элемент, после которого вставляется содержимое
htmlText — строка, которая будет обработана и вставлена после elem
Throws:
IllegalStateException — если для документа не установлен HTMLEditorKit.Parser
BadLocationException — если вставка невозможна из-за структурной проблемы
IOException — если произошла ошибка ввода-вывода
Since:
1.3

getElement

public Element getElement(String id)
Возвращает элемент, у которого есть заданный идентификатор Attribute. Если элемент не найден, возвращается null. Обратите внимание, что этот метод работает с Attribute, а не с тегом символа. В следующем фрагменте HTML: <a id="HelloThere"> атрибут — 'id', а тег символа — 'a'. Это вспомогательный метод для getElement(RootElement, HTML.Attribute.id, id). Он не потокобезопасен.
Parameters:
id — строка, представляющая искомый Attribute
Returns:
элемент с заданным Attribute или null, если он не найден, или null, если id равен null
Since:
1.3
See Also:
  • HTML.Attribute

getElement

public Element getElement(Element e, Object attribute, Object value)
Возвращает дочерний элемент e, содержащий атрибут attribute со значением value, или null, если такой элемент не найден. Этот метод не потокобезопасен.
Parameters:
e — корневой элемент, с которого начинается поиск
attribute — искомый Attribute
value — значения для указанного Attribute
Returns:
элемент с заданным Attribute и заданным value, или null, если он не найден
Since:
1.3
See Also:
  • HTML.Attribute

fireChangedUpdate

protected void fireChangedUpdate(DocumentEvent e)
Уведомляет всех слушателей, которые зарегистрировали интерес к уведомлениям об этом типе события. Экземпляр события создается лениво с использованием параметров, переданных в метод fire.
Overrides:
fireChangedUpdate в классе AbstractDocument
Parameters:
e — событие
See Also:
  • EventListenerList

fireUndoableEditUpdate

protected void fireUndoableEditUpdate(UndoableEditEvent e)
Уведомляет всех слушателей, которые зарегистрировали интерес к уведомлениям об этом типе события. Экземпляр события создается лениво с использованием параметров, переданных в метод fire.
Overrides:
fireUndoableEditUpdate в классе AbstractDocument
Parameters:
e — событие
See Also:
  • EventListenerList

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.desktop/javax/swing/text/html/HTMLDocument.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API