Методы обратной связи необходимы в любом языке программирования. В JavaScript вы, вероятно, использовали console.log() или, возможно, alert() . В PHP вы можете использовать var_dump() или print_r() . В Ruby вы можете использовать debug или inspect . Все эти функции позволяют вам отлаживать любое значение и выяснять, что делает ваш код в любой точке логики, где вам нужна помощь.
У Sass есть три директивы для обратной связи с разработчиками. Это @error , @warn и @debug . В этой статье мы рассмотрим, как использовать эти директивы, для каких сценариев они лучше всего подходят и какую обратную связь они могут предоставить другим разработчикам, использующим наш код.
Основной синтаксис и использование
Все эти три директивы имеют одинаковый синтаксис:
@directive "String of text to output.";
Ну, это не совсем так. Три директивы ожидают чего угодно, не обязательно строки. Это означает, что вы можете предупреждать, бросать или отлаживать карту, список, число, строку — в основном все, что вы хотите. Однако, поскольку мы часто используем эти директивы, чтобы дать некоторый контекст по проблеме, мы обычно передаем строку, описывающую ситуацию.
Если вам нужно интерполировать значение переменной в этой строке, вы можете сделать это, используя стандартную интерполяцию Sass ( #{$variable} ), и значение будет напечатано в строке. С помощью этого метода вы можете сообщить разработчику как имя переменной, так и ее текущее значение:
@error "Sorry, but `#{$variable}` is not a valid value for $variable.";
Обратите внимание, что галочки (`) вокруг интерполяции не требуются. Вы можете включить их, потому что они дают разработчику очевидную точку начала / окончания для содержимого переменной.
Если разработчик допускает ошибку при использовании вашего кода Sass, эти директивы отправят указанное сообщение компилятору, а компилятор покажет это сообщение разработчику. Например, приложения с графическим интерфейсом (например, CodeKit ) будут отображать системное уведомление с ошибкой. Некоторые пакеты уведомлений Grunt и Gulp также могут это делать.
Если разработчик компилирует с помощью командной строки (Sass, Compass, Grunt или Gulp), сообщение, скорее всего, попадет в их консоль (Terminal, iTerm2, Putty и т. Д.). Если вы пишете Sass онлайн с помощью Sassmeister или Codepen , вы получите только ограниченную обратную связь, но вы можете получить встроенное уведомление в редакторе или текст в окне вывода.
Теперь, когда мы знаем, как писать сообщения @error , @warn и @debug и где они будут появляться для разработчика, давайте посмотрим на разницу между этими директивами и наилучшим использованием для каждой из них.
Остановите все — директива @error
Директива Sass @error полностью останавливает компилятор Sass и отправляет его строку текста на выход компилятора как фатальную ошибку. Используйте эту директиву, когда вам нужно отправить сообщение, которое немедленно останавливает разработчика и заставляет его немедленно исправить свою ошибку. Это идеально для того, чтобы сообщить разработчику, что он сделал что-то не так или ввел значение, которое совершенно несовместимо. Sass будет содержать номер строки с любой фатальной ошибкой, включая вывод @error . Директива @error идеально подходит для проверки аргументов в миксине или функции.
Примечание. Если ваш компилятор старше Sass 3.4 или LibSass 3.1, @error недоступен. Вы можете использовать эту функцию log() для эмуляции @error в более старых версиях Sass.
Например, если вы написали функцию, для расчетов которой используется определенный формат ввода, вы можете проверить ввод и использовать @error чтобы остановить компилятор и предупредить разработчика, что они допустили ошибку, которая не может быть упущенным Если вы написали функцию, основанную на паре ключ / значение с карты, @error может убедиться, что ключ, вызываемый с карты, действительно существует.
Этот инструмент управления цветом Sass использует @error чтобы гарантировать, что разработчик использует только имя цвета, которое является допустимым именем цвета CSS или ключ из связанной карты:
Карта:
$colors: ( brand-red: #c0392b, brand-blue: #2980b9, text-gray: #2c3e50, text-silver: #bdc3c7 );
Функция (упрощенная для краткости):
@function color-variation($color) { @if map-has-key($colors, $color) { @return map-get($colors, $color); } @error "Invalid color name: `#{$color}`."; }
Использование:
.element { color: color-variation(brand-orange); }
Выход:
>> Invalid color name: `brand-orange`. >> Line 9 Column 7 sass/test.scss
В этом примере, если разработчик пытается вызвать функцию color-variation() со строкой, которая не является ни действительным цветом CSS, ни ключом из карты $colors , Sass ничего не может сделать, чтобы вывести действительный цвет. Использование @error дает разработчику конкретную и действенную обратную связь.
Не пропустите это — директива @warn
Директива @warn значительно менее серьезна, чем @error . Он отправляет компилятору свое сообщение для чтения разработчику, но позволяет компилятору завершить свою работу и написать весь CSS. Хотя @error подходит для исправления ошибки, которая полностью нарушает функцию или @warn , @warn лучше подходит для уведомлений об устаревании или для того, чтобы разработчик следовал определенным рекомендациям.
Примечание. Разработчики Sass, использующие флаг --quiet при компиляции, не увидят вывод @warn . Если разработчику абсолютно необходимо увидеть отзывы, которые посылает ваш Sass, @error на @error . @warn редко можно отключить, но это возможно.
Sass также будет содержать номер строки с @warn чтобы помочь разработчику найти и улучшить любой код, который необходимо отредактировать. Например, у вас может быть библиотека, полная миксинов, и вы планируете отказаться от нескольких миксов в будущем выпуске. Один из способов помочь вашим разработчикам подготовиться к этому изменению — @warn их о предстоящем устаревании:
// No one should ever prefix border-radius properties 😉 // so let's deprecate this from our imaginary library: @mixin border-radius($radius) { @warn "The `border-radius()` mixin will be deprecated in version 2.0."; -webkit-border-radius: $radius; -moz-border-radius: $radius; -ms-border-radius: $radius; -o-border-radius: $radius; border-radius: $radius; }
Выход:
WARNING: The `border-radius()` mixin will be deprecated in version 2.0. on line 2 of sass/test.scss from line 21 of sass/test.scss
Вы можете увидеть это в действии в этом частичном устаревании от Bourbon Sass.
Еще один хороший пример использования @warn — соблюдение стандартов командного кода. Вы можете написать функцию, которая может успешно обрабатывать ввод как в пикселях, так и в единицах rem, но вы можете предпочесть, чтобы все в вашей команде использовали rems. Вот пример @warn чтобы помочь вашим коллегам следовать этому стандарту:
@function do-math($input) { @if unit($input) == "px" { @warn "Please remember to use rem values in the `do-math()` function."; // do px math and @return a value to prevent the function from going any further } // do rem math and @return a value }
Выход:
WARNING: Please remember to use rem values in the `do-math()` function. on line 3 of sass/test.scss from line 12 of sass/test.scss
Если вам было @debug Директива @debug
Директива Sass @debug является наименее навязчивой из всех трех директив обратной связи. Он выводит значение любого содержащегося в нем выражения Sass (переменная, математика и т. Д.) В консоль разработчика. Это не совсем полезно для библиотек с открытым исходным кодом или командных библиотек. Скорее, @debug идеально подходит для личной работы по отладке. Если вы в сложном математике и хотите знать, что в данный момент содержится в одной из ваших переменных, используйте @debug чтобы узнать.
Использование:
$color-blue: #1c94c6; $font-sizes: sm, p, bq, heading, hero; $colors: ( brand-red: #c0392b, brand-blue: #2980b9, text-gray: #2c3e50, text-silver: #bdc3c7 ); .element { @debug $color-blue; // single value @debug $font-sizes; // list @debug $colors; // map @debug 4em * 3; // math expression @debug "My very own string just because."; // string }
Выход:
sass/test.scss:5: DEBUG: #1c94c6 sass/test.scss:6: DEBUG: sm, p, bq, heading, hero sass/test.scss:7: DEBUG: (brand-red: #c0392b, brand-blue: #2980b9, text-gray: #2c3e50, text-silver: #bdc3c7) sass/test.scss:8: DEBUG: 12em sass/test.scss:9: DEBUG: My very own string just because.
Вывод
Программирование в черной дыре без обратной связи было бы ужасно. К счастью, Sass имеет несколько директив, которые могут отправлять отзывы компилятору, чтобы помочь разработчикам избежать ошибок, поддерживать стандарты и устранять неполадки в расширенной логике. Вы можете использовать @error , @warn и @debug чтобы сэкономить время для себя и для всех, кто использует ваш код.
Есть ли у вас творческое использование этих директив? Поделитесь ими в комментариях!