Руководство разработчика

И++ / FC

Функция ЭКСПОРТ_ФОРМЫ

Функция ЭКСПОРТ_ФОРМЫ позволяет выполнить подстановку данных в шаблон документа офисных приложений Word, Excel или OpenOffice. 

ФУНКЦИЯ ЛОГИКА: ЭКСПОРТ_ФОРМЫ(СТРОКА: приложение; 
                              СТРОКА: имя_файла; 
                              СТРОКА: опции; 
                              ПОДСТАНОВКА_ФОРМЫ: подстановка)

Параметры

приложение
Название целевого приложения:
"Default"–автоматический выбор;
"Word"–Microsoft Word;
"Excel"–Microsoft Excel;
"OpenOffice Writer"–OpenOffice.org Writer;
"OpenOffice Calc"–OpenOffice.org Calc;
"XML"–запись данных в XML файл для последующего экспорта утилитой xmlexp.exe.
Если установлено значение "Default", будет выполняться автоматический выбор приложенияв зависимости от того, что установлено на компьютере. В остальных случаях экспорт будет осуществляться вуказанное приложение.
имя_файла
Имя файла шаблона документа относительно рабочей папки. Расширение файла помогает сделать автоматический выбор приложения в режиме "Default".
опции
Опции экспорта позволяют сохранить результат в файл в формате офисного приложения. Опции задают имя файла для сохранения и дополнительную команду. Команда отделяется от имени файла символом ">". Поддерживается команда close – закрытие документа после сохранения. Например: "d:\export\saved.xls>close".
подстановка
Набор подстановок: простых и табличных.

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

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

Возвращаемое значение

ДА – в случае успешного выполнения, НЕТ – в противном случае.

В некоторых случаях передаваемый текст может быть неверно интерпретирован целевым приложением в зависимости от региональных настроек форматов Windows или самого целевого приложения. В частности, Excel может интерпретировать текст "10.11" не как число, а как дату 10 ноября. Чтобы избежать подобных эффектов и обеспечить передачу текста без искажений, в документе Excel нужно задавать проблемным ячейкам формат "Текстовый".

Табличные подстановки производятся в позицию помеченной ключевой строкой табличной подстановки. В этой строке могут располагаться ключевые строки для подстановок значений столбцов таблицы. Если в табличной подстановке нет строк, то строка в документе удаляется. Если в табличной подстановке более одной строки, то дополнительные строки добавляются копированием исходной строки документа. В каждую строку таблицы выполняется подстановка соответствующих значений табличных данных. Данные табличной подстановки задаются значением типа ПОДСТАНОВКА_ТАБЛИЦЫ, где столбцы задаются строковыми именами, а строки пронумерованы.

Табличная подстановка может выполняться не в строки, а в столбцы. Для этого имя таблицы должно начинаться с символа ^. В виде строковой константы И++ имя может выглядеть так: "^^табл". Ключевые строки для подстановки данных должны располагаться в столбце, помеченном именем таблицы. Подстановка по столбцам поддерживается только для электронных таблиц: Excel и Сalc.

При экспорте в Excel и OpenOffice Calc можно указать номер или имя листа в ключевой строке подстановки.

Например:
"#2:_ЗАМЕНИ_ЭТО" – "_ЗАМЕНИ_ЭТО" на втором листе,
"Часть2:_ЗАМЕНИ_ЭТО" – "_ЗАМЕНИ_ЭТО" на листе "Часть2".

При подстановках в Word и OpenOffice Writer часть ключевой строки перед ":" не учитывается.

При заполнении шаблонов в Excel и OpenOffice Calc не происходит автоматическая подгонка высот строк, которые содержат измененные ячейки. Это происходит из-за особенностей реализации этих приложений. Для обеспечения подгонки высоты строк для ячеек с многострочным текстом (в т.ч. объединенных) при разработке шаблона их следует особым образом пометить. Для помеченных ячеек библиотекой экспорта выполняется дополнительная обработка, восполняющая недостатки целевых приложений.

Для выполнения дополнительной обработки многострочных ячеек в шаблоне должны выполняться два требования:

  1. для ячейки должен быть включен признак "перенос по словам";
  2. фон ячейки должен иметь цвет "Лаванда" RGB(204, 153, 255), номер в Excel 39, название в OpenOffice "фиолетовый 10".

После обработки таких ячеек цвет фона заменяется на белый.

Функция ЭКСПОРТ_ФОРМЫ позволяет производить подстановку изображений в шаблон документа с соблюдением параметров формата изображения-заглушки, установленного в шаблоне. Подстановка изображения производится как по названию изображения, которое задано в шаблоне, так и по порядковому номеру в шаблоне. Синтаксис указания подстановки изображения в шаблон офисного приложения приведен ниже. 

@<имя_изображения>
@#<номер_изображения>

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

Использование порядкового номера не гарантирует точность подстановки в заданное место из-за того, что порядок присвоения номера изображению в документе точно неизвестен. Кроме того, в приложении Word изображения в документе разделяются на коллекции inline-shape (обтекание в тексте) и free floating shape (обтекание текстом), и в каждой коллекции свой порядок нумерации. То есть если в шаблоне документа два изображения: одно с обтеканием в тексте, другое с обтеканием перед текстом. В коде ниже указывается, что нужно осуществить подстановку во второе изображение в шаблоне документа. 

ПЕРЕМ ПОДСТАНОВКА_ФОРМЫ: д
д.поля["@#2"] = путь_шаблона + "data.jpg"
ПЕРЕМ рез = ЭКСПОРТ_ФОРМЫ("Word", путь_шаблона + "imgsubst_sample.dotx", путь_шаблона + "saved.doc", д)

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

В примере ниже демонстрируется заполнение шаблона изображением и строковыми данными. Имеется шаблон imgsubst_sample.xltx, где при помощи ключевых строк "стр", "назв", "цена" установлены места для подстановки, у изображения-заглушки для подстановки штрих-кода задано имя "img". 

КОНСТ путь_шаблона = "C:\Users\Admin\Desktop\tmpl\";
ВЫЧИСЛИТЬ
  ПЕРЕМ ПОДСТАНОВКА_ФОРМЫ: подстановка
  ПЕРЕМ ПОДСТАНОВКА_ТАБЛИЦЫ: табл
  ПЕРЕМ ЦЕЛОЕ: строка = 1
  ПЕРЕМ ЧИСЛО: итого
  ЦИКЛ ПОКА (строка < 5)
    табл.данные[строка, "назв"] = "Товар " + СТР(строка)
    табл.данные[строка, "цена"] = СЛУЧ_ЧИСЛО(2000)/5
    строка++
  КОНЕЦ_ЦИКЛА
  подстановка.таблицы["Лист3:стр"] = табл
  подстановка.поля["Лист3:@img"] = путь_шаблона + "code_1.jpg"
  подстановка.поля["Лист3:ДАТА"] = ДАТА_ТЕК
  ЦИКЛ ИНДЕКС(сумма = табл.данные[строка, "цена"])
    итого += сумма
  КОНЕЦ_ЦИКЛА
  подстановка.поля["Лист3:%Итого%"] = итого
  ПЕРЕМ рез = ЭКСПОРТ_ФОРМЫ("Excel", путь_шаблона + "imgsubst_sample.xltx", путь_шаблона 
  + "saved.xls" , подстановка)
КОНЕЦ
В результате получен документ saved.xls с содержимым.

См. также:

Многолетний опыт автоматизации бухучета и отчетности