Създаване на добавка за Office Това се превърна в много мощен начин за разширяване на Word, Excel, Outlook, PowerPoint и други приложения. Microsoft 365 без да е необходимо да се разработват традиционни добавки за настолни компютри. Тези нови добавки са базирани на стандартни уеб технологии и JavaScript API за Office, което позволява създаването на модерни, сигурни и лесни за внедряване среди в цялата организация.
В следващите редове ще намерите много пълно ръководство за инструменти за разработка, типове манифести, налични API и опции за внедряванеинтегриране на официалната документация на Microsoft. Идеята е, че можете да преминете от нулата до работеща добавка, разбирайки какво прави всяка част и какви технически решения трябва да вземете на всяка стъпка.
Какво представлява модерната добавка за Office и как е структурирана?
Модерни добавки за Office Те разчитат на платформата за добавки на Office, която е обща за Word, Excel, PowerPoint, OneNote, Outlook и Project, на настолни компютри, в уеб и в някои случаи на мобилни устройства. Всички те споделят една и съща основна архитектура, съставена от две ясно разграничени части.
Първото парче е манифест на комплиментаТози файл действа като „лична карта“ на добавката. Той декларира метаданните (ИД, име, версия, езици), с кои приложения на Office може да се използва, какви разрешения са ѝ необходими, какви команди добавя към лентата, какви икони използва, къде се хоства уеб приложението и в какви контексти трябва да се активира (например в Outlook, само за съобщения или срещи, които отговарят на определени правила).
Втората част е уеб приложение Това приложение предоставя потребителския интерфейс и бизнес логиката. Състои се от HTML, CSS и JavaScript (или TypeScript) и се изпълнява в HTML контейнер на Office (прозорец за задачи, добавка за съдържание или диалогов прозорец). Оттам използва библиотеката office.js, за да чете и записва в документа, да извиква външни услуги, да обработва удостоверяване, да показва диалогови прозорци и да изпълнява всякакви други типични задачи на модерно уеб приложение.
Инструменти за създаване на добавки за Office
Няма един-единствен начин за стартиране на проект за добавки. Microsoft предлага няколко официални инструментаТези инструменти са предназначени за различни потребителски профили: от тези, които предпочитат шаблони на Visual Studio, до тези, които работят ежедневно с Node.js и Visual Studio Code. Съществуват и инструменти на трети страни или по-специализирани инструменти, като например редактори на потребителски интерфейс за VBA.
Генератор на Yeoman за добавки към Office
Генераторът на Yeoman за Office вероятно е най-гъвкавият вариант за уеб разработчици. Позволява ви да създавате проекти, базирани на Node.js, които можете да редактирате с Кода на Visual Studio или предпочитания от вас издател. Съветникът ви води през поредица от въпроси, за да изберете типа добавка (прозорец на задачите, добавка за съдържание, персонализирани функции, Outlook и др.) и целевото приложение.
С този генератор можете създават проекти за Excel, OneNote, Outlook, PowerPoint, Project, Word и персонализирани функции на Excel. Освен това, ви позволява да избирате между прост стек с HTML, CSS и JavaScript/TypeScript или архитектура, базирана на React, също в JavaScript или TypeScript, с вече подготвена цялата структура на проекта.
Visual Studio за проекти на Office
Ако се движите по-удобно в .NET средиVisual Studio включва специфични шаблони за добавки на Office. Тези шаблони обхващат предимно Excel, Outlook, Word и PowerPoint, създавайки цялостно решение, което включва манифеста на добавката, уеб приложението и, по избор, свързани backend проекти.
Проектът Visual Studio Той също е базиран на HTML, CSS и JavaScript, но се интегрира с класическата екосистема на Microsoft.Интегрирано дебъгване, публикуване, пакетиране и др. Това е добър избор, когато вече работите с корпоративни решения във Visual Studio и искате всичко да е централизирано в една и съща IDE.
Комплект инструменти за агенти на Microsoft 365 и комплект за разработчици на добавки за Office
Комплект инструменти за агенти на Microsoft 365 Той е проектиран да надхвърли традиционните добавки и да създаде практически всякакъв тип разширение за екосистемата на Microsoft 365, комбинирайки ботове, разширения за Teams и добавки. С този инструмент можете да генерирате проекти за добавки за Office, които се вписват в по-широки приложения на Microsoft 365.
Комплект за разработчици на добавки за Office Това е разширение за Visual Studio Code, което значително опростява ежедневието. От VS Code можете да създавате нови проекти за добавки, да зареждате готови за тестване примерни кодове и да управлявате целия жизнен цикъл на разработка, без да напускате редактора. Разширението е проектирано да работи както с унифицирани манифести, така и с манифести само за добавки.
Манифестът: сърцето на конфигурацията на добавката
Всяка добавка на Office е описана от файл с манифест Това указва на приложенията как да го заредят, какви опции на интерфейса да предоставят и какви разрешения да изискват. Има два основни шаблона за манифест и изборът между тях определя как можете да интегрирате добавката си с други разширения на Microsoft 365.
Видове манифест: само допълнение и унифициран манифест
- Манифест само на допълване. Това е класическият формат за добавки на Office в Excel, OneNote, Outlook, PowerPoint, Project и Word. Написан е в XML и се фокусира единствено върху описанието на добавката, без да я смесва с други видове приложения.
- Унифициран манифест за Microsoft 365. Еволюцията на модела на манифеста във формат JSON, исторически използван в приложенията на Teams. Този формат позволява различни видове разширения на Microsoft 365 – добавки за Office, разширения на Teams и др. – да бъдат пакетирани в едно приложение.
Логиката на конфигурацията е сходна и в двата случаяВие дефинирате уникален идентификатор (обикновено GUID), версията, показваното име, описанието, поддържаните езици, иконите, типовете разрешения (например четене или четене/писане на документи) и структурата на интерфейса (раздели, групи и бутони на лентата). Вие също така задавате URL адреса за стартиране на уеб приложението и всички допълнителни настройки, като например клавишни комбинации в Excel или Word, правила за задействане в Outlook или размерите на панелите и добавките за съдържание.
Ключови елементи, декларирани в манифеста
В допълнение към основни метаданниМанифестът трябва внимателно да описва как добавката се интегрира в средата за работа с Office. Това включва изображения за брандиране и икони на команди на лентата, които трябва да се хостват на сървър, който позволява кеширане (HTTP заглавки с Cache-Control: no-cache или подобно за производство).
Друг критичен аспект е сигурносттаВсички URL адреси, сочещи към уеб приложението или ресурсите на добавките, трябва да използват HTTPS. Въпреки че някои сценарии за разработка позволяват HTTP или самоподписани сертификати, ако искате да стартирате добавката в Office в уеб или да я публикувате в Microsoft Marketplace, SSL е задължителен, за да се избегнат предупреждения за смесено съдържание и да се гарантира защита на данните при пренасяне.
Ако планирате да разпространявате добавката си чрез Microsoft Marketplace, манифестът трябва да включва: В допълнение към уникалния GUID, достъпен и валиден URL адрес за техническа поддръжка. Microsoft прилага серия от насоки за валидиране, при които се проверяват съгласуваността на данните в манифеста, поведението на добавката и съответствието с изискванията за сигурност и потребителско изживяване.
Разрешени домейни и произходи за Office.js
Манифестът също така контролира кои домейни могат да се навигират в панела на плъгинитеВ Office в уеб и новия Outlook за Windows, панелът на задачите може да зареди почти всеки URL адрес. В настолните приложения обаче поведението е по-строго: ако добавката се опита да премине към домейн, различен от домейна на началната страница, URL адресът се отваря извън приложението, в отделен прозорец на браузъра.
За да избегнете това външно прескачане на работния плотМожете изрично да посочите всеки допълнителен домейн, който искате да се показва в прозореца на добавката, в манифеста. Ако целта е посочена, тя ще се отвори в панела както в настолната версия на Office, така и в Office в уеб версията; в противен случай, на настолната версия, ще се отвори във външен браузър.
Взаимодействие с документи чрез Office JavaScript API
Уеб приложението на добавката комуникира с документа на Office. (или със съобщението в случая на Outlook) чрез библиотеката на Office JavaScript API, достъпна чрез официалната CDN мрежа на Microsoft на адрес https://appsforoffice.microsoft.com/lib/1/hosted/office.jsПросто цитирайте този скрипт в раздела <head> от страницата, за да можете да използвате наличните типове и методи.
След като библиотеката бъде заредена, имате достъп до два допълващи се API модела:
- API-та, специфични за приложението.
- Често срещани API.
Всеки модел е проектиран да покрива различни сценарии, въпреки че могат да се комбинират в един и същ аксесоар в зависимост от нуждите.
API-та, специфични за приложението
API-тата, специфични за приложението, предоставят силно типизирани обекти Те представляват собствени обекти на конкретното приложение на Office. Например, в Excel имате обекти за работни листове, диапазони, таблици и диаграми, които ви позволяват да манипулирате данни по структуриран и ефикасен начин.
Този модел е базиран на пакетни операцииСвързвате действия във верига в контекст и когато сте готови, синхронизирате промените с Office. Този начин на работа намалява броя на преходите между добавката и приложението, което значително подобрява производителността, особено в Office в уеб.
Общи API за споделени функции
Общи API-та Те се фокусират върху междусекторни функционалности, присъстващи в няколко приложения: елементи на интерфейса, диалогови прозорци, клиентски настройки и др. Този модел използва обратни извиквания вместо обещания и по дизайн всяко извикване извършва една операция срещу приложението.
С често срещани API можете например, да покажете изскачащ диалогов прозорец, да управлявате конфигурацията на добавка на различни хостове или да получите достъп до определени възможности на Outlook, PowerPoint или Project, които все още не са обхванати от специфични за приложението API, в зависимост от случая на употреба.
Набори от изисквания и междуплатформена съвместимост
Съвместимостта с API е организирана в набори от изискванияТези групират специфични API членове под име на версия. Има специфични за приложението набори от изисквания, като например ExcelApi 1.7и други споделени, като например DialogApi 1.1, които работят там, където се поддържа функционалността на диалоговия прозорец.
Добавката може да проверява по време на изпълнение дали приложението на Office, под което се изпълнява, отговаря на необходимите изисквания. Това ви позволява да персонализирате работата или да деактивирате разширените функции, когато хостът не отговаря на минималните изисквания, вместо да причинявате неочаквани грешки.
Разгледайте API със Script Lab
Script Lab е безплатно допълнение Той служи като тестова площадка за Office JavaScript API. Инсталира се от Microsoft Marketplace и работи в приложения като Excel или Word, което ви позволява да пишете и изпълнявате фрагменти от код в реално време в текущия документ.
В Script Lab имате достъп до библиотека с готови за употреба примери, демонстриращи различни възможности на APIМожете да използвате тези фрагменти като основа за вашия собствен код, да ги модифицирате и незабавно да видите резултата в документа, което значително ускорява фазата на прототипиране и тестване на функционалностите, преди да ги включите в крайния си плъгин.
Как да разширите потребителския интерфейс на Office
Едно от големите предимства на добавките е, че те позволяват интегрирайте функционалността директно в интерфейса на Officeтака че потребителят да не се чувства сякаш „напуска“ приложението. Това се постига чрез комбиниране на команди на плъгини и HTML контейнери, като например панели за задачи, плъгини за съдържание и диалогови прозорци.
- Команди за добавки Те се използват за добавяне на персонализирани раздели, нови групи и допълнителни бутони или менюта към лентата на Office.
- HTML контейнери (прозорци на задачи, добавки за съдържание и диалогови прозорци) действат като повърхност, върху която да се показва собственият интерфейс на добавката.
В типичен сценарий може да имате команда, която добавя група с бутон „Анализиране на данни“ в Excel; при натискане се отваря панел със задачи отдясно с вашето уеб приложение, което анализира избрания диапазон, извиква услуга за машинно обучение и връща резултатите, като маркира клетки или създава диаграми, използвайки специфичния API на Excel.
Създаване на добавка за прозорец на задачи с Yeoman (пример за Word)
За да приложим всички тези концепции на практикаПолезно е да се види как на практика да се изгради добавка за прозорец на задачи, използвайки генератора на Yeoman, както за Word, така и за Outlook. Въпреки че детайлите на интерфейса се различават между приложенията, структурата на проекта и работният процес са много сходни.
Предварителни изисквания за средата за разработка
Преди генерирането на проектаТрябва да имате инсталирана най-новата LTS версия на Node.js, която може да бъде изтеглена от официалния уебсайт. След инсталирането, инсталирайте Yeoman и генератора на Office глобално, като използвате командата npm install -g yo generator-officeНакрая се уверете, че сте свързали Office с абонамент за Microsoft 365, който включва Office в уеб, тъй като ще тествате добавката както на настолен компютър, така и в браузър.
Създаване на добавка за Word с панел на задачите
Първата стъпка е определете вида на манифеста които искате да използвате в зависимост от това дали възнамерявате да комбинирате добавката си с други разширения в едно приложение или не. След като вземете решението си, изпълнявате yo office в работната директория.
По време на интерактивен асистентМожете например да изберете тип проект, да зададете име като „Моята добавка за Office“ и да изберете Word като целево клиентско приложение. Когато приключи, генераторът създава папката на проекта, инсталира зависимостите на Node и подготвя всичко за работа.
В решението ще намерите файла с манифеста (manifest.json o manifest.xml) в корена, който определя конфигурацията на плъгина; файлът ./src/taskpane/taskpane.html с маркировката на панела със задачи; CSS в ./src/taskpane/taskpane.css; и кодът, който извиква Office API в ./src/taskpane/taskpane.ts o .jsв зависимост от това дали сте избрали TypeScript или JavaScript.
За да тествате добавката в настолния WordПросто трябва да отидете в главната папка на проекта (cd "My Office Add-in"и изпълнявам npm startТази команда стартира локалния уеб сървър и стартира Word с вече заредена добавка в режим на странично зареждане. Ако предпочитате да го изпробвате в Word в уеб, можете да използвате команда като тази: npm run start -- web --document {url}, като замените URL адреса с този на документ, съхранен в OneDrive или SharePoint.
Сървър за разработка и управление на зависимости
По време на развитието е често срещано че npm install Възможно е да се получи неуспех по време на автоматичната стъпка, която Yeoman изпълнява, особено ако има конфликти с версии на зависимости. В тези случаи просто отидете в папката на проекта и го стартирайте. npm install ръчно, за да го решите.
Ако се появят предупреждения за остарели зависимостиМожете да разчитате на инструмента npm-check-updates, инсталирайки го с npm i -g npm-check-updates, бягане ncu -u за актуализиране на диапазоните от версии в package.json и завършване на процеса с нов npm installМного от тези предупреждения не са критични, но е добра практика да ги преглеждате периодично, за да поддържате проекта в добро състояние.
За да спрете сървъра за разработка и деинсталирайте плъгина в режим на странично зареждане, можете да го стартирате npm stop в главната директория. Ако преди това сте качили добавката ръчно (например чрез качване на манифеста в Office в уеб), ще трябва да я премахнете ръчно и от съответния интерфейс за администриране.
От основната структура на добавката и инструментите за разработка (Yeoman, Visual Studio, Agents Toolkit, Script Lab) до ролята на манифеста, JavaScript API, контролите за сигурност и опциите за внедряване (локално, Marketplace, централизирано внедряване или чрез доставчици като Qlik), имате... сравнително пълна карта да решите какъв тип добавка ви е необходима, как да я изградите и как да я предоставите на потребителите си без технически изненади.