แนวทางการจัดรูปแบบข้อความ

การใช้สไตล์ตัวหนา ตัวเอียง และโค้ดที่สอดคล้องและเหมาะสมสำหรับองค์ประกอบข้อความจะปรับปรุงความสามารถในการอ่านและช่วยหลีกเลี่ยงความเข้าใจผิด

ตัวหนา

ใช้ตัวหนาสำหรับองค์ประกอบ UI เช่น การเลือกเมนู ชื่อกล่องโต้ตอบ และชื่อเขตข้อมูลอินพุต

ตัวอย่าง

• อย่างนี้: ที่ Solution Explorer ให้คลิกขวาที่โหนดโครงการ จากนั้นเลือก เพิ่ม > รายการใหม่
• ไม่ใช่อย่างนี้: ที่ Solution Explorer ให้คลิกขวาที่โหนดโครงการจากนั้นเลือก เพิ่ม > รายการใหม่
• ไม่ใช่อย่างนี้: ที่ Solution Explorer ให้คลิกขวาที่โหนดโครงการจากนั้นเลือก เพิ่ม > รายการใหม่

ตัวเอียง

ใช้ตัวเอียงสำหรับ:

• แนะนำคำศัพท์ใหม่พร้อมคำจำกัดความหรือคำอธิบาย
• ชื่อไฟล์ ชื่อโฟลเดอร์ พาธ
• อินพุตจากผู้ใช้

ตัวอย่าง

• อย่างนี้: ที่ App Service แอปทํางานใน แผนบริการแอป แผนบริการแอปกำหนดชุดของทรัพยากรการคำนวณเพื่อให้เว็บแอปทำงาน
• ไม่ใช่อย่างนี้: ที่ App Service แอปทํางานใน "แผนบริการแอป" แผนบริการแอปกําหนดชุดของทรัพยากรการคํานวณเพื่อให้เว็บแอปทํางาน
• อย่างนี้: แทนที่โค้ดใน HttpTriggerCSharp.cs ด้วยโค้ดต่อไปนี้
• ไม่ใช่อย่างนี้: แทนที่โค้ดใน HttpTriggerCSharp.cs ด้วยโค้ดต่อไปนี้
• อย่างนี้: ป้อน ContosoUniversity สําหรับ ชื่อ จากนั้นเลือก เพิ่ม
• ไม่ใช่อย่างนี้: ป้อน "ContosoUniversity" สําหรับ ชื่อ จากนั้นเลือก เพิ่ม

สไตล์โค้ด

ใช้สไตล์โค้ดสำหรับ:

• องค์ประกอบของโค้ด เช่น ชื่อเมธอด ชื่อคุณสมบัติ และคำสำคัญภาษา
• คำสั่ง SQL
• ชื่อแพคเกจ NuGet
• คําสั่งคอมมานไลน์*
• ชื่อตารางและคอลัมน์ฐานข้อมูล
• ชื่อทรัพยากรที่ไม่ควรแปลเป็นภาษาท้องถิ่น (เช่น ชื่อเครื่องเสมือน)
• URL ที่คุณไม่ต้องการให้สามารถคลิกได้

เพราะเหตุใด คำแนะนำสไตล์เก่าระบุตัวหนาสำหรับองค์ประกอบข้อความเหล่านี้มากมาย อย่างไรก็ตาม บทความส่วนใหญ่มีการแปลเป็นภาษาท้องถิ่นและสไตล์โค้ดจะบอกให้นักแปลปล่อยให้ไม่มีการแปลส่วนนั้นของข้อความ

สไตล์โค้ดสามารถเป็นแบบ อินไลน์ (ล้อมรอบด้วย ') หรือ บล็อกโค้ดแบบ ล้อมด้วยเฟนซ์ (ล้อมรอบด้วย ''') ที่ครอบคลุมหลายบรรทัด ใส่ส่วนย่อยของโค้ดและพาธที่ยาวกว่าในบล็อกโค้ดแบบล้อมด้วยอักขระ

* ในคําสั่งบรรทัดคําสั่ง ให้ใช้เครื่องหมายทับไปข้างหน้าในเส้นทางไฟล์หากได้รับการสนับสนุนในทุกแพลตฟอร์ม ใช้เครื่องหมายทับขวาเพื่อแสดงคําสั่งที่ทํางานบน Windows เมื่อรองรับเฉพาะเครื่องหมายทับขวาเท่านั้น ตัวอย่างเช่น เครื่องหมายทับทํางานบน .NET CLI บนทุกแพลตฟอร์ม ดังนั้นคุณจะใช้ dotnet build foldername/filename.csproj แทนdotnet build foldername\filename.csproj

ตัวอย่างการใช้สไตล์อินไลน์

• อย่างนี้: ตามค่าเริ่มต้น เฟรมเวิร์กของเอนทิตี ตีความคุณสมบัติที่ชื่อ Id หรือ ClassnameID เป็นคีย์หลัก
• ไม่ใช่อย่างนี้: ตามค่าเริ่มต้น เฟรมเวิร์กของเอนทิตี ตีความคุณสมบัติที่ชื่อ Id หรือ ClassnameID เป็นคีย์หลัก
• อย่างนี้: แพคเกจ Microsoft.EntityFrameworkCore ให้การสนับสนุนรันไทม์สําหรับ EF Core
• ไม่ใช่อย่างนี้: แพคเกจ Microsoft EntityFrameworkCore ให้การสนับสนุนรันไทม์สําหรับ EF Core

ตัวอย่างของบล็อกโค้ดแบบล้อมด้วยอักขระ

• อย่างนี้: ไม่มีคําสั่งที่ถูกส่งไปยังฐานข้อมูลตามคําสั่งที่เพิ่งเปลี่ยน IQueryableเช่นโค้ดต่อไปนี้:

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

• ไม่ใช่อย่างนี้: ไม่มีคําสั่งที่ถูกส่งไปยังฐานข้อมูลตามคําสั่งที่เพิ่งเปลี่ยน IQueryable เช่น นักเรียน var = บริบท Students.Where(s => s.LastName == "Davolio")

• อย่างนี้: ตัวอย่างเช่น เมื่อต้องการเรียกใช้ Get-ServiceLog.ps1 สคริปต์ใน C:\Scripts ไดเรกทอรี ให้พิมพ์:

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

• ไม่ใช่อย่างนี้: ตัวอย่างเช่น เมื่อต้องการเรียกใช้ สคริปต์ Get-ServiceLog.ps1 ใน ไดเรกทอรี C:\Scripts ให้พิมพ์: "C:\Scripts\Get-ServiceLog.ps1"

• บล็อกโค้ดแบบล้อมด้วยอักขระทั้งหมดต้องมีแท็กภาษาที่ผ่านการอนุมัติ สำหรับรายการแท็กภาษาที่รองรับ ให้ดู วิธีการรวมโค้ดใน Docs

ข้อความตัวอย่าง

ถ้าคุณต้องการให้ผู้ใช้แทนที่ส่วนของสตริงที่ป้อนเข้าด้วยค่าของตนเอง ให้ใช้ข้อความตัวอย่างที่ทําเครื่องหมายด้วยวงเล็บมุม (น้อยกว่า < และมากกว่า > อักขระ)

ตัวเลือกที่ 1: ใช้การจัดรูปแบบโค้ดเพื่อล้อมรอบคําในตัวแทนข้อความหรือวลีที่ครอบคลุม ตัวอย่างเช่น คุณสามารถใช้แบ็กทิกเดี่ยว ' สําหรับการจัดรูปแบบโค้ดแบบอินไลน์สําหรับวลีเดียว หรือใช้เครื่องหมายสามครั้ง ''' สําหรับการจัดรูปแบบแบบล้อมด้วยรหัส

`az group delete -n <ResourceGroupName>`

แสดงผลเป็น:

az group delete -n <ResourceGroupName>

or

ตัวเลือกที่ 2: ใช้อักขระ\เครื่องหมายทับขวาเพื่อเลี่ยงอักขระวงเล็บมุมใน Markdown เช่น \< และ\> ในขณะที่จําเป็นต้องมีการเล็ดรอดแรกบนวงเล็บ \< มุมซ้าย แต่การเล็ดลอดวงเล็บ \> ปิดจะทํางานได้เช่นกันสําหรับความสอดคล้อง HTML ที่แสดงผลไม่แสดงอักขระหลีกในตัวอ่าน:

az group delete -n \<ResourceGroupName\>

แสดงผลเป็น:

ลบกลุ่ม az -n <ResourceGroupName>

แจ้งให้ผู้อ่านเกี่ยวกับตัวยึด: ในข้อความที่อยู่ก่อนหน้าตัวอย่างตัวแทนข้อความดังกล่าว ให้อธิบายผู้อ่านว่าต้องนําข้อความในวงเล็บออกและแทนที่ด้วยค่าจริง เราขอแนะนําให้ใช้ตัวเอียงสําหรับการป้อนข้อมูลของผู้ใช้ คุณสามารถจัดรูปแบบตัวเอียงภายในมุมในวงเล็บโค้ดแบบอินไลน์:

ในตัวอย่างต่อไปนี้ แทนที่ตัวแทนข้อความ <ResourceGroupName> ด้วยชื่อกลุ่มทรัพยากรของคุณเอง

ข้อควรระวัง

ไซต์ Microsoft Learn ไม่แสดง <ตัวแทน> ข้อความที่ใช้วงเล็บมุมในกรณีที่วงเล็บไม่สามารถเลือนไปได้อย่างถูกต้อง หรือข้อความไม่ได้จัดรูปแบบโค้ด กระบวนการสร้าง Microsoft Learn ตี <ความวลีตัวแทน> ข้อความเป็นแท็ก HTML ที่อาจเป็นอันตรายต่อเบราว์เซอร์ของผู้อ่าน และทําเครื่องหมายว่าเป็น แท็ก html ที่ไม่ได้รับอนุญาต คุณจะเห็นคําแนะนําในรายงานรุ่น และคําตัวแทนจะไม่แสดงในผลลัพธ์หน้า Microsoft Learn เมื่อเกิดเหตุการณ์ดังกล่าว

เมื่อต้องการหลีกเลี่ยงการสูญเสียเนื้อหาในตัวแทนข้อความ ให้ใช้codeการจัดรูปแบบหรืออักขระเลี่ยง (\<\>) ตามที่อธิบายไว้ก่อนหน้านี้

เราไม่สนับสนุนการใช้วงเล็บปีกกา { } เป็นตัวแทนไวยากรณ์ ผู้อ่านสามารถสร้างความสับสนกับตัวแทนเครื่องหมายวงเล็บปีกกาแบบเดียวกับที่ใช้ใน:

• ข้อความที่แทนที่ได้
• สตริงรูปแบบ
• การใช้ตัวแปรในสตริง
• เทมเพลตข้อความ
• โครงสร้างการเขียนโปรแกรมที่คล้ายกัน

การกําหนดปลอกและระยะห่าง: คุณสามารถแยกชื่อตัวแทนข้อความด้วยเครื่องหมายยัติภังค์ ("เคบับกรณี") หรือด้วยขีดล่าง หรือคุณสามารถทําได้โดยใช้ตัวพิมพ์ Pascal กรณี Kebab อาจสร้างข้อผิดพลาดทางไวยากรณ์ และขีดล่างอาจขัดแย้งกับการขีดเส้นใต้ได้ ตัวพิมพ์ใหญ่ทั้งหมดสามารถขัดแย้งกับค่าคงที่ที่มีชื่อในหลายภาษา แม้ว่าตัวยึดอาจดึงดูดความสนใจไปยังชื่อตัวแทนข้อความได้ด้วย

<Resource-Group-Name> หรือ <ResourceGroupName>

หัวเรื่องและข้อความลิงก์

อย่าใช้สไตล์อินไลน์ เช่น ตัวเอียง หรือตัวหนากับหัวเรื่องหรือข้อความไฮเปอร์ลิงก์

เพราะเหตุใด?

ผู้คนพึ่งพาข้อความไฮเปอร์ลิงก์มาตรฐานเพื่อระบุองค์ประกอบข้อความว่าเป็นลิงก์แบบคลิกได้ ยกตัวอย่างเช่น การจัดรูปแบบลิงก์เป็นตัวเอียงอาจบดบังข้อเท็จจริงที่ว่าข้อความนั้นเป็นลิงก์ หัวเรื่องมีสไตล์เป็นของตัวเอง และการผสมสไตล์อื่น ๆ เข้าด้วยกันดูไม่ดี

ตัวอย่างของหัวเรื่องและข้อความลิงก์

• อย่างนี้: ไฟล์ function.json ถูกสร้างขึ้นโดย NuGet package Microsoft.NET.Sdk.Functions

• ไม่ใช่อย่างนี้: ไฟล์ function.json ถูกสร้างขึ้นโดยแพคเกจ NuGet Microsoft.NET.Sdk.Functions

• อย่างนี้:

  ### The Microsoft.NET.Sdk.Functions package
  

• ไม่ใช่อย่างนี้:

  ### The *Microsoft.NET.Sdk.Functions* package
  

คีย์ลัดและแป้นพิมพ์ลัด

เมื่ออ้างถึงคีย์หนึ่งหรือคีย์ผสม ให้ทำตามหลักทั่วไปเหล่านี้:

• ใช้ตัวอักษรแรกของชื่อคีย์
• ล้อมรอบชื่อคีย์ด้วย <kbd> และ </kbd> แท็ก HTML
• ใช้ "+" เพื่อเชื่อมคีย์ที่ผู้ใช้เลือกในเวลาเดียวกัน

ตัวอย่างของคีย์ลัดและแป้นพิมพ์ลัด

• อย่างนี้: เลือก Alt+Ctrl S+
• ไม่ใช่อย่างนี้: กด ALT+CTRL+S
• ไม่ใช่อย่างนี้: กดALT+CTRL+S

ข้อยกเว้น

หลักเกณฑ์ของสไตล์ไม่ใช่กฎที่เข้มงวด ในบริบทที่หลักเกณฑ์ดังกล่าวเป็นอุปสรรคต่อความสามารถในการอ่าน ให้ทำสิ่งที่แตกต่างกัน ตัวอย่างเช่น ตาราง HTML ที่มีองค์ประกอบโค้ดมากมายอาจดูยุ่งเกินไปกับการจัดรูปแบบโค้ดในทุกที่ คุณอาจเลือกการจัดรูปแบบที่เป็นตัวหนาในบริบทนั้น

ถ้าคุณเลือกสไตล์ข้อความอธิบายรูปภาพที่มีการเรียกใช้โค้ดตามปกติ กรุณาตรวจสอบให้แน่ใจว่าข้อความที่มีการแปลในบทความเวอร์ชันที่แปลเป็นภาษาท้องถิ่นสามารถใช้งานได้ โค้ดเป็นสไตล์เดียวที่ป้องกันการแปลโดยอัตโนมัติ สำหรับสถานการณ์ที่คุณต้องการป้องกันไม่ให้มีการแปลเป็นภาษาท้องถิ่นโดยไม่ใช้สไตล์โค้ด โปรดดู สตริงที่ไม่แปลเป็นภาษาท้องถิ่น