Gestionar propiedades del documento con Node.js a través de C++

Introducción

Microsoft Excel proporciona la capacidad de agregar propiedades a los archivos de hojas de cálculo. Estas propiedades del documento proporcionan información útil y se dividen en 2 categorías como se detalla a continuación.

• Propiedades predeterminadas del sistema (integradas): Las propiedades integradas contienen información general sobre el documento, como el título del documento, el nombre del autor, estadísticas del documento, entre otros.
• Propiedades definidas por el usuario (personalizadas): Propiedades personalizadas definidas por el usuario final en forma de par nombre-valor.

El punto más importante a tener en cuenta sobre las propiedades integradas y personalizadas es que las propiedades integradas se pueden acceder y modificar, pero no crear ni eliminar. Sin embargo, las propiedades personalizadas se pueden crear y gestionar.

Cómo administrar propiedades de documento utilizando Microsoft Excel

Microsoft Excel te permite gestionar las propiedades del documento de los archivos de Excel de forma WYSIWYG. Por favor, sigue los pasos a continuación para abrir el diálogo de Propiedades en Excel 2016.

1. Desde el menú Archivo, seleccione Información.

Seleccionar menú Información

1. Haga clic en el encabezado Propiedades y seleccione “Propiedades avanzadas”.

Haciendo clic en la selección de Propiedades avanzadas

1. Administre las propiedades del documento del archivo.

Cuadro de propiedades
En el cuadro de propiedades, hay pestañas diferentes, como General, Resumen, Estadísticas, Contenidos y Aduanas. Cada pestaña ayuda a configurar diferentes tipos de información relacionada con el archivo. La pestaña Aduanas se usa para gestionar propiedades personalizadas.

Cómo trabajar con las propiedades del documento usando Aspose.Cells

Los desarrolladores pueden gestionar dinámicamente las propiedades del documento usando las APIs de Aspose.Cells. Esta característica ayuda a los desarrolladores a almacenar información útil junto con el archivo, como cuándo se recibió el archivo, se procesó, se marcó con la hora, y así sucesivamente.

Las APIs Aspose.Cells for Node.js via C++ escriben directamente la información sobre la API y el número de versión en los documentos de salida. Por ejemplo, al convertir un Documento a PDF, Aspose.Cells for Node.js via C++ llena el campo Aplicación con el valor ‘Aspose.Cells’ y el campo Productor PDF con el valor, por ejemplo, ‘Aspose.Cells v17.9’.

Ten en cuenta que no puedes instruir a Aspose.Cells for Node.js via C++ para cambiar o eliminar esta información de los Documentos de salida.

Cómo acceder a las propiedades del documento

Las APIs de Aspose.Cells soportan ambos tipos de propiedades del documento, integradas y personalizadas. La clase Workbook de Aspose.Cells representa un archivo de Excel y, como un archivo de Excel, la clase Workbook puede contener múltiples hojas de cálculo, cada una representada por la clase Worksheet mientras que la colección de hojas de cálculo está representada por la clase WorksheetCollection.

Utiliza WorksheetCollection para acceder a las propiedades del documento del archivo como se describe a continuación.

• Para acceder a las propiedades de documento integradas, use WorksheetCollection.getBuiltInDocumentProperties().
• Para acceder a las propiedades de documento personalizadas, use WorksheetCollection.getCustomDocumentProperties().

Tanto WorksheetCollection.getBuiltInDocumentProperties() como WorksheetCollection.getCustomDocumentProperties() devuelven la instancia de Aspose.Cells.Properties.DocumentPropertyCollection. Esta colección contiene Aspose.Cells.Properties.DocumentProperty objetos, cada uno de los cuales representa una sola propiedad del documento, ya sea integrada o personalizada.

Depende del requisito de la aplicación cómo acceder a una propiedad; es decir, usando el índice o el nombre de la propiedad desde DocumentPropertyCollection como se demuestra en el ejemplo a continuación.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
const filePath = path.join(dataDir, "sample-document-properties.xlsx");
// Instantiate a Workbook object
// Open an Excel file
const workbook = new AsposeCells.Workbook(filePath);

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Accessing a custom document property by using the property name
const customProperty1 = customProperties.get("ContentTypeId");
console.log(`${customProperty1.getName()} ${customProperty1.getValue()}`);

// Accessing the same custom document property by using the property index
const customProperty2 = customProperties.get(0);
console.log(`${customProperty2.getName()} ${customProperty2.getValue()}`);

La clase Aspose.Cells.Properties.DocumentProperty permite recuperar el nombre, valor y tipo de la propiedad del documento:

• Para obtener el nombre de la propiedad, use DocumentProperty.getName().
• Para obtener el valor de la propiedad, usa DocumentProperty.getValue(). DocumentProperty.getValue() devuelve el valor como un Objeto.
• Para obtener el tipo de propiedad, usa DocumentProperty.getType(). Esto devuelve uno de los valores de la enumeración PropertyType. Después de obtener el tipo de propiedad, usa uno de los métodos DocumentProperty.ToXXX para obtener el valor del tipo apropiado en lugar de usar DocumentProperty.getValue(). Los métodos DocumentProperty.ToXXX se describen en la tabla a continuación.

La clase DocumentProperty también proporciona un conjunto de métodos que devuelven los valores de otros tipos de datos.

Nombre de Miembro	Descripción	Método ToXXX
Boolean	El tipo de dato de propiedad es Booleano	ABoolean
Date	El tipo de datos de la propiedad es DateTime. Tenga en cuenta que Microsoft Excel solo almacena la parte de la fecha, no se puede almacenar la hora en una propiedad personalizada de este tipo	ToDateTime
Float	El tipo de datos de la propiedad es Double	ToDouble
Number	El tipo de datos de la propiedad es Int32	ToInt
String	El tipo de dato de la propiedad es string	ToString

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
const filePath = path.join(dataDir, "sample-document-properties.xlsx");
// Instantiate a Workbook object
// Open an Excel file
const workbook = new AsposeCells.Workbook(filePath);

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Accessing a custom document property
const customProperty1 = customProperties.get(0);

// Storing the value of the document property as an object
const objectValue = customProperty1.getValue();

// Accessing a custom document property
const customProperty2 = customProperties.get(1);

// Checking the type of the document property and then storing the value of the
// document property according to that type
if (customProperty2.getType() === AsposeCells.PropertyType.String) {
const value = customProperty2.getValue().toString();
console.log(`${customProperty2.getName()} : ${value}`);
}

Cómo agregar o eliminar propiedades de documento personalizadas

Como hemos descrito anteriormente al principio de este tema, los desarrolladores no pueden agregar o eliminar propiedades integradas porque estas propiedades están definidas por el sistema, pero es posible agregar o eliminar propiedades personalizadas porque estas son definidas por el usuario.

Cómo agregar propiedades personalizadas

Las APIs de Aspose.Cells han expuesto el método add(string, string) para la clase CustomDocumentPropertyCollection con el fin de agregar propiedades personalizadas a la colección. El método add(string, string) añade la propiedad al archivo de Excel y devuelve una referencia para la nueva propiedad del documento como un objeto Aspose.Cells.Properties.DocumentProperty.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
// Instantiate a Workbook object
// Open an Excel file
const workbook = new AsposeCells.Workbook(path.join(dataDir, "sample-document-properties.xlsx"));

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Adding a custom document property to the Excel file
customProperties.add("Publisher", "Aspose");

// Saving resultant spreadsheet
workbook.save(path.join(dataDir, "out_sample-document-properties.xlsx"));

Cómo configurar la propiedad personalizada de “Vínculo con contenido”

Para crear una propiedad personalizada vinculada al contenido de un rango dado, llama al método CustomDocumentPropertyCollection.addLinkToContent(string, string) y pasa el nombre de la propiedad y la fuente. Puedes verificar si una propiedad está configurada como vinculada al contenido usando la propiedad DocumentProperty.isLinkedToContent(). Además, también es posible obtener el rango fuente usando la propiedad getSource() de la clase DocumentProperty.

Utilizamos un archivo de plantilla simple de Microsoft Excel en el ejemplo. El libro de trabajo tiene un rango con nombre definido etiquetado como MiRango que se refiere a un valor de celda.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
// Instantiate an object of Workbook
// Open an Excel file
const workbook = new AsposeCells.Workbook(path.join(dataDir, "sample-document-properties.xlsx"));

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getWorksheets().getCustomDocumentProperties();

// Add link to content.
customProperties.addLinkToContent("Owner", "MyRange");

// Accessing the custom document property by using the property name
const customProperty1 = customProperties.get("Owner");

// Check whether the property is linked to content
const isLinkedToContent = customProperty1.isLinkedToContent();

// Get the source for the property
const source = customProperty1.getSource();

// Save the file
workbook.save(path.join(dataDir, "out_sample-document-properties.xlsx"));

Cómo eliminar propiedades personalizadas

Para eliminar propiedades personalizadas usando Aspose.Cells, llama al método DocumentPropertyCollection.remove(string) y pasa el nombre de la propiedad del documento a eliminar.

const path = require("path");
const AsposeCells = require("aspose.cells.node");

// The path to the documents directory.
const dataDir = path.join(__dirname, "data");
// Instantiate a Workbook object
// Open an Excel file
const workbook = new AsposeCells.Workbook(path.join(dataDir, "sample-document-properties.xlsx"));

// Retrieve a list of all custom document properties of the Excel file
const customProperties = workbook.getCustomDocumentProperties();

// Removing a custom document property
customProperties.remove("Publisher");

// Save the file
workbook.save(path.join(dataDir, "out_sample-document-properties.xlsx"));

Temas avanzados

• Agregar propiedades personalizadas visibles dentro del Panel de información del documento
• Establecer las propiedades ScaleCrop y LinksUpToDate de las propiedades de documento Integradas
• Especificar la versión del documento del archivo de Excel mediante propiedades de documento integradas
• Especificar el idioma del archivo de Excel mediante propiedades de documento integradas