Строительные
блоки

// ── Of: структура из пар ключ-значение (до 20 пар) ───────────────────────
Шапка = A1sDS.Of(
    "Дата",        '20260201',
    "Организация", МояОрг,
    "Склад",       СкладГП,
    "Комментарий", "Корпус А — февраль");
// → Структура { Дата:'...', Организация:СсылкаОрг, Склад:СсылкаСклад, ... }

// ── OfFixed: то же, но результат — ФиксированнаяСтруктура ────────────────
// Удобно для констант — платформа не даст изменить значения случайно
Режимы = A1sDS.OfFixed(
    "ОсновнойСклад",    СкладОсновной,
    "РезервныйСклад",  СкладРезерв);
// Режимы.ОсновнойСклад = X  ← ошибка: ФиксированнаяСтруктура нельзя изменить

// ── OfKeys: структура из СПИСКА ключей с одним значением ─────────────────
// Применяется для инициализации счётчиков, флагов, накопителей
Счётчики = A1sDS.OfKeys("Создано, Обновлено, Ошибок", 0);
// → { Создано: 0, Обновлено: 0, Ошибок: 0 }

// После обработки строк — накапливаем:
Счётчики.Создано    = Счётчики.Создано + 1;
Счётчики.Обновлено  = Счётчики.Обновлено + 3;

Сообщить("Создано: "   + Счётчики.Создано
       + ", Ошибок: " + Счётчики.Ошибок);

// ── Сценарий: обработка параметров загрузки из внешней системы ───────────
// Пользователь передал только часть настроек — остальное берём по умолчанию

НастройкиПользователя = A1sDS.Of(
    "Организация", МояОрг,    // пользователь задал
    "Дата",        '20260201');    // пользователь задал
// Склад, Валюта, НДС — не задал → возьмём из умолчаний

Умолчания = A1sDS.Of(
    "Организация", ОрганизацияПоУмолчанию,
    "Склад",       СкладОсновной,
    "Валюта",      "RUB",
    "НДС",         Истина);

Итог = A1sDS.Defaults(НастройкиПользователя, Умолчания);
// Итог → { Организация: МояОрг,      ← от пользователя (НЕ перезаписано!)
//           Дата:        '20260201',  ← от пользователя
//           Склад:       СкладОсновной, ← из умолчаний
//           Валюта:      "RUB",       ← из умолчаний
//           НДС:         Истина }     ← из умолчаний

// ── Применение: передаём итоговые параметры в документ ───────────────────
Dok = A1sDocs.Of("ВыпускПродукцииУслуг", Итог);

// ── Паттерн: базовая структура документа + override для конкретного случая

БазоваяШапка = A1sDS.Of(
    "Организация", МояОрг,
    "Склад",       СкладОсновной,
    "Валюта",      "RUB",
    "Дата",        ТекущаяДата());

// Для экспортной сделки — переопределяем валюту и склад
ШапкаЭкспорт = A1sDS.Merge(БазоваяШапка, A1sDS.Of(
    "Валюта", "USD",
    "Склад",  СкладЭкспорт));
// ШапкаЭкспорт → { Организация: МояОрг, Склад: СкладЭкспорт,
//                   Валюта: "USD", Дата: ТекДата }
// БазоваяШапка — НЕ изменилась (Merge возвращает новую структуру)

// ── Паттерн DTO-фабрика: функция с необязательным Overrides ──────────────
Функция НовыйВыпуск(Overrides = Неопределено)
    База = A1sDS.Of(
        "Организация", МояОрг,
        "Склад",       СкладГП,
        "Дата",        ТекущаяДата());
    Возврат A1sDS.Merge(База, Overrides); // если Overrides=Неопределено — вернёт копию базы
КонецФункции

// Вызов без параметров — базовые значения
Dok1 = A1sDocs.Of("ВыпускПродукцииУслуг", НовыйВыпуск());

// Вызов с параметрами — база + override
Dok2 = A1sDocs.Of("ВыпускПродукцииУслуг",
    НовыйВыпуск(A1sDS.Of("Дата", '20260301', "Комментарий", "Март")));

// Допустим, из JSON-API пришла большая структура
ДанныеAPI = A1sDS.Of(
    "id",            "kv-101",
    "Наименование", "Квартира 101",
    "Площадь",      42.5,
    "Этаж",         3,
    "token",         "eyJ0...",     // служебное — нам не нужно
    "_version",      7,              // служебное — нам не нужно
    "Цена",          3500000);

// ── Pick: взять только нужные поля ───────────────────────────────────────
ДляСправочника = A1sDS.Pick(ДанныеAPI, "Наименование, Площадь, Этаж, Цена");
// → { Наименование: "Квартира 101", Площадь: 42.5, Этаж: 3, Цена: 3500000 }
// token и _version — отброшены

// ── Omit: взять всё, кроме указанных ─────────────────────────────────────
ДляСправочника2 = A1sDS.Omit(ДанныеAPI, "id, token, _version");
// → { Наименование: "Квартира 101", Площадь: 42.5, Этаж: 3, Цена: 3500000 }
// Эквивалентно Pick выше, но Pick точнее — Omit добавит любые новые поля из API автоматически

// ── Практика: передать только нужные поля в Ensure ───────────────────────
A1sCatalogs.Ensure(
    "Номенклатура",
    ДанныеAPI.Наименование,
    A1sDS.Omit(ДанныеAPI, "id, token, _version"));

// ── Rename: одна структура ────────────────────────────────────────────────
// JSON из внешнего API: поля с английскими именами
СтрокаAPI = A1sDS.Of(
    "name",     "Квартира 101",
    "area",     42.5,
    "floor",    3,
    "price",    3500000);

// Карта переименования: {старое_имя: "новое_имя"}
КартаПолей = A1sDS.Of(
    "name",  "Наименование",
    "area",  "Площадь",
    "floor", "Этаж",
    "price", "Цена");

ДляСправочника = A1sDS.Rename(СтрокаAPI, КартаПолей);
// → { Наименование: "Квартира 101", Площадь: 42.5, Этаж: 3, Цена: 3500000 }


// ── RenameFields: МАССИВ структур (новое в v2.1) ──────────────────────────
// Пришёл массив JSON-строк, нужно переименовать поля во всех сразу
// и загрузить в ТЧ документа через LoadRows

ДанныеJSON = A1sAR.Of(
    A1sDS.Of("item", "Квартира 101", "qty", 1, "sum", 3500000),
    A1sDS.Of("item", "Квартира 102", "qty", 1, "sum", 3100000),
    A1sDS.Of("item", "Квартира 103", "qty", 1, "sum", 4400000));

// Схема один раз — описываем ДО цикла
// Поля вне схемы копируются как есть (qty → qty если не указано)
Схема = A1sDS.Of(
    "item", "Номенклатура",  // item → Номенклатура
    "qty",  "Количество",    // qty  → Количество
    "sum",  "Сумма");        // sum  → Сумма

ПодготовленныеСтроки = A1sDS.RenameFields(ДанныеJSON, Схема);
// → массив структур с русскими именами:
//   [{ Номенклатура: "Квартира 101", Количество: 1, Сумма: 3500000 }, ...]

// Загружаем в ТЧ документа
A1sDocs.LoadRows(Dok, "Продукция", ПодготовленныеСтроки);

// ── Сценарий: параметры фильтра формируются в зависимости от флагов ───────

Фильтр = A1sDS.Of("Организация", МояОрг);  // обязательное поле

// Добавляем склад только если он задан в параметрах формы
A1sDS.AddIf(Фильтр, "Склад", Склад, ЗначениеЗаполнено(Склад));

// Добавляем период только если включён флаг "ПоПериоду"
A1sDS.AddIf(Фильтр, "НачалоПериода", НачалоПериода, ФильтрПоПериоду);
A1sDS.AddIf(Фильтр, "КонецПериода",  КонецПериода,  ФильтрПоПериоду);

// Добавляем комментарий с альтернативным значением при ложном условии
A1sDS.AddIf(Фильтр, "Режим",
    "Детальный",     // если ДетальныйРежим = Истина
    ДетальныйРежим,
    "Краткий");     // иначе — "Краткий"

// ── Всё вместе, инлайн-стиль ─────────────────────────────────────────────
Параметры = A1sDS.Of("Организация", МояОрг);
A1sDS.AddIf(Параметры, "Склад",    Склад,    ЗначениеЗаполнено(Склад));
A1sDS.AddIf(Параметры, "Контрагент", Контрагент, ЗначениеЗаполнено(Контрагент));
ДокументыПоФильтру = A1sDocs.Refs("РеализацияТоваровУслуг",
    "Организация = &Организация", Параметры);

// ── HasKeys: валидация обязательных полей перед загрузкой ─────────────────
СтрокаJSON = A1sDS.Of("Наименование", "Кв 101", "Площадь", 42.5);
// Поля "Этаж" и "Цена" отсутствуют

Если НЕ A1sDS.HasKeys(СтрокаJSON, "Наименование, Площадь, Цена") Тогда
    Сообщить("Ошибка: не заполнены обязательные поля (Цена)");
    Возврат;
КонецЕсли;

// ── GetKeys: перебрать все ключи структуры ────────────────────────────────
Ключи = A1sDS.GetKeys(СтрокаJSON);  // → ["Наименование", "Площадь"]
Сообщить("Поля: " + A1sAR.Join(Ключи, ", "));  // "Поля: Наименование, Площадь"

// ── GroupBy: сгруппировать строки выпуска по этажу и посчитать суммы ──────
СтрокиВыпуска = A1sAR.Of(
    A1sDS.Of("Этаж", "3", "Сумма", 3500000),
    A1sDS.Of("Этаж", "3", "Сумма", 3100000),
    A1sDS.Of("Этаж", "4", "Сумма", 4400000),
    A1sDS.Of("Этаж", "4", "Сумма", 5100000));

ИтогиПоЭтажам = A1sDS.GroupBy(СтрокиВыпуска, "Этаж", "Сумма");
// → { "3": 6600000, "4": 9500000 }
// Без запроса к БД, без ТЗ.Итог() — просто из массива структур

Сообщить("Этаж 3: " + ИтогиПоЭтажам["3"]);  // 6600000
Сообщить("Этаж 4: " + ИтогиПоЭтажам["4"]);  // 9500000

// ── Of: элементы любого типа ──────────────────────────────────────────────
Числа   = A1sAR.Of(1, 2, 3, 4, 5);
Имена   = A1sAR.Of("ПРОЖИВАНИЕ", "ПИТАНИЕ", "ПРОЧЕЕ");
Ссылки  = A1sAR.Of(Ном1, Ном2, Ном3);    // ссылки тоже работают
Строки  = A1sAR.Of(               // массив структур — для AddRows
    A1sDS.Of("Ном", Ном1, "Кол", 1),
    A1sDS.Of("Ном", Ном2, "Кол", 2));

// Флаг ТолькоУникальные — убрать дубликаты при создании
УникальныеИмена = A1sAR.Of("А", "Б", "А", "В", "Б", /*ТолькоУникальные=*/ Истина);
// → ["А", "Б", "В"]

// ── OfN: массив заданного размера с одинаковым значением ─────────────────
Нули    = A1sAR.OfN(5, 0);         // [0, 0, 0, 0, 0]
Флаги   = A1sAR.OfN(10, Ложь);    // [Ложь, Ложь, ... × 10]
Буфер   = A1sAR.OfN(100, "");     // 100 пустых строк — для заполнения в цикле

// ── Concatenate: объединить несколько массивов ────────────────────────────
ВсеНом = A1sAR.Concatenate(НомДок1, НомДок2, НомДок3);
// Принимает до 8 массивов + флаг ТолькоУникальные

УникВсеНом = A1sAR.Concatenate(НомДок1, НомДок2, НомДок3, /*ТолькоУникальные*/ Истина);

// ── Union: объединение — уникальные элементы из всех массивов ─────────────
// Эквивалентно Concatenate с ТолькоУникальные=Истина, но читается явнее
ОбщаяНоменклатура = A1sAR.Union(НомДок1, НомДок2, НомДок3);

// ── Difference: что выпустили, но ещё не реализовали ─────────────────────
ВыпущеннаяНом   = A1sAR.Of(Ном101, Ном102, Ном103, Ном201);
РеализованнаяНом = A1sAR.Of(Ном101, Ном201);

НевыпущенноеОстаток = A1sAR.Difference(ВыпущеннаяНом, РеализованнаяНом);
// → [Ном102, Ном103] — то что выпустили, но не реализовали

// ── Intersection: пересечение — что есть в обоих ─────────────────────────
ОбщиеПозиции = A1sAR.Intersection(ВыпущеннаяНом, РеализованнаяНом);
// → [Ном101, Ном201]

// ── Сценарий: пользователь выбрал несколько номенклатур на форме ──────────
// Список может содержать пустые ссылки и дубликаты

ВыборПользователя = A1sAR.Of(
    Ном1, Неопределено, Ном2, Ном1,         // дубль Ном1
    A1sCatalogs.Empty("Номенклатура"),       // пустая ссылка
    Ном3, Неопределено);

// Шаг 1: убрать Неопределено и пустые ссылки
БезПустых = A1sAR.PickFilled(ВыборПользователя);
// → [Ном1, Ном2, Ном1, Ном3]  (Неопределено и пустые ссылки убраны)

// Шаг 2: убрать дублирующиеся ссылки
ЧистыйСписок = A1sAR.RemoveDuplicates(БезПустых);
// → [Ном1, Ном2, Ном3]

// ── Всё в одну строку: RemoveDuplicates(PickFilled(...)) ─────────────────
ГотовыйСписок = A1sAR.RemoveDuplicates(
    A1sAR.PickFilled(ВыборПользователя));

// ── PickRefs: оставить только ссылки (убирает строки, числа, Неопределено)
// Используется когда массив содержит разнотипные значения
СмешанныйМассив = A1sAR.Of(Ном1, "текст", Ном2, 42, Ном3);
ТолькоСсылки    = A1sAR.PickRefs(СмешанныйМассив);
// → [Ном1, Ном2, Ном3]  (строки и числа убраны)

// ── PickNotNull: оставить всё кроме Неопределено (включая пустые ссылки)
// Когда пустая ссылка — валидное значение, но Неопределено — нет
БезНеопределено = A1sAR.PickNotNull(ВыборПользователя);

// ── Сценарий: загрузить 500 квартир в справочник, порциями по 100 ─────────
// Зачем пачками? Чтобы не держать транзакцию открытой слишком долго

ВсеКвартиры = /* ... массив из 500 строк из Excel ... */;
Сообщить("Всего позиций: " + ВсеКвартиры.Количество());

// Разбиваем на пачки по 100
Пачки = A1sAR.Chunk(ВсеКвартиры, 100);
// → [[строки 1-100], [строки 101-200], ..., [строки 401-500]]
// Каждый элемент Пачки — это массив строк из Excel

НомерПачки = 0;
Для Каждого Пачка Из Пачки Цикл
    НомерПачки = НомерПачки + 1;
    Сообщить("Пачка " + НомерПачки + ": " + Пачка.Количество() + " записей");

    Для Каждого СтрокаExcel Из Пачка Цикл
        A1sCatalogs.EnsureUpdate(
            "Номенклатура",
            СтрокаExcel.Наименование,
            A1sDS.Pick(СтрокаExcel, "Площадь, Этаж, Цена"));
    КонецЦикла;

    // Пауза между пачками (опционально, для больших баз)
    ОбработкаПрерыванияПользователя();
КонецЦикла;

Сообщить("✓ Загружено " + ВсеКвартиры.Количество() + " позиций в "
    + Пачки.Количество() + " пачках");

ВыпускиЗаМесяц = A1sDocs.AllInPeriod("ВыпускПродукцииУслуг", '20260201', '20260228');

// ── Безопасный доступ — не упадёт на пустом массиве ──────────────────────
ПервыйВыпуск    = A1sAR.First(ВыпускиЗаМесяц);   // Неопределено если пустой
ПоследнийВыпуск = A1sAR.Last(ВыпускиЗаМесяц);    // Неопределено если пустой

Если ПервыйВыпуск = Неопределено Тогда
    Сообщить("За февраль выпусков нет");
КонецЕсли;

// vs классический — требует проверки размера вручную:
// Если ВыпускиЗаМесяц.Количество() > 0 Тогда
//     ПервыйВыпуск = ВыпускиЗаМесяц[0];   ← IndexOutOfBounds если забыть проверку
// КонецЕсли;

// ── Contains: проверить вхождение ────────────────────────────────────────
ДозволенныеСклады = A1sAR.Of(СкладОсновной, СкладРезерв, СкладЭкспорт);

Если НЕ A1sAR.Contains(ДозволенныеСклады, ВыбранныйСклад) Тогда
    ВызватьИсключение "Склад не входит в список разрешённых";
КонецЕсли;

// ── IsEmpty: проверить что массив пустой ─────────────────────────────────
Если A1sAR.IsEmpty(ВыпускиЗаМесяц) Тогда
    Сообщить("Нет документов за период");
    Возврат;
КонецЕсли;

// ── IndexOf: найти позицию элемента (−1 если не найден) ──────────────────
ПозицияВыпуска = A1sAR.IndexOf(ВыпускиЗаМесяц, КонкретныйВыпуск);
Если ПозицияВыпуска >= 0 Тогда
    Сообщить("Найден на позиции: " + ПозицияВыпуска);
КонецЕсли;

// ── AddIf: собрать список ошибок условно ──────────────────────────────────
Ошибки = Новый Массив;

A1sAR.AddIf(Ошибки, "Не заполнена Организация",  НЕ ЗначениеЗаполнено(Организация));
A1sAR.AddIf(Ошибки, "Не заполнен Склад",       НЕ ЗначениеЗаполнено(Склад));
A1sAR.AddIf(Ошибки, "ТЧ пустая",               Dok.Продукция.Количество() = 0);

Если НЕ A1sAR.IsEmpty(Ошибки) Тогда
    ВызватьИсключение "Ошибки заполнения: " + A1sAR.Join(Ошибки, "; ");
    // → "Ошибки заполнения: Не заполнена Организация; ТЧ пустая"
КонецЕсли;

// ── AddIf с альтернативным значением ─────────────────────────────────────
СтатусыДокументов = Новый Массив;
Для Каждого Ссылка Из ВыпускиЗаМесяц Цикл
    A1sAR.AddIf(СтатусыДокументов,
        "✓ проведён",     // если проведён
        A1sDocs.IsPosted(Ссылка),
        "✗ не проведён"); // иначе
КонецЦикла;

// ── Join: вывести список в одну строку ───────────────────────────────────
ИменаНом = A1sAR.Of("Квартира 101", "Квартира 102", "Квартира 103");
Сообщить("Загружено: " + A1sAR.Join(ИменаНом, ", "));
// → "Загружено: Квартира 101, Квартира 102, Квартира 103"

// Join работает с любыми типами — числа, даты тоже преобразуются в строку
СуммыВСтроку = A1sAR.Join(A1sAR.Of(3500000, 3100000, 4400000), " + ");
// → "3 500 000 + 3 100 000 + 4 400 000"