Erstellen von Zellenwerten für verknüpfte Entitäten

Verknüpfte Entitätszellenwerte integrieren Datentypen aus externen Datenquellen und können die Daten als Entität Karte anzeigen, z. B. reguläre Entitätswerte. Sie ermöglichen es Ihnen, Ihre Datentypen so zu skalieren, dass sie große Datasets darstellen, ohne alle Daten in die Arbeitsmappe herunterzuladen. Die über die Excel-Benutzeroberfläche verfügbaren Datendomänen "Aktien" und "Geografie" stellen verknüpfte Entitätszellenwerte bereit. In diesem Artikel wird erläutert, wie Sie einen eigenen Datenanbieter in einem Excel-Add-In erstellen, um benutzerdefinierte Werte für Endbenutzer bereitzustellen.

Verknüpfte Entitätszellenwerte sind mit einer externen Datenquelle verknüpft. Sie bieten die folgenden Vorteile gegenüber regulären Entitätswerten.

Zellenwerte für verknüpfte Entitäten können geschachtelt werden, und geschachtelte Zellenwerte für verknüpfte Entitäten werden erst abgerufen, wenn auf sie verwiesen wird. entweder durch den Benutzer oder durch das Arbeitsblatt. Dies trägt dazu bei, die Dateigröße zu reduzieren und die Arbeitsmappenleistung zu verbessern.
Excel verwendet einen Cache, damit verschiedene Zellen nahtlos auf denselben Wert der verknüpften Entitätszelle verweisen können. Dies verbessert auch die Leistung von Arbeitsmappen.

In diesem Artikel werden die in den folgenden Artikeln beschriebenen Informationen erläutert. Es wird empfohlen, die folgenden Artikel zu lesen, bevor Sie lernen, wie Sie Ihre eigenen Werte für verknüpfte Entitätszellen erstellen.

Zentrale Konzepte

Verknüpfte Entitätszellenwerte stellen dem Benutzer Daten bereit, die aus einer externen Datenquelle verknüpft sind. Der Benutzer kann sie als Entitätswert Karte anzeigen.

Screenshot: Entitätswertdaten Karte für den verknüpften Datentyp Seattle Geography im Arbeitsblatt.

Wie reguläre Entitätswerte können auch verknüpfte Entitätszellenwerte in Formeln referenziert werden.

Screenshot der Verwendung von Punktnotation in einer Formel mit =A1. Zum Anzeigen von Feldern für den Seattle Geography-Datentyp.

Definitionen

Die folgenden Definitionen sind grundlegend, um zu verstehen, wie Sie Ihre eigenen Werte für verknüpfte Entitätszellen implementieren.

Datendomäne für verknüpfte Entitäten : Eine Datendomäne für verknüpfte Entitäten beschreibt die Gesamtkategorie, zu der eine Entität gehört. Einige Beispiele sind Mitarbeiter, Organisationen oder Autos.
Zellenwert der verknüpften Entität: Ein aus einer Datendomäne erstelltes instance. Ein Beispiel ist ein Mitarbeiterwert für jemanden namens Joe. Er kann als Entitätswert Karte angezeigt werden.
Datenanbieter : Der Datenanbieter wird von Excel als Datenquelle für eine oder mehrere registrierte Datendomänen für verknüpfte Entitäten erkannt.
Dienstfunktion zum Laden verknüpfter Entitäten: Jede Datendomäne für verknüpfte Entitäten definiert eine Dienstfunktion laden, die als Datenquelle für diese Domäne fungiert. Die Funktion zum Laden verknüpfter Entitäten verarbeitet Anforderungen aus Excel, um Zellenwerte für verknüpfte Entitäten für die Arbeitsmappe abzurufen. Sie implementieren sie als benutzerdefinierte TypeScript- oder JavaScript-Funktion.

Wie Ihr Add-In Werte für verknüpfte Entitätszellen bereitstellt

Dieses Diagramm zeigt die Schritte, die ausgeführt werden, wenn Das Add-In geladen wird und dann einen neuen verknüpften Entitätszellenwert in eine Zelle einfügt. In der folgenden Beschreibung wird erläutert, was in den einzelnen Schritten des Prozesses geschieht.

Diagramm, das die fünf Schritte für ein Add-In zeigt, um Datendomänen zu registrieren und Anforderungen von Excel zu verarbeiten, um Eigenschaften aus einem verknüpften Entitätszellenwert abzurufen.

Excel lädt Ihr Add-In, und Ihr Add-In registriert alle verknüpften Entitätsdatendomänen, die es unterstützt. Jede Registrierung enthält die ID einer Dienstfunktion zum Laden verknüpfter Entitäten. Diese ID wird später von Excel aufgerufen, um Eigenschaftswerte für den Zellenwert der verknüpften Entität aus der Datendomäne der verknüpften Entität anzufordern. In diesem Beispiel wird eine Datendomäne namens Products registriert.
Excel verfolgt jede registrierte Datendomäne für verknüpfte Entitäten in einer Datendomänensammlung für verknüpfte Entitäten nach. Dadurch kann Excel ihre Dienstfunktion zum Laden verknüpfter Entitäten aufrufen, wenn Daten für einen Zellenwert einer verknüpften Entität benötigt werden.
Das Add-In fügt einen neuen verknüpften Entitätszellenwert in das Arbeitsblatt ein. In diesem Beispiel wird ein neuer verknüpfter Entitätszellenwert für das Produkt Chai erstellt. Dies geschieht in der Regel, wenn der Benutzer eine Schaltfläche in Ihrem Add-In auswählt, was dazu führt, dass ein oder mehrere verknüpfte Entitätszellenwerte erstellt werden. Wenn Sie neue Werte für verknüpfte Entitätszellen erstellen, enthalten diese nur eine anfängliche Textzeichenfolge, die in der Zelle angezeigt wird. Excel ruft die Dienstfunktion zum Laden der verknüpften Entität auf, um die verbleibenden Eigenschaftswerte abzurufen. Ihr Add-In kann auch verknüpfte Entitätszellenwerte aus benutzerdefinierten Funktionen erstellen.
Excel ruft die Dienstfunktion zum Laden verknüpfter Entitäten auf, die Sie in Schritt 1 registriert haben. Dies tritt jedes Mal auf, wenn Sie einen neuen Wert für eine verknüpfte Entitätszelle erstellen oder wenn eine Datenaktualisierung erfolgt. Excel ruft die Dienstfunktion zum Laden der verknüpften Entität auf, um alle Eigenschaftswerte abzurufen.
Die Dienstfunktion zum Laden von verknüpften Entitäten gibt einen aktuellen verknüpften Entitätszellenwert (Excel.LinkedEntityCellValue) für die verknüpfte Entitäts-ID (Excel.LinkedEntityId) zurück, die von Excel angefordert wird. In der Regel fragt Ihre Dienstfunktion zum Laden der verknüpften Entität eine externe Datenquelle ab, um die Werte abzurufen und den Wert der verknüpften Entitätszelle zu erstellen. In diesem Beispiel werden die Werte für Produkt-ID, Kategorie, Menge und Preis zurückgegeben.

Hinweis

Wenn Excel mehrere Werte für verknüpfte Entitätszellen benötigt, werden die verknüpften Entitäts-IDs als Batch an Ihre Dienstfunktion zum Laden verknüpfter Entitäten übergeben. Der Ladedienst für verknüpfte Entitäten gibt dann ein Batchergebnis aller Werte zurück.

Die folgenden Abschnitte enthalten zusätzliche Details zu den zuvor in diesem Artikel definierten Begriffen.

Datenanbieter

Ihr Add-In ist der Datenanbieter und wird von Excel als Datenquelle für eine oder mehrere registrierte Datendomänen erkannt. Ihr Add-In macht eine oder mehrere Datenanbieterfunktionen verfügbar, die Daten für verknüpfte Entitätszellenwerte zurückgeben. Der Datenanbieter wird durch eine Textzeichenfolge wie Contoso oder den Namen Ihres Add-Ins identifiziert. Der Name muss innerhalb Ihres Add-Ins eindeutig sein.

Datendomänen für verknüpfte Entitäten

Der Datenanbieter (Ihr Add-In) registriert mindestens eine Datendomäne. Eine Datendomäne beschreibt eine Entität in Excel. Beispielsweise kann ein Datenanbieter die Datendomänen für Produkte und Kategorien bereitstellen. Die Domänen müssen in Excel registriert werden, damit sie mit diesen Domänen zusammenarbeiten können, um Zellenwerte für verknüpfte Entitäten abzurufen und anzuzeigen und Berechnungen auszuführen.

Eine Datendomäne beschreibt Excel die folgenden Attribute:

Der Name des Datenanbieters, dem er zugeordnet ist.
Eine Domänen-ID zur eindeutigen Identifizierung, z. B. Produkte.
Ein Anzeigename für den Benutzer, z. B. Produkte.
Eine Dienstfunktion zum Laden einer verknüpften Entität, die aufgerufen werden soll, wenn Excel einen Verknüpften Entitätszellenwert benötigt.
Ein angegebener Aktualisierungsmodus und ein angegebenes Intervall, das die Häufigkeit der Aktualisierung beschreibt.

Ein Beispiel für eine Datendomäne für verknüpfte Entitäten ist die Geography-Datendomäne in Excel, die Zellenwerte für verknüpfte Entitäten für Städte bereitstellt.

Zellenwert der verknüpften Entität

Ein Zellenwert einer verknüpften Entität ist ein instance, der aus einer Datendomäne erstellt wird. Ein Beispiel ist ein Wert für Seattle aus der Geography-Datendomäne. Es zeigt einen Entitätswert Karte wie reguläre Entitätszellenwerte an.

Screenshot: Entitätswertdaten Karte für den verknüpften Datentyp Seattle Geography im Arbeitsblatt.

Da zellenwerte verknüpfter Entitäten mit der Datendomäne verknüpft sind, können sie aktualisiert werden. Außerdem werden die Werte für geschachtelte verknüpfte Entitätszellen nur abgerufen, wenn der Benutzer sie anfordert (z. B. anzeigen der Entität Karte). Geschachtelte Entitätszellenwerte werden nicht mit dem Arbeitsblatt gespeichert, es sei denn, sie werden vom Arbeitsblatt referenziert (z. B. eine Formel). Dadurch wird die Dateigröße reduziert und die Leistung verbessert.

Funktion zum Laden von verknüpften Entitäten

Jede Datendomäne erfordert eine Funktion, die Excel aufrufen kann, wenn verknüpfte Entitätszellenwerte benötigt werden. Ihr Add-In stellt den Dienst als JavaScript- oder TypeScript-Funktion bereit, die mit @linkedEntityLoadService gekennzeichnet ist. Es wird empfohlen, nur eine Ladedienstfunktion zu erstellen, um eine optimale Leistung zu erzielen. Excel sendet alle Anforderungen für verknüpfte Entitätszellenwerte als Batch an die Load-Dienstfunktion.

Erstellen eines Datenanbieters mit Datendomänen

In den folgenden Abschnitten dieses Artikels wird gezeigt, wie Sie TypeScript-Code schreiben, um ein Excel-Add-In zu implementieren, das ein Datenanbieter für Contoso ist. Sie stellt zwei Datendomänen mit den Namen Produkte und Kategorien bereit.

Registrieren der Datendomänen

Sehen wir uns den Code zum Registrieren neuer Domänen namens Produkte und Kategorien an. Der Datenanbietername lautet Contoso. Wenn das Add-In geladen wird, registriert es zuerst die Datendomänen bei Excel.

Verwenden Sie den Excel.LinkedEntityDataDomainCreateOptions-Typ , um die gewünschten Optionen zu beschreiben, einschließlich der Funktion, die als Ladedienst für verknüpfte Entitäten verwendet werden soll. Fügen Sie die Domäne dann der Workbook.linkedEntityDataDomains-Auflistung hinzu. Es wird empfohlen, Domänen zu registrieren, wenn Sie Ihr Office-Add-In initialisieren. Der folgende Code zeigt, wie Sie die Datendomänen "Produkte", "Kategorien" und " Lieferanten " registrieren.

Office.onReady(async () => {
    await Excel.run(async (context) => {
        const productsDomain: Excel.LinkedEntityDataDomainCreateOptions = {
            dataProvider: "Contoso",
            id: "products",
            name: "Products",
            // ID of the custom function that is called on demand by Excel to resolve or refresh linked entity cell values of this data domain.
            loadFunctionId: "CONTOSOLOADSERVICE",
            // periodicRefreshInterval is only required when supportedRefreshModes contains "Periodic".
            periodicRefreshInterval: 300,
            // Manual refresh mode is always supported, even if unspecified.
            supportedRefreshModes: [
                Excel.LinkedEntityDataDomainRefreshMode.periodic,
                Excel.LinkedEntityDataDomainRefreshMode.onLoad
            ]
        };

        const categoriesDomain: Excel.LinkedEntityDataDomainCreateOptions = {
            dataProvider: "Contoso",
            id: "categories",
            name: "Categories",
            loadFunctionId: "CONTOSOLOADSERVICE",
            periodicRefreshInterval: 300,
            supportedRefreshModes: [
                Excel.LinkedEntityDataDomainRefreshMode.periodic,
                Excel.LinkedEntityDataDomainRefreshMode.onLoad
            ]
        };

        const suppliersDomain: Excel.LinkedEntityDataDomainCreateOptions = {
            dataProvider: "Contoso",
            id: "suppliers",
            name: "Suppliers",
            loadFunctionId: "CONTOSOLOADSERVICE"
        };
        // Register the data domains by adding them to the collection.
        context.workbook.linkedEntityDataDomains.add(productsDomain);
        context.workbook.linkedEntityDataDomains.add(categoriesDomain);
        context.workbook.linkedEntityDataDomains.add(suppliersDomain);

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

Einfügen eines Zellwerts einer verknüpften Entität

Es gibt zwei Möglichkeiten, einen verknüpften Entitätszellenwert in eine Zelle auf einem Arbeitsblatt einzufügen.

Erstellen Sie eine Befehlsschaltfläche im Menüband oder eine Schaltfläche in Ihrem Aufgabenbereich. Wenn der Benutzer die Schaltfläche auswählt, fügt Ihr Code einen verknüpften Entitätszellenwert ein.
Erstellen Sie eine benutzerdefinierte Funktion, die einen Verknüpften Entitätszellenwert zurückgibt.

Im folgenden Codebeispiel wird gezeigt, wie Sie einen neuen verknüpften Entitätszellenwert in die ausgewählte Zelle einfügen. Dieser Code kann über eine Befehlsschaltfläche im Menüband oder über eine Schaltfläche im Aufgabenbereich aufgerufen werden. Hinweise zum folgenden Code:

Sie müssen einen serviceId von 268436224 für alle verknüpften Entitätszellenwerte angeben, die Sie zurückgeben. Dadurch wird Excel informiert, dass der Wert der verknüpften Entitätszelle einem Excel-Add-In zugeordnet ist.
Sie müssen eine cultureangeben. Excel übergibt sie an ihre Dienstfunktion zum Laden verknüpfter Entitäten, damit Sie die ursprüngliche Kultur beibehalten können, wenn die Arbeitsmappe in einer anderen Kultur geöffnet wird.
Die text -Eigenschaft wird dem Benutzer in der Zelle angezeigt, während der Datenwert der verknüpften Entität aktualisiert wird. Dadurch wird verhindert, dass der Benutzer eine leere Zelle sieht, während die Aktualisierung abgeschlossen ist.

async function insertProduct() {
    await Excel.run(async (context) => {
        const productLinkedEntity: Excel.LinkedEntityCellValue = {
            type: Excel.CellValueType.linkedEntity,
            id: {
                entityId: "P1", // Don't use exclamation marks in this value.
                domainId: "products", // Don't use exclamation marks in this value.
                serviceId: 268436224,
                culture: "en-US",
            },
            text: "Chai",
        };
        context.workbook.getActiveCell().valuesAsJson = [[productLinkedEntity]];
        await context.sync();
    });
}

Hinweis

Verwenden Sie keine Ausrufezeichen in den entityID Werten oder domainId .

Im folgenden Codebeispiel wird gezeigt, wie sie einen Verknüpften Entitätszellenwert mithilfe einer benutzerdefinierten Funktion einfügen. Ein Benutzer kann einen verknüpften Entitätszellenwert abrufen, indem er in eine beliebige Zelle eingibt =CONTOSO.GETPRODUCTBYID("productid") . Die Hinweise für das vorherige Codebeispiel gelten auch für dieses Beispiel.

/**
 * Custom function that shows how to insert a `LinkedEntityCellValue`.
 * @customfunction
 * @param {string} productID Unique ID of the product.
 * @return {any} `LinkedEntityCellValue` for the requested product, if found.
 */
function getProductById(productID: string): any {
    const product = getProduct(productID);
    if (product === null) {
        throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable, "Invalid productID");
    }
    const productLinkedEntity: Excel.LinkedEntityCellValue = {
        type: Excel.CellValueType.linkedEntity,
        id: {
            entityId: product.productID,
            domainId: "products",
            serviceId: 268436224,
            culture: "en-US",
        },
        text: product.productName
    };

    return productLinkedEntity;
}

Implementieren der Dienstfunktion zum Laden verknüpfter Entitäten

Das Add-In muss eine Dienstfunktion zum Laden verknüpfter Entitäten bereitstellen, um Anforderungen aus Excel zu verarbeiten, wenn Eigenschaftswerte für verknüpfte Entitätszellenwerte erforderlich sind. Die Funktion wird mit dem @linkedEntityLoadService JSDoc-Tag identifiziert.

Das folgende Codebeispiel zeigt, wie Sie eine Funktion erstellen, die Datenanforderungen von Excel für die Datendomänen Products und Categories verarbeitet. Hinweise zum folgenden Code:

Sie verwendet Hilfsfunktionen, um die Werte der verknüpften Entitätszelle zu erstellen. Dieser Code wird später gezeigt.
Wenn ein Fehler auftritt, wird ein CustomFunctions.ErrorCode.notAvailable Fehler ausgelöst. Dies wird in der Zelle angezeigt #CONNECT! , die dem Benutzer angezeigt wird.

// Linked entity data domain constants
const productsDomainId = "products";
const categoriesDomainId = "categories";
const suppliersDomainId = "suppliers";

// Linked entity cell value constants
const addinDomainServiceId = 268436224;
const defaultCulture = "en-US";

/**
 * Custom function which acts as the "service" or the data provider for a `LinkedEntityDataDomain`, that is
 * called on demand by Excel to resolve/refresh `LinkedEntityCellValue`s of that `LinkedEntityDataDomain`.
 * @customfunction
 * @linkedEntityLoadService
 * @param {any} request Request to resolve/refresh `LinkedEntityCellValue` objects.
 * @return {any} Resolved/Refreshed `LinkedEntityCellValue` objects that were requested in the passed-in request.
 */
function contosoLoadService(request: any): any {
    const notAvailableError = new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
    console.log(`Fetching linked entities from request: ${request} ...`);

    try {
        // Parse the request that was passed-in by Excel.
        const parsedRequest: Excel.LinkedEntityLoadServiceRequest = JSON.parse(request);
        // Initialize result to populate and return to Excel.
        const result: Excel.LinkedEntityLoadServiceResult = { entities: [] };

        // Identify the domainId of the request and call the corresponding function to create
        // linked entity cell values for that linked entity data domain.
        for (const { entityId } of parsedRequest.entities) {
            var linkedEntityResult = null;
            switch (parsedRequest.domainId) {
                case productsDomainId: {
                    linkedEntityResult = makeProductLinkedEntity(entityId);
                    break;
                }
                case categoriesDomainId: {
                    linkedEntityResult = makeCategoryLinkedEntity(entityId);
                    break;
                }
                case suppliersDomainId: {
                    linkedEntityResult = makeSupplierLinkedEntity(entityId);
                    break;
                }
                default:
                    throw notAvailableError;
            }

            if (!linkedEntityResult) {
                // Throw an error to signify to Excel that resolution/refresh of the requested linkedEntityId failed.
                throw notAvailableError;
            }

            result.entities.push(linkedEntityResult);
        }

        return result;
    } catch (error) {
        console.error(error);
        throw notAvailableError;
    }
}

Das folgende Codebeispiel zeigt die Hilfsfunktion zum Erstellen eines Werts für eine produktgebundene Entitätszelle. Diese Funktion wird vom vorherigen Code contosoLoadService aufgerufen, um eine verknüpfte Entität für eine bestimmte Produkt-ID zu erstellen. Hinweise zum folgenden Code:

Es werden dieselben Einstellungen wie im vorherigen insertProduct Beispiel für die typeEigenschaften , idund text verwendet.
Sie enthält zusätzliche Eigenschaften, die für die Datendomäne Products spezifisch sind, z Product Name . B. und Unit Price.
Es wird eine verzögerte geschachtelte verknüpfte Entität für die Kategorie des Produkts erstellt. Die Eigenschaften für die Kategorie werden erst angefordert, wenn sie benötigt werden.

/** Helper function to create a linked entity from product properties. */
function makeProductLinkedEntity(productID: string): any {
    // Search the product data in the data source for a matching product ID.
    const product = getProduct(productID);
    if (product === null) {
        // Return null if no matching product is found.
        return null;
    }

    const productLinkedEntity: Excel.LinkedEntityCellValue = {
        type: "LinkedEntity",
        text: product.productName,
        id: {
            entityId: product.productID,
            domainId: productsDomainId,
            serviceId: addinDomainServiceId,
            culture: defaultCulture
        },
        properties: {
            "Product ID": {
                type: "String",
                basicValue: product.productID
            },
            "Product Name": {
                type: "String",
                basicValue: product.productName
            },
            "Quantity Per Unit": {
                type: "String",
                basicValue: product.quantityPerUnit
            },
            // Add Unit Price as a formatted number.
            "Unit Price": {
                type: "FormattedNumber",
                basicValue: product.unitPrice,
                numberFormat: "$* #,##0.00"
            },
            Discontinued: {
                type: "Boolean",
                basicValue: product.discontinued
            }
        },
        layouts: {
            compact: {
                icon: "ShoppingBag"
            },
            card: {
                title: { property: "Product Name" },
                sections: [
                    {
                        layout: "List",
                        properties: ["Product ID"]
                    },
                    {
                        layout: "List",
                        title: "Quantity and price",
                        collapsible: true,
                        collapsed: false,
                        properties: ["Quantity Per Unit", "Unit Price"]
                    },
                    {
                        layout: "List",
                        title: "Additional information",
                        collapsed: true,
                        properties: ["Discontinued"]
                    }
                ]
            }
        }
    };

    // Add image property to the linked entity and then add it to the card layout.
    if (product.productImage) {
        productLinkedEntity.properties["Image"] = {
            type: "WebImage",
            address: product.productImage
        };
        productLinkedEntity.layouts.card.mainImage = { property: "Image" };
    }

    // Add a deferred nested linked entity for the product category.
    const category = getCategory(product.categoryID.toString());
    if (category) {
        productLinkedEntity.properties["Category"] = {
            type: "LinkedEntity",
            text: category.categoryName,
            id: {
                entityId: category.categoryID.toString(),
                domainId: categoriesDomainId,
                serviceId: addinDomainServiceId,
                culture: defaultCulture
            }
        };

        // Add nested product category to the card layout.
        productLinkedEntity.layouts.card.sections[0].properties.push("Category");
    }

    // Add a deferred nested linked entity for the supplier.
    const supplier = getSupplier(product.supplierID.toString());
    if (supplier) {
        productLinkedEntity.properties["Supplier"] = {
            type: "LinkedEntity",
            text: supplier.companyName,
            id: {
                entityId: supplier.supplierID.toString(),
                domainId: suppliersDomainId,
                serviceId: addinDomainServiceId,
                culture: defaultCulture
            }
        };

        // Add nested product supplier to the card layout.
        productLinkedEntity.layouts.card.sections[2].properties.push("Supplier");
    }

    return productLinkedEntity;
}

Im folgenden Codebeispiel wird die Hilfsfunktion zum Erstellen eines Werts einer kategoriegebundenen Entitätszelle veranschaulicht. Diese Funktion wird vom vorherigen Code contosoLoadService aufgerufen, um eine verknüpfte Entität für eine bestimmte Kategorie-ID zu erstellen.

/** Helper function to create a linked entity from category properties. */
function makeCategoryLinkedEntity(categoryID: string): any {
    // Search the sample JSON category data for a matching category ID.
    const category = getCategory(categoryID);
    if (category === null) {
        // Return null if no matching category is found.
        return null;
    }

    const categoryLinkedEntity: Excel.LinkedEntityCellValue = {
        type: "LinkedEntity",
        text: category.categoryName,
        id: {
            entityId: category.categoryID,
            domainId: categoriesDomainId,
            serviceId: addinDomainServiceId,
            culture: defaultCulture
        },
        properties: {
            "Category ID": {
                type: "String",
                basicValue: category.categoryID,
                propertyMetadata: {
                    // Exclude the category ID property from the card view and auto-complete.
                    excludeFrom: {
                        cardView: true,
                        autoComplete: true
                    }
                }
            },
            "Category Name": {
                type: "String",
                basicValue: category.categoryName
            },
            Description: {
                type: "String",
                basicValue: category.description
            }
        },
        layouts: {
            compact: {
                icon: "Branch"
            }
        }
    };

    return categoryLinkedEntity;
}

Das folgende Codebeispiel zeigt die Hilfsfunktion zum Erstellen eines Zellenwerts für eine lieferantengebundene Entität. Diese Funktion wird vom vorherigen Code contosoLoadService aufgerufen, um eine verknüpfte Entität für eine bestimmte Lieferanten-ID zu erstellen.

/** Helper function to create linked entity from supplier properties. */
function makeSupplierLinkedEntity(supplierID: string): any {
    // Search the sample JSON category data for a matching supplier ID.
    const supplier = getSupplier(supplierID);
    if (supplier === null) {
        // Return null if no matching supplier is found.
        return null;
    }

    const supplierLinkedEntity: Excel.LinkedEntityCellValue = {
        type: "LinkedEntity",
        text: supplier.companyName,
        id: {
            entityId: supplier.supplierID,
            domainId: suppliersDomainId,
            serviceId: addinDomainServiceId,
            culture: defaultCulture
        },
        properties: {
            "Supplier ID": {
                type: "String",
                basicValue: supplier.supplierID
            },
            "Company Name": {
                type: "String",
                basicValue: supplier.companyName
            },
            "Contact Name": {
                type: "String",
                basicValue: supplier.contactName
            },
            "Contact Title": {
                type: "String",
                basicValue: supplier.contactTitle
            }
        },
        cardLayout: {
            title: { property: "Company Name" },
            sections: [
                {
                    layout: "List",
                    properties: ["Supplier ID", "Company Name", "Contact Name", "Contact Title"]
                }
            ]
        }
    };

    return supplierLinkedEntity;
}

Das folgende Codebeispiel enthält Beispieldaten, die Sie mit den vorherigen Codebeispielen verwenden können.

/// Sample product data.
const products = [
    {
        productID: "P1",
        productName: "Chai",
        supplierID: "S1",
        categoryID: "C1",
        quantityPerUnit: "10 boxes x 20 bags",
        unitPrice: 18,
        discontinued: false,
        productImage: "https://upload.wikimedia.org/wikipedia/commons/thumb/0/04/Masala_Chai.JPG/320px-Masala_Chai.JPG"
    }
];

/// Sample product category data.
const categories = [
    {
        categoryID: "C1",
        categoryName: "Beverages",
        description: "Soft drinks, coffees, teas, beers, and ales"
    }];

/// Sample product supplier data.
const suppliers = [
    {
        supplierID: "S1",
        companyName: "Exotic Liquids",
        contactName: "Ema Vargova",
        contactTitle: "Purchasing Manager"
    }];

Datenaktualisierungsoptionen

Wenn Sie eine Datendomäne registrieren, kann der Benutzer sie jederzeit manuell aktualisieren, z. B. indem er auf der Registerkarte Daten die Option Alle aktualisieren auswählt. Es gibt drei Aktualisierungsmodi, die Sie für Ihre Datendomäne angeben können.

manual– Die Daten werden nur aktualisiert, wenn der Benutzer sich für die Aktualisierung entscheidet. Dies ist der Standardmodus. Die manuelle Aktualisierung kann immer vom Benutzer ausgeführt werden, auch wenn der Aktualisierungsmodus auf onLoad oder periodicfestgelegt ist.
onLoad– Die Daten werden aktualisiert, wenn die Datendomäne registriert wird (in der Regel beim Laden des Add-Ins). Anschließend werden die Daten nur noch manuell vom Benutzer aktualisiert. Wenn Sie Daten beim Öffnen der Arbeitsmappe aktualisieren möchten, konfigurieren Sie Das Add-In so, dass es beim Öffnen des Dokuments geladen wird. Weitere Informationen finden Sie unter Ausführen von Code in Ihrem Office-Add-In beim Öffnen des Dokuments.
periodic– Die Daten werden aktualisiert, wenn die Datendomäne registriert wird (in der Regel beim Laden des Add-Ins). Anschließend werden die Daten nach einem angegebenen Zeitintervall kontinuierlich aktualisiert. Sie können beispielsweise angeben, dass die Datendomäne alle 300 Sekunden aktualisiert wird (dies ist der Mindestwert). Die Anzahl der Sekunden wird immer auf die nächste Anzahl von Minuten aufgerundet, da das Aktualisierungsintervall nur in Minuten ausgeführt wird.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine Datendomäne so konfigurieren, dass sie beim Laden aktualisiert wird und dann alle 5 Minuten aktualisiert wird.

const productsDomain: Excel.LinkedEntityDataDomainCreateOptions = {
    dataProvider: domainDataProvider,
    id: "products",
    name: "Products",
    // ID of the custom function that is called on demand by Excel to resolve or refresh linked entity cell values of this data domain.
    loadFunctionId: loadFunctionId,
    // periodicRefreshInterval is only required when supportedRefreshModes contains "Periodic".
    periodicRefreshInterval: 300, // equivalent to 5 minutes.
    // Manual refresh mode is always supported, even if unspecified.
    supportedRefreshModes: [
        Excel.LinkedEntityDataDomainRefreshMode.periodic,
        Excel.LinkedEntityDataDomainRefreshMode.onLoad
    ]
};

Sie können auch programmgesteuert eine Aktualisierung für eine verknüpfte Entitäts-Datendomäne anfordern, indem Sie eine der folgenden Methoden verwenden.

LinkedEntityDataDomain.refresh() – Aktualisiert alle LinkedEntityCellValue Objekte der Datendomäne der verknüpften Entität.
LinkedEntityDataDomainCollection.refreshAll() – Aktualisiert alle LinkedEntityCellValue Objekte aller datenverknüpften Entitätsdomänen in der Auflistung.

Die Aktualisierungsmethoden fordern eine asynchrone Aktualisierung an. Um die Ergebnisse der Aktualisierung zu ermitteln, lauschen Sie auf das onRefreshCompleted Ereignis. Das folgende Codebeispiel zeigt ein Beispiel für das Lauschen auf das onRefreshCompleted Ereignis.

await Excel.run(async (context) => {
    const dataDomains = context.workbook.linkedEntityDataDomains;
    dataDomains.onRefreshCompleted.add(onLinkedEntityDomainRefreshed);

    await context.sync();
});

async function onLinkedEntityDomainRefreshed(eventArgs: Excel.LinkedEntityDataDomainRefreshCompletedEventArgs): Promise<any> {
    console.log("Linked entity domain refreshed: " + eventArgs.id);
    console.log("Refresh status: " + eventArgs.refreshed);
    console.log("Refresh error: " + eventArgs.errors);
    return null;
}

Fehlerbehandlung mit dem Ladedienst für verknüpfte Entitäten

Wenn Excel Ihr Add-In aufruft, um Daten für einen verknüpften Entitätszellenwert abzurufen, kann ein Fehler auftreten. Wenn Excel überhaupt keine Verbindung mit Ihrem Add-In herstellen kann, z. B. wenn das Add-In nicht geladen wird, zeigt Excel dem Benutzer den #CONNECT! Fehler an.

Wenn bei der Dienstfunktion zum Laden der verknüpften Entität ein Fehler auftritt, sollte der notAvailableError Fehler ausgelöst werden. Dies bewirkt, dass Excel dem Benutzer angezeigt wird #CONNECT! .

Der folgende Code zeigt, wie sie einen Fehler in einer Dienstfunktion zum Laden verknüpfter Entitäten behandeln.

async function contosoLoadService(request: any): Promise<any> {
    const notAvailableError = new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
    try {
        // Create and return a new linked entity cell value.
        let linkedEntityResult = ...
      ...
        if (!linkedEntityResult) {
            // Throw an error to signify to Excel that resolution or refresh of the requested linkedEntityId failed.
            throw notAvailableError;
        }
      ...
    } catch (error) {
        console.error(error);
        throw notAvailableError;
    }
}

Debuggen des Ladediensts für verknüpfte Entitäten

Die meisten Add-In-Funktionen für Datentypen verknüpfter Entitäten können mithilfe der Anleitung unter Übersicht über das Debuggen von Office-Add-Ins debuggt werden. Die Dienstfunktion zum Laden verknüpfter Entitäten kann jedoch in einer freigegebenen Runtime oder einer reinen JavaScript-Runtime implementiert werden (auch als Runtime für benutzerdefinierte Funktionen bekannt). Wenn Sie die Funktion in einer reinen JavaScript-Runtime implementieren möchten, verwenden Sie die Anleitung zum Debuggen von benutzerdefinierten Funktionen in einer nicht freigegebenen Laufzeit .

Die Dienstfunktion zum Laden von verknüpften Entitäten verwendet die Architektur benutzerdefinierter Funktionen, unabhängig davon, welche Laufzeit Sie verwenden. Es gibt jedoch erhebliche Unterschiede zu regulären benutzerdefinierten Funktionen.

Die Funktionen des Diensts zum Laden von verknüpften Entitäten unterscheiden sich von benutzerdefinierten Funktionen:

Endbenutzern werden sie nicht zur Verwendung in Formeln angezeigt.
Die JSDoc-Tags @streaming oder @volatilewerden nicht unterstützt. Dem Benutzer wird ein #CALC!- Fehler angezeigt, wenn diese Tags verwendet werden.

Funktionen zum Laden von verknüpften Entitäten weisen die folgenden Ähnlichkeiten mit benutzerdefinierten Funktionen auf:

Sie verwenden die Benennung und Lokalisierung von benutzerdefinierten Funktionen.
Sie verwenden den gleichen Fehlerbehandlungsansatz.

Verhalten in Excel 2019 und früher

Wenn jemand ein Arbeitsblatt mit verknüpften Entitätszellenwerten in einer älteren Excel-Version öffnet, die keine Werte für verknüpfte Entitätszellen unterstützt, zeigt Excel die Zellenwerte als Fehler an. Dies ist das entworfene Verhalten. Aus diesem Grund legen Sie bei jedem Einfügen oder Aktualisieren eines Zellenwerts für basicTypeError verknüpfte Entitäten auf und basicValue auf #VALUE! fest. Dies ist der Fehler, den Excel als Fallback für ältere Versionen verwendet.

Bewährte Methoden

Verwenden Sie keine Ausrufezeichen in den entityID Werten oder domainId .
Registrieren Sie datendomänen verknüpfter Entitäten im Initialisierungscode Office.OnReady , damit der Benutzer sofort über Funktionen verfügt, z. B. die Möglichkeit, die Werte der verknüpften Entitätszelle zu aktualisieren.
Ändern Sie nach der Veröffentlichung Ihres Add-Ins nicht die Datendomänen-IDs der verknüpften Entität. Konsistente IDs für dieselben logischen Objekte helfen bei der Leistung.
Geben Sie immer die text -Eigenschaft an, wenn Sie einen neuen Wert für eine verknüpfte Entitätszelle erstellen. Dieser Wert wird angezeigt, während Excel Ihre Datenanbieterfunktion aufruft, um die verbleibenden Eigenschaftswerte abzurufen. Andernfalls wird dem Benutzer eine leere Zelle angezeigt, bis die Daten abgerufen werden.

Weitere Informationen

Übersicht über Datentypen in Excel-Add-Ins

Feedback

War diese Seite hilfreich?

Last updated on 2025-05-13