Skip to content

Commit 28f6710

Browse files
alison-mkAlexJerabek
alison-mk
and
AlexJerabek
authored
[Excel] Add snippets for worksheet events and CellValue type union (#1052)
* [Excel] (Data types) Map existing snippet to CellValue * [Excel] (Events) Add WorksheetNamedChanged to existing snippet * Update snippet metadata * [Excel] (Events) Add onMoved event handler to existing snippet * Update snippet metadata * Run npm start * Apply suggestions from code review Co-authored-by: Alex Jerabek <38896772+AlexJerabek@users.noreply.github.com> * Add second new worksheet button per feedback * Adjust activate worksheet UX --------- Co-authored-by: Alex Jerabek <38896772+AlexJerabek@users.noreply.github.com>
1 parent 0cdf23a commit 28f6710

File tree

6 files changed

+195
-33
lines changed

6 files changed

+195
-33
lines changed

‎playlists-prod/excel.yaml‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -604,24 +604,22 @@
604604
name: Workbook and worksheet collection events
605605
fileName: events-workbook-and-worksheet-collection.yaml
606606
description: >-
607-
Registers event handlers that run when a worksheet is added, activated, or
608-
deactivated, or when the settings of a workbook are changed.
607+
Registers event handlers that run when a worksheet is added, activated,
608+
deactivated, moved, or when the settings of a workbook are changed.
609609
rawUrl: >-
610610
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml
611611
group: Events
612612
api_set:
613-
ExcelApi: '1.7'
613+
ExcelApi: '1.17'
614614
- id: excel-events-worksheet
615615
name: Worksheet events
616616
fileName: events-worksheet.yaml
617-
description: >-
618-
Registers event handlers that run when data is changed in worksheet, the
619-
selected range changes in a worksheet, or the worksheet is recalculated.
617+
description: Registers event handlers that run when worksheet events occur.
620618
rawUrl: >-
621619
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml
622620
group: Events
623621
api_set:
624-
ExcelApi: '1.7'
622+
ExcelApi: '1.17'
625623
- id: excel-events-worksheet-protection
626624
name: Worksheet protection events
627625
fileName: events-worksheet-protection.yaml

‎playlists/excel.yaml‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -604,24 +604,22 @@
604604
name: Workbook and worksheet collection events
605605
fileName: events-workbook-and-worksheet-collection.yaml
606606
description: >-
607-
Registers event handlers that run when a worksheet is added, activated, or
608-
deactivated, or when the settings of a workbook are changed.
607+
Registers event handlers that run when a worksheet is added, activated,
608+
deactivated, moved, or when the settings of a workbook are changed.
609609
rawUrl: >-
610610
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml
611611
group: Events
612612
api_set:
613-
ExcelApi: '1.7'
613+
ExcelApi: '1.17'
614614
- id: excel-events-worksheet
615615
name: Worksheet events
616616
fileName: events-worksheet.yaml
617-
description: >-
618-
Registers event handlers that run when data is changed in worksheet, the
619-
selected range changes in a worksheet, or the worksheet is recalculated.
617+
description: Registers event handlers that run when worksheet events occur.
620618
rawUrl: >-
621619
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/30-events/events-worksheet.yaml
622620
group: Events
623621
api_set:
624-
ExcelApi: '1.7'
622+
ExcelApi: '1.17'
625623
- id: excel-events-worksheet-protection
626624
name: Worksheet protection events
627625
fileName: events-worksheet-protection.yaml

‎samples/excel/30-events/events-workbook-and-worksheet-collection.yaml‎

Lines changed: 71 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
11
order: 14
22
id: excel-events-workbook-and-worksheet-collection
33
name: Workbook and worksheet collection events
4-
description: Registers event handlers that run when a worksheet is added, activated, or deactivated, or when the settings of a workbook are changed.
4+
description: Registers event handlers that run when a worksheet is added, activated, deactivated, moved, or when the settings of a workbook are changed.
55
author: OfficeDev
66
host: EXCEL
77
api_set:
8-
ExcelApi: '1.7'
8+
ExcelApi: '1.17'
99
script:
1010
content: |-
1111
document.getElementById("register-on-add-handler").addEventListener("click", () => tryCatch(registerOnAddHandler));
1212
document.getElementById("add-worksheet").addEventListener("click", () => tryCatch(addWorksheet));
1313
1414
document.getElementById("register-on-activate-handler").addEventListener("click", () => tryCatch(registerOnActivateHandler));
15+
document.getElementById("activate-worksheet").addEventListener("click", () => tryCatch(activateWorksheet));
1516
document.getElementById("register-on-deactivate-handler").addEventListener("click", () => tryCatch(registerOnDeactivateHandler));
1617
document.getElementById("delete-worksheet").addEventListener("click", () => tryCatch(deleteWorksheet));
1718
19+
document.getElementById("register-on-moved-handler").addEventListener("click", () => tryCatch(registerOnMovedHandler));
20+
document.getElementById("move-worksheet").addEventListener("click", () => tryCatch(moveWorksheet));
21+
1822
document.getElementById("create-setting").addEventListener("click", () => tryCatch(createSetting));
1923
document.getElementById("change-setting").addEventListener("click", () => tryCatch(changeSetting));
2024
document.getElementById("register-settings-changed-handler").addEventListener("click", () => tryCatch(registerSettingsChangedHandler));
@@ -35,7 +39,7 @@ script:
3539
sheet.load("name, position");
3640
3741
await context.sync();
38-
console.log('Added worksheet named "${sheet.name}" in position ${sheet.position}');
42+
console.log(`Added worksheet named "${sheet.name}" in position ${sheet.position}`);
3943
});
4044
}
4145
@@ -64,6 +68,16 @@ script:
6468
});
6569
}
6670
71+
async function activateWorksheet() {
72+
await Excel.run(async (context) => {
73+
// Switching between worksheets triggers the onActivate event.
74+
const sheet = context.workbook.worksheets.add();
75+
sheet.activate();
76+
77+
await context.sync();
78+
});
79+
}
80+
6781
async function registerOnDeactivateHandler() {
6882
await Excel.run(async (context) => {
6983
let sheets = context.workbook.worksheets;
@@ -99,6 +113,50 @@ script:
99113
});
100114
}
101115
116+
async function registerOnMovedHandler() {
117+
await Excel.run(async (context) => {
118+
let sheets = context.workbook.worksheets;
119+
sheets.load("items");
120+
await context.sync();
121+
122+
if (sheets.items.length > 0) {
123+
let sheet = sheets.items[0];
124+
sheets.onMoved.add(onWorksheetMoved);
125+
await context.sync();
126+
console.log("A handler has been registered for the worksheet onMoved event.");
127+
} else {
128+
console.log("No worksheets available to register onMoved event.");
129+
}
130+
});
131+
}
132+
133+
async function moveWorksheet() {
134+
await Excel.run(async (context) => {
135+
let sheets = context.workbook.worksheets;
136+
sheets.load("items");
137+
await context.sync();
138+
139+
if (sheets.items.length > 1) {
140+
let firstSheet = sheets.items[0];
141+
firstSheet.position = sheets.items.length - 1;
142+
await context.sync();
143+
console.log(`Moved worksheet "${firstSheet.name}" to the end.`);
144+
} else {
145+
console.log("Need at least 2 worksheets to demonstrate moving.");
146+
}
147+
});
148+
}
149+
150+
async function onWorksheetMoved(event) {
151+
await Excel.run(async (context) => {
152+
console.log("Handler for worksheet onMoved event has been triggered.");
153+
console.log(` Worksheet ID: ${event.worksheetId}`);
154+
console.log(` Position before move: ${event.positionBefore}`);
155+
console.log(` Position after move: ${event.positionAfter}`);
156+
console.log(` Event source: ${event.source}`);
157+
});
158+
}
159+
102160
async function createSetting() {
103161
await Excel.run(async (context) => {
104162
const settings = context.workbook.settings;
@@ -172,20 +230,22 @@ script:
172230
template:
173231
content: |-
174232
<section>
175-
<p>This sample shows how to register and use handlers for when a worksheet is added, activated, or deactivated, or when the settings of a workbook are changed.</p>
233+
<p>This sample shows how to register and use event handlers for workbook and worksheet collection events.</p>
176234
</section>
177235
<section>
178236
<h3>Try it out</h3>
179-
<p><b>Added</b></p>
180-
<section>
181-
<button id="register-on-add-handler">Register onAdded event handler</button>
182-
<button id="add-worksheet">Add worksheet</button>
183-
</section>
184-
<p><b>Activated/Deactivated</b></p>
237+
<h4>Added</h4>
238+
<button id="register-on-add-handler">Register onAdded event handler</button>
239+
<button id="add-worksheet">Add worksheet</button>
240+
<h4>Activated and deactivated</h4>
185241
<button id="register-on-activate-handler">Register onActivated event handler</button>
242+
<button id="activate-worksheet">Add and activate worksheet</button>
186243
<button id="register-on-deactivate-handler">Register onDeactivated event handler</button>
187244
<button id="delete-worksheet">Delete worksheet</button>
188-
<p><b>Settings</b></p>
245+
<h4>Worksheet moved</h4>
246+
<button id="register-on-moved-handler">Register onMoved handler</button>
247+
<button id="move-worksheet">Move first worksheet to end</button>
248+
<h4>Settings changed</h4>
189249
<button id="create-setting">Create setting</button>
190250
<button id="register-settings-changed-handler">Register settings-changed handler</button>
191251
<button id="change-setting">Change setting</button>

‎samples/excel/30-events/events-worksheet.yaml‎

Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
order: 15
22
id: excel-events-worksheet
33
name: Worksheet events
4-
description: Registers event handlers that run when data is changed in worksheet, the selected range changes in a worksheet, or the worksheet is recalculated.
4+
description: Registers event handlers that run when worksheet events occur.
55
author: OfficeDev
66
host: EXCEL
77
api_set:
8-
ExcelApi: '1.7'
8+
ExcelApi: '1.17'
99
script:
1010
content: |-
1111
document.getElementById("setup").addEventListener("click", () => tryCatch(setup));
@@ -19,6 +19,9 @@ script:
1919
2020
document.getElementById("delete-data").addEventListener("click", () => tryCatch(deleteData));
2121
22+
document.getElementById("register-on-name-changed-handler").addEventListener("click", () => tryCatch(registerOnNameChangedHandler));
23+
document.getElementById("change-worksheet-name").addEventListener("click", () => tryCatch(changeWorksheetName));
24+
2225
async function registerSelectionChangedHandler() {
2326
await Excel.run(async (context) => {
2427
let sheet = context.workbook.worksheets.getItem("Sample");
@@ -131,11 +134,44 @@ script:
131134
console.log(` Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
132135
}
133136
});
137+
}
138+
139+
async function registerOnNameChangedHandler() {
140+
await Excel.run(async (context) => {
141+
let sheet = context.workbook.worksheets.getItem("Sample");
142+
sheet.onNameChanged.add(onNameChanged);
143+
await context.sync();
144+
145+
console.log("Added a worksheet-level onNameChanged event handler.");
146+
});
147+
}
148+
149+
async function changeWorksheetName() {
150+
await Excel.run(async (context) => {
151+
let sheet = context.workbook.worksheets.getItem("Sample");
152+
153+
// Change the worksheet name to trigger the event.
154+
sheet.name = `NewWorksheetName`;
155+
await context.sync();
156+
157+
console.log(`Changed worksheet name to: ` + sheet.name);
158+
});
159+
}
160+
161+
async function onNameChanged(event: Excel.WorksheetNameChangedEventArgs) {
162+
await Excel.run(async (context) => {
163+
console.log(`Handler for worksheet onNameChanged event has been triggered.`);
164+
console.log(` Name before change: ` + event.nameBefore);
165+
console.log(` Name after change: ` + event.nameAfter);
166+
});
134167
}
135168
136169
async function setup() {
137170
await Excel.run(async (context) => {
171+
// Remove the previous sample worksheet.
138172
context.workbook.worksheets.getItemOrNullObject("Sample").delete();
173+
174+
// Create the main Sample worksheet with data.
139175
const sheet = context.workbook.worksheets.add("Sample");
140176
141177
let salesTable = sheet.tables.add("A1:F1", true);
@@ -170,24 +206,30 @@ script:
170206
template:
171207
content: |-
172208
<section>
173-
<p>This sample shows how to register and use an event handler for the worksheet onSelectionChanged event.</p>
209+
<p>This sample shows how to register and use event handlers for worksheet events.</p>
174210
</section>
175211
<section class="setup">
176212
<h3>Set up</h3>
177213
<button id="setup">Add sample data</button>
178214
</section>
179215
<section>
180216
<h3>Try it out</h3>
181-
<p><b>Selection Changed</b></p><section>
217+
<h4>Selection changed</h4>
182218
<button id="register-on-selection-changed-handler">Register onSelectionChanged handler</button>
183219
<button id="select-range">Select range</button>
184-
<p><b>Changed and Calculated</b></p>
220+
221+
<h4>Changed and calculated</h4>
185222
<button id="register-on-changed-handler">Register onChanged event handler</button>
186223
<button id="register-onCalculated-handler">Register onCalculated handler</button>
187224
<button id="recalculate">Change the value of E2</button>
188-
<p><b>Detect insert and delete shift directions</b></p>
189-
<p>Use the "Insert" and "Delete" buttons in the Excel UI to trigger the onChanged event. Or, use the following "Delete" button to see the properties returned by the event when a table row is removed.</p>
225+
226+
<h4>Detect insert and delete shift directions</h4>
227+
<p>Use the <strong>Insert</strong> and <strong>Delete</strong> buttons in the Excel UI to trigger the onChanged event. Or, use the following button to see the properties returned by the event when a table row is removed.</p>
190228
<button id="delete-data">Delete data from table</button>
229+
230+
<h4>Worksheet name changed</h4>
231+
<button id="register-on-name-changed-handler">Register onNameChanged handler</button>
232+
<button id="change-worksheet-name">Change worksheet name</button>
191233
</section>
192234
language: html
193235
style:

‎snippet-extractor-metadata/excel.xlsx‎

317 Bytes
Binary file not shown.

‎snippet-extractor-output/snippets.yaml‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -861,6 +861,42 @@ Excel.CellPropertiesLoadOptions#address:member:
861861
console.log(
862862
`Address: ${cellProperties.address}\nStyle: ${cellProperties.style}\nFill Color: ${cellProperties.format.fill.color}\nFont Color: ${cellProperties.format.font.color}`);
863863
});
864+
Excel.CellValue:type:
865+
- >-
866+
// Link to full sample:
867+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-web-image.yaml
868+
869+
870+
// This function inserts a web image into the currently selected cell.
871+
872+
await Excel.run(async (context) => {
873+
// Retrieve image data from the task pane and then clear the input fields.
874+
const imageUrl = (document.getElementById("url") as HTMLInputElement).value;
875+
const imageAltText = (document.getElementById("alt-text") as HTMLInputElement).value;
876+
clearForm();
877+
878+
// Load the active cell.
879+
const activeCell = context.workbook.getActiveCell();
880+
activeCell.load();
881+
await context.sync();
882+
883+
if (!imageUrl) {
884+
console.log("Please enter an image URL.");
885+
return;
886+
}
887+
888+
// Create a web image object and assign the image details.
889+
const webImage: Excel.WebImageCellValue = {
890+
type: "WebImage", /* The string equivalent of `Excel.CellValueType.webImage`. */
891+
address: imageUrl,
892+
altText: imageAltText
893+
};
894+
895+
// Insert web image into the active cell.
896+
activeCell.valuesAsJson = [[webImage]];
897+
898+
await context.sync();
899+
});
864900
Excel.CellValueConditionalFormat#format:member:
865901
- >-
866902
// Link to full sample:
@@ -8791,7 +8827,7 @@ Excel.WorksheetChangedEventArgs#changeDirectionState:member:
87918827
console.log(` Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
87928828
}
87938829
});
8794-
}
8830+
}
87958831
- >-
87968832
// Link to full sample:
87978833
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml
@@ -8835,6 +8871,34 @@ Excel.WorksheetChangedEventArgs#triggerSource:member:
88358871
console.log(` Cells deleted shift direction: ` + event.changeDirectionState.deleteShiftDirection);
88368872
}
88378873
});
8874+
}
8875+
Excel.WorksheetMovedEventArgs:event:
8876+
- >-
8877+
// Link to full sample:
8878+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml
8879+
8880+
8881+
async function onWorksheetMoved(event) {
8882+
await Excel.run(async (context) => {
8883+
console.log("Handler for worksheet onMoved event has been triggered.");
8884+
console.log(` Worksheet ID: ${event.worksheetId}`);
8885+
console.log(` Position before move: ${event.positionBefore}`);
8886+
console.log(` Position after move: ${event.positionAfter}`);
8887+
console.log(` Event source: ${event.source}`);
8888+
});
8889+
}
8890+
Excel.WorksheetNameChangedEventArgs:event:
8891+
- >-
8892+
// Link to full sample:
8893+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-worksheet.yaml
8894+
8895+
8896+
async function onNameChanged(event: Excel.WorksheetNameChangedEventArgs) {
8897+
await Excel.run(async (context) => {
8898+
console.log(`Handler for worksheet onNameChanged event has been triggered.`);
8899+
console.log(` Name before change: ` + event.nameBefore);
8900+
console.log(` Name after change: ` + event.nameAfter);
8901+
});
88388902
}
88398903
Excel.WorksheetCollection#onActivated:member:
88408904
- >-

0 commit comments

Comments
 (0)