Поделиться через

Создание значений ячеек связанной сущности

Значения ячеек связанных сущностей интегрируют типы данных из внешних источников данных и могут отображать данные как сущности карта, например значения обычных сущностей. Они позволяют масштабировать типы данных для представления больших наборов данных без скачивания всех данных в книгу. Домены данных Stocks и Geography, доступные в пользовательском интерфейсе Excel, предоставляют значения связанных ячеек сущностей. В этой статье объясняется, как создать собственный поставщик данных в надстройке Excel, чтобы предоставить пользовательские значения для конечных пользователей.

Значения ячеек связанной сущности связаны с внешним источником данных. Они предоставляют следующие преимущества по сравнению с обычными значениями сущностей.

  • Значения ячеек связанной сущности могут быть вложенными, а значения вложенных ячеек связанных сущностей не извлекаются до тех пор, пока не будет указана ссылка; либо пользователем, либо листом. Это помогает уменьшить размер файла и повысить производительность книги.
  • Excel использует кэш, чтобы разные ячейки могли легко ссылаться на одно и то же значение ячейки связанной сущности. Это также повышает производительность книги.

В этой статье рассматриваются сведения, описанные в следующих статьях. Мы рекомендуем прочитать следующие статьи, прежде чем изучать, как создавать собственные значения ячеек связанной сущности.

Ключевые понятия

Значения ячеек связанной сущности предоставляют пользователю данные, связанные из внешнего источника данных. Пользователь может просматривать их как значение сущности карта.

Снимок экрана: данные значения сущности, карта для связанного типа данных Seattle Geography на листе.

Как и значения обычных сущностей, на значения связанных ячеек сущностей можно ссылаться в формулах.

Снимок экрана: использование точечной нотации в формуле с использованием =A1. Отображение полей для типа данных Seattle Geography.

Определения

Следующие определения являются основой для понимания того, как реализовать собственные значения ячеек связанной сущности.

  • Домен данных связанной сущности — домен данных связанной сущности описывает общую категорию, к которой принадлежит сущность. Некоторые примеры — сотрудники, организации или автомобили.
  • Значение ячейки связанной сущности — экземпляр, созданный из домена данных. Примером является значение сотрудника по имени Джо. Его можно отобразить как значение сущности карта.
  • Поставщик данных . Поставщик данных распознается Excel в качестве источника данных для одного или нескольких зарегистрированных доменов данных связанных сущностей.
  • Функция службы загрузки связанных сущностей . Каждый домен данных связанной сущности определяет функцию службы загрузки, которая выступает в качестве источника данных для этого домена. Функция службы загрузки связанной сущности обрабатывает запросы из Excel на получение значений ячеек связанной сущности для книги. Его можно реализовать как пользовательскую функцию TypeScript или JavaScript.

Как надстройка предоставляет значения ячеек связанной сущности

На этой схеме показаны шаги, которые выполняются при загрузке надстройки, а затем вставке нового значения связанной сущности в ячейку. В следующем описании объясняется, что происходит на каждом этапе процесса.

Схема: пять шагов для надстройки для регистрации доменов данных и обработки запросов из Excel для получения свойств из значения связанной ячейки сущности.

  1. Excel загружает надстройку, а надстройка регистрирует все домены данных связанных сущностей, которые она поддерживает. Каждая регистрация включает идентификатор функции службы загрузки связанной сущности. Этот идентификатор вызывается позже Excel для запроса значений свойств для значения ячейки связанной сущности из домена данных связанной сущности. В этом примере зарегистрирован один домен данных с именем Products .
  2. Excel отслеживает каждый зарегистрированный домен данных связанной сущности в коллекции доменов данных связанной сущности. Это позволяет Excel вызывать функцию службы загрузки связанной сущности, когда данные требуются для значения ячейки связанной сущности.
  3. Надстройка вставляет новое значение ячейки связанной сущности на лист. В этом примере создается новое значение ячейки связанной сущности для продукта Chai. Обычно это происходит из-за того, что пользователь нажимает кнопку в надстройке, что приводит к созданию одного или нескольких значений связанной ячейки сущности. При создании новых значений ячеек связанной сущности они содержат только начальную текстовую строку, отображаемую в ячейке. Excel вызывает функцию службы загрузки связанной сущности, чтобы получить оставшиеся значения свойств. Надстройка также может создавать значения связанных ячеек сущностей из пользовательских функций.
  4. Excel вызывает функцию службы загрузки связанной сущности, зарегистрированную на шаге 1. Это происходит каждый раз при создании нового значения ячейки связанной сущности или при обновлении данных. Excel вызывает функцию службы загрузки связанной сущности, чтобы получить все значения свойств.
  5. Функция службы загрузки связанной сущности возвращает актуальное значение ячейки связанной сущности (Excel.LinkedEntityCellValue) для идентификатора связанной сущности (Excel.LinkedEntityId), запрошенного Excel. Как правило, функция службы загрузки связанной сущности запрашивает внешний источник данных, чтобы получить значения и создать значение ячейки связанной сущности. В этом примере возвращаются значения для идентификатора продукта, категории, количества и цены .

Примечание.

Если Excel требуется несколько значений ячеек связанной сущности, идентификаторы связанных сущностей передаются в виде пакета в функцию службы загрузки связанной сущности. Затем служба загрузки связанной сущности возвращает пакетный результат всех значений.

В следующих разделах содержатся дополнительные сведения о терминах, определенных ранее в этой статье.

Поставщик данных

Ваша надстройка является поставщиком данных и распознается Excel в качестве источника данных для одного или нескольких зарегистрированных доменов данных. Надстройка предоставляет одну или несколько функций поставщика данных, которые возвращают данные для значений связанных ячеек сущности. Поставщик данных определяется текстовой строкой, например Contoso или именем надстройки. Имя должно быть уникальным в пределах надстройки.

Домены данных связанной сущности

Поставщик данных (надстройка) регистрирует один или несколько доменов данных. Домен данных описывает сущность в Excel. Например, поставщик данных может предоставить домены данных продуктов и категорий . Домены должны быть зарегистрированы в Excel, чтобы они могли работать с этими доменами для получения и отображения значений связанных ячеек сущности и выполнения вычислений.

Домен данных описывает в Excel следующие атрибуты:

  • Имя поставщика данных, с которым он связан.
  • Идентификатор домена для уникальной идентификации, например продуктов.
  • Отображаемое имя пользователя, например Products.
  • Функция службы загрузки связанной сущности, вызываемая, когда Excel требуется значение ячейки связанной сущности.
  • Указанный режим обновления и интервал, описывающий частоту обновления.

Примером домена данных связанной сущности является домен данных Geography в Excel, который предоставляет значения ячеек связанной сущности для городов.

Значение ячейки связанной сущности

Значение ячейки связанной сущности — это экземпляр, созданный из домена данных. Примером является значение для Сиэтла из домена данных Geography. В нем отображается значение сущности, карта например значения обычной ячейки сущности.

Снимок экрана: данные значения сущности, карта для связанного типа данных Seattle Geography на листе.

Так как значения ячеек связанной сущности связаны с доменом данных, их можно обновить. Кроме того, значения вложенных ячеек связанной сущности не извлекаются, если пользователь не запросит их (например, просмотр сущности карта). А значения вложенных ячеек сущностей не сохраняются на листе, если на них не ссылаются (например, на формулу). Это уменьшает размер файла и повышает производительность.

Функция службы загрузки связанной сущности

Для каждого домена данных требуется функция, которую Excel может вызывать, когда ей нужны значения связанной ячейки сущности. Надстройка предоставляет службу как функцию JavaScript или TypeScript, помеченную @linkedEntityLoadService. Для оптимальной производительности рекомендуется создать только одну функцию службы загрузки. Excel отправляет все запросы на значения ячеек связанной сущности в виде пакета в функцию службы загрузки.

Создание поставщика данных с доменами данных

В следующих разделах этой статьи показано, как написать код TypeScript для реализации надстройки Excel, которая является поставщиком данных для Contoso. Он предоставляет два домена данных с именами Products и Categories.

Регистрация доменов данных

Давайте рассмотрим код для регистрации новых доменов с именем Products and Categories. Имя поставщика данных — Contoso. Когда надстройка загружается, она сначала регистрирует домены данных в Excel.

Используйте тип Excel.LinkedEntityDataDomainCreateOptions , чтобы описать нужные параметры, включая функцию, используемую в качестве службы загрузки связанной сущности. Затем добавьте домен в коллекцию Workbook.linkedEntityDataDomains . Рекомендуется регистрировать домены при инициализации надстройки Office. В следующем коде показано, как зарегистрировать домены данных Products, Categories и Suppliers .

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();
    });
});

Вставка значения ячейки связанной сущности

Существует два способа вставки значения связанной ячейки сущности в ячейку на листе.

  • Создайте кнопку команды на ленте или кнопку в области задач. Когда пользователь нажимает кнопку, код вставляет значение связанной ячейки сущности.
  • Создайте пользовательскую функцию, которая возвращает значение ячейки связанной сущности.

В следующем примере кода показано, как вставить новое значение ячейки связанной сущности в выбранную ячейку. Этот код можно вызвать с помощью кнопки команды на ленте или кнопки в области задач. Примечания о следующем коде:

  • Необходимо указать для всех возвращаемых значений serviceId268436224 ячейки связанной сущности. Это сообщает Excel о том, что значение ячейки связанной сущности связано с надстройкой Excel.
  • Необходимо указать culture. Excel передаст его в функцию службы загрузки связанной сущности, чтобы вы могли сохранить исходный язык и региональные параметры при открытии книги с другим языком и региональными параметрами.
  • Свойство text отображается пользователю в ячейке при обновлении значения данных связанной сущности. Это не позволит пользователю увидеть пустую ячейку во время завершения обновления.
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();
    });
}

Примечание.

Не используйте восклицательные знаки в значениях entityID или domainId .

В следующем примере кода показано, как вставить значение ячейки связанной сущности с помощью пользовательской функции. Пользователь может получить значение связанной ячейки сущности, введя =CONTOSO.GETPRODUCTBYID("productid") в любую ячейку. Примечания к предыдущему примеру кода также относятся к этому примеру.

/**
 * 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;
}

Реализация функции службы загрузки связанных сущностей

Надстройка должна предоставлять функцию службы загрузки связанной сущности для обработки запросов из Excel, если для любых значений ячеек связанной сущности требуются значения свойств. Функция идентифицируется с помощью тега @linkedEntityLoadService JSDoc.

В следующем примере кода показано, как создать функцию, которая обрабатывает запросы данных из Excel для доменов данных Products и Categories . Примечания к следующему коду:

  • Он использует вспомогательные функции для создания значений связанных ячеек сущности. Этот код будет показан позже.
  • При возникновении ошибки возникает CustomFunctions.ErrorCode.notAvailable ошибка. Отображается #CONNECT! в ячейке, которую видит пользователь.
// 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;
    }
}

В следующем примере кода показана вспомогательная функция для создания значения ячейки связанной с продуктом сущности. Эта функция вызывается предыдущим кодом contosoLoadService для создания связанной сущности для определенного идентификатора продукта. Примечания к следующему коду:

  • В нем используются те же параметры, что и в предыдущем insertProduct примере для typeсвойств , idи text .
  • Он включает в себя дополнительные свойства, относящиеся к домену данных Products , такие как Product Name и Unit Price.
  • Он создает отложенную вложенную связанную сущность для категории продукта. Свойства для категории не запрашиваются до тех пор, пока они не потребуются.
/** 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;
}

В следующем примере кода показана вспомогательная функция для создания значения ячейки связанной сущности категории. Эта функция вызывается предыдущим кодом contosoLoadService для создания связанной сущности для определенного идентификатора категории.

/** 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;
}

В следующем примере кода показана вспомогательная функция для создания значения ячейки связанной сущности поставщика. Эта функция вызывается предыдущим кодом contosoLoadService для создания связанной сущности для определенного идентификатора поставщика.

/** 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;
}

Следующий пример кода содержит примеры данных, которые можно использовать с предыдущими примерами кода.

/// 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"
    }];

Параметры обновления данных

При регистрации домена данных пользователь может обновить его вручную в любое время, например выбрав Обновить все на вкладке Данные . Существует три режима обновления, которые можно указать для домена данных.

  • manual— Данные обновляются только в том случае, если пользователь решает обновить. Это режим по умолчанию. Обновление вручную всегда может выполняться пользователем, даже если для режима обновления задано значение onLoad или periodic.
  • onLoad— данные обновляются при регистрации домена данных (обычно при загрузке надстройки). После этого данные обновляются пользователем только вручную. Если вы хотите обновить данные при открытии книги, настройте надстройку для загрузки при открытии документа. Дополнительные сведения см. в статье Запуск кода в надстройке Office при открытии документа.
  • periodic— данные обновляются при регистрации домена данных (обычно при загрузке надстройки). После этого данные постоянно обновляются после указанного интервала времени. Например, можно указать, что домен данных обновляется каждые 300 секунд (это минимальное значение). Количество секунд всегда округляется до ближайшего числа минут, так как интервал обновления выполняется только в минутах.

В следующем примере кода показано, как настроить домен данных для обновления при загрузке, а затем продолжить обновление каждые 5 минут.

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
    ]
};

Вы также можете программно запросить обновление домена данных связанной сущности с помощью любого из следующих методов.

  • LinkedEntityDataDomain.refresh() — обновляет все LinkedEntityCellValue объекты домена данных связанной сущности.
  • LinkedEntityDataDomainCollection.refreshAll() — обновляет все LinkedEntityCellValue объекты всех доменов данных связанных сущностей в коллекции.

Методы обновления запрашивают обновление, которое происходит асинхронно. Чтобы определить результаты обновления, прослушайте onRefreshCompleted событие. В следующем примере кода показан пример прослушивания onRefreshCompleted события.

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;
}

Обработка ошибок со службой загрузки связанной сущности

Когда Excel вызывает надстройку для получения данных для значения ячейки связанной сущности, может возникнуть ошибка. Если Excel вообще не удается подключиться к надстройке, например когда надстройка не загружена, Excel отобразит #CONNECT! ошибку для пользователя.

Если функция службы загрузки связанной сущности обнаруживает ошибку, она должна вызвать ошибку notAvailableError . Это приводит к тому, что Excel будет отображаться #CONNECT! для пользователя.

В следующем коде показано, как обработать ошибку в функции службы загрузки связанной сущности.

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;
    }
}

Отладка службы загрузки связанной сущности

Большинство функциональных возможностей надстроек для типов данных связанных сущностей можно отладить с помощью инструкций, приведенных в статье Обзор отладки надстроек Office. Однако функция службы загрузки связанной сущности может быть реализована в общей среде выполнения или в среде выполнения, доступной только для JavaScript (также известной как среда выполнения пользовательских функций). Если вы решили реализовать функцию в среде выполнения, доступной только для JavaScript, используйте руководство по отладке пользовательских функций в необщей среде выполнения .

Функция службы загрузки связанных сущностей использует архитектуру пользовательских функций независимо от используемой среды выполнения. Однако существуют существенные отличия от обычных пользовательских функций.

Функции службы загрузки связанных сущностей имеют следующие отличия от пользовательских функций:

  • Они не отображаются для конечных пользователей для использования в формулах.
  • Они не поддерживают теги @streaming JSDoc или @volatile. Если эти теги используются, пользователь увидит ошибку #CALC! .

Функции службы загрузки связанных сущностей имеют следующие сходства с пользовательскими функциями:

Поведение в Excel 2019 и более ранних версиях

Если кто-то открывает лист со значениями ячеек связанных сущностей в более старой версии Excel, которая не поддерживает значения ячеек связанных сущностей, Excel отображает значения ячеек как ошибки. Это спроектированное поведение. Поэтому при каждом вставке или обновлении значения ячейки basicTypeError связанной сущности basicValue для задается значение , а для — значение #VALUE! . Это ошибка, которую Excel использует в качестве резервного варианта в более старых версиях.

Лучшие методики

  • Не используйте восклицательные знаки в значениях entityID или domainId .
  • Зарегистрируйте домены данных связанных сущностей в коде Office.OnReady инициализации, чтобы у пользователя была возможность немедленного обновления значений ячеек связанной сущности.
  • После публикации надстройки не изменяйте идентификаторы доменов связанных данных сущности. Согласованные идентификаторы в одних и том же логических объектах помогают повысить производительность.
  • Всегда укажите text свойство при создании нового значения ячейки связанной сущности. Это значение отображается, когда Excel вызывает функцию поставщика данных для получения оставшихся значений свойств. В противном случае пользователь видит пустую ячейку, пока не будут получены данные.

См. также

  • Last updated on