From 50cf7f3a864dc016c208294d9865d46c1fd5e85a Mon Sep 17 00:00:00 2001 From: donlvMSFT Date: Tue, 24 Jun 2025 12:52:47 +0800 Subject: [PATCH 1/3] sample for using custom enum in custom function --- playlists-prod/excel.yaml | 9 ++ playlists/excel.yaml | 9 ++ .../custom-enum-function.yaml | 87 +++++++++++++++++++ view-prod/excel.json | 1 + view/excel.json | 1 + 5 files changed, 107 insertions(+) create mode 100644 samples/excel/16-custom-functions/custom-enum-function.yaml diff --git a/playlists-prod/excel.yaml b/playlists-prod/excel.yaml index 3b67eee0d..491d9814f 100644 --- a/playlists-prod/excel.yaml +++ b/playlists-prod/excel.yaml @@ -287,6 +287,15 @@ group: Custom Functions api_set: CustomFunctionsRuntime: 1.4 +- id: excel-custom-functions-custom-enum-function + name: Function with custom enum parameters + fileName: custom-enum-function.yaml + description: Use custom enum as parameters in custom functions for searching flights. + rawUrl: >- + https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-enum-function.yaml + group: Custom Functions + api_set: + CustomFunctionsRuntime: '1.5' - id: excel-custom-xml-parts-create-set-get-and-delete-custom-xml-parts name: Using custom XML parts fileName: create-set-get-and-delete-custom-xml-parts.yaml diff --git a/playlists/excel.yaml b/playlists/excel.yaml index 2a8b5c90f..fbfa1fd00 100644 --- a/playlists/excel.yaml +++ b/playlists/excel.yaml @@ -287,6 +287,15 @@ group: Custom Functions api_set: CustomFunctionsRuntime: 1.4 +- id: excel-custom-functions-custom-enum-function + name: Function with custom enum parameters + fileName: custom-enum-function.yaml + description: Use custom enum as parameters in custom functions for searching flights. + rawUrl: >- + https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-enum-function.yaml + group: Custom Functions + api_set: + CustomFunctionsRuntime: '1.5' - id: excel-custom-xml-parts-create-set-get-and-delete-custom-xml-parts name: Using custom XML parts fileName: create-set-get-and-delete-custom-xml-parts.yaml diff --git a/samples/excel/16-custom-functions/custom-enum-function.yaml b/samples/excel/16-custom-functions/custom-enum-function.yaml new file mode 100644 index 000000000..ef753810a --- /dev/null +++ b/samples/excel/16-custom-functions/custom-enum-function.yaml @@ -0,0 +1,87 @@ +order: 7 +id: excel-custom-functions-custom-enum-function +name: Function with custom enum parameters +description: Use custom enum as parameters in custom functions for searching flights. +host: EXCEL +api_set: + CustomFunctionsRuntime: '1.5' +script: + content: | + /** + * Enum representing different airports. + * @customenum {string} + */ + enum AirPorts { + // Beijing is the capital of China. + Beijing = "PEK", + + // Shanghai is a major financial hub in China. + Shanghai = "PVG", + + // Seattle is known for its tech industry and the Space Needle. + Seattle = "SEA", + + // San Francisco is famous for the Golden Gate Bridge and tech startups. + SanFrancisco = "SFO", + + // Tokyo is the capital of Japan and known for its modern architecture and culture. + Tokyo = "HND" + } + + /** + * Enum representing the days of the week. + * @customenum {number} + */ + enum DayOfWeek { + Monday = 1, + Tuesday = 2, + Wednesday = 3, + Thursday = 4, + Friday = 5, + Saturday = 6, + Sunday = 7 + } + + /** + * Function to get flight schedule. + * @customfunction + * @param {AirPorts} departure where the flight departs from + * @param {AirPorts} destination where the flight arrives + * @param {DayOfWeek[]} day days of the week when the flight is available + * @returns Available flight schedule + */ + function fetchFlightSchedule(departure: AirPorts, destination: AirPorts, day: DayOfWeek[]): string[][] { + const flights: string[][] = []; + flights.push(["Flights from " + departure + " to " + destination, "", "", "", ""]); + flights.push(["Day", "Flight Number", "Departure Time", "Arrival Time", "Price"]); + const daysOfWeek = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]; + + day.forEach((d) => { + const dayName = daysOfWeek[d - 1]; + const numberOfFlights = Math.floor(Math.random() * 3) + 1; // 1 to 3 flights + + for (let i = 0; i < numberOfFlights; i++) { + const flightNumber = `AA${Math.floor(Math.random() * 900) + 100}`; + const departureTime = `${Math.floor(Math.random() * 12) + 1}:00 ${Math.random() > 0.5 ? "AM" : "PM"}`; + const arrivalTime = `${Math.floor(Math.random() * 12) + 1}:00 ${Math.random() > 0.5 ? "AM" : "PM"}`; + const price = `$${Math.floor(Math.random() * 500) + 100}`; + + flights.push([dayName, flightNumber, departureTime, arrivalTime, price]); + } + }); + + return flights; + } + language: typescript +libraries: | + https://appsforoffice.microsoft.com/lib/1/hosted/office.js + @types/office-js + + office-ui-fabric-core@11.1.0/dist/css/fabric.min.css + office-ui-fabric-js@1.5.0/dist/css/fabric.components.min.css + + core-js@2.4.1/client/core.min.js + @types/core-js + + jquery@3.1.1 + @types/jquery@3.3.1 \ No newline at end of file diff --git a/view-prod/excel.json b/view-prod/excel.json index b267d8b88..acb89bd11 100644 --- a/view-prod/excel.json +++ b/view-prod/excel.json @@ -30,6 +30,7 @@ "excel-custom-functions-web-call": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/web-call-function.yaml", "excel-custom-functions-errors": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-functions-errors.yaml", "excel-data-types-custom-functions": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/data-types-custom-functions.yaml", + "excel-custom-functions-custom-enum-function": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-enum-function.yaml", "excel-custom-xml-parts-create-set-get-and-delete-custom-xml-parts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/18-custom-xml-parts/create-set-get-and-delete-custom-xml-parts.yaml", "excel-custom-xml-parts-test-xml-for-unique-namespace": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/18-custom-xml-parts/test-xml-for-unique-namespace.yaml", "excel-chart-chart-title-ts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/private-samples/excel/20-chart/chart-title-ts.yaml", diff --git a/view/excel.json b/view/excel.json index c805307dd..ab96d452e 100644 --- a/view/excel.json +++ b/view/excel.json @@ -30,6 +30,7 @@ "excel-custom-functions-web-call": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/web-call-function.yaml", "excel-custom-functions-errors": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-functions-errors.yaml", "excel-data-types-custom-functions": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/data-types-custom-functions.yaml", + "excel-custom-functions-custom-enum-function": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-enum-function.yaml", "excel-custom-xml-parts-create-set-get-and-delete-custom-xml-parts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/18-custom-xml-parts/create-set-get-and-delete-custom-xml-parts.yaml", "excel-custom-xml-parts-test-xml-for-unique-namespace": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/18-custom-xml-parts/test-xml-for-unique-namespace.yaml", "excel-chart-chart-title-ts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/private-samples/excel/20-chart/chart-title-ts.yaml", From d7939f83ca2836d996f82905229db630318cf1ce Mon Sep 17 00:00:00 2001 From: donlvMSFT Date: Wed, 25 Jun 2025 14:23:06 +0800 Subject: [PATCH 2/3] resolve comments --- playlists-prod/excel.yaml | 10 ++++++---- playlists/excel.yaml | 10 ++++++---- ...om-enum-function.yaml => custom-enum.yaml} | 20 +++++++++---------- view-prod/excel.json | 2 +- view/excel.json | 2 +- 5 files changed, 24 insertions(+), 20 deletions(-) rename samples/excel/16-custom-functions/{custom-enum-function.yaml => custom-enum.yaml} (78%) diff --git a/playlists-prod/excel.yaml b/playlists-prod/excel.yaml index 491d9814f..0b0a981ea 100644 --- a/playlists-prod/excel.yaml +++ b/playlists-prod/excel.yaml @@ -287,12 +287,14 @@ group: Custom Functions api_set: CustomFunctionsRuntime: 1.4 -- id: excel-custom-functions-custom-enum-function +- id: excel-custom-functions-custom-enum name: Function with custom enum parameters - fileName: custom-enum-function.yaml - description: Use custom enum as parameters in custom functions for searching flights. + fileName: custom-enum.yaml + description: >- + Use custom enum as parameters in a custom function that searches for + flights. rawUrl: >- - https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-enum-function.yaml + https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-enum.yaml group: Custom Functions api_set: CustomFunctionsRuntime: '1.5' diff --git a/playlists/excel.yaml b/playlists/excel.yaml index fbfa1fd00..8bcbfbcf2 100644 --- a/playlists/excel.yaml +++ b/playlists/excel.yaml @@ -287,12 +287,14 @@ group: Custom Functions api_set: CustomFunctionsRuntime: 1.4 -- id: excel-custom-functions-custom-enum-function +- id: excel-custom-functions-custom-enum name: Function with custom enum parameters - fileName: custom-enum-function.yaml - description: Use custom enum as parameters in custom functions for searching flights. + fileName: custom-enum.yaml + description: >- + Use custom enum as parameters in a custom function that searches for + flights. rawUrl: >- - https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-enum-function.yaml + https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-enum.yaml group: Custom Functions api_set: CustomFunctionsRuntime: '1.5' diff --git a/samples/excel/16-custom-functions/custom-enum-function.yaml b/samples/excel/16-custom-functions/custom-enum.yaml similarity index 78% rename from samples/excel/16-custom-functions/custom-enum-function.yaml rename to samples/excel/16-custom-functions/custom-enum.yaml index ef753810a..fd203e545 100644 --- a/samples/excel/16-custom-functions/custom-enum-function.yaml +++ b/samples/excel/16-custom-functions/custom-enum.yaml @@ -1,17 +1,17 @@ order: 7 -id: excel-custom-functions-custom-enum-function +id: excel-custom-functions-custom-enum name: Function with custom enum parameters -description: Use custom enum as parameters in custom functions for searching flights. +description: Use custom enum as parameters in a custom function that searches for flights. host: EXCEL api_set: CustomFunctionsRuntime: '1.5' script: content: | /** - * Enum representing different airports. + * A custom enum representing different airports. * @customenum {string} */ - enum AirPorts { + enum Airports { // Beijing is the capital of China. Beijing = "PEK", @@ -29,7 +29,7 @@ script: } /** - * Enum representing the days of the week. + * A custom enum representing the days of the week. * @customenum {number} */ enum DayOfWeek { @@ -43,14 +43,14 @@ script: } /** - * Function to get flight schedule. + * A function that shows how to use custom enums to get a flight schedule. * @customfunction - * @param {AirPorts} departure where the flight departs from - * @param {AirPorts} destination where the flight arrives - * @param {DayOfWeek[]} day days of the week when the flight is available + * @param {Airports} departure Where the flight departs. + * @param {Airports} destination Where the flight arrives. + * @param {DayOfWeek[]} day Days of the week when the flight is available. * @returns Available flight schedule */ - function fetchFlightSchedule(departure: AirPorts, destination: AirPorts, day: DayOfWeek[]): string[][] { + function fetchFlightSchedule(departure: Airports, destination: Airports, day: DayOfWeek[]): string[][] { const flights: string[][] = []; flights.push(["Flights from " + departure + " to " + destination, "", "", "", ""]); flights.push(["Day", "Flight Number", "Departure Time", "Arrival Time", "Price"]); diff --git a/view-prod/excel.json b/view-prod/excel.json index acb89bd11..464d0eaff 100644 --- a/view-prod/excel.json +++ b/view-prod/excel.json @@ -30,7 +30,7 @@ "excel-custom-functions-web-call": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/web-call-function.yaml", "excel-custom-functions-errors": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-functions-errors.yaml", "excel-data-types-custom-functions": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/data-types-custom-functions.yaml", - "excel-custom-functions-custom-enum-function": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-enum-function.yaml", + "excel-custom-functions-custom-enum": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/16-custom-functions/custom-enum.yaml", "excel-custom-xml-parts-create-set-get-and-delete-custom-xml-parts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/18-custom-xml-parts/create-set-get-and-delete-custom-xml-parts.yaml", "excel-custom-xml-parts-test-xml-for-unique-namespace": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/18-custom-xml-parts/test-xml-for-unique-namespace.yaml", "excel-chart-chart-title-ts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/private-samples/excel/20-chart/chart-title-ts.yaml", diff --git a/view/excel.json b/view/excel.json index ab96d452e..a03037bbd 100644 --- a/view/excel.json +++ b/view/excel.json @@ -30,7 +30,7 @@ "excel-custom-functions-web-call": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/web-call-function.yaml", "excel-custom-functions-errors": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-functions-errors.yaml", "excel-data-types-custom-functions": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/data-types-custom-functions.yaml", - "excel-custom-functions-custom-enum-function": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-enum-function.yaml", + "excel-custom-functions-custom-enum": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/16-custom-functions/custom-enum.yaml", "excel-custom-xml-parts-create-set-get-and-delete-custom-xml-parts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/18-custom-xml-parts/create-set-get-and-delete-custom-xml-parts.yaml", "excel-custom-xml-parts-test-xml-for-unique-namespace": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/18-custom-xml-parts/test-xml-for-unique-namespace.yaml", "excel-chart-chart-title-ts": "https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/private-samples/excel/20-chart/chart-title-ts.yaml", From 51db9a5e66e0114fb6dddfb9bdd20adc0f5d8325 Mon Sep 17 00:00:00 2001 From: donlvMSFT Date: Wed, 25 Jun 2025 14:27:56 +0800 Subject: [PATCH 3/3] resolve comment --- samples/excel/16-custom-functions/custom-enum.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/samples/excel/16-custom-functions/custom-enum.yaml b/samples/excel/16-custom-functions/custom-enum.yaml index fd203e545..3bff6245f 100644 --- a/samples/excel/16-custom-functions/custom-enum.yaml +++ b/samples/excel/16-custom-functions/custom-enum.yaml @@ -48,7 +48,7 @@ script: * @param {Airports} departure Where the flight departs. * @param {Airports} destination Where the flight arrives. * @param {DayOfWeek[]} day Days of the week when the flight is available. - * @returns Available flight schedule + * @returns The available flight schedule. */ function fetchFlightSchedule(departure: Airports, destination: Airports, day: DayOfWeek[]): string[][] { const flights: string[][] = [];