Erstellen von Datentypen für verknüpfte Entitäten in Excel-Add-Ins

Verwenden Sie Zellenwerte für verknüpfte Entitäten, wenn Ihr Excel-Add-In externe Daten anzeigen muss, ohne das vollständige Dataset in der Arbeitsmappe zu speichern. Sie können beispielsweise ein Produkt, einen Kunden oder einen Lieferanten in einer Zelle anzeigen, eine umfangreiche Karte für Details öffnen und geschachtelte Daten nur laden, wenn Excel sie benötigt.

Excel verwendet das gleiche Muster für integrierte verknüpfte Datentypen wie Aktien und Geografie. In diesem Artikel wird gezeigt, wie Sie einen eigenen Datenanbieter in einem Excel-Add-In erstellen.

In diesem Artikel erfahren Sie, wie Sie:

• Registrieren von Datendomänen für verknüpfte Entitäten.
• Fügen Sie Zellenwerte für verknüpfte Entitäten aus einem Befehl oder einer benutzerdefinierten Funktion ein.
• Implementieren Sie eine Dienstfunktion zum Laden verknüpfter Entitäten.
• Konfigurieren von Aktualisierung und Fehlerbehandlung.

Bevor Sie beginnen, lesen Sie diese verwandten Artikel:

• Übersicht über Datentypen in Excel-Add-Ins
• Verwenden von Datentypen in Excel-Add-Ins
• Verwenden von Karten mit Zellwertdatentypen
• Hinzufügen von Eigenschaften zu Excel-Basiszellenwerten

Funktionsweise verknüpfter Entitätszellenwerte

Verknüpfte Entitätszellenwerte verbinden Arbeitsmappenzellen mit einer externen Datenquelle und zeigen das Ergebnis als Entität Karte an.

Wie reguläre Entitätswerte können Sie in Formeln auf Verknüpfte Entitätszellenwerte verweisen.

Im Vergleich zu regulären Entitätswerten bieten verknüpfte Entitätszellenwerte diese Vorteile.

• Geschachtelte Werte für verknüpfte Entitäten werden erst abgerufen, wenn der Benutzer oder das Arbeitsblatt darauf verweist. Dies trägt dazu bei, die Dateigröße zu reduzieren und die Arbeitsmappenleistung zu verbessern.
• Excel speichert Zellenwerte für verknüpfte Entitäten zwischen, damit mehrere Zellen effizient auf denselben Wert verweisen können.

Schlüsselbegriffe

Verwenden Sie die folgenden Begriffe in diesem Artikel.

• 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.

Funktionsweise des Flows für verknüpfte Entitäten

Dieses Diagramm zeigt, was geschieht, nachdem das Add-In einen verknüpften Entitätszellenwert geladen und in eine Zelle einfügt.

1. 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. Excel ruft diese ID später auf, 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.
2. 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.
3. Das Add-In fügt einen neuen verknüpften Entitätszellenwert in das Arbeitsblatt ein. In diesem Beispiel erstellen Sie einen neuen verknüpften Entitätszellenwert für das Produkt Chai. Dieser Schritt tritt in der Regel auf, wenn der Benutzer eine Schaltfläche in Ihrem Add-In auswäht, die zum Erstellen eines oder mehrerer verknüpfter Entitätszellenwerte führt. 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.
4. 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.
5. 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.

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. Legen Sie in Excel.LinkedEntityDataDomainCreateOptions auf eine Textzeichenfolge wie Contoso oder den Namen Ihres Add-Ins festdataProvider. 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.

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 wird gezeigt, wie TypeScript-Code für ein Excel-Add-In geschrieben wird, das als Datenanbieter für Contoso fungiert. In diesem Beispiel stellt das Add-In drei Datendomänen bereit: Produkte, Kategorien und Lieferanten.

Registrieren der Datendomänen

Registrieren Sie zunächst jede Datendomäne, die Ihr Add-In unterstützt. In diesem Beispiel lautet der Name des Datenanbieters Contoso , und die Domänen sind Produkte, Kategorien und Lieferanten.

Verwenden Sie Excel.LinkedEntityDataDomainCreateOptions , um jede Domäne zu definieren, einschließlich der Funktion zum Laden von verknüpften Entitäten, die Excel aufrufen soll. Fügen Sie dann jede Domäne der Workbook.linkedEntityDataDomains-Auflistung hinzu. Registrieren Sie Domänen, wenn Sie Ihr Office-Add-In initialisieren.

Der folgende Code registriert die Datendomänen Produkte, Kategorien und Lieferanten .

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 Arbeitsblattzelle einzufügen.

• Erstellen Sie eine Befehlsschaltfläche im Menüband oder eine Schaltfläche im 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 Beispiel wird ein neuer verknüpfter Entitätszellenwert in die ausgewählte Zelle eingefügt. Sie können diesen Code über einen Menübandbefehl oder über eine Schaltfläche im Aufgabenbereich aufrufen.

Beachten Sie die folgenden Anforderungen:

• 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 diesen Wert an Die Funktion zum Laden von verknüpften 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();
    });
}

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. Dieser Fehler 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, können Benutzer sie jederzeit manuell aktualisieren, z. B. durch Auswahl von Daten>aktualisieren alle. Sie können auch einen oder mehrere der folgenden Aktualisierungsmodi konfigurieren.

• manual: Aktualisiert Daten nur, wenn der Benutzer sich für die Aktualisierung entscheidet. Dies ist der Standardmodus. Die manuelle Aktualisierung ist immer verfügbar, auch wenn der Aktualisierungsmodus auf onLoad oder periodicfestgelegt ist.
• onLoad: Aktualisiert Daten, wenn die Datendomäne registriert ist. Dies geschieht in der Regel beim Laden des Add-Ins. Danach aktualisieren Benutzer die Daten manuell. Wenn Sie Beim Öffnen der Arbeitsmappe Daten 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: Aktualisiert Daten, wenn die Datendomäne registriert ist, und aktualisiert sie dann in einem angegebenen Intervall erneut. Sie können z. B. alle 300 Sekunden aktualisieren, was der Mindestwert ist. Excel rundet das Intervall auf die nächste Minute auf, da es nur in Ganzen-Minuten-Schritten aktualisiert 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

Sie können die meisten Add-In-Funktionen für verknüpfte Entitäten debuggen, indem Sie die Anleitung unter Übersicht über das Debuggen von Office-Add-Ins befolgen. Die Dienstfunktion zum Laden von verknüpften Entitäten kann jedoch in einer freigegebenen Runtime oder in einer reinen JavaScript-Runtime ausgeführt werden, die auch als Runtime für benutzerdefinierte Funktionen bezeichnet wird. Wenn Sie die Funktion in einer reinen JavaScript-Runtime implementieren, verwenden Sie das Debuggen von benutzerdefinierten Funktionen in einer nicht freigegebenen Runtime.

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. Es handelt sich hierbei um ein beabsichtigtes Verhalten. Dieses Verhalten ist auch der Grund, warum Sie jedes basicType Mal, Error wenn Sie einen verknüpften Entitätszellenwert einfügen oder aktualisieren, #VALUE! auf und festlegenbasicValue. Dieser Fehler ist der Fallback, den Excel für ältere Versionen verwendet.

Bewährte Methoden

• Verwenden Sie keine Ausrufezeichen in den entityID Werten oder domainId .
• Registrieren Sie Datendomänen für verknüpfte Entitäten in Ihrem Office.onReady Initialisierungscode, damit Benutzer die Werte der verknüpften Entitätszellen aktualisieren können, sobald das Add-In geladen wird.
• Ä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
• Verwenden von Datentypen in Excel-Add-Ins
• Verwenden von Karten mit Zellwertdatentypen
• Hinzufügen von Eigenschaften zu Excel-Basiszellenwerten
• Benutzerdefinierte Funktionen und Datentypen