Создание собственной библиотеки в 1С 8.3

Библиотека в 1С — это переносимый набор объектов метаданных и общих модулей с экспортными методами, который собирают в одной конфигурации и затем встраивают в другие. Создают её в Конфигураторе: добавляют общие модули с процедурами и функциями, помечают методы ключевым словом Экспорт, группируют объекты в подсистему и передают в целевую конфигурацию через объединение конфигураций или как расширение.

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

Что в 1С называют библиотекой и где она живёт

Под библиотекой понимают две близкие вещи. Первая — ваш собственный набор повторно используемого кода: общие модули с функциями, которые вызывают из разных мест (РаботаСоСтроками.ОчиститьПробелы(...)). Вторая — полноценный набор объектов: справочники, регистры, обработки, документы, объединённые в подсистему и распространяемые как единое целое. Образец второго подхода — Библиотека стандартных подсистем (БСП) от фирмы 1С.

Хранится всё это в конфигурации. Отдельного «файла библиотеки» как контейнера в платформе нет: на выходе вы получаете либо файл выгрузки конфигурации .cf, либо файл расширения .cfe. Их и переносят в целевые базы.

Проектируем состав и зоны ответственности

Сначала определите границы: какие задачи библиотека решает и что в неё точно не входит. Чёткая граница экономит время позже — не придётся выдёргивать «приросшие» объекты из чужой конфигурации.

Продумайте три вещи:

• 📦 Состав объектов. Какие справочники, регистры, обработки нужны. Что из этого — публичный интерфейс, а что внутренняя кухня.
• 🏷️ Префикс имён. Задайте уникальный префикс для всех объектов и общих модулей (например, мбУведомления, мбРаботаСФайлами). Это главная защита от конфликтов имён при встраивании в чужую базу.
• 🔗 Зависимости. От чего библиотека зависит — от платформы определённой версии, от БСП, от конкретных объектов целевой конфигурации. Минимум зависимостей = проще подключение.

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

Заложите версионирование сразу. Самый простой вариант — экспортная функция, которая возвращает номер версии строкой. По ней в целевой базе можно понять, какая версия библиотеки встроена, и решить, нужно ли обновление:

// Общий модуль "мбБиблиотекаСлужебный"
Функция ВерсияБиблиотеки() Экспорт
    Возврат "1.2.3";
КонецФункции

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

Создаём объекты метаданных и подсистему

Откройте Конфигуратор целевой «библиотечной» конфигурации (удобно вести библиотеку в отдельной пустой базе). В дереве конфигурации добавьте нужные объекты через контекстное меню соответствующей ветки.

Порядок такой:

1. Создайте объекты данных: справочники, регистры сведений, при необходимости документы. Имена — с вашим префиксом.
2. Добавьте подсистему: ветка Общие → Подсистемы, команда «Добавить». В её составе отметьте галочками все объекты библиотеки.
3. Заполните свойства подсистемы: синоним, картинку, признак «Включать в командный интерфейс», если объекты должны появляться в разделах у пользователя.

Подсистема — это «обёртка», по которой позже удобно отбирать объекты библиотеки при объединении конфигураций. Без неё перенос тоже возможен, но вручную отмечать десятки объектов утомительно и легко что-то пропустить.

Общие модули и экспорт процедур

Код библиотеки размещают в общих модулях: ветка Общие → Общие модули. Для каждого модуля в палитре свойств задают контекст выполнения — это определяет, откуда метод можно вызвать.

Ключевые флаги общего модуля:

Метод становится частью публичного интерфейса, только если помечен словом Экспорт:

// Общий модуль "мбРаботаСоСтрокамиКлиентСервер"
// Контекст: Сервер + Клиент (управляемое приложение)

Функция ОчиститьИНН(Знач ИНН) Экспорт
    Возврат СтрЗаменить(СокрЛП(ИНН), " ", "");
КонецФункции

Вызов из любого места конфигурации, где доступен модуль:

ИННБезПробелов = мбРаботаСоСтрокамиКлиентСервер.ОчиститьИНН(Контрагент.ИНН);

Методы без Экспорт видны только внутри своего модуля — это удобно для внутренних вспомогательных процедур, которые не должны «торчать наружу».

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

Процедура ЗаписатьВЖурнал(Текст, Уровень = Неопределено) Экспорт
    УровеньЗаписи = ?(Уровень = Неопределено,
        УровеньЖурналаРегистрации.Информация, Уровень);
    ЗаписьЖурналаРегистрации("МояБиблиотека", УровеньЗаписи, , , Текст);
КонецПроцедуры

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

Подключаем библиотеку к рабочей конфигурации

Когда библиотека собрана, её переносят в целевую базу. Рабочий способ для набора объектов — объединение конфигураций.

1. В библиотечной базе: Конфигурация → Сохранить конфигурацию в файл… — получите файл .cf.
2. В целевой базе: Конфигурация → Сравнить, объединить с конфигурацией из файла… и укажите этот .cf.
3. В окне сравнения снимите все галочки, затем по подсистеме отметьте только объекты библиотеки. Проверьте режим объединения для каждого — «Взять из файла» для новых объектов.
4. Выполните объединение, затем Конфигурация → Обновить конфигурацию базы данных (клавиша F7).

В окне сравнения платформа подсвечивает, какие объекты отличаются и как именно. Для новых объектов библиотеки выбирайте режим «Взять из файла»; объекты, которых в целевой базе быть не должно, оставляйте без галочки. Если имена всё-таки пересеклись, платформа предложит сопоставить объекты вручную — в этом месте и выручает уникальный префикс, потому что сопоставлять оказывается нечего.

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

Для регулярно обновляемой библиотеки есть механизм поставки: Конфигурация → Поставка конфигурации → Создать файлы поставки и обновления…. Он формирует файлы .cf и .cfu, по которым целевая база принимает новые версии как обновление, сохраняя разграничение «ваше / чужое». Так распространяют и БСП.

Расширение конфигурации как альтернатива

Если задача — добавить функциональность, не меняя основную конфигурацию (например, когда она на строгой поддержке), используйте расширение. Механизм появился в платформе 8.3.6.

Расширение — это отдельная мини-конфигурация поверх основной. Вы создаёте в нём свои общие модули и объекты, а при необходимости заимствуете объекты основной конфигурации и дорабатываете их. Основная конфигурация при этом остаётся нетронутой.

Подключение: Конфигурация → Расширения конфигурации, добавляете расширение, разрабатываете, затем выгружаете в файл .cfe. В рабочей базе расширение загружают через ту же форму списка расширений и применяют.

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

Проверяем и отлаживаем код библиотеки

Перед передачей библиотеки прогоните её через проверки платформы.

• Синтаксический контроль модуля — в редакторе модуля запустите проверку синтаксиса. Ловит опечатки и обращения к несуществующим методам в пределах модуля.
• Проверка конфигурации — Конфигурация → Проверить конфигурацию…. Отметьте синтаксический контроль модулей и проверку логической целостности. Так находят оборванные ссылки на объекты, которые вы, например, забыли включить в состав библиотеки.

Для пошаговой отладки включите её в настройках запуска Конфигуратора (Сервис → Параметры), затем запустите 1С:Предприятие в режиме отладки.

1. Поставьте точку останова на нужной строке (клавиша F9).
2. Запустите сценарий, который вызывает ваш метод.
3. Когда выполнение остановится, идите по строкам: F11 — с заходом в процедуру, F10 — через неё.
4. Значения переменных смотрите в окне «Табло» или через «Вычислить выражение».

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

Типичные ошибки при разработке библиотеки

Ошибки здесь однотипные и легко узнаваемые по симптому.

• 🔴 Забыли Экспорт. Метод не виден снаружи, при вызове — ошибка вида «Процедура или функция с указанным именем не определена». Проверьте ключевое слово в объявлении.
• 🔴 Неверный контекст модуля. Вызываете серверную функцию с клиента, а у модуля не стоит «Вызов сервера» — получаете ошибку доступности метода. Либо добавьте флаг, либо выносите вызов на сервер.
• 🔴 Конфликт имён при объединении. В целевой базе уже есть объект с таким же именем. Отсюда правило про уникальный префикс: с ним пересечений почти не бывает.
• 🔴 Жёсткие ссылки на объекты целевой конфигурации. Библиотека обращается к справочнику, которого в чужой базе нет. Публичные методы должны получать данные через параметры, а не лезть напрямую к посторонним объектам.
• 🔴 Кэш не к месту. Включённое «Повторное использование возвращаемых значений» на функции, читающей данные базы, возвращает устаревший результат. Кэшируйте только неизменные вычисления.
• 🔴 Потеря доработок при обновлении. Если библиотеку в целевой базе правили вручную, следующее объединение затрёт правки. Ведите разработку в исходной библиотечной конфигурации и раздавайте новые версии, а не чините объекты на местах.