Параметры компилятора Angular

19.04.2023

Когда вы используете опережающую компиляцию (AOT), вы можете контролировать компиляцию вашего приложения, указывая шаблонные опции компилятора в конфигурационном файле TypeScript.

Объект опций шаблона, angularCompilerOptions, является родственным объекту compilerOptions, который предоставляет стандартные опции компилятору TypeScript.

{
    "compileOnSave": false,
    "compilerOptions": {
        "baseUrl": "./"
        // ...
    },
    "angularCompilerOptions": {
        "enableI18nLegacyMessageIdFormat": false,
        "strictInjectionParameters": true
        // ...
    }
}

Наследование конфигурации с помощью extends

Как и компилятор TypeScript, компилятор Angular AOT также поддерживает extends в секции angularCompilerOptions конфигурационного файла TypeScript. Свойство extends находится на верхнем уровне, параллельно compilerOptions и angularCompilerOptions.

Конфигурация TypeScript может наследовать параметры из другого файла с помощью свойства extends. Сначала загружаются параметры конфигурации из базового файла, а затем переопределяются параметрами из наследуемого файла конфигурации.

Например:

{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "outDir": "./out-tsc/app"
        // ...
    },
    "angularCompilerOptions": {
        "strictTemplates": true,
        "preserveWhitespaces": true
        // ...
    }
}

Более подробную информацию можно найти в TypeScript Handbook.

Опции шаблонов

Для настройки компилятора шаблонов AOT доступны следующие опции.

annotationsAs

Определяет, как выдавать аннотации, специфичные для Angular, для улучшения древовидности. Неангулярные аннотации не затрагиваются.

Одно из значений static fields или decorators. По умолчанию используется значение static fields.

• По умолчанию компилятор заменяет декораторы на статическое поле в классе, что позволяет продвинутым древовидным компиляторам, таким как Closure compiler, удалять неиспользуемые классы.

• Значение decorators оставляет декораторы на месте, что ускоряет компиляцию.

  TypeScript эмитирует вызовы помощника __decorate.

  Для отражения во время выполнения используйте --emitDecoratorMetadata.

  То, что полученный код не может корректно древовидно шифроваться.

annotateForClosureCompiler

Если true, используйте Tsickle для аннотирования выдаваемого JavaScript комментариями JSDoc, необходимыми Closure Compiler. По умолчанию false.

compilationMode

Определяет режим компиляции, который будет использоваться. Доступны следующие режимы:

Режимы	Подробности
'full'	Генерирует полностью AOT-компилированный код в соответствии с версией Angular, которая используется в данный момент.
'partial'	Генерирует код в стабильной, но промежуточной форме, подходящей для опубликованной библиотеки.

Значение по умолчанию — 'full'.

disableExpressionLowering

При значении true, установленном по умолчанию, преобразует код, который используется или может быть использован в аннотации, чтобы его можно было импортировать из модулей фабрики шаблонов. Более подробную информацию смотрите в Переписывание метаданных.

При false отключает эту перезапись, требуя, чтобы перезапись выполнялась вручную.

disableTypeScriptVersionCheck

Если true, компилятор не смотрит на версию TypeScript и не сообщает об ошибке, если используется неподдерживаемая версия TypeScript. Не рекомендуется, так как неподдерживаемые версии TypeScript могут иметь неопределенное поведение.

По умолчанию false.

enableI18nLegacyMessageIdFormat

Указывает компилятору шаблонов Angular создавать унаследованные идентификаторы для сообщений, помеченных в шаблонах атрибутом i18n. Дополнительную информацию о маркировке сообщений для локализации смотрите в Mark text for translations.

Установите значение false, если ваш проект не опирается на переводы, созданные ранее с использованием устаревших идентификаторов. По умолчанию установлено значение true.

Инструментарий извлечения сообщений до Ivy создавал различные устаревшие форматы для извлеченных идентификаторов сообщений. Эти форматы сообщений имеют некоторые проблемы, такие как обработка пробельных символов и зависимость от информации, содержащейся в исходном HTML шаблона.

Новый формат сообщений более устойчив к изменениям пробельных символов, одинаков для всех форматов файлов перевода и может быть создан непосредственно из вызовов $localize. Это позволяет сообщениям $localize в коде приложения использовать тот же ID, что и идентичные сообщения i18n в шаблонах компонентов.

enableResourceInlining

Если true, заменяет свойства templateUrl и styleUrls во всех декораторах @Component на встроенное содержимое в свойствах template и styles.

Если эта функция включена, вывод ngc в .js не включает в себя URL-адреса лениво загруженных шаблонов или стилей.

Для библиотечных проектов, созданных с помощью Angular CLI, конфигурация разработки по умолчанию имеет значение true.

enableLegacyTemplate

При true включает устаревший элемент <template> вместо <ng-template>. По умолчанию false.

Может требоваться некоторыми сторонними библиотеками Angular.

flatModuleId

ID модуля для импорта плоского модуля (когда flatModuleOutFile имеет значение true). Ссылки, созданные компилятором шаблонов, используют это имя модуля при импорте символов из плоского модуля.

Игнорируется, если flatModuleOutFile равно false.

flatModuleOutFile

Если true, генерирует индекс плоского модуля по заданному имени файла и соответствующие метаданные плоского модуля. Используется для создания плоских модулей, которые упаковываются аналогично @angular/core и @angular/common.

Когда эта опция используется, package.json для библиотеки должен ссылаться на созданный индекс плоского модуля вместо индексного файла библиотеки.

Создает только один файл .metadata.json, который содержит все метаданные, необходимые для символов, экспортируемых из индекса библиотеки. В созданных файлах .ngfactory.js для импорта символов используется индекс плоского модуля. Символы включают как публичные API из индекса библиотеки, так и закрытые внутренние символы.

По умолчанию за индекс библиотеки принимается файл .ts, указанный в поле files. Если указано более одного .ts файла, libraryIndex используется для выбора используемого файла.

Если указано более одного файла .ts без индекса libraryIndex, будет выдана ошибка.

Создается индекс плоского модуля .d.ts и .js с заданным именем flatModuleOutFile в том же месте, что и файл индекса библиотеки .d.ts.

Например, если библиотека использует файл public_api.ts в качестве библиотечного индекса модуля, поле tsconfig.json files будет ["public_api.ts"]. Опция flatModuleOutFile может быть установлена, например, в "index.js", что создаст файлы index.d.ts и index.metadata.json.

Поле module в package.json библиотеки будет "index.js", а поле typings будет "index.d.ts".

fullTemplateTypeCheck

При рекомендуемом значении true включается фаза binding expression validation компилятора шаблонов. Эта фаза использует TypeScript для проверки выражений связывания. Для получения дополнительной информации смотрите Проверка типов шаблонов.

По умолчанию false, но при использовании команды Angular CLI ng new --strict в конфигурации нового проекта устанавливается значение true.

Опция fullTemplateTypeCheck была упразднена в Angular 13 в пользу семейства опций компилятора strictTemplates.

generateCodeForLibraries

При true создает фабричные файлы (.ngfactory.js и .ngstyle.js) для файлов .d.ts с соответствующим файлом .metadata.json. Значение по умолчанию — true.

При значении false фабричные файлы создаются только для файлов .ts. Сделайте это при использовании фабричных сводок.

preserveWhitespaces

По умолчанию, когда false, удаляет пустые текстовые узлы из скомпилированных шаблонов, что приводит к меньшим размерам фабричных модулей шаблонов. Установите значение true, чтобы сохранить пустые текстовые узлы.

При использовании гидратации рекомендуется использовать preserveWhitespaces: false, что является значением по умолчанию. Если вы решите включить сохранение пробельных символов, добавив preserveWhitespaces: true в tsconfig, возможно, вы столкнетесь с проблемами при работе с hydration. Эта конфигурация еще не полностью поддерживается. Убедитесь, что это значение также последовательно установлено в файлах tsconfig сервера и клиента. Более подробную информацию смотрите в руководстве hydration guide.

skipMetadataEmit

Когда true, не создает файлы .metadata.json. По умолчанию false.

Файлы .metadata.json содержат информацию, необходимую компилятору шаблонов из файла .ts, которая не включена в файл .d.ts, создаваемый компилятором TypeScript. Эта информация включает, например, содержание аннотаций, таких как шаблон компонента, которые TypeScript передает в файл .js, но не в файл .d.ts.

Можно установить значение true при использовании фабричных аннотаций, поскольку фабричные аннотации включают копию информации, содержащейся в файле .metadata.json.

Установите значение true, если вы используете опцию TypeScript --outFile, потому что файлы метаданных не действительны для этого стиля вывода TypeScript. Сообщество Angular не рекомендует использовать --outFile в Angular.

Вместо этого используйте бандлер, например webpack.

skipTemplateCodegen

При значении true не создает файлы .ngfactory.js и .ngstyle.js. Это отключает большую часть компилятора шаблонов и отключает отчет о диагностике шаблонов.

Может использоваться для указания компилятору шаблонов создавать файлы .metadata.json для распространения с пакетом npm. Это позволяет избежать создания файлов .ngfactory.js и .ngstyle.js, которые не могут быть распространены в npm.

Для библиотечных проектов, созданных с помощью Angular CLI, конфигурация разработки по умолчанию имеет значение true.

strictMetadataEmit

При значении true сообщает об ошибке в файл .metadata.json, если "skipMetadataEmit" имеет значение false. По умолчанию false.

Используется только тогда, когда "skipMetadataEmit" равно false и "skipTemplateCodegen" равно true.

Эта опция предназначена для проверки файлов .metadata.json, создаваемых для комплектации с пакетом npm. Проверка строгая и может выдать ошибку для метаданных, которые никогда не выдадут ошибку при использовании компилятором шаблонов. Вы можете подавить ошибку, выдаваемую этой опцией для экспортируемого символа, включив @dynamic в комментарий, документирующий символ.

Для файлов .metadata.json допустимо наличие ошибок. Компилятор шаблонов сообщает об этих ошибках, если метаданные используются для определения содержимого аннотации.

Сборщик метаданных не может предсказать символы, предназначенные для использования в аннотации. Он упреждающе включает узлы ошибок в метаданные для экспортируемых символов.

Затем компилятор шаблонов может использовать узлы ошибок, чтобы сообщить об ошибке, если эти символы используются.

Если клиент библиотеки намерен использовать символ в аннотации, компилятор шаблонов обычно не сообщает об этом. Об этом сообщается после того, как клиент действительно использует символ. Эта опция позволяет обнаружить эти ошибки на этапе сборки библиотеки и используется, например, при создании самих библиотек Angular.

Для проектов библиотек, созданных с помощью Angular CLI, конфигурация разработки по умолчанию имеет значение true.

strictInjectionParameters

При true сообщает об ошибке для параметра, тип инъекции которого не может быть определен. При false, параметры конструктора классов, помеченных @Injectable, тип которых не может быть определен, выдают предупреждение.

Рекомендуемое значение — true, по умолчанию — false.

Когда вы используете команду Angular CLI ng new --strict, в конфигурации созданного проекта устанавливается значение true.

strictTemplates

При true включает строгую проверку типов шаблонов.

Флаги строгости, которые включает эта опция, позволяют включать и выключать определенные типы строгой проверки типов шаблонов. Смотрите устранение ошибок шаблонов.

Когда вы используете команду Angular CLI ng new --strict, в конфигурации нового проекта устанавливается значение true.

trace

Когда true, выводит дополнительную информацию при компиляции шаблонов. По умолчанию false.

Опции командной строки

В большинстве случаев вы взаимодействуете с Angular Compiler косвенно, используя Angular CLI. При отладке некоторых проблем вам может показаться полезным вызвать Angular Compiler напрямую. Вы можете использовать команду ngc из пакета @angular/compiler-cli npm для вызова компилятора из командной строки.

Команда ngc — это просто обертка вокруг команды компилятора TypeScript tsc и настраивается в основном с помощью опций конфигурации tsconfig.json, документированных в предыдущих разделах.

Помимо конфигурационного файла, для настройки ngc можно использовать опции командной строки tsc.

Комментарии