visualizer / vendor / phpoffice / phpspreadsheet / docs / topics / worksheets.md

worksheets.md in Visualizer – Tables & Charts Manager with Built-in AI Generator 3.7.4, at vendor/phpoffice/phpspreadsheet/docs/topics/worksheets.md

129 lines 4.6 KB

Raw Download Zip

1	# Worksheets
2
3	A worksheet is a collection of cells, formulae, images, graphs, etc. It
4	holds all data necessary to represent a spreadsheet worksheet.
5
6	When you load a workbook from a spreadsheet file, it will be loaded with
7	all its existing worksheets (unless you specified that only certain
8	sheets should be loaded). When you load from non-spreadsheet files (such
9	as a CSV or HTML file) or from spreadsheet formats that don't identify
10	worksheets by name (such as SYLK), then a single worksheet called
11	"WorkSheet1" will be created containing the data from that file.
12
13	When you instantiate a new workbook, PhpSpreadsheet will create it with
14	a single worksheet called "WorkSheet1".
15
16	The `getSheetCount()` method will tell you the number of worksheets in
17	the workbook; while the `getSheetNames()` method will return a list of
18	all worksheets in the workbook, indexed by the order in which their
19	"tabs" would appear when opened in MS Excel (or other appropriate
20	Spreadsheet program).
21
22	Individual worksheets can be accessed by name, or by their index
23	position in the workbook. The index position represents the order that
24	each worksheet "tab" is shown when the workbook is opened in MS Excel
25	(or other appropriate Spreadsheet program). To access a sheet by its
26	index, use the `getSheet()` method.
27
28	``` php
29	// Get the second sheet in the workbook
30	// Note that sheets are indexed from 0
31	$spreadsheet->getSheet(1);
32	```
33
34
35	Methods also exist allowing you to reorder the worksheets in the
36	workbook.
37
38	To access a sheet by name, use the `getSheetByName()` method, specifying
39	the name of the worksheet that you want to access.
40
41	``` php
42	// Retrieve the worksheet called 'Worksheet 1'
43	$spreadsheet->getSheetByName('Worksheet 1');
44	```
45
46	Alternatively, one worksheet is always the currently active worksheet,
47	and you can access that directly. The currently active worksheet is the
48	one that will be active when the workbook is opened in MS Excel (or
49	other appropriate Spreadsheet program).
50
51	``` php
52	// Retrieve the current active worksheet
53	$spreadsheet->getActiveSheet();
54	```
55
56	You can change the currently active sheet by index or by name using the
57	`setActiveSheetIndex()` and `setActiveSheetIndexByName()` methods.
58
59	## Adding a new Worksheet
60
61	You can add a new worksheet to the workbook using the `createSheet()`
62	method of the `Spreadsheet` object. By default, this will be created as
63	a new "last" sheet; but you can also specify an index position as an
64	argument, and the worksheet will be inserted at that position, shuffling
65	all subsequent worksheets in the collection down a place.
66
67	``` php
68	$spreadsheet->createSheet();
69	```
70
71	A new worksheet created using this method will be called
72	`Worksheet<n>` where `<n>` is the lowest number possible to
73	guarantee that the title is unique.
74
75	Alternatively, you can instantiate a new worksheet (setting the title to
76	whatever you choose) and then insert it into your workbook using the
77	`addSheet()` method.
78
79	``` php
80	// Create a new worksheet called "My Data"
81	$myWorkSheet = new \PhpOffice\PhpSpreadsheet\Worksheet\Worksheet($spreadsheet, 'My Data');
82
83	// Attach the "My Data" worksheet as the first worksheet in the Spreadsheet object
84	$spreadsheet->addSheet($myWorkSheet, 0);
85	```
86
87	If you don't specify an index position as the second argument, then the
88	new worksheet will be added after the last existing worksheet.
89
90	## Copying Worksheets
91
92	Sheets within the same workbook can be copied by creating a clone of the
93	worksheet you wish to copy, and then using the `addSheet()` method to
94	insert the clone into the workbook.
95
96	``` php
97	$clonedWorksheet = clone $spreadsheet->getSheetByName('Worksheet 1');
98	$clonedWorksheet->setTitle('Copy of Worksheet 1');
99	$spreadsheet->addSheet($clonedWorksheet);
100	```
101
102	You can also copy worksheets from one workbook to another, though this
103	is more complex as PhpSpreadsheet also has to replicate the styling
104	between the two workbooks. The `addExternalSheet()` method is provided for
105	this purpose.
106
107	$clonedWorksheet = clone $spreadsheet1->getSheetByName('Worksheet 1');
108	$spreadsheet->addExternalSheet($clonedWorksheet);
109
110	In both cases, it is the developer's responsibility to ensure that
111	worksheet names are not duplicated. PhpSpreadsheet will throw an
112	exception if you attempt to copy worksheets that will result in a
113	duplicate name.
114
115	## Removing a Worksheet
116
117	You can delete a worksheet from a workbook, identified by its index
118	position, using the `removeSheetByIndex()` method
119
120	``` php
121	$sheetIndex = $spreadsheet->getIndex(
122	$spreadsheet->getSheetByName('Worksheet 1')
123	);
124	$spreadsheet->removeSheetByIndex($sheetIndex);
125	```
126
127	If the currently active worksheet is deleted, then the sheet at the
128	previous index position will become the currently active sheet.
129