Основная страница

 

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


 

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

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

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

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

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

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

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

Пример:

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

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

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

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

Синтаксис:

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

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

AddValue

Параметры:

<Значение>

Выражение со значением, которое добавляется в список.

<Строка>

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

Описание:

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

Пример:

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

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

Перем ВР;

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

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

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

      Расчет = ВР;

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

   КонецЕсли;

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

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

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

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

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

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

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

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

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

Синтаксис:

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

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

InsertValue

Параметры:

<Позиция>

Числовое выражение — номер позиции в списке, начиная с которого будут вставлены новые значения. Номер позиции может быть от 1 до РазмерСписка() + 1.

<Знач>

Выражение со значением, которое добавляется в список.

<Строка>

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

<Колич>

Необязательный параметр. Числовое выражение — количество повторов. По умолчанию — 1.

Описание:

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

Пример:

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

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

Перем ВР;

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

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

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

      Расчет = ВР;

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

   КонецЕсли;

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

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

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

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

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

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

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

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

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

Синтаксис:

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

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

GetListSize

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

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

Описание:

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

Пример:

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

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

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

Синтаксис:

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

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

FindValue

Параметры:

<Знач>

Выражение со значением, которое необходимо найти в списке.

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

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

Описание:

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

Пример:

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

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

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

Синтаксис:

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

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

GetValue

Параметры:

<Позиция>

Числовое выражение — номер элемента в списке, значение которого будет возвращено. Номер позиции может быть от 1 до количества элементов в списке.

<Перем>

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

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

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

Описание:

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

Пример:

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

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

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

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

Синтаксис:

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

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

SetValue

Параметры:

<Позиция>

Числовое выражение — номер позиции в списке, начиная с которого будут установлены новые значения, т. е. «старые» будут заменены. Номер позиции может быть от 1 до РазмерСписка+1.

<Знач>

Выражение со значением, которое добавляется в список.

<Строка>

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

<Колич>

Необязательный параметр. Числовое выражение — количество повторов. По умолчанию — 1.

Описание:

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

Пример:

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

Получить

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

Синтаксис:

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

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

Get

Параметры:

<Строка>

Строковое выражение, содержащее задаваемое символьное представление получаемого значения.

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

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

Описание:

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

Пример:

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

Установить

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

Синтаксис:

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

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

Set

Параметры:

<Строка>

Строковое выражение, содержащее задаваемое символьное представление добавляемого значения.

<Знач>

Выражение со значением, которое добавляется в список.

Описание:

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

Пример:

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

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

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

Синтаксис:

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

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

RemoveValue

Параметры:

<Позиция>

Числовое выражение — номер позиции в списке, начиная с которой будут удалены значения. Номер позиции может быть от 1 до количества элементов в списке.

<Колич>

Необязательный параметр. Числовое выражение — количество повторов. По умолчанию — 1.

Описание:

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

Пример:

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

УдалитьВсе

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

Синтаксис:

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

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

RemoveAll

Описание:

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

Пример:

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

Сортировать

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

Синтаксис:

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

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

Sort

Параметры:

<Направление>

Необязательный параметр. Числовое выражение. Если — 0, то сортировка по возрастанию. Если не 0 то сортировка по убыванию. Значение по умолчанию — 0.

<ДокументыПоДате>

Необязательный параметр. Имеет смысл только в том случае, если значениями списка значений являются документы. В этом случае можно задавать сортировку документов по их хронологии. Число: 1 — сортировка по хронологии документов; 0 — нет. Значение по умолчанию — 0.

Описание:

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

Пример:

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

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

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

Синтаксис:

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

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

SortByPresent

Параметры:

<Направление>

Необязательный параметр. Числовое выражение. Если — 0, то сортировка производится по возрастанию. Если отлично от 0, то сортировка по убыванию.

Описание:

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

Пример:

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

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

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

Синтаксис:

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

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

MoveValue

Параметры:

<Колич>

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

<НомерПоз>

Номер позиции, значение которой надо переместить.

Описание:

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

Пример:

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

Принадлежит

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

Синтаксис:

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

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

Belong

Параметры:

<Значение>

Значение, проверяемое на вхождение в список значений.

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

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

Описание:

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

      КонецЕсли;

   КонецЦикла;

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

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

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

Синтаксис:

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

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

ChooseValue

Параметры:

<Значение>

Идентификатор переменной, куда помещается значение — результат выбора.

<3аголовок>

Строковое выражение, значение которого отображается в заголовке диалогового окна. Может использоваться для подсказки пользователю.

<Позиция>

Идентификатор переменной, куда помещается номер позиции выбранного значения в списке.

<Таймаут>

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

<СпособВыбора>

Необязательный параметр. Числовое выражение, значение которого задает способ выбора значения:

0 — в виде диалога;

1 — выбор производится в виде меню, которое подстраивается по месту текущего элемента диалога или ячейки таблицы, откуда вызвано;

2 — выбор маленьким списком (список похож на выбор значения перечисления), также привязанным к позиции элемента диалога.

Значение по умолчанию — 0.

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

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

Описание:

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

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

Пример:

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

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

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

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

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

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

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

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

   КонецЦикла;

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

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

   КонецЕсли;

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

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

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

Синтаксис:

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

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

CheckValues

Параметры:

<Значение>

Идентификатор переменной, куда помещается значение — результат выбора.

<Загoлoвoк>

Строковое выражение, значение которого отображается в заголовке диалогового окна. Может использоваться для подсказки пользователю.

<Пoзиция>

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

<Tаймayт>

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

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

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

Описание:

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

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

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

Пример:

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

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

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

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

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

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

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

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

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

   КонецЦикла;

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

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

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

Пометка

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

Синтаксис:

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

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

Check

Параметры:

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

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

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

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

Описание:

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

Пример:

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

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

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

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

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

      КонецЕсли;

   КонецЦикла;

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

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

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

Синтаксис:

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

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

CurSel

Параметры:

<ИндексСтроки>

Необязательный параметр. Числовое выражение с задаваемым индексом строки для элемента диалога типа «Список» или «Поле со списком», на которое требуется установить курсор. Если параметр не задан, то положение курсора в поле диалога не меняется.

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

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

Описание:

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

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

Пример:

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

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

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

Синтаксис:

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

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

FromSeparatedString

Параметры:

<Строка>

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

Описание:

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

Пример:

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

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

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

Синтаксис:

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

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

ToSeparatedString

Описание:

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

Пример:

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

Выгрузить

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

Синтаксис:

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

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

Unload

Параметры:

<Знач>

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

<НачПоз>

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

<Колич>

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

Описание:

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

Пример:

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



Перейти  к оглавлению: Описание встроенного языка

Hosted by uCoz