Поделиться через


Office.CustomProperties interface

Объект CustomProperties представляет пользовательские свойства, относящиеся к конкретному почтовому элементу и относящиеся к надстройке Outlook. Например, может потребоваться, чтобы надстройка сохранила некоторые данные, относящиеся к текущему сообщению, которое активировало надстройку. Если пользователь повторно откроет то же сообщение в будущем и снова активирует надстройку, надстройка сможет получить данные, сохраненные в качестве пользовательских свойств.

Дополнительные сведения см CustomProperties. в статье Получение и настройка метаданных надстройки для надстройки Outlook.

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

При использовании пользовательских свойств в надстройке имейте в виду следующее:

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

  • Максимальная длина CustomProperties объекта JSON составляет 2500 символов.

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

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

Методы

get(name)

Возвращает значение указанного настраиваемого свойства.

getAll()

Возвращает объект со всеми настраиваемыми свойствами в коллекции пар "имя-значение". Ниже приведены эквивалентные данные.

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

Вы можете выполнить итерацию по объекту словаря, чтобы обнаружить все names и values.

remove(name)

Удаляет указанное свойство из коллекции настраиваемых свойств.

Чтобы свойство было удалено безвозвратно, вызовите метод saveAsync объекта CustomProperties.

saveAsync(callback, asyncContext)

Сохраняет пользовательские свойства в сообщении или встрече.

Необходимо вызвать метод saveAsync, чтобы сохранить все изменения, внесенные с помощью метода set или remove объекта CustomProperties. Сохранение — асинхронное действие.

Рекомендуется, чтобы функция обратного вызова проверяла и обрабатывала ошибки из saveAsync. В частности, надстройка чтения может активироваться, когда подключенный пользователь открыл форму чтения, а затем отключился. Если надстройка вызывает saveAsync в отключенном состоянии, saveAsync возвращает ошибку. Функция обратного вызова должна соответствующим образом обрабатывать эту ошибку.

saveAsync(asyncContext)

Сохраняет пользовательские свойства в сообщении или встрече.

Необходимо вызвать метод saveAsync, чтобы сохранить все изменения, внесенные с помощью метода set или remove объекта CustomProperties. Сохранение — асинхронное действие.

Рекомендуется, чтобы функция обратного вызова проверяла и обрабатывала ошибки из saveAsync. В частности, надстройка чтения может активироваться, когда подключенный пользователь открыл форму чтения, а затем отключился. Если надстройка вызывает saveAsync в отключенном состоянии, saveAsync возвращает ошибку. Функция обратного вызова должна соответствующим образом обрабатывать эту ошибку.

set(name, value)

Присваивает указанному свойству заданное значение.

Метод set присваивает указанному свойству заданное значение. Чтобы убедиться, что заданное свойство и значение сохраняются в почтовом элементе saveAsync , необходимо вызвать метод .

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

Сведения о методе

get(name)

Возвращает значение указанного настраиваемого свойства.

get(name: string): any;

Параметры

name

string

Имя возвращаемого настраиваемого свойства.

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

any

Значение указанного настраиваемого свойства.

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#get-property-name").val();
const propertyValue = customProps.get(propertyName);
console.log(`The value of custom property "${propertyName}" is "${propertyValue}".`);

getAll()

Возвращает объект со всеми настраиваемыми свойствами в коллекции пар "имя-значение". Ниже приведены эквивалентные данные.

customProps.get("name")

var dictionary = customProps.getAll(); dictionary["name"]

Вы можете выполнить итерацию по объекту словаря, чтобы обнаружить все names и values.

getAll(): any;

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

any

Объект со всеми настраиваемыми свойствами в коллекции пар "имя-значение".

Комментарии

[ Набор API: Почтовый ящик 1.9 ]

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

let allCustomProps;
if (Office.context.requirements.isSetSupported("Mailbox", "1.9")) {
  allCustomProps = customProps.getAll();
} else {
  allCustomProps = customProps["rawData"];
}

console.log(allCustomProps);

remove(name)

Удаляет указанное свойство из коллекции настраиваемых свойств.

Чтобы свойство было удалено безвозвратно, вызовите метод saveAsync объекта CustomProperties.

remove(name: string): void;

Параметры

name

string

Объект name удаляемого свойства.

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

void

Комментарии

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#remove-property-name").val();
customProps.remove(propertyName);
console.log(`Custom property "${propertyName}" removed.`);

saveAsync(callback, asyncContext)

Сохраняет пользовательские свойства в сообщении или встрече.

Необходимо вызвать метод saveAsync, чтобы сохранить все изменения, внесенные с помощью метода set или remove объекта CustomProperties. Сохранение — асинхронное действие.

Рекомендуется, чтобы функция обратного вызова проверяла и обрабатывала ошибки из saveAsync. В частности, надстройка чтения может активироваться, когда подключенный пользователь открыл форму чтения, а затем отключился. Если надстройка вызывает saveAsync в отключенном состоянии, saveAsync возвращает ошибку. Функция обратного вызова должна соответствующим образом обрабатывать эту ошибку.

saveAsync(callback: (asyncResult: Office.AsyncResult<void>) => void, asyncContext?: any): void;

Параметры

callback

(asyncResult: Office.AsyncResult<void>) => void

После завершения метода функция, переданная в callback параметре, вызывается с одним параметром типа Office.AsyncResult.

asyncContext

any

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

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

void

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Важно! В Outlook в Windows пользовательские свойства, сохраненные в режиме создания, сохраняются только после закрытия создаваемого элемента или после Office.context.mailbox.item.saveAsync вызова.

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

customProps.saveAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error(`saveAsync failed with message ${result.error.message}`);
    return;
  }

  console.log(`Custom properties saved with status: ${result.status}`);
});

saveAsync(asyncContext)

Сохраняет пользовательские свойства в сообщении или встрече.

Необходимо вызвать метод saveAsync, чтобы сохранить все изменения, внесенные с помощью метода set или remove объекта CustomProperties. Сохранение — асинхронное действие.

Рекомендуется, чтобы функция обратного вызова проверяла и обрабатывала ошибки из saveAsync. В частности, надстройка чтения может активироваться, когда подключенный пользователь открыл форму чтения, а затем отключился. Если надстройка вызывает saveAsync в отключенном состоянии, saveAsync возвращает ошибку. Функция обратного вызова должна соответствующим образом обрабатывать эту ошибку.

saveAsync(asyncContext?: any): void;

Параметры

asyncContext

any

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

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

void

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

set(name, value)

Присваивает указанному свойству заданное значение.

Метод set присваивает указанному свойству заданное значение. Чтобы убедиться, что заданное свойство и значение сохраняются в почтовом элементе saveAsync , необходимо вызвать метод .

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

set(name: string, value: string): void;

Параметры

name

string

Имя свойства, которому присваивается значение.

value

string

Значение, присваиваемое свойству.

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

void

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: чтение элемента

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/15-item-custom-properties/load-set-get-save.yaml

const propertyName = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);