Форматированный документ

1С:Предприятие 8.3.14. Документация
Глава 7. Формы

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

Для работы с форматированным документом предназначен объект ФорматированныйДокумент, с помощью которого можно выполнять программную обработку документа, и поле вида Поле форматированного документа, который предназначен для интерактивного изменения форматированного документа.

В информационной базе форматированный документ рекомендуется хранить в реквизите типа ХранилищеЗначения, в который помещается объект типа ФорматированныйДокумент.

Для того чтобы предоставить пользователю возможность интерактивного изменения документа, следует выполнить следующие шаги:

• Создать реквизит формы типа ФорматированныйДокумент и установить для него свойство Сохраняемые данные.
• Создать элемент формы типа Поле ввода вида Поле форматированного документа и связать его с ранее созданным реквизитом.
• При чтении данных формы (обработчик ПриЧтенииНаСервере()) загрузить в реквизит формы документ (метод УстановитьHTML()), который необходимо редактировать, предварительно получив его из информационной базы.
• Перед записью данных формы (обработчик ПередЗаписьюНаСервере()) получить результат (метод ПолучитьHTML()) редактирования документа и поместить его в реквизит, сохраняемый в информационной базе.

В процессе работы с документом можно использовать закладки. Закладка описывает положение некоторого символа в документе. При определении положения нужно учитывать следующие особенности:

• содержимое документа считается одной последовательностью символов;
• перенос строки считается одним символом;
• картинка считается одним символом.

Если положение символа, с которым связана закладка, изменится, то закладка будет отслеживать положение связанного символа. Если удаляется символ, с которым связана закладка, то закладка пытается привязаться к следующему символу, а если этого символа нет ‑ закладка будет указывать на конец документа. Если заменить целиком весь форматированный документ, то все закладки в этом документе станут невалидными.

С помощью закладок можно получать и устанавливать выделение или позицию курсора в редакторе, добавлять и удалять элементы текста в документе (собственно текст, картинка, перевод строки).

Если при получении выделения позиция начала и позиция окончания совпадают, это значит, что выделение отсутствует и получено положение курсора. Так же и при установке выделения: если начальная и конечная позиция выделения совпадают, происходит изменение позиции курсора, без выделения. При программном изменении текста собственно отображение выделения в поле форматированного документа не изменится. Если перед изменением текста выполнялось получение границ выделения, то после изменения текста, закладки могут изменить свою позицию, сохранив при этом свое положение. Другими словами, если вставка происходила внутрь выделения, то позиция закладки, описывающей окончание выделения, увеличится на размер вставленного текста и т. д.

Приведем пример получения и установки выделения в редакторе форматированного документа.

// Содержимое - реквизит формы типа ФорматированныйДокумент
// Редактор - элемент формы типа Поле форматированного документа
// Начало - реквизит формы типа Число. Указывает позицию начала выделения.
// Окончание - реквизит формы типа Число. Указывает позицию окончания выделения.
&НаКлиенте
Процедура ПолучитьВыделение()
    ПозицияНачала = 0;
    ПозицияОкончания = 0;  Элементы.Редактор.ПолучитьГраницыВыделения(ПозицияНачала,ПозицияОкончания);
    Начало = Содержимое.ПолучитьПозициюПоЗакладке(ПозицияНачала);
    Окончание = Содержимое.ПолучитьПозициюПоЗакладке(ПозицияОкончания);
КонецПроцедуры
&НаКлиенте
Процедура УстановитьВыделение()
    ПозицияНачала = Содержимое.ПолучитьЗакладкуПоПозиции(Начало);
    ПозицияОкончания = Содержимое.ПолучитьЗакладкуПоПозиции(Окончание);    Элементы.Редактор.УстановитьГраницыВыделения(ПозицияНачала,ПозицияОкончания);
КонецПроцедуры

При выполнении операций удаления закладка, описывающая начало удаляемого фрагмента, может оказаться некорректной. Если при этом необходимо сохранить позицию начала удаляемого фрагмента, то следует воспользоваться позицией начала фрагмента. Так, пример замены выделенного текста другим текстом будет выглядеть следующим образом.

Если в форматированном документе присутствуют гиперссылки и форматированный документ отображается в режиме Только просмотр, то гиперссылки доступны для перехода. Переход выполняется в новом окне веб-браузера.

Процедура ВставитьСтрокуВТекущуюПозицию(Редактор, Содержимое, Строка)
    Перем Начало, Конец;
    Редактор.ПолучитьГраницыВыделения(Начало, Конец);
    Позиция = Содержимое.ПолучитьПозициюПоЗакладке(Начало);
    Содержимое.Удалить(Начало, Конец);
    Начало = Содержимое.ПолучитьЗакладкуПоПозиции(Позиция);
    Содержимое.Вставить(Начало, Строка);
    Закладка = Содержимое.ПолучитьЗакладкуПоПозиции(Позиция + СтрДлина(Строка));
    Редактор.УстановитьГраницыВыделения(Закладка, Закладка);
КонецПроцедуры

Также имеется возможность программного доступа к тексту форматированного документа. Сам текст состоит из объектов типа ПараграфФорматированногоДокумента, который доступен через свойство Элементы объекта ФорматированныйДокумент. При этом каждый параграф состоит из объектов типа

•  ТекстФорматированногоДокумента, 
• ПереводСтрокиФорматированногоДокумента 
•  КартинкаФорматированногоДокумента (элементы форматированного документа).

Доступ к этой коллекции обеспечивается через свойство Элементы объекта ПараграфФорматированногоДокумента. Границей элемента не обязательно является граница слова.

Например, следующий пример показывает перебор всех параграфов форматированного документа, содержащих текст, и отдельную обработку каждого параграфа.

Пример:

 Для каждого Параграф Из Документ.Элементы Цикл
Если Параграф.ТипПараграфа = ТипПараграфа.Обычный Тогда
 ОбработатьОбычныйПараграф(Параграф);
 ИначеЕсли Параграф.ТипПараграфа = ТипПараграфа.МаркированныйСписок Тогда       ОбработатьСписок(Параграф);
  ИначеЕсли Параграф.ТипПараграфа = ТипПараграфа.НумерованныйСписок Тогда
      ОбработатьСписок(Параграф);
 Иначе 
 Продолжить;
 КонецЕсли; 
КонецЦикла; 

Обработка элементов форматированного документа, входящего в состав параграфа, может оказаться полезной в том случае, если нужно, например, убрать все оформление в виде курсива или полужирного шрифта.

Пример:

 Полужирный = Новый Шрифт(, , Истина);
 Курсив = Новый Шрифт(, , , Истина);
 Обычный = Новый Шрифт; 
Для каждого Элемент Из Параграф.Элементы Цикл 
 Если ТипЗнч(Элемент) = Тип("ПереводСтрокиФорматированногоДокумента") Тогда         Продолжить;
 КонецЕсли; 
Если Элемент.Шрифт = Полужирный Или Элемент.Шрифт = Курсив Тогда             Элемент.Шрифт = Обычный
 КонецЕсли;
КонецЦикла; 

При программной работе с текстом также могут помочь методы ПолучитьЭлементы() и СформироватьЭлементы(). Эти методы возвращают массив элементов форматированного документа. Чтобы увидеть разницу в работе этих методов, рассмотрим пример форматированного документа, содержащего следующую строку: 012 456 890. Строка состоит из 11 символов, где на месте символов 4 и 8 расположены пробелы. Необходимо получить элементы, которые расположены между позициями 2 и 9 этого документа.

 ПозицияНачала = Документ.ПолучитьЗакладкуПоПозиции(2);
 ПозицияОкончания = Документ.ПолучитьЗакладкуПоПозиции(9); 
Результат = Документ.ПолучитьЭлементы(ПозицияНачала, ПозицияОкончания);
 Для каждого Элемент Из Результат Цикл  
   Сообщить("Текст - " + Элемент.Текст); 
КонецЦикла;
 Результат = Документ.СформироватьЭлементы(ПозицияНачала, ПозицияОкончания);
 Для каждого Элемент Из Результат Цикл
     Сообщить("Текст - " + Элемент.Текст);
 КонецЦикла; 

Разница в работе этих методов будет в том, что метод ПолучитьЭлементы() возвращает все элементы, которые попадают между заданными закладками (включая все граничные элементы), т. е. рассматриваемом примере будет выведен следующий текст:

 Текст - 012 456 890 

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

 Текст - 2 456 8 

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

См. также

• Хранилище значения