Gerenciar anotações em suplementos do Excel usando a API JavaScript do Excel

Use anotações quando precisar de anotações simples baseadas em células em uma pasta de trabalho. Este artigo mostra como adicionar, mostrar, editar, redimensionar e excluir anotações usando a API JavaScript do Excel.

Se você precisar de threads de conversa com respostas e menções, consulte Gerenciar comentários em suplementos do Excel usando a API JavaScript do Excel. Para comparar os dois sistemas de anotações no Excel, confira A diferença entre comentários encadeados e anotações.

O que é possível fazer com as anotações

Use as APIs de anotação do Excel para:

• Adicionar uma anotação a uma única célula.
• Mostrar ou ocultar o conteúdo das anotações.
• Atualize o texto da anotação.
• Alterar o tamanho da anotação.
• Apagar uma anotação.

As anotações estão vinculadas a uma célula individual. Qualquer pessoa que visualize a pasta de trabalho com permissões suficientes poderá exibir uma anotação. As anotações em uma pasta de trabalho são rastreadas pela Workbook.notes propriedade. Isso inclui anotações criadas por usuários e também anotações criadas pelo seu suplemento. A Workbook.notes propriedade é um objeto NoteCollection que contém uma coleção de objetos Note . As anotações também podem ser acessadas no nível da planilha .

Adicionar uma anotação

Use o NoteCollection.add método para adicionar anotações a uma pasta de trabalho. Esse método usa dois parâmetros:

• cellAddress: a célula em que a nota é adicionada. Pode ser uma cadeia de caracteres ou um objeto de intervalo . O intervalo deve ser uma única célula.
• content: o conteúdo da nota, como uma cadeia de caracteres.

O exemplo de código a seguir mostra como adicionar uma anotação à célula selecionada em uma planilha.

await Excel.run(async (context) => {
    // This function adds a note to the selected cell.
    const selectedRange = context.workbook.getSelectedRange();

    // Note that an InvalidArgument error is thrown if multiple cells are selected.
    context.workbook.notes.add(selectedRange, "The first note.");
    await context.sync();
});

Alterar visibilidade da nota

Por padrão, o conteúdo de uma anotação fica oculto, a menos que um usuário passe o mouse sobre a célula com a anotação ou defina a pasta de trabalho para exibir anotações. Para exibir uma nota, use a propriedade Note.visible . O exemplo de código a seguir mostra como alterar a visibilidade de uma anotação.

await Excel.run(async (context) => {
    // This function sets the note on cell A1 to visible.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const firstNote = sheet.notes.getItem("A1");

    firstNote.visible = true;
    await context.sync();
});

Editar o conteúdo de uma anotação

Para editar o conteúdo de uma nota, use a propriedade Note.content . O exemplo a seguir mostra como alterar o conteúdo da primeira nota no NoteCollection.

await Excel.run(async (context) => {
    // This function changes the content in the first note.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const note = sheet.notes.getItemAt(0);

    note.content = "Changing the content of the first note.";
    await context.sync();
});

Alterar o tamanho de uma anotação

Para aumentar ou diminuir as notas, use as propriedades Nota.altura e Nota.largura .

O exemplo a seguir mostra como definir o tamanho da primeira nota no NoteCollectionarquivo .

await Excel.run(async (context) => {
    // This function changes the height and width of the first note.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const note = sheet.notes.getItemAt(0);

    note.width = 400;
    note.height = 200;

    await context.sync();
});

Excluir uma anotação

Para excluir uma anotação, use o método Note.delete . O exemplo a seguir mostra como excluir a observação anexada à célula A2.

await Excel.run(async (context) => {
    // This function deletes the note from cell A2.
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const note = sheet.notes.getItem("A2");

    note.delete();
    await context.sync();
});

Confira também

• Principais conceitos de modelo de objeto do Excel para Suplementos do Office
• Gerenciar pastas de trabalho do Excel com a API JavaScript do Excel
• Gerenciar comentários em suplementos do Excel usando a API JavaScript do Excel
• Inserir comentários e anotações no Excel