copenhagen_theme

ธีมโคเปนเฮเกนโดย Zendesk

ธีมโคเปนเฮเกนเป็นธีมเริ่มต้นของ Zendesk Guide ได้รับการออกแบบมาให้ตอบสนองและเข้าถึงได้ เรียนรู้เพิ่มเติมเกี่ยวกับการปรับแต่ง Zendesk Guide ที่นี่

ธีมโคเปนเฮเกนสำหรับศูนย์ช่วยเหลือประกอบด้วย:

• ไฟล์ Manifest
• ชุดของแม่แบบ
• ไฟล์สไตล์ชีตและ JavaScript
• โฟลเดอร์สินทรัพย์

วิธีใช้

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

การปรับแต่งธีมของคุณ

เมื่อคุณแยกพื้นที่เก็บข้อมูลนี้แล้ว คุณสามารถแก้ไขเทมเพลต, CSS, JavaScript และจัดการเนื้อหาได้อย่างอิสระ

ไฟล์ Manifest

รายการช่วยให้คุณสามารถกำหนดกลุ่มการตั้งค่าสำหรับธีมของคุณซึ่งสามารถเปลี่ยนแปลงได้ผ่านทาง UI ใน Theming Center คุณสามารถอ่านเพิ่มเติมเกี่ยวกับไฟล์รายการได้ที่นี่

โฟลเดอร์การตั้งค่า

หากคุณมีตัวแปรประเภท file คุณต้องระบุไฟล์เริ่มต้นสำหรับตัวแปรนั้นในโฟลเดอร์ /settings ไฟล์นี้จะถูกใช้บนแผงการตั้งค่าตามค่าเริ่มต้น และผู้ใช้สามารถอัปโหลดไฟล์อื่นได้หากต้องการ อดีต. หากคุณต้องการให้มีตัวแปรสำหรับภาพพื้นหลังของส่วน ตัวแปรในไฟล์ Manifest ของคุณจะมีลักษณะดังนี้:

 {
  ...
  "settings" : [ {
    "label" : "Images" ,
    "variables" : [ {
      "identifier" : "background_image" ,
      "type" : "file" ,
      "description" : "Background image for X section" ,
      "label" : "Background image" ,
    } ]
  } ]
}

และนี่จะค้นหาไฟล์ภายในโฟลเดอร์การตั้งค่าชื่อ: background_image

การเพิ่มสินทรัพย์

คุณสามารถเพิ่มเนื้อหาลงในโฟลเดอร์เนื้อหาและใช้ใน CSS, JavaScript และเทมเพลตของคุณได้ คุณสามารถอ่านเพิ่มเติมเกี่ยวกับสินทรัพย์ได้ที่นี่

กำลังเผยแพร่ธีมของคุณ

หลังจากที่คุณปรับแต่งธีมของคุณแล้ว คุณสามารถดาวน์โหลดพื้นที่เก็บข้อมูลเป็นไฟล์ zip และนำเข้าไปยัง Theming Center

คุณสามารถปฏิบัติตามเอกสารสำหรับการนำเข้าได้ที่นี่

คุณยังสามารถนำเข้าได้โดยตรงจาก GitHub - เรียนรู้เพิ่มเติมที่นี่

เทมเพลต

ธีมประกอบด้วยเทมเพลตทั้งหมดที่ใช้สำหรับศูนย์ช่วยเหลือซึ่งมีฟีเจอร์ ทั้งหมด ให้เลือก รายการเทมเพลตในธีม:

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

คุณสามารถเพิ่มเทมเพลตเสริมได้สูงสุด 10 เทมเพลตสำหรับ:

• หน้าบทความ
• หน้าหมวดหมู่
• หน้ามาตรา

คุณทำได้โดยการสร้างไฟล์ภายใต้โฟลเดอร์ templates/article_pages , templates/category_pages หรือ templates/section_pages เรียนรู้เพิ่มเติมที่นี่

สไตล์ชีตและ JavaScript

เราใช้ Rollup เพื่อรวบรวมไฟล์ JS และ CSS ที่ใช้ในธีม - style.css และ script.js อย่าแก้ไขสิ่งเหล่านี้โดยตรง เนื่องจากจะถูกสร้างใหม่ในระหว่างการเผยแพร่

ในการเริ่มต้น:

$ yarn install
$ yarn start

ซึ่งจะรวบรวมซอร์สโค้ดทั้งหมดใน src และ styles และคอยดูการเปลี่ยนแปลง นอกจากนี้ยังจะเริ่ม preview ด้วย

หมายเหตุ:

• เราตั้งใจไม่ใช้ babel เมื่อคอมไพล์ script.js เพื่อที่เราจะได้เอาต์พุตบันเดิลที่สะอาด ตรวจสอบให้แน่ใจว่าใช้เฉพาะฟีเจอร์ ecmascript ที่รองรับอย่างกว้างขวาง (ES2015)
• ห้ามแก้ไข style.css , script.js และไฟล์ภายในโฟลเดอร์ assets โดยตรง พวกมันถูกสร้างขึ้นใหม่ระหว่างการเปิดตัว
• การแสดงตัวอย่างจำเป็นต้องเข้าสู่ระบบ ดังนั้นตรวจสอบให้แน่ใจว่าได้รัน yarn zcli login -i ก่อน หากคุณยังไม่เคยดำเนินการดังกล่าวมาก่อน

สินทรัพย์

ธีมโคเปนเฮเกนมาพร้อมกับเนื้อหา JavaScript บางส่วน แต่คุณสามารถเพิ่มเนื้อหาอื่น ๆ ให้กับธีมของคุณได้โดยวางไว้ในโฟลเดอร์ assets

ทำปฏิกิริยาส่วนประกอบ

ตั้งแต่เวอร์ชัน 4.0.0 ธีมโคเปนเฮเกนใช้ส่วนประกอบ React บางส่วนเพื่อเรนเดอร์บางส่วนของ UI ส่วนประกอบเหล่านี้อยู่ในโฟลเดอร์ src/modules และสร้างขึ้นโดยใช้ไลบรารีส่วนประกอบ Zendesk Garden

คอมโพเนนต์เหล่านี้รวมเป็นโมดูล JavaScript ดั้งเดิมโดยเป็นส่วนหนึ่งของกระบวนการสร้าง Rollup และส่งออกมาเป็นไฟล์ JS ในโฟลเดอร์ assets เนื่องจากแอสเซทถูกเปลี่ยนชื่อเมื่อติดตั้งธีม จึงต้องนำเข้าโมดูลโดยใช้ตัวช่วยแอสเซท

เพื่อให้กระบวนการนำเข้าโมดูลง่ายขึ้น เราได้เพิ่มปลั๊กอิน Rollup ที่สร้างแผนที่นำเข้าที่จับคู่ชื่อโมดูลกับ URL ของเนื้อหา จากนั้นอิมพอร์ตแมปนี้จะถูกแทรกลงในเทมเพลต document_head.hbs ในระหว่างการสร้าง

ตัวอย่างเช่น หากคุณกำหนดโมดูลชื่อ my-module ในโฟลเดอร์ src/modules/my-module คุณสามารถเพิ่มโมดูลนั้นลงในไฟล์ rollup.config.mjs ได้ดังนี้:

 export default defineConfig ( [
  // ...
  // Configuration for bundling modules in the src/modules directory
  {
    // ...
    input : {
      "my-module" : "src/modules/my-module/index.js" ,
    } ,
    // ...
  }
] ) ;

Rollup จะสร้างไฟล์ชื่อ my-module-bundle.js ในโฟลเดอร์ assets และแผนที่นำเข้านี้จะถูกเพิ่มลงในเทมเพลต document_head.hbs :

 < script type =" importmap " >
{
  "imports" : {
    "my-module" : "{{asset 'my-module-bundle.js'}}" ,
  }
}
</ script >

จากนั้น คุณสามารถนำเข้าโมดูลในเทมเพลตของคุณได้ดังนี้:

 < script type = " module " >
  import { something } from " my-module " ;

  // ...
</ script > 

ความเป็นสากล

I18n ถูกนำไปใช้ในส่วนประกอบ React โดยใช้ไลบรารี react-i18next เราใช้ไฟล์ JSON แบบแบนและเราใช้ . เป็นตัวคั่นสำหรับพหูพจน์ ซึ่งแตกต่างจากค่าเริ่มต้น _ และได้รับการกำหนดค่าระหว่างการเริ่มต้น

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

การบูรณาการกับระบบการแปลของ Zendesk

การเพิ่มสตริงการแปล

สตริงการแปลจะถูกเพิ่มโดยตรงในซอร์สโค้ด โดยปกติจะใช้ตะขอ useTranslation โดยส่งคีย์และค่าภาษาอังกฤษเริ่มต้น:

 import { useTranslation } from 'react-i18next' ;

function MyComponent ( ) {
  const { t } = useTranslation ( ) ;

  return < div > { t ( "my-key" , "My default value" ) } < / div>
}

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

พหูพจน์

เมื่อใช้รูปพหูพจน์ เราจำเป็นต้องระบุค่าเริ่มต้นสำหรับค่า zero one และค่า other ตามที่ระบบการแปลของเราร้องขอ ซึ่งสามารถทำได้โดยการส่งค่าเริ่มต้นในตัวเลือกของฟังก์ชัน t

 t ( "my-key" , {
  "defaultValue.zero" : "{{count}} items" ,
  "defaultValue.one" : "{{count}} item" ,
  "defaultValue.other" : "{{count}} items" ,
  count : ...
} ) 

การสกัดสตริง

สคริปต์ bin/extract-strings.mjs สามารถใช้เพื่อแยกสตริงการแปลจากซอร์สโค้ดและใส่ไว้ในไฟล์ YAML ที่ได้รับจากระบบการแปลภายในของเรา การใช้สคริปต์ได้รับการบันทึกไว้ในสคริปต์เอง

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

กำลังอัปเดตไฟล์การแปล

ใช้ bin/update-modules-translations.mjs เพื่อดาวน์โหลดคำแปลล่าสุดสำหรับโมดูลทั้งหมด จากนั้นไฟล์ทั้งหมดจะถูกรวมกลุ่มโดยกระบวนการสร้างในไฟล์ [MODULE]-translations-bundle.js ไฟล์เดียว

ในครั้งแรกที่มีการเพิ่มการแปลลงในโมดูล คุณจะต้องเพิ่มการแมประหว่างโฟลเดอร์โมดูลและชื่อแพ็คเกจบนระบบการแปลไปยังตัวแปร MODULE ในสคริปต์ ตัวอย่างเช่น หากโมดูลอยู่ใน src/modules/my-module และชื่อแพ็กเกจคือ cph-theme-my-module คุณต้องเพิ่ม:

 const MODULES = {
  ... ,
  "my-module" : "cph-theme-my-module"
}

การทดสอบการเข้าถึง

เราใช้สคริปต์โหนดที่กำหนดเองซึ่งเรียกใช้ Lighthouse สำหรับการทดสอบการเข้าถึงแบบอัตโนมัติ

มีสองวิธีในการรันสคริปต์:

• โหมดการพัฒนา - ดำเนินการตรวจสอบการเข้าถึงในหน้าตัวอย่างธีมท้องถิ่นในบัญชีเฉพาะ ต้องใช้ zcli themes:preview เพื่อให้ทำงาน;
• โหมด CI - ดำเนินการตรวจสอบการเข้าถึงในธีมสดของบัญชีเฉพาะ

อาจจำเป็นต้องมีการทดสอบด้วยตนเองเพิ่มเติมนอกเหนือจากที่กล่าวมาข้างต้น ทั้งนี้ขึ้นอยู่กับขอบเขตของการทดสอบ เครื่องมือต่างๆ เช่น ax DevTools โปรแกรมอ่านหน้าจอ เช่น VoiceOver ตัวตรวจสอบคอนทราสต์ ฯลฯ สามารถช่วยการทดสอบดังกล่าวได้

โหมดการพัฒนา

หากต้องการเรียกใช้การตรวจสอบการเข้าถึงขณะเปลี่ยนธีม:

1. เริ่มรวบรวมและดูตัวอย่างการเปลี่ยนแปลงตามปกติ:

$ yarn install
$ yarn start

2. สร้างไฟล์ .a11yrc.json ในโฟลเดอร์รูท (ดูตัวอย่าง)

   1. ระบุบัญชี/โดเมนย่อยเพื่อดูตัวอย่างธีมเพื่อให้แน่ใจว่าตรงกับโปรไฟล์ zcli ที่ใช้งานอยู่
   2. กรอก username และ password ด้วยข้อมูลรับรองของผู้ใช้ผู้ดูแลระบบ
   3. ระบุ urls ที่จะทดสอบ (หากปล่อยว่างไว้ สคริปต์จะทดสอบ URL ทั้งหมด)

3. ในคอนโซลแยกต่างหาก ให้รันการตรวจสอบการเข้าถึงในโหมดการพัฒนา:

 yarn test-a11y -d

จากนั้นการตรวจสอบ A11y จะทำงานบนการแสดงตัวอย่างที่เริ่มต้นในขั้นตอน 1

โหมดซีไอ

หากต้องการดำเนินการตรวจสอบการเข้าถึงในธีมที่ใช้งานจริงของบัญชีใดบัญชีหนึ่ง จะต้อง:

1. ติดตั้งโมดูลโหนด:

 yarn install

2. ตั้งค่า end_user_email , end_user_password , subdomain และ urls เป็นตัวแปรสภาพแวดล้อม และดำเนินการตรวจสอบการเข้าถึงในโหมด CI เช่น:

 end_user_email=<EMAIL> 
end_user_password=<PASSWORD> 
subdomain=<SUBDOMAIN> 
urls="
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests/new
    https://<SUBDOMAIN>.zendesk.com/hc/en-us/requests" 
yarn test-a11y 

รายการละเว้น

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

รายการควรรวมถึง:

• รหัสการตรวจสอบ;
• path เป็นสตริงรูปแบบ URL
• selector เป็นสตริง

ตัวอย่างเช่น:

  custom: {
    ignore: {
      tabindex: [
        {
          path : "*" ,
          selector : "body > a.skip-navigation" ,
        } ,
      ] ,
      aria - allowed - attr : [
        {
          path : "/hc/:locale/profiles/:id" ,
          selector : "body > div.profile-info"
        }
      ]
    } ,
  } ,

ในตัวอย่างนี้ ข้อผิดพลาดสำหรับดัชนี tabindex การตรวจสอบที่มี body > a.skip-navigation จะถูกรายงานเป็นคำเตือนในทุกหน้า ( * ) สิ่งเดียวกันนี้จะเกิดขึ้นสำหรับการตรวจสอบ aria-allowed-attr ด้วย body > div.profile-info แต่สำหรับหน้าโปรไฟล์ผู้ใช้ /hc/:locale/profiles/:id เท่านั้น

โปรดทราบว่าควรใช้เมื่อจำเป็นเท่านั้น การเข้าถึงควรเป็นจุดสนใจและมีความสำคัญเมื่อทำการเปลี่ยนแปลงธีม

มีส่วนร่วม

ยินดีต้อนรับคำขอดึงบน GitHub ที่ https://github.com/zendesk/copenhagen_theme โปรดระบุ @zendesk/vikings เมื่อสร้างคำขอดึง

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

 <type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• type: อธิบายหมวดหมู่ของการเปลี่ยนแปลง ดูประเภทที่รองรับ
• ขอบเขต: (ไม่บังคับ) อธิบายสิ่งที่ได้รับผลกระทบจากการเปลี่ยนแปลง
• เรื่อง: คำอธิบายเล็กๆ น้อยๆ ของการเปลี่ยนแปลง
• เนื้อความ: (ไม่บังคับ) ข้อมูลบริบทเพิ่มเติมเกี่ยวกับการเปลี่ยนแปลง
• ส่วนท้าย: (ไม่บังคับ) เพิ่มลิงก์ภายนอก การอ้างอิงปัญหา และข้อมูลเมตาอื่นๆ

เช่น:

 chore: automate release
fix(styles): fix button padding
feat(script): add auto focus to fields with errors

เราใช้ husky และ commitlint เพื่อตรวจสอบข้อความเมื่อกระทำ

เราใช้การดำเนินการ Github ร่วมกับ semantic-release เพื่อเผยแพร่ธีมเวอร์ชันใหม่เมื่อมีการรวม PR ในการผสานแต่ละครั้ง semantic-release จะวิเคราะห์ข้อความที่คอมมิตและสรุปการชนเวอร์ชันความหมาย จากนั้นจะสร้างแท็ก git อัปเดตเวอร์ชันรายการ และสร้างบันทึกการเปลี่ยนแปลงที่เกี่ยวข้อง

ประเภทคอมมิต

รายการด้านล่างจะอธิบายประเภทการคอมมิตที่รองรับและผลกระทบในรีลีสและบันทึกการเปลี่ยนแปลง

พิมพ์	คำอธิบาย	ปล่อย	บันทึกการเปลี่ยนแปลง
สร้าง	การเปลี่ยนแปลงที่ส่งผลต่อระบบบิลด์หรือการขึ้นต่อกันภายนอก	-	-
งานบ้าน	การเปลี่ยนแปลงอื่นๆ ที่ไม่แก้ไขซอร์สโค้ด	-	-
ci	การเปลี่ยนแปลงไฟล์การกำหนดค่า CI และสคริปต์ของเรา	-	-
เอกสาร	เอกสารประกอบการเปลี่ยนแปลงเท่านั้น	-	-
ความสำเร็จ	คุณลักษณะใหม่	ส่วนน้อย	คุณสมบัติ
แก้ไข	แก้ไขข้อบกพร่อง	แพทช์	แก้ไขข้อบกพร่อง
สมบูรณ์แบบ	การเปลี่ยนแปลงรหัสที่ช่วยปรับปรุงประสิทธิภาพ	แพทช์	การปรับปรุงประสิทธิภาพ
ปรับโครงสร้างใหม่	การเปลี่ยนแปลงโค้ดที่ไม่แก้ไขข้อบกพร่องหรือเพิ่มฟีเจอร์	-	-
ย้อนกลับ	คืนค่าการคอมมิตก่อนหน้านี้	แพทช์	เปลี่ยนกลับ
สไตล์	การเปลี่ยนแปลงที่ไม่ส่งผลต่อความหมายของโค้ด (ช่องว่าง การจัดรูปแบบ เครื่องหมายอัฒภาคที่หายไป ฯลฯ)	-	-
ทดสอบ	เพิ่มการทดสอบที่ขาดหายไปหรือแก้ไขการทดสอบที่มีอยู่	-	-

การเปลี่ยนแปลงที่ทำลายล้าง

คอมมิตที่เพิ่มการเปลี่ยนแปลงที่แตกหักควรรวม BREAKING CHANGE ไว้ในเนื้อหาหรือส่วนท้ายของข้อความคอมมิต

เช่น:

 feat: update theme to use theming api v2

BREAKING CHANGE: theme is now relying on functionality that is exclusive to the theming api v2

จากนั้นสิ่งนี้จะสร้างรุ่นหลักและเพิ่มส่วน BREAKING CHANGES ในบันทึกการเปลี่ยนแปลง

รายงานข้อผิดพลาด

ต้องส่งรายงานข้อผิดพลาดผ่านช่องทางการสนับสนุนมาตรฐานของ Zendesk: https://www.zendesk.com/contact/