Word.CustomPropertyCollection class

Pacote:

word

Contém a coleção de Word. Objetos CustomProperty.

Extends

OfficeExtension.ClientObject

Comentários

[ Conjunto de API: WordApi 1.3 ]

Propriedades

context	O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.
items	Obtém os itens filhos carregados nesta coleção.

Métodos

add(key, value)	Cria uma nova propriedade personalizada ou define uma existente.
deleteAll()	Exclui todas as propriedades personalizadas nesta coleção.
getCount()	Obtém a contagem das propriedades personalizadas.
getItem(key)	Obtém um objeto de propriedade personalizada por sua chave, que diferencia maiúsculas de minúsculas. Gerará um ItemNotFound erro se a propriedade personalizada não existir.
getItemOrNullObject(key)	Obtém um objeto de propriedade personalizada por sua chave, que diferencia maiúsculas de minúsculas. Se a propriedade personalizada não existir, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.
load(options)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNames)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
load(propertyNamesAndPaths)	Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.
toJSON()	Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que é passado para ele.) Considerando que o objeto original Word.CustomPropertyCollection é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado como Word.Interfaces.CustomPropertyCollectionData) que contém uma matriz de "itens" com cópias rasas de quaisquer propriedades carregadas dos itens da coleção.
track()	Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação para context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, você precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.
untrack()	Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará chamar context.sync() antes que a versão da memória entre em vigor.

Detalhes da propriedade

context

O contexto de solicitação associado ao objeto. Isso conecta o processo do suplemento ao processo do aplicativo host do Office.

context: RequestContext;

Valor da propriedade

Word.RequestContext

items

Obtém os itens filhos carregados nesta coleção.

readonly items: Word.CustomProperty[];

Valor da propriedade

Word.CustomProperty[]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/30-properties/read-write-custom-document-properties.yaml

await Word.run(async (context) => {
    const properties = context.document.properties.customProperties;
    properties.load("key,type,value");

    await context.sync();
    for (let i = 0; i < properties.items.length; i++)
        console.log("Property Name:" + properties.items[i].key + "; Type=" + properties.items[i].type + "; Property Value=" + properties.items[i].value);
});

Detalhes do método

add(key, value)

Cria uma nova propriedade personalizada ou define uma existente.

add(key: string, value: any): Word.CustomProperty;

Parâmetros

key

string

Obrigatório. A chave da propriedade personalizada, que é insensibilidade de maiúsculas de minúsculas.

value

any

Obrigatório. O valor da propriedade personalizada.

Retornos

Word.CustomProperty

Comentários

[ Conjunto de API: WordApi 1.3 ]

Exemplos

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/30-properties/read-write-custom-document-properties.yaml

await Word.run(async (context) => {
    context.document.properties.customProperties.add("Numeric Property", 1234);

    await context.sync();
    console.log("Property added");
});

...

await Word.run(async (context) => {
    context.document.properties.customProperties.add("String Property", "Hello World!");

    await context.sync();
    console.log("Property added");
});

deleteAll()

Exclui todas as propriedades personalizadas nesta coleção.

deleteAll(): void;

Retornos

void

Comentários

[ Conjunto de API: WordApi 1.3 ]

getCount()

Obtém a contagem das propriedades personalizadas.

getCount(): OfficeExtension.ClientResult<number>;

Retornos

OfficeExtension.ClientResult<number>

Comentários

[ Conjunto de API: WordApi 1.3 ]

getItem(key)

Obtém um objeto de propriedade personalizada por sua chave, que diferencia maiúsculas de minúsculas. Gerará um ItemNotFound erro se a propriedade personalizada não existir.

getItem(key: string): Word.CustomProperty;

Parâmetros

key

string

A chave que identifica o objeto de propriedade personalizado.

Retornos

Word.CustomProperty

Comentários

[ Conjunto de API: WordApi 1.3 ]

getItemOrNullObject(key)

Obtém um objeto de propriedade personalizada por sua chave, que diferencia maiúsculas de minúsculas. Se a propriedade personalizada não existir, esse método retornará um objeto com sua isNullObject propriedade definida como true. Para obter mais informações, consulte *Métodos e propriedades orNullObject.

getItemOrNullObject(key: string): Word.CustomProperty;

Parâmetros

key

string

Obrigatório. A chave que identifica o objeto de propriedade personalizado.

Retornos

Word.CustomProperty

Comentários

[ Conjunto de API: WordApi 1.3 ]

load(options)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(options?: Word.Interfaces.CustomPropertyCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.CustomPropertyCollection;

Parâmetros

options

Word.Interfaces.CustomPropertyCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions

Fornece opções para quais propriedades do objeto carregar.

Retornos

Word.CustomPropertyCollection

load(propertyNames)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNames?: string | string[]): Word.CustomPropertyCollection;

Parâmetros

propertyNames

string | string[]

Uma cadeia de caracteres delimitada por vírgulas ou uma matriz de cadeias de caracteres que especificam as propriedades a serem carregadas.

Retornos

Word.CustomPropertyCollection

load(propertyNamesAndPaths)

Coloca um comando na fila para carregar as propriedades especificadas do objeto. Você deve chamar context.sync() antes de ler as propriedades.

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.CustomPropertyCollection;

Parâmetros

propertyNamesAndPaths

OfficeExtension.LoadOption

propertyNamesAndPaths.select é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades a serem carregadas e propertyNamesAndPaths.expand é uma cadeia de caracteres delimitada por vírgulas que especifica as propriedades de navegação a serem carregadas.

Retornos

Word.CustomPropertyCollection

toJSON()

Substitui o método JavaScript toJSON() para fornecer uma saída mais útil quando um objeto de API é passado para JSON.stringify(). (JSON.stringifypor sua vez, chama o toJSON método do objeto que é passado para ele.) Considerando que o objeto original Word.CustomPropertyCollection é um objeto API, o toJSON método retorna um objeto JavaScript simples (digitado como Word.Interfaces.CustomPropertyCollectionData) que contém uma matriz de "itens" com cópias rasas de quaisquer propriedades carregadas dos itens da coleção.

toJSON(): Word.Interfaces.CustomPropertyCollectionData;

Retornos

Word.Interfaces.CustomPropertyCollectionData

track()

Acompanha o objeto para ajuste automático com base nas alterações adjacentes no documento. Essa chamada é uma abreviação para context.trackedObjects.add(thisObject). Se você estiver usando esse objeto entre .sync chamadas e fora da execução sequencial de um lote ".run" e receber um erro "InvalidObjectPath" ao definir uma propriedade ou invocar um método no objeto, você precisará adicionar o objeto à coleção de objetos rastreados quando o objeto foi criado pela primeira vez. Se esse objeto fizer parte de uma coleção, você também deverá acompanhar a coleção pai.

track(): Word.CustomPropertyCollection;

Retornos

Word.CustomPropertyCollection

untrack()

Libere a memória associada a este objeto, se ele já tiver sido rastreado anteriormente. Essa chamada é abreviada para context.trackedObjects.remove(thisObject). Ter muitos objetos rastreados desacelera o aplicativo host, por isso, lembre-se de liberar todos os objetos adicionados após usá-los. Você precisará chamar context.sync() antes que a versão da memória entre em vigor.

untrack(): Word.CustomPropertyCollection;

Retornos

Word.CustomPropertyCollection