Office.CustomProperties interface

Ссылка

Пакет:: outlook

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

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

Пользовательские свойства, сохраненные в режиме создания, не передаются получателям почтового элемента. При отправке сообщения или встречи с пользовательскими свойствами доступ к его свойствам можно получить из элемента в папке Отправленные. Если вы хотите сделать пользовательские данные доступными для получателей, рассмотрите возможность использования InternetHeaders .
Максимальная длина CustomProperties объекта JSON составляет 2500 символов.
Outlook для Mac не кэшируют пользовательские свойства. Если сеть пользователя выходит из строя, почтовые надстройки не смогут получить доступ к своим настраиваемым свойствам.

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

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

Методы

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

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

Примеры

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

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

Примеры

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

Важно! Метод 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 = $("#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

Важно! В 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(asyncContext?: any): void;

Параметры

asyncContext: any

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

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

void

set(name, value)

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

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

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

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

Параметры

name: string

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

value: string

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

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

void

Важно! Метод 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 = $("#set-property-name").val();
const propertyValue = $("#property-value").val();
customProps.set(propertyName, propertyValue);
console.log(`Custom property "${propertyName}" set to value "${propertyValue}".`);

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

Office.CustomProperties interface

Комментарии

Методы

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

get(name)

Параметры

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

Комментарии

Примеры

getAll()

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

Комментарии

Примеры

remove(name)

Параметры

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

Комментарии

Примеры

saveAsync(callback, asyncContext)

Параметры

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

Комментарии

Примеры

saveAsync(asyncContext)

Параметры

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

Комментарии

set(name, value)

Параметры

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

Комментарии

Примеры

Дополнительные ресурсы