Các mục thanh bên

Chúng tôi đã giới thiệu ba loại vật phẩm trong ví dụ ở phần trước: , , và , có cách sử dụng khá trực quan. Chúng tôi sẽ chính thức giới thiệu các API của họ. Ngoài ra còn có loại thứ tư: , mà chúng tôi sẽ giải thích chi tiết sau.doccategorylinkautogenerated

Tài liệu: liên kết đến trang tài liệu, liên kết trang đó với thanh bên Liên kết: liên kết đến bất kỳ trang nội bộ hoặc bên ngoài nào Danh mục: tạo một danh sách thả xuống các mục thanh bên Tự động tạo: tự động tạo lát cắt thanh bên HTML: hiển thị HTML thuần túy ở vị trí của mục *Tham khảo: liên kết đến trang tài liệu, không làm cho mục tham gia vào quá trình tạo điều hướng Tài liệu: liên kết đến tài liệu Sử dụng loại để liên kết đến trang tài liệu và gán tài liệu đó vào thanh bên:doc

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut

Ví dụ:

sidebars.js

export default {
  mySidebar: [
    // Normal syntax:
    {
      type: 'doc',
      id: 'doc1', // document ID
      label: 'Getting started', // sidebar label
    },

    // Shorthand syntax:
    'doc2', // document ID
  ],
};

Nếu bạn sử dụng cách viết tắt tài liệu hoặc thanh bên được tạo tự động, bạn sẽ mất khả năng tùy chỉnh nhãn thanh bên thông qua định nghĩa mục. Tuy nhiên, bạn có thể sử dụng vấn đề phía trước của Markdown trong tài liệu đó, có mức độ ưu tiên cao hơn so với khóa trong mục thanh bên. Tương tự, bạn có thể sử dụng để khai báo siêu dữ liệu tùy chỉnh cho trang tài liệu.sidebar_labellabelsidebar_custom_props

ghi Một mục đặt liên kết thanh bên ngầm. Không gán cùng một tài liệu cho nhiều thanh bên: thay đổi loại thành thay thế.docref

mẹo Đạo cụ tùy chỉnh sidebar là một cách hữu ích để truyền siêu dữ liệu doc tùy ý đến phía máy khách, vì vậy bạn có thể nhận thêm thông tin khi sử dụng bất kỳ hook nào liên quan đến doc để tìm nạp đối tượng doc.

Liên kết: liên kết đến bất kỳ trang nào Use the type to link to any page (internal or external) that is not a doc.link

type SidebarItemLink = {
  type: 'link';
  label: string;
  href: string;
  className?: string;
  description?: string;
};

Ví dụ:

sidebars.js

export default {
  myLinksSidebar: [
    // External link
    {
      type: 'link',
      label: 'Facebook', // The link label
      href: 'https://facebook.com', // The external URL
    },

    // Internal link
    {
      type: 'link',
      label: 'Home', // The link label
      href: '/', // The internal path
    },
  ],
};

HTML: hiển thị đánh dấu tùy chỉnh Sử dụng loại để hiển thị HTML tùy chỉnh trong thẻ của mục.

html<li>

Điều này có thể hữu ích để chèn các mục tùy chỉnh như dải phân cách, tiêu đề mục, quảng cáo và hình ảnh.

type SidebarItemHtml = {
  type: 'html';
  value: string;
  defaultStyle?: boolean; // Use default menu item styles
  className?: string;
};

Example:

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
      defaultStyle: true, // Use the default menu item styling
    },
  ],
};

mẹo Mục menu đã được bao bọc trong một thẻ, vì vậy nếu mục tùy chỉnh của bạn đơn giản, chẳng hạn như tiêu đề, chỉ cần cung cấp một chuỗi làm giá trị và sử dụng thuộc tính để tạo kiểu cho nó:

<li>className

sidebars.js

export default {
  myHtmlSidebar: [
    {
      type: 'html',
      value: 'Core concepts',
      className: 'sidebar-title',
    },
  ],
};

Danh mục: tạo hệ thống phân cấp Sử dụng loại để tạo hệ thống phân cấp của các mục thanh bên.category

type SidebarItemCategory = {
  type: 'category';
  label: string; // Sidebar label text.
  items: SidebarItem[]; // Array of sidebar items.
  className?: string;
  description?: string;

  // Category options:
  collapsible: boolean; // Set the category to be collapsible
  collapsed: boolean; // Set the category to be initially collapsed or open by default
  link: SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
};

Ví dụ:

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      collapsible: true,
      collapsed: false,
      items: [
        'creating-pages',
        {
          type: 'category',
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

mẹo Sử dụng cú pháp viết tắt khi bạn không cần tùy chỉnh:

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        Docs: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
      },
    ],
  },
};

Liên kết thể loại Với liên kết danh mục, nhấp vào một danh mục có thể điều hướng bạn đến một trang khác.

mẹo Sử dụng liên kết danh mục để giới thiệu một danh mục tài liệu.

Các danh mục được tạo tự động có thể sử dụng tệp category.yml để khai báo liên kết.

Trang chỉ mục được tạo Bạn có thể tự động tạo một trang chỉ mục hiển thị tất cả các con trực tiếp của danh mục này. Cho phép bạn tùy chỉnh tuyến đường của trang được tạo, mặc định là .slug/category/[categoryName]

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {
        type: 'generated-index',
        title: 'Docusaurus Guides',
        description: 'Learn about the most important Docusaurus concepts!',
        slug: '/category/docusaurus-guides',
        keywords: ['guides'],
        image: '/img/docusaurus.png',
      },
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

Xem thực tế trên trang Hướng dẫn Docusaurus.

mẹo Sử dụng liên kết như một cách nhanh chóng để có được tài liệu giới thiệu.generated-index

Liên kết tài liệu Một thể loại có thể liên kết đến một tài liệu hiện có.

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      link: {type: 'doc', id: 'introduction'},
      items: ['pages', 'docs', 'blog', 'search'],
    },
  ],
};

Xem nó trong thực tế trên trang giới thiệu i18n.

Nhúng chỉ mục được tạo vào trang tài liệu Bạn cũng có thể nhúng danh sách thẻ đã tạo vào trang tài liệu thông thường với thành phần. Nó sẽ hiển thị tất cả các mục thanh bên của danh mục cha của tài liệu hiện tại.DocCardList

docs/sidebar/index.md
import DocCardList from '@theme/DocCardList';

<DocCardList />

📄️ Sidebar items
We have introduced three types of item types in the example in the previous section autogenerated, which we will explain in detail later.

📄️ Autogenerated
Docusaurus can create a sidebar automatically from your filesystem structure: each folder creates a sidebar category, and each file creates a doc link.

📄️ Using multiple sidebars
You can create a sidebar for each set of Markdown files that you want to group together.

Danh mục có thể thu gọn Chúng tôi hỗ trợ tùy chọn mở rộng/thu gọn danh mục. Các thể loại có thể thu gọn theo mặc định, nhưng bạn có thể tắt tính năng thu gọn bằng .collapsible: false

sidebars.js

export default {
  docs: [
    {
      type: 'category',
      label: 'Guides',
      items: [
        'creating-pages',
        {
          type: 'category',
          collapsible: false,
          label: 'Docs',
          items: ['introduction', 'sidebar', 'markdown-features', 'versioning'],
        },
      ],
    },
  ],
};

Để làm cho tất cả các danh mục không thể thu gọn theo mặc định, hãy đặt tùy chọn thành :sidebarCollapsibleplugin-content-docsfalse

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsible: false,
        },
      },
    ],
  ],
};

ghi Tùy chọn in được ưu tiên hơn cấu hình plugin, vì vậy có thể làm cho một số danh mục nhất định có thể thu gọn khi được đặt thành toàn cục.sidebars.jssidebarCollapsiblefalse

Danh mục mở rộng theo mặc định Các thể loại có thể thu gọn được thu gọn theo mặc định. Nếu bạn muốn chúng được mở rộng trong lần render đầu tiên, bạn có thể đặt thành:collapsedfalse

sidebars.js

export default {
  docs: {
    Guides: [
      'creating-pages',
      {
        type: 'category',
        label: 'Docs',
        collapsed: false,
        items: ['markdown-features', 'sidebar', 'versioning'],
      },
    ],
  },
};

Tương tự như , bạn cũng có thể đặt cấu hình toàn cầu thành . Các tùy chọn riêng lẻ trong sẽ vẫn được ưu tiên hơn cấu hình này.collapsibleoptions.sidebarCollapsedfalsecollapsedsidebars.js

docusaurus.config.js

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarCollapsed: false,
        },
      },
    ],
  ],
};

cảnh báo Khi một thể loại có nhưng (thông qua hoặc thông qua cấu hình plugin), thể loại sau được ưu tiên và thể loại vẫn được hiển thị dưới dạng mở rộng.collapsed: truecollapsible: falsesidebars.js

Sử dụng viết tắt Bạn có thể thể hiện các mục thanh bên điển hình mà không cần tùy chỉnh nhiều một cách ngắn gọn hơn với cú pháp viết tắt. Có hai phần cho điều này: viết tắt doc và viết tắt category.

Viết tắt Doc Một mục có type có thể chỉ đơn giản là một chuỗi đại diện cho ID của nó:doc

Tay dài Viết tắt sidebars.js

export default {
  sidebar: [
    {
      type: 'doc',
      id: 'myDoc',
    },
  ],
};

Vì vậy, có thể đơn giản hóa ví dụ trên thành:

sidebars.js

export default {
  mySidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'doc1',
      ],
    },
    {
      type: 'category',
      label: 'Docusaurus',
      items: [
        'doc2',
        'doc3',
      ],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Viết tắt thể loại Một mục thể loại có thể được biểu diễn bằng một đối tượng có khóa là nhãn của nó và giá trị là một mảng các mục con.

Tay dài Viết tắt sidebars.js

export default {
  sidebar: [
    {
      type: 'category',
      label: 'Getting started',
      items: ['doc1', 'doc2'],
    },
  ],
};

Điều này cho phép chúng tôi đơn giản hóa ví dụ đó thành:

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
    },
    {
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Mỗi đối tượng tốc ký sau khi chuyển đổi này sẽ chứa chính xác một mục. Bây giờ hãy xem xét ví dụ đơn giản hơn dưới đây:

sidebars.js

export default {
  mySidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: ['doc2', 'doc3'],
    },
    {
      type: 'link',
      label: 'Learn more',
      href: 'https://example.com',
    },
  ],
};

Lưu ý cách hai cách viết tắt danh mục liên tiếp được nén thành một đối tượng với hai mục nhập. Cú pháp này tạo ra một lát cắt thanh bên: bạn không nên xem đối tượng đó là một mục hàng loạt — đối tượng này được mở gói, với mỗi mục trở thành một mục riêng biệt và chúng được ghép lại với các mục còn lại (trong trường hợp này là liên kết "Tìm hiểu thêm") để tạo thành cấp thanh bên cuối cùng. Các lát cắt thanh bên cũng rất quan trọng khi thảo luận về các thanh bên được tạo tự động.

Bất cứ nơi nào bạn có một mảng các mục được rút gọn thành một danh mục viết tắt, bạn cũng có thể bỏ qua mảng bao gồm đó.

Trước Sau sidebars.js

export default {
  sidebar: [
    {
      'Getting started': ['doc1'],
      Docusaurus: [
        {
          'Basic guides': ['doc2', 'doc3'],
          'Advanced guides': ['doc4', 'doc5'],
        },
      ],
    },
  ],
};