diff --git a/docs/1c-extension-spec.md b/docs/1c-extension-spec.md index 85f9e4f6..43c00156 100644 --- a/docs/1c-extension-spec.md +++ b/docs/1c-extension-spec.md @@ -324,9 +324,20 @@ Enums/ # Перечисления ``` -### 5.4. Заимствованные формы +### 5.4. Формы в расширениях -Метаданные формы (файл `.xml` в каталоге `Forms/`): +В расширении существуют **два принципиально разных сценария** работы с формами: + +| Сценарий | Описание | `` | ID элементов | `callType` | +|----------|----------|:------------:|:------------:|:----------:| +| **Собственная форма** на заимствованном объекте | Новая форма, не существующая в базовой конфигурации | Нет | Обычные (1+) | Нет | +| **Заимствованная форма** | Расширение существующей формы базовой конфигурации | Есть | Базовые + 1000000+ | Есть | + +> **Как отличить:** Если файл метаданных формы (`.xml`) содержит `Adopted` — это заимствованная форма. Собственные формы не имеют `ObjectBelonging`. + +#### 5.4.1. Метаданные заимствованной формы + +Файл `.xml` в каталоге `Forms/`: ```xml
@@ -341,7 +352,196 @@ Enums/ # Перечисления
``` -Содержимое формы (расширение) хранится в `Forms/ФормаСписка/Ext/Form.xml`, модуль формы — в `Forms/ФормаСписка/Ext/Form/Module.bsl`. +Содержимое формы хранится в `Forms/ФормаСписка/Ext/Form.xml`, модуль формы — в `Forms/ФормаСписка/Ext/Form/Module.bsl`. + +#### 5.4.2. Структура Form.xml заимствованной формы + +Form.xml заимствованной формы — **двухчастный файл**: + +```xml +
+ + + + + + ... + + + + + + Расш1_ПриСозданииПосле + + + + + + ... + + + + Расш1_НоваяКомандаВместо + + + + + + ... + + + + + ... + + +
+``` + +**Ключевые правила:** + +1. **Часть 1** (до ``) — **результирующая форма**, содержит ВСЕ элементы: и базовые, и добавленные расширением. Именно эта часть определяет итоговую форму при запуске. + +2. **Часть 2** (``) — **полная копия оригинальной формы** из базовой конфигурации. Используется платформой для контроля совместимости — при обновлении конфигурации платформа сравнивает `` с текущей формой конфигурации и предупреждает о расхождениях. + +3. Элемент `` всегда идёт **последним** в `
` и имеет атрибут `version`. + +#### 5.4.3. Нумерация ID элементов + +| Диапазон | Принадлежность | +|----------|---------------| +| `-1` | Авто-командная панель (`AutoCommandBar`) — фиксированный ID | +| `1` – `999999` | Элементы базовой формы (сохраняют оригинальные ID) | +| `1000000`+ | Реквизиты (`Attributes`) и команды (`Commands`), добавленные расширением | + +> **Важно:** Визуальные элементы форм (элементы в `ChildItems`), добавленные расширением в тело базовой формы, могут использовать ID из обычного диапазона (продолжая нумерацию базовой формы). Диапазон 1000000+ гарантирован для `Attributes` и `Commands`. + +#### 5.4.4. Атрибут callType — перехват событий и команд + +В заимствованных формах события и действия команд используют атрибут `callType` для определения момента перехвата: + +| Значение | Описание | +|----------|----------| +| `Before` | Обработчик расширения вызывается **до** оригинального обработчика | +| `After` | Обработчик расширения вызывается **после** оригинального обработчика | +| `Override` | Обработчик расширения **заменяет** оригинальный обработчик | + +##### События формы (form-level) + +```xml + + Расш1_ПриСозданииНаСервереПосле + Расш1_ПриОткрытииПеред + Расш1_ПередЗаписьюНаСервереПосле + Расш1_ОбработкаОповещенияПосле + +``` + +##### События элементов формы (element-level) + +```xml + + + Расш1_БанкПриИзменении + Расш1_БанкОчистка + + ... + + + + + Расш1_СписокВыборПеред + + ... +
+``` + +##### Действия команд (Command Action) + +Команда может иметь **несколько элементов ``** с разными `callType`: + +```xml + + + Расш1_ПодборИзКлассификатораПеред + Расш1_ПодборИзКлассификатораПосле + + + + + Расш1_НоваяКомандаВместо + + + + + Расш1_ЗапросКорректировкиПосле + +``` + +> **Отличие от обычной формы:** В обычной форме (конфигурации или собственной форме расширения) у `` и `` **нет** атрибута `callType` — обработчик вызывается напрямую. + +#### 5.4.5. Собственная форма на заимствованном объекте + +Расширение может добавить к заимствованному объекту **собственную форму**, не существующую в базовой конфигурации. Такая форма: + +- **Не имеет** `ObjectBelonging` и `ExtendedConfigurationObject` в метаданных формы +- **Не содержит** `` в Form.xml +- **Не использует** атрибут `callType` +- Использует обычную нумерацию ID (1+) +- Формат полностью совпадает с форматом форм конфигурации (см. [1c-form-spec.md](1c-form-spec.md)) + +```xml + + + + Расш1_МояФорма + ... + + Managed + ... + + +``` + +```xml + +
+ + ПриСозданииНаСервере + + ... + ... +
+``` + +#### 5.4.6. Модуль заимствованной формы + +Модуль формы (`Forms/Имя/Ext/Form/Module.bsl`) в заимствованной форме использует те же декораторы перехвата, что и другие модули расширений (см. раздел 7.2): + +```bsl +&НаСервере +&Вместо("ЗаполнитьПодменюПараметры") +Процедура Расш1_ЗаполнитьПодменюПараметры() + ПродолжитьВызов(); +КонецПроцедуры + +&НаКлиенте +&ИзменениеИКонтроль("ПараметрыНаЯзыке") +Функция Расш1_ПараметрыНаЯзыке(КодЯзыка) + // ... тело с #Вставка / #Удаление маркерами ... +КонецФункции + +// Обработчик собственной команды расширения (без декоратора) +&НаКлиенте +Процедура Расш1_НоваяКомандаВместо(Команда) + // ... +КонецПроцедуры +``` + +> **Обработчики событий с `callType`** (определённые в Form.xml секции Events/Action) реализуются в модуле как обычные процедуры **без** аннотаций-декораторов — привязка к событию уже задана в XML через `callType`. ---