Работа с фигурами с помощью API JavaScript для Excel
Excel определяет фигуры как любой объект, который находится на слое документа Excel. Это означает, что все, что находится за пределами ячейки, является фигурой. В этой статье описывается использование геометрических фигур, линий и изображений в сочетании с API Shape и ShapeCollection . Диаграммы рассматриваются в собственной статье Работа с диаграммами с помощью API JavaScript для Excel.
На следующем рисунке показаны фигуры, образующие термометр.
Создание фигур
Фигуры создаются с помощью и хранятся в коллекции фигур листа (Worksheet.shapes). ShapeCollection имеет несколько .add* методов для этой цели. Все фигуры имеют имена и идентификаторы, созданные для них при добавлении в коллекцию. name Это свойства и id соответственно. name может быть задано надстройкой для простого получения с помощью ShapeCollection.getItem(name) метода .
Следующие типы фигур добавляются с помощью связанного метода.
| Shape | Добавление метода | Подпись |
|---|---|---|
| Геометрическая фигура | addGeometricShape | addGeometricShape(geometricShapeType: Excel.GeometricShapeType): Excel.Shape |
| Изображение (JPEG или PNG) | addImage | addImage(base64ImageString: string): Excel.Shape |
| Line | addLine | addLine(startLeft: number, startTop: number, endLeft: number, endTop: number, connectorType?: Excel.ConnectorType): Excel.Shape |
| Svg | addSvg | addSvg(xml: string): Excel.Shape |
| Текстовое поле | addTextBox | addTextBox(text?: string): Excel.Shape |
Геометрические фигуры
Геометрическая фигура создается с помощью ShapeCollection.addGeometricShape. Этот метод принимает перечисление GeometryShapeType в качестве аргумента.
В следующем примере кода создается прямоугольник 150 x 150 пикселей с именем Square , расположенный в 100 пикселях от верхней и левой сторон листа.
// This sample creates a rectangle positioned 100 pixels from the top and left sides
// of the worksheet and is 150x150 pixels.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let rectangle = shapes.addGeometricShape(Excel.GeometricShapeType.rectangle);
rectangle.left = 100;
rectangle.top = 100;
rectangle.height = 150;
rectangle.width = 150;
rectangle.name = "Square";
await context.sync();
});
изображения;
Изображения JPEG, PNG и SVG можно вставлять на лист в виде фигур. Метод ShapeCollection.addImage принимает строку в кодировке base64 в качестве аргумента. Это изображение в формате JPEG или PNG в строковой форме. ShapeCollection.addSvg также принимает строку, хотя этот аргумент — XML, определяющий рисунок.
В следующем примере кода показано, как файл изображения загружается FileReader в виде строки. Строка содержит метаданные base64, удаленные до создания фигуры.
// This sample creates an image as a Shape object in the worksheet.
let myFile = document.getElementById("selectedFile");
let reader = new FileReader();
reader.onload = (event) => {
Excel.run(function (context) {
let startIndex = reader.result.toString().indexOf("base64,");
let myBase64 = reader.result.toString().substr(startIndex + 7);
let sheet = context.workbook.worksheets.getItem("MyWorksheet");
let image = sheet.shapes.addImage(myBase64);
image.name = "Image";
return context.sync();
}).catch(errorHandlerFunction);
};
// Read in the image file as a data URL.
reader.readAsDataURL(myFile.files[0]);
Lines
Строка создается с ShapeCollection.addLineпомощью . Для этого метода требуются левое и верхнее поля начальной и конечной точек строки. Он также принимает перечисление ConnectorType , чтобы указать, как линия перевертывается между конечными точками. В следующем примере кода на листе создается прямая линия.
// This sample creates a straight line from [200,50] to [300,150] on the worksheet.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let line = shapes.addLine(200, 50, 300, 150, Excel.ConnectorType.straight);
line.name = "StraightLine";
await context.sync();
});
Линии могут быть соединены с другими объектами Shape. Методы connectBeginShape и connectEndShape присоединяют начало и конец линии к фигурам в указанных точках соединения. Расположение этих точек зависит от формы, но Shape.connectionSiteCount можно использовать , чтобы убедиться, что надстройка не подключается к точке, которая находится вне границ. Линия отсоединяется от любых присоединенных фигур с помощью disconnectBeginShape методов и disconnectEndShape .
В следующем примере кода линия MyLine соединяется с двумя фигурами с именами LeftShape и RightShape.
// This sample connects a line between two shapes at connection points '0' and '3'.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let line = shapes.getItem("MyLine").line;
line.connectBeginShape(shapes.getItem("LeftShape"), 0);
line.connectEndShape(shapes.getItem("RightShape"), 3);
await context.sync();
});
Перемещение и изменение размера фигур
Фигуры располагаются поверх листа. Их размещение определяется свойством left и top . Они выступают в качестве полей от соответствующих краев листа, а [0, 0] — это левый верхний угол. Их можно задать напрямую или изменить с учетом текущего incrementLeft положения с помощью методов и incrementTop . Насколько фигура повернута из позиции по умолчанию, также устанавливается таким образом, при этом свойством rotation является абсолютная величина incrementRotation , а методом, изменяющим существующее вращение.
Глубина фигуры относительно других фигур определяется свойством zorderPosition . Для этого используется setZOrder метод ShapeZOrder. setZOrder изменяет порядок текущей фигуры относительно других фигур.
Надстройка имеет несколько вариантов изменения высоты и ширины фигур. Задание свойства height или width изменяет указанное измерение без изменения другого измерения. scaleWidth И scaleHeight настройте соответствующие размеры фигуры относительно текущего или исходного размера (на основе значения указанного ShapeScaleType). Необязательный параметр ShapeScaleFrom указывает, откуда масштабируется фигура (левый верхний угол, средний или правый нижний угол). lockAspectRatio Если свойство имеет значение true, методы масштабирования поддерживают текущее пропорции фигуры, также изменяя другое измерение.
Примечание.
Прямые height изменения свойств и width влияют только на это свойство, независимо от lockAspectRatio его значения.
В следующем примере кода показана фигура, масштабируемая до 1,25 раза больше исходного размера и повернутая на 30 градусов.
// In this sample, the shape "Octagon" is rotated 30 degrees clockwise
// and scaled 25% larger, with the upper-left corner remaining in place.
await Excel.run(async (context) => {
let sheet = context.workbook.worksheets.getItem("MyWorksheet");
let shape = sheet.shapes.getItem("Octagon");
shape.incrementRotation(30);
shape.lockAspectRatio = true;
shape.scaleWidth(
1.25,
Excel.ShapeScaleType.currentSize,
Excel.ShapeScaleFrom.scaleFromTopLeft);
await context.sync();
});
Текст в фигурах
Геометрические фигуры могут содержать текст. Фигуры имеют textFrame свойство типа TextFrame. Объект TextFrame управляет параметрами отображения текста (например, полями и переполнением текста). TextFrame.textRange — это объект TextRange с текстовым содержимым и параметрами шрифта.
В следующем примере кода создается геометрическая фигура "Волна" с текстом "Текст фигуры". Он также настраивает фигуру и цвета текста, а также задает горизонтальное выравнивание текста по центру.
// This sample creates a light-blue wave shape and adds the purple text "Shape text" to the center.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let wave = shapes.addGeometricShape(Excel.GeometricShapeType.wave);
wave.left = 100;
wave.top = 400;
wave.height = 50;
wave.width = 150;
wave.name = "Wave";
wave.fill.setSolidColor("lightblue");
wave.textFrame.textRange.text = "Shape text";
wave.textFrame.textRange.font.color = "purple";
wave.textFrame.horizontalAlignment = Excel.ShapeTextHorizontalAlignment.center;
await context.sync();
});
Метод addTextBoxShapeCollection создает тип Rectangle с белым фоном и черным текстомGeometricShape. Это то же самое, что создается кнопкой "Текстовое поле" в Excel на вкладке "Вставка ". addTextBox принимает строковый аргумент для задания текста TextRangeобъекта .
В следующем примере кода показано создание текстового поля с текстом "Hello!".
// This sample creates a text box with the text "Hello!" and sizes it appropriately.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let textbox = shapes.addTextBox("Hello!");
textbox.left = 100;
textbox.top = 100;
textbox.height = 20;
textbox.width = 45;
textbox.name = "Textbox";
await context.sync();
});
Группы фигур
Фигуры можно группировать. Это позволяет пользователю рассматривать их как единую сущность для позиционирования, определения размера и других связанных задач. ShapeGroup — это тип , поэтому надстройка Shapeобрабатывает группу как одну фигуру.
В следующем примере кода показаны три фигуры, которые группируются вместе. В следующем примере кода показано, что группа фигур перемещается вправо на 50 пикселей.
// This sample takes three previously-created shapes ("Square", "Pentagon", and "Octagon")
// and groups them into a single ShapeGroup.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let square = shapes.getItem("Square");
let pentagon = shapes.getItem("Pentagon");
let octagon = shapes.getItem("Octagon");
let shapeGroup = shapes.addGroup([square, pentagon, octagon]);
shapeGroup.name = "Group";
console.log("Shapes grouped");
await context.sync();
});
// This sample moves the previously created shape group to the right by 50 pixels.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let shapeGroup = shapes.getItem("Group");
shapeGroup.incrementLeft(50);
await context.sync();
});
Важно!
На отдельные фигуры в группе ссылаются ShapeGroup.shapes через свойство, которое имеет тип GroupShapeCollection. Они больше не доступны через коллекцию фигур листа после группировки. Например, если лист содержит три фигуры и все они сгруппированы вместе, метод листа shapes.getCount вернет число 1.
Экспорт фигур в виде изображений
Любой Shape объект можно преобразовать в изображение. Shape.getAsImage возвращает строку в кодировке base64. Формат изображения указывается в виде перечисления PictureFormat , передаваемого в getAsImage.
await Excel.run(async (context) => {
let shapes = context.workbook.worksheets.getItem("MyWorksheet").shapes;
let shape = shapes.getItem("Image");
let stringResult = shape.getAsImage(Excel.PictureFormat.png);
await context.sync();
console.log(stringResult.value);
// Instead of logging, your add-in may use the base64-encoded string to save the image as a file or insert it in HTML.
});
Удаление фигур
Фигуры удаляются с листа с помощью Shape метода объекта delete . Другие метаданные не требуются.
В следующем примере кода удаляются все фигуры из MyWorksheet.
// This deletes all the shapes from "MyWorksheet".
await Excel.run(async (context) => {
let sheet = context.workbook.worksheets.getItem("MyWorksheet");
let shapes = sheet.shapes;
// We'll load all the shapes in the collection without loading their properties.
shapes.load("items/$none");
await context.sync();
shapes.items.forEach(function (shape) {
shape.delete();
});
await context.sync();
});
См. также
Office Add-ins
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по