Office.CustomProperties interface

Ссылка

Пакет:: outlook

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

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

Пользовательские свойства, сохраненные в режиме создания, не передаются получателям почтового элемента. При отправке сообщения или встречи с пользовательскими свойствами доступ к его свойствам можно получить из элемента в папке Отправленные. Если вы хотите сделать пользовательские данные доступными для получателей, рассмотрите возможность использования 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

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

Примеры

// 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 = $("#propertyName").val();
const propertyValue = customProps.get(propertyName);
$("#propertyValue").val(propertyValue);
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

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

remove(name)

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

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

remove(name: string): void;

Параметры

name: string

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

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

void

Примеры

// 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 = $("#propertyName").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: создание или чтение

Примеры

// The following JavaScript code sample shows how to asynchronously use
// the loadCustomPropertiesAsync method to load custom properties that
// are specific to the current item, and the saveAsync method to save
// these to the mail item. After loading the custom properties,
// the code sample uses the get method to read the custom property myProp,
// the set method to write the custom property myProp, and then finally
// calls the saveAsync method to save the custom properties.

// The initialize function is required for all add-ins.
Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        const item = Office.context.mailbox.item;
        item.loadCustomPropertiesAsync(customPropsCallback);
    });
};

function customPropsCallback(asyncResult) {
    const customProps = asyncResult.value;
    const myProp = customProps.get("myProp");
    console.log("myProp: " + myProp); // First run on current item will return `undefined`.

    // Set myProp custom property.
    customProps.set("myProp", "value");
    customProps.saveAsync(saveCallback);
}

function saveCallback(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error(asyncResult.error.message);
    }
    else {
        // Async call to save custom properties completed.
        // Proceed to do the appropriate for your add-in.
    }
}

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

Примеры

// 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 = $("#propertyName").val();
const propertyValue = $("#propertyValue").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)

Параметры

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

Комментарии

Примеры

Обратная связь

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