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

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

ตัวหนา

ใช้ตัวหนาสำหรับองค์ประกอบ 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>

หรือ

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

az group delete -n \<ResourceGroupName\>

แสดงเป็น:

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

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

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

ข้อควรระวัง

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

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

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

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

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

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

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

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

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

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

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

• อย่างนี้: ไฟล์ function.json ถูกสร้างขึ้นโดยแพคเกจ NuGet 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 ที่มีองค์ประกอบโค้ดมากมายอาจดูยุ่งเกินไปกับการจัดรูปแบบโค้ดในทุกที่ คุณอาจเลือกการจัดรูปแบบที่เป็นตัวหนาในบริบทนั้น

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