Excel.SensitivityLabelsCatalog class

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

提供方法来检查 Excel 中敏感度标签目录的状态,并在启用目录的情况下检索所有可用的敏感度标签。

扩展

属性

context

与对象关联的请求上下文。 这将加载项的进程连接到 Office 主机应用程序的进程。

getLabelingCapabilities

获取 Excel 的标签功能。 用于 Array.includes 确定功能是否可用。

getLabelingCapability

获取是否在 Excel 中启用敏感度标签目录。

方法

getAttributes()

获取启用 ABAC 的标签 (ABAC) 属性目录元数据的基于属性的访问控制。 验证主机的标记功能 attributeBasedAccessControlEnabled包括 ;否则,此方法将失败并显示错误。

getLabels()

获取当前用户可用的敏感度标签。

load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

toJSON()

覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Excel.SensitivityLabelsCatalog 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Excel.Interfaces.SensitivityLabelsCatalogData) ,其中包含从原始对象加载的任何子属性的浅层副本。

属性详细信息

context

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

与对象关联的请求上下文。 这将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

getLabelingCapabilities

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取 Excel 的标签功能。 用于 Array.includes 确定功能是否可用。

readonly getLabelingCapabilities: Excel.LabelingCapability[];

属性值

注解

API 集:ExcelApi BETA (仅预览版)

getLabelingCapability

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取是否在 Excel 中启用敏感度标签目录。

readonly getLabelingCapability: Excel.LabelingCapability | "NoLicense" | "LabelingDisabled" | "LabelingPolicyNotFound" | "LabelingEnabled" | "AttributeBasedAccessControlEnabled";

属性值

Excel.LabelingCapability | "NoLicense" | "LabelingDisabled" | "LabelingPolicyNotFound" | "LabelingEnabled" | "AttributeBasedAccessControlEnabled"

注解

API 集:ExcelApi BETA (仅预览版)

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/98-preview-apis/manage-sensitivity-labels.yaml

// Check whether sensitivity labeling is available for the current user.
await Excel.run(async (context) => {
    const labelCatalog: Excel.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available in this version of Excel.");
        return;
    }

    labelCatalog.load("getLabelingCapability");
    await context.sync();

    switch (labelCatalog.getLabelingCapability) {
        case Excel.LabelingCapability.labelingEnabled:
            console.log("Sensitivity labeling is enabled.");
            break;
        case Excel.LabelingCapability.labelingDisabled:
            console.log("Sensitivity labeling is disabled.");
            break;
        case Excel.LabelingCapability.labelingPolicyNotFound:
            console.log("No sensitivity labeling policy was found.");
            break;
        case Excel.LabelingCapability.noLicense:
            console.log("The current user doesn't have a valid sensitivity labeling license.");
            break;
        default:
            console.log(`Unknown labeling capability: ${labelCatalog.getLabelingCapability}`);
            break;
    }
});

方法详细信息

getAttributes()

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取启用 ABAC 的标签 (ABAC) 属性目录元数据的基于属性的访问控制。 验证主机的标记功能 attributeBasedAccessControlEnabled包括 ;否则,此方法将失败并显示错误。

getAttributes(): OfficeExtension.ClientResult<SensitivityLabelAbacAttribute[]>;

返回

当前用户的可用 ABAC 属性。

注解

API 集:ExcelApi BETA (仅预览版)

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/98-preview-apis/manage-sensitivity-labels.yaml

// Get available ABAC attributes and describe the kind of value each attribute accepts.
const container = document.getElementById("abac-attributes");
while (container.firstChild) {
    container.removeChild(container.firstChild);
}
await Excel.run(async (context) => {
    const labelCatalog: Excel.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available in this version of Excel.");
        return;
    }

    labelCatalog.load("getLabelingCapabilities");
    await context.sync();

    const capabilities: Excel.LabelingCapability[] = labelCatalog.getLabelingCapabilities;
    if (capabilities.indexOf(Excel.LabelingCapability.attributeBasedAccessControlEnabled) === -1) {
        console.warn("ABAC attributes aren't enabled or available for the current user.");
        return;
    }

    const catalogAttributes: OfficeExtension.ClientResult<Excel.SensitivityLabelAbacAttribute[]> =
        labelCatalog.getAttributes();
    await context.sync();

    if (catalogAttributes.value.length === 0) {
        console.log("No ABAC attributes are available in the sensitivity label catalog.");
        return;
    }

    console.log("Available ABAC attributes:");
    catalogAttributes.value.forEach((attribute: Excel.SensitivityLabelAbacAttribute) => {
        let dataTypeDescription: string;
        switch (attribute.dataType) {
            case Excel.SensitivityLabelAbacAttributeDataType.booleanValue:
                dataTypeDescription = "Boolean";
                break;
            case Excel.SensitivityLabelAbacAttributeDataType.dateValue:
                dataTypeDescription = "Date";
                break;
            case Excel.SensitivityLabelAbacAttributeDataType.numberValue:
                dataTypeDescription = "Number";
                break;
            case Excel.SensitivityLabelAbacAttributeDataType.stringValue:
                dataTypeDescription = "String";
                break;
            case Excel.SensitivityLabelAbacAttributeDataType.unknown:
                dataTypeDescription = "Unknown";
                break;
            default:
                dataTypeDescription = `Unrecognized (${attribute.dataType})`;
                break;
        }

        console.log(`ABAC attribute: ${attribute.displayName}`, {
            dataType: attribute.dataType,
            dataTypeDescription,
            displayOrder: attribute.displayOrder,
            isActive: attribute.isActive,
            isMultiValued: attribute.isMultiValued,
            values: attribute.values.map((attributeValue: Excel.SensitivityLabelAbacAttributeValue) => ({
                displayName: attributeValue.displayName,
                displayOrder: attributeValue.displayOrder,
                id: attributeValue.id,
                isActive: attributeValue.isActive
            }))
        });
    });

    addAttributeOptions(catalogAttributes.value);
});

getLabels()

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

获取当前用户可用的敏感度标签。

getLabels(): Excel.SensitivityLabelDetailsCollection;

返回

当前 SensitivityLabelDetailsCollection 对象。

注解

API 集:ExcelApi BETA (仅预览版)

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/98-preview-apis/manage-sensitivity-labels.yaml

// Get the published labels and sublabels available to the current user.
await Excel.run(async (context) => {
    const labelSelect = document.getElementById("label-id") as HTMLSelectElement;
    labelSelect.options.length = 0;

    const placeholder = document.createElement("option");
    placeholder.textContent = "Select a label";
    placeholder.value = "";
    labelSelect.add(placeholder);

    const labelCatalog: Excel.SensitivityLabelsCatalog = context.sensitivityLabelsCatalog;
    if (!labelCatalog) {
        console.warn("The sensitivity label catalog isn't available in this version of Excel.");
        return;
    }

    const availableLabels: Excel.SensitivityLabelDetailsCollection = labelCatalog.getLabels();
    availableLabels.load(
        "items/color,items/id,items/isAbacAttributesRequired,items/isAbacEnabled,items/isEnabled," +
        "items/name,items/order,items/protectionType,items/siteId,items/tooltip," +
        "items/children/items/id,items/children/items/name,items/children/items/isEnabled"
    );
    await context.sync();

    if (availableLabels.items.length === 0) {
        console.log("No sensitivity labels are available for the current user.");
        return;
    }

    console.log("Available sensitivity labels:");
    availableLabels.items.forEach((labelDetails: Excel.SensitivityLabelDetails) => {
        const childLabels = labelDetails.children && labelDetails.children.items.length
            ? labelDetails.children.items
                .map((childLabel: Excel.SensitivityLabelDetails) => `${childLabel.name} (${childLabel.id})`)
                .join(", ")
            : "None";
        console.log(
            `\n${labelDetails.name}\n` +
            `  ID: ${labelDetails.id}\n` +
            `  Site ID: ${labelDetails.siteId}\n` +
            `  Tooltip: ${labelDetails.tooltip}\n` +
            `  Color: ${labelDetails.color}\n` +
            `  Enabled: ${labelDetails.isEnabled ? "Yes" : "No"}\n` +
            `  Display order: ${labelDetails.order}\n` +
            `  ABAC enabled: ${labelDetails.isAbacEnabled ? "Yes" : "No"}\n` +
            `  ABAC attributes required: ${labelDetails.isAbacAttributesRequired ? "Yes" : "No"}\n` +
            `  Sublabels: ${childLabels}\n` +
            `  Protection type: ${labelDetails.protectionType}`
        );
    });

    addLabelOptions(availableLabels);
});

load(options)

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(options?: Excel.Interfaces.SensitivityLabelsCatalogLoadOptions): Excel.SensitivityLabelsCatalog;

参数

options
Excel.Interfaces.SensitivityLabelsCatalogLoadOptions

为要加载的对象属性提供选项。

返回

load(propertyNames)

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNames?: string | string[]): Excel.SensitivityLabelsCatalog;

参数

propertyNames

string | string[]

指定要加载的属性的逗号分隔的字符串或字符串数组。

返回

load(propertyNamesAndPaths)

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.SensitivityLabelsCatalog;

参数

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select 是指定要加载的属性的逗号分隔字符串,以及 propertyNamesAndPaths.expand 指定要加载的导航属性的逗号分隔字符串。

返回

toJSON()

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

覆盖 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 (JSON.stringify反过来调用 toJSON 传递给它的对象的方法。) 虽然原始 Excel.SensitivityLabelsCatalog 对象是 API 对象, toJSON 但该方法返回一个纯 JavaScript 对象, (类型化为 Excel.Interfaces.SensitivityLabelsCatalogData) ,其中包含从原始对象加载的任何子属性的浅层副本。

toJSON(): Excel.Interfaces.SensitivityLabelsCatalogData;

返回