Глава 28
Работа со Списком Значений

• Контекст работы со Списком Значений
  • Методы объекта Список Значений
• ДобавитьЗначение
• ВставитьЗначение
• РазмерСписка
• НайтиЗначение
• ПолучитьЗначение
• УстановитьЗначение
• Получить
• Установить
• УдалитьЗначение
• УдалитьВсе
• Сортировать
• СортироватьПоПредставлению
• СдвинутьЗначение
• Принадлежит
• ВыбратьЗначение
• ОтметитьЗначения
• Пометка
• ТекущаяСтрока
• ИзСтрокиСРазделителями
• ВСтрокуСРазделителями
• Выгрузить

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

Объект типа «СписокЗначений» — это средство языка (не сохраняемый в БД объект), которое позволяет строить «динамические массивы» и манипулировать ими (добавлять, редактировать, удалять элементы, сортировать). Список значений может быть наполнен значениями любого типа, т. е. в одном списке типы хранимых значений могут быть разными. Одним из примеров использования данного объекта может служить организация выбора конкретного документа из списка возможных документов, сформированного по сложному алгоритму.

Контекст работы со Списком Значений

Во всех программных модулях вызов соответствующих методов может выполняться при помощи переменной со ссылкой на объект типа «СписокЗначений». Такие объекты можно создавать при помощи функции СоздатьОбъект, ссылка на который присваивается переменной. Кроме того, если в форму диалога при помощи визуальных средств конфигуратора вставлены специальные элементы форм диалога «Список» и «Поле со списком», то идентификаторы этих элементов доступны в контексте программного модуля этой формы как уже существующие объекты типа «СписокЗначений».

Чтобы вызвать метод объекта, имя метода (с указанием необходимых параметров) пишется через точку после имени объекта.

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

Англоязычный синоним ключевого слова СписокЗначений — ValueList.

Пример:

МойСписок = СоздатьОбъект("СписокЗначений");

Методы объекта Список Значений

ДобавитьЗначение

Добавить значение в список.

Синтаксис:

ДобавитьЗначение(<Значение>, <Строка>)

Англоязычный синоним:

AddValue

Параметры:

Описание:

Метод ДобавитьЗначение добавляет значение и его символьное представление в конец списка. Представление используется в дальнейшем для удобства сортировки и выбора значений из списка (отображается в диалоговом окне выбора).

Пример:

// Объявляем переменные

Перем Список;

Перем ВР;

// процедура выбора значения

Процедура ВыбратьВР()

   Если Список.ВыбратьЗначение(ВР, "Выбор дог: паты") = 1 Тогда

      Расчет = ВР;

      НазваниеВР = Расчет.Код;

   КонецЕсли;

КонецПроцедуры

// инициализация переменных

Список = СоздатьОбъект("СписокЗначений");

Список.ДобавитьЗначение(ВидРасчета.ДоплатаЛроцентом, "Процентом");

Список.ДобавитьЗначение(ВидРасчета.ДоплатаСуммой, "Суммой");

// первоначальное значение

НазваниеВР = Расчет.Код;

ВставитьЗначение

Вставить значение в указанную позицию списка.

Синтаксис:

ВставитьЗначение(<Позиция>, <Знач>, <Строка>, <Колич>)

АНГЛОЯЗЫЧНЫЙ СИНОНИМ:

InsertValue

Параметры:

Описание:

Метод ВставитьЗначение добавляет значение и его символьное представление в указанную позицию списка <Позиция> заданное число раз <Колич>. Представление используется в дальнейшем для удобства сортировки и выбора значений из списка (отображается в диалоговом окне выбора).

Пример:

// Объявляем переменные

Перем Список;

Перем ВР;

// процедура выбора значения

Процедура ВыбратьВР()

   Если Список.ВыбратьЗначение(ВР, "Выбор доплаты") = 1 Тогда

      Расчет = ВР;

      НазваниеВР = Расчет.Код;

   КонецЕсли;

КонецПроцедуры

// инициализация переменных

Список = СоздатьОбъект("СписокЗначений");

Список.ВставитьЗначение(1, Вид Расчета.ДоплатаПроцентом, "Процентом");

Список.ВставитьЗначение(1, Вид Расчета.ДоплатаСуммой, "Суммой");

// первоначальное значение

НазваниеВР = Расчет.Код;

РазмерСписка

Определить размер списка.

Синтаксис:

РазмерСписка()

Англоязычный синоним:

GetListSize

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

Числовое значение — количество элементов в списке.

Описание:

Метод РазмерСписка позволяет определить общее количество элементов в списке.

Пример:

Разм = Список.РазмерСписка();

НайтиЗначение

Определить номер позиции в списке для элемента, имеющего заданное значение.

Синтаксис:

НайтиЗначение(<Знач>)

Англоязычный синоним:

FindValue

Параметры:

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

Номер позиции в списке, где расположено требуемое значение. Если значение не найдено, то — 0.

Описание:

С помощью метода НайтиЗначение можно определить номер позиции в списке для элемента, имеющего значение <Знач>.

Пример:

Позиция = Спис.НайтиЗначение(Вид Расчета.ДоплатаПроцентом);

ПолучитьЗначение

Получить значение элемента по номеру в списке.

Синтаксис:

ПолучитьЗначение(<Позиция>, <Перем>)

Англоязычный синоним:

GetValue

Параметры:

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

Полученное значение из списка.

Описание:

С помощью метода ПолучитьЗначение можно получить значение элемента, находящегося в указанной позиции списка.

Пример:

ОпредПредст = "";

ОпредВид=Спис.ПолучитьЗначение(1, ОпредПредст);

УстановитьЗначение

Установить значение в указанной позиции списка.

Синтаксис:

УстановитьЗначение(<Позиция>, <Знач>, <Строка>, <Колич>)

Англоязычный синоним:

SetValue

Параметры:

Описание:

Метод УстановитьЗначение устанавливает значения и его символьные лредставления, начиная с указанной позиции списка <Позиция> заданное число повторов <Колич>. Представление используется в дальнейшем для удобства сортировки и выбора значений из списка (отображается в диалоговом окне выбора).

Пример:

Спис.УстановитьЗначение(1, ВидРасчета.ДоплатаПроцентом, "Процентом");

Получить

Получить значение элемента по указанному представлению.

Синтаксис:

Получить(<Строка>)

Англоязычный синоним:

Get

Параметры:

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

Полученное значение из списка.

Описание:

Метод Получить возвращает значение по указанному представлению. Если значения с таким представлением нет, то возвращается пустое значение.

Пример:

ОпредЗнач = Спис.Получить("ОпредПредст");

Установить

Установить значение с указанным представлением.

Синтаксис:

Установить(<Строка>, <Знач>)

Англоязычный синоним:

Set

Параметры:

Описание:

Метод Установить устанавливает в списке значение с указанным представлением, если значение с таким представлением уже есть — изменятеся значение, если нет — добавляется в конец списка значение с указанным представлением.

Пример:

Спис.Установить("Процентом", ВидРасчета.ДоплатаПроцентом);

УдалитьЗначение

Удалить значение в указанной позиции списка.

Синтаксис:

УдалитьЗначение(<Позиция>, <Колич>)

Англоязычный синоним:

RemoveValue

Параметры:

Описание:

Метод УдалитьЗначение удаляет <Колич> значений, начиная с указаний позиции <Позиция>.

Пример:

Список.УдалитьЗначение(1, 2);

УдалитьВсе

Удалить все элементы списка.

Синтаксис:

УдалитьВсе()

Англоязычный синоним:

RemoveAll

Описание:

Метод УдалитьВсе удаляет все элементы списка.

Пример:

Список.УдалитьВсе();

Сортировать

Отсортировать список по значениям.

Синтаксис:

Сортировать(<Направление>, <ДокументыПоДате>)

Англоязычный синоним:

Sort

Параметры:

Описание:

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

Пример:

Спис.Сортировать();

СортироватьПоПредставлению

Отсортировать список по представлению.

Синтаксис:

СортироватьПоПредставлению(<Направление>)

Англоязычный синоним:

SortByPresent

Параметры:

Описание:

Метод СортироватьПоПредставлению выполняет сортировку списка по символьному представлению в соответствии с порядком, заданным параметром <Направление>.

Пример:

Спис.СортироватьПоПредставлению();

СдвинутьЗначение

Переместить значение списка значений на новую позицию.

Синтаксис:

СдвинутьЗначение(<Колич>, <НомерПоз>)

Англоязычный синоним:

MoveValue

Параметры:

Описание:

С помощью метода СдвинутьЗначение можно переместить значение списка значений на новую позицию.

Пример:

Спис.СдвинутьЗначение(1, Поз);

Принадлежит

Проверяет вхождение в список значений указанного значения.

Синтаксис:

Принадлежит(<Значение>)

Англоязычный синоним:

Belong

Параметры:

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

Число: 1 — если проверяемое значение входит в список значений; 0 — если не входит.

Описание:

Метод Принадлежит проверяет вхождение в список значений заданного значения. Другими словами, оператор Список.Принадлежит(ВыбДок) проверяет, является ли значение ВыбДок подмножеством списка значений Список.

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

Данный метод оптимизирует проверку принадлежности при массовых последовательных сравнениях, если между сравнениями сам список значений не меняется.

Пример:

Процедура ПроверитьКлиентов(СписокГруппКлиентов)

   // в качестве параметра Процедуры передается СписокЗначений

   // в котором записаны как элементы справочника Клиенты, так и

   // группы этого справочника

   Док = СоздатьОбъект("Документ.Накладная");

   Док.ВыбратьДокументы();

   Пока Док.ПолучитьДокумент() = 1 Цикл

      Если СписокГруппКлиентов.Принадлежит(Док.Клиент) = 1 Тогда

         Сообщить(Док.Клиент.Наименование + " " + Док);

      КонецЕсли;

   КонецЦикла;

КонецПроцедуры

ВыбратьЗначение

Открыть окно для интерактивного выбора значения из списка.

Синтаксис:

ВыбратьЗначение(<Значение>, <3аголовок>, <Позиция> , <Таймаут>, <Спосо6Выбора>)

Англоязычный синоним:

ChooseValue

Параметры:

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

Число: 1 — если выбор произведен (нажата кнопка «ОК»); 0 — если выбор не призведен (нажата кнопка «ОТМЕНА»); -1 (минус единица) — закончилось время <Таймаут> ожидания отклика пользователя.

Описание:

Метод ВыбратьЗначение вызывает диалоговое окно для интерактивного выбора значения из заранее подготовленного списка. Возвращаемое числовое значение: 1 — если выбор произведен, 0 — если нет. Параметр <Значение> указывает на значение того элемента списка, на котором будет установлен курсор при открытии окна выбора. В этот же параметр возвращается выбранное значение. В параметр <Позиция> возвращается номер позиции выбранного значения в списке. Если выбор отменен, то значение параметров не меняются.

Данный метод может использоваться только для переменных созданных функцией СоздатьОбъект.

Пример:

Процедура ВыбратьКредит(ДокКредита)

   Список = СоздатьОбъект("СписокЗначений");

   Рег = СоздатьОбъект("Регистр.ТоварныйКредит");

   Per.УстановитьФильтр(Клиент, );

   Per.ВыбратьИтоги();

   Пока Per.ПолучитьИтог() = 1 Цикл

      Док = Рег.Документ;

      Список.ДобавитьЗначение(Док, "" + Док + " — Остаток = " + Рег.Долг);

   КонецЦикла;

   Если Список.ВыбратьЗначение(ВыбДок, "Выберите кредит") = 1 Тогда

      ДокКредита = ВыбДок;

   КонецЕсли;

КонецПроцедуры

ОтметитьЗначения

Открыть окно для интерактивной пометки значений списка.

Синтаксис:

ОтметитьЗначения(<Значение>, <3аголовок>, <Позиция>, <Таймаут>)

Англоязычный синоним:

CheckValues

Параметры:

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

Число: 1 — если выбор произведен (нажата кнопка «ОК»); 0 — если выбоо не произведен (нажата кнопка «ОТМЕНА»); -1 (минус единица) — закончилось время <Таймаут> ожидания отклика пользователя.

Описание:

Метод ОтметитьЗначения вызывает диалоговое окно для интерактивной пометки значений списка из заранее подготовленного списка.

Возможность выбора значения — это дополнительная возможность, предоставляемая данным методом. Параметр <Значение> указывает на значение того элемента списка, на котором будет установлен курсор при открытии окна выбора. В этот же параметр возвращается последнее выбранное значение- В параметр <Позиция> возвращается номер позиции последнего выбранного значения в списке. Если выбор отменен, то значение параметров не меняются.

Данный метод может использоваться только для переменных созданных функцией СоздатьОбъект.

Пример:

Функция ВыбратьКредит (ДокКредита)

   Перем ВыбДок;

   Список = СоздатьОбъект("СписокЗначений");

   Рег = СоздатьОбъект("Регистр.ТоварныйКредит");

   Рег.УстановитьФильтр(Клиент, );

   Рег.ВыбратьИтоги();

   Пока Рег.ПолучитьИтог() = 1 Цикл

      Док = Рег.Документ;

      Список. ДобавитьЗначение(Док, "" + Док + " — Остаток = " + Рег.Долг);

   КонецЦикла;

   Список.ОтметитьЗначения(ВыбДок, "Выберите кредиты");

   Возврат Список;

КонецФункции

Пометка

Пометить значение списка.

Синтаксис:

Пометка(<Позиция>, <Отметка>}

Англоязычный синоним:

Check

Параметры:

<Позиция> Номер позиции выбранного значения в списке.

<Отметка> Необязательный параметр. Число: 1 — установить отметку; 0 — снять отметку. Если данный параметр опущен, то отметка значения списка не изменяется.

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

Значение метки до выполнения метода. Число: 1 — отметка установлена; 0 _- отметка не установлена.

Описание:

Метод Пометка позволяет пометить указанную позицию списка значений.

Пример:

Функция ОтметитьДокумент(Список, ВыбДок)

   Для Н = 1 по Список.РазмерСписка() Цикл

      Док = Список.ПолучитьЗначение(Н);

      Если Док = ВыбДок Тогда

         Список.Пометка(Н, 1);

      КонецЕсли;

   КонецЦикла;

КонецФункции

ТекущаяСтрока

Установить/определить текущий элемент списка в элементе диалога типа «Список» или «Поле со списком».

Синтаксис:

ТекущаяСтрока(<ИндексСтроки>)

Англоязычный синоним:

CurSel

Параметры:

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

Числовое значение, соответствующее индексу текущей строки поля диалога (до его изменения).

Описание:

Метод ТекущаяСтрока в тексте программного модуля можно использовать синтаксически как функцию или процедуру. Данный метод позволяет установить и/или считать текущее положение курсора в элементе диалога типа «Список» или «Поле со списком».

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

Пример:

Список.ТекущаяСтрока(2);

ИзСтрокиСРазделителями

Заполнить список значениями из переданной строки.

Синтаксис:

ИзСтрокиСРазделителями(<Строка>)

Англоязычный синоним:

FromSeparatedString

Параметры:

Описание:

Метод ИзСтрокиСРазделителями заполняет список значениями из переданной в качестве параметра строки, содержащей строки в двойных кавычках и числа, разделенные запятыми.

Пример:

Спис.ИзСтрокиСРазделителями("5, 6, 12, 68, ""ОпредПредст""");

ВСтрокуСРазделителями

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

Синтаксис:

ВСтрокуСРазделителями()

Англоязычный синоним:

ToSeparatedString

Описание:

Метод ВСтрокуСРазделителями преобразует список значений в строку, содержащую строки в двойных кавычках и числа, разделенные запятыми.

Пример:

СтрПроводка = Спис.ВСтрокуСРазделителями();

Выгрузить

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

Синтаксис:

Выгрузить(<Знач>, <НачПоз>, <Колич>)

Англоязычный синоним:

Unload

Параметры:

Описание:

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

Пример:

СтарСписок.Выгрузить(НовСписок);

---

---