Udostępnij za pośrednictwem

Wskazówki dotyczące formatowania tekstu

  • Artykuł

Spójne i właściwe stosowanie pogrubienia, kursywy i stylu kodu dla elementów tekstowych zwiększa czytelność i pomaga uniknąć nieporozumień.

Pogrubiona

Stosuj pogrubienie w przypadku elementów interfejsu użytkownika, takich jak opcje menu, nazwy okien dialogowych i nazwy pól z danymi wejściowymi.

Przykłady

  • To: w Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu, a następnie wybierz polecenie Dodaj > nowy element.
  • Nie jest to: w Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu, a następnie wybierz polecenie Dodaj > nowy element.
  • Nie jest to: w Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu, a następnie wybierz polecenie Dodaj > nowy element.

Kursywa

Stosowanie kursywy:

  • Wprowadzenie nowych terminów wraz z definicją lub wyjaśnieniem.
  • Nazwy plików, nazwy folderów, ścieżki.
  • Dane wejściowe użytkownika.

Przykłady

  • Poprawnie: W usłudze App Service aplikacja działa w ramach planu usługi App Service. Plan usługi App Service definiuje zestaw zasobów obliczeniowych, których używa aplikacja internetowa.
  • Nie jest tak: w usłudze App Service aplikacja działa w planie usługi App Service. Plan usługi App Service definiuje zestaw zasobów obliczeniowych dla aplikacji internetowej do uruchomienia.
  • To: zastąp kod w HttpTriggerCSharp.cs następującym kodem.
  • Nie jest to: zastąp kod w HttpTriggerCSharp.cs pliku następującym kodem.
  • To: wprowadź wartość ContosoUniversity w polu Nazwa, a następnie wybierz pozycję Dodaj.
  • Nie jest to: wprowadź wartość "ContosoUniversity" w polu Nazwa, a następnie wybierz pozycję Dodaj.

Styl kodu

Stosowanie stylu kodu:

  • Elementy kodu, takie jak nazwy metod, nazwy właściwości i słowa kluczowe języka.
  • Polecenia SQL
  • Nazwy pakietów NuGet
  • Polecenia wiersza polecenia*
  • Nazwy tabel i kolumn baz danych
  • Nazwy zasobów, które nie powinny być lokalizowane (takie jak nazwy maszyn wirtualnych)
  • Adresy URL, które nie są przeznaczone do klikania

Dlaczego? W starszych przewodnikach stylu określano pogrubienie dla wielu z tych elementów tekstowych. Jednak większość artykułów jest zlokalizowana, a styl kodu nakazuje tłumaczowi pozostawić tę część tekstu nieprzetłumaczoną.

Styl kodu może być wbudowany (otoczony przez ") lub ogrodzone bloki kodu (otoczony przez ""), które obejmują wiele wierszy. Dłuższe fragmenty kodu i ścieżki należy umieszczać w ogrodzonych blokach kodu.

* W poleceniach wiersza polecenia użyj ukośników w ścieżkach plików, jeśli są one obsługiwane na wszystkich platformach. Użyj ukośników odwrotnych, aby zilustrować polecenia uruchamiane w systemie Windows, gdy obsługiwane są tylko ukośniki odwrotne. Na przykład ukośniki przesyłania dalej działają w interfejsie wiersza polecenia platformy .NET na wszystkich platformach, więc należy użyć polecenia dotnet build foldername/filename.csproj zamiast dotnet build foldername\filename.csproj.

Przykłady używania stylów śródwierszowych

  • Poprawnie: Domyślnie platforma Entity Framework interpretuje właściwość o nazwie Id lub ClassnameID jako klucz podstawowy.
  • Niepoprawnie: Domyślnie platforma Entity Framework interpretuje właściwość o nazwie Id lub ClassnameID jako klucz podstawowy.
  • Poprawnie: Pakiet Microsoft.EntityFrameworkCore zapewnia obsługę środowiska uruchomieniowego dla platformy EF Core.
  • Niepoprawnie: Pakiet Microsoft.EntityFrameworkCore zapewnia obsługę środowiska uruchomieniowego dla platformy EF Core.

Przykłady ogrodzonych bloków kodu

  • Poprawnie: Żadne polecenia nie są wysyłane do bazy danych przez instrukcje, które tylko zmieniają element IQueryable, jak w następującym kodzie:

        ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```

  • Nie jest to: żadne polecenia nie są wysyłane do bazy danych przez instrukcje, które po prostu zmieniają element IQueryable, takie jak var students = context. Students.Where(s => s.LastName == "Davolio").

  • Poprawnie: Aby na przykład uruchomić skrypt Get-ServiceLog.ps1 w katalogu C:\Scripts, wpisz:

        ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```

  • Niepoprawnie: Aby na przykład uruchomić skrypt Get-ServiceLog.ps1 w katalogu C:\Scripts, wpisz: „C:\Scripts\Get-ServiceLog.ps1”.

  • Wszystkie ogrodzone bloki kodu muszą mieć zatwierdzony tag języka. Aby zapoznać się z listą obsługiwanych tagów języka, zobacz Jak dołączać kod do dokumentów.

Symbole zastępcze

Jeśli chcesz, aby użytkownik zamienił część ciągu wejściowego na własne wartości, użyj tekstu zastępczego oznaczonego nawiasami kątowymi (mniejsze niż < i większe niż > znaki).

Opcja 1. Użyj stylu kodu, aby otaczać wyraz zastępczy lub frazę obejmującą. Na przykład można użyć pojedynczych backticks " do formatowania kodu wbudowanego dla pojedynczej frazy lub potrójnych znaczników "" na potrzeby formatowania ogrodzonego kodu.

`az group delete -n <ResourceGroupName>`

Renderowane jako:

az group delete -n <ResourceGroupName>

lub

Opcja 2. Użyj znaku \ ukośnika odwrotnego, aby uniknąć znaków nawiasu kątowego w języku Markdown, takich jak \< i \>. Chociaż wymagana jest tylko pierwsza ucieczka w lewym nawiasie kątowym \< , ucieczka nawiasu \> zamykającego działa zbyt w celu zapewnienia spójności. Renderowany kod HTML nie wyświetla znaku ucieczki dla czytnika:

az group delete -n \<ResourceGroupName\>

Renderowane jako:

az group delete -n <ResourceGroupName>

Poinformuj czytelnika o symbolu zastępczym: w tekście poprzedzającym takie przykłady symboli zastępczych wyjaśnij czytelnikowi, że tekst w nawiasach musi zostać usunięty i zastąpiony rzeczywistymi wartościami. Zalecamy użycie kursywy dla danych wejściowych użytkownika. Kursywę można sformatować w kodzie wbudowanym w nawias kątowy:

W poniższym przykładzie zastąp tekst <ResourceGroupName> zastępczy własną nazwą grupy zasobów.

Uwaga

Witryna microsoft Learn nie renderuje <tekstu zastępczego> , który używa nawiasów kątowych w przypadkach, gdy nawiasy nie są poprawnie uniknięte lub tekst nie jest sformatowany kodowo. Proces kompilacji środowiska Microsoft Learn interpretuje <frazę symbolu zastępczego> jako tag HTML, który może być niebezpieczny dla przeglądarki czytelnika i flaguje go jako niedozwolony tag HTML. W raporcie kompilacji zostanie wyświetlona sugestia, a wyraz zastępczy nie jest renderowany w danych wyjściowych strony usługi Microsoft Learn, gdy tak się stanie.

Aby uniknąć utraty zawartości w symbolach zastępczych, użyj code znaków formatowania lub ucieczki (\< \>) zgodnie z wcześniejszym opisem.

Odradzamy używanie nawiasów klamrowych { } jako symboli zastępczych składniowych. Czytelnicy mogą mylić symbole zastępcze nawiasów klamrowych z tą samą notacją używaną w:

  • Tekst z możliwością zamiany
  • Formatuj ciągi
  • Interpolacja ciągów
  • Szablony tekstu
  • Podobne konstrukcje programistyczne

Wielkość liter i odstępy: możesz oddzielić nazwy symboli zastępczych łącznikami ("przypadek kebabab") lub podkreśleniami albo można to zrobić przy użyciu wielkości liter Pascal. Przypadek Kebab może generować błędy składni, a podkreślenia mogą powodować konflikt z podkreśleniami. Wszystkie limity mogą powodować konflikt z nazwanymi stałymi w wielu językach, ale może również zwrócić uwagę na nazwę symbolu zastępczego.

<Resource-Group-Name> lub <ResourceGroupName>

Tekst nagłówków i linków

Nie należy stosować stylu śródliniowego, takiego jak kursywa ani pogrubiona do nagłówków ani tekstu hiperłącza.

Dlaczego?

Użytkownicy rozpoznają elementy tekstowe jako linki z możliwością klikania, bazując na standardowym tekście hiperlinków. Stylowanie linku jako kursywy może na przykład zasłaniać fakt, że tekst jest linkiem. Nagłówki mają własne style i mieszanie ich z innymi stylami wygląda niewłaściwie.

Przykłady nagłówków i tekstu łącza

Klawisze i skróty klawiaturowe

W razie odwoływania się do klawiszy lub kombinacji klawiszy przestrzegaj tych konwencji:

  • Używaj wielkiej pierwszej litery w nazwach klawiszy.
  • Umieść nazwy kluczy za pomocą <kbd> tagów HTML i </kbd> .
  • Użyj ciągu "+", aby dołączyć klucze wybrane przez użytkownika w tym samym czasie.

Przykłady i skrótów klawiaturowych

  • To: wybierz Alt+Ctrl+S.
  • Nie: naciśnij ALT+CTRL+S.
  • Nie jest to: naciśnij pozycję ALT+CTRL+S.

Wyjątki

Wskazówki dotyczące stylów nie są sztywnymi regułami. W kontekstach, w których nie zmniejsza to czytelności, można zrobić coś innego. Na przykład tabela HTML zawierająca głównie elementy kodu może wyglądać na zbyt zagęszczoną w przypadku zastosowania wszędzie stylu kodu. W tym kontekście można wybrać styl pogrubienia.

Jeśli wybierzesz alternatywny styl tekstu, w którym zwykle jest wymagany kod, upewnij się, że tekst może być tłumaczony w zlokalizowanych wersjach artykułu. Kod jest jedynym stylem, który automatycznie zapobiega tłumaczeniu. W scenariuszach, w których chcesz zapobiec lokalizacji bez używania stylu kodu, zobacz sekcję Niezlokalizowane ciągi.