Office.CustomProperties interface

Пакет:

outlook

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

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

Комментарии

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

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

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

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

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

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

Применимый режим Outlook: Compose или чтение

Используется

• Office.AppointmentCompose: loadCustomPropertiesAsync
• Office.AppointmentRead: loadCustomPropertiesAsync
• Office.LoadedMessageCompose: loadCustomPropertiesAsync
• Office.LoadedMessageRead: loadCustomPropertiesAsync
• Office.MessageCompose: loadCustomPropertiesAsync
• Office.MessageRead: loadCustomPropertiesAsync

Методы

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: Compose или чтение

Важно! В классической версии Outlook для Windows настраиваемые свойства, сохраненные в элементе почты в режиме чтения, остаются доступными во время пересылки элемента.

Примеры

// 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 = (document.getElementById("get-property-name") as HTMLInputElement).value;
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: Compose или чтение

Важно! В классической версии Outlook для Windows настраиваемые свойства, сохраненные в элементе почты в режиме чтения, остаются доступными во время пересылки элемента.

Примеры

// 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

Комментарии

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

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

Применимый режим Outlook: Compose или чтение

Важно! Этотremove метод не поддерживается в сообщениях, которые в настоящее время загружаются с помощью этого методаloadItemByIdAsync. Дополнительные сведения см. в статье "Активация надстройки 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 = (document.getElementById("remove-property-name") as HTMLInputElement).value;
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: Compose или чтение

Примеры

// 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: Compose или чтение

set(name, value)

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

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

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

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

Параметры

name

string

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

value

string

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

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

void

Комментарии

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

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

Применимый режим Outlook: Compose или чтение

Важно! Этотset метод не поддерживается в сообщениях, которые в настоящее время загружаются с помощью этого методаloadItemByIdAsync. Дополнительные сведения см. в статье "Активация надстройки 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 = (document.getElementById("set-property-name") as HTMLInputElement).value;
const propertyValue = (document.getElementById("property-value") as HTMLInputElement).value;
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);