移动端组件研发主题

针对移动端组件研发场景，dumi 基于默认主题提供了移动端组件研发主题，具备以下特性：

1. 移动端设备尺寸的 demo 预览，强制以 iframe 模式加载
2. 基于 umi-hd 的 H5 高清方案
3. 支持默认主题的全部特性，包括站点配置项及 demo 的 compact、background 等配置项
4. demo 预览器支持响应式降级为默认主题模式

预览效果可访问 指南 - 移动端组件研发 查看。

站点配置

移动端组件研发主题提供了如下站点配置项，均在 .dumirc.ts 中的 themeConfig 配置项中配置。

hd

• 类型：{ rules: umiHDConfig[] }
• 默认值：{ rules: [{ mode: 'vw', options: [100, 750] }] }

配置 demo 渲染的高清方案，默认为 750 高清方案，支持的配置项值请参考类型定义。

配置为空数组时可禁用 umi-hd 高清方案：

export default {
  themeConfig: {
    hd: { rules: [] },
  },
};

也可以根据不同设备屏幕宽度切换高清方案：

export default {
  themeConfig: {
    hd: {
      rules: [
        { maxWidth: 375, mode: 'vw', options: [100, 750] },
        { minWidth: 376, maxWidth: 750, mode: 'vw', options: [100, 1500] },
      ],
    },
  },
};

deviceWidth

• 类型：number
• 默认值：375

配置 demo 预览器右侧设备的宽度，必须为数值，设备宽高比始终保持为 1.78。

editLink 2.2.2+

• 类型：boolean | string
• 默认值：true

配置是否在 Markdown 页面内容区域底部展示当前文档的编辑链接。

当配置为 true 时 dumi 会根据项目 package.json 中的 repository 配置及当前分支，使用 hosted-git-info 自动生成编辑链接，仅支持部分代码托管平台；如果你使用的是其他代码托管平台或私有化部署的平台，可以使用字符串模板自定义编辑链接，例如 https://gitlab.example.com/group/repo/{filename}，其中 {filename} 会被替换为当前文档在仓库中的文件路径。

sourceLink 2.3.0+

• 类型：boolean | string
• 默认值：true

主要用于 API Table 中类型的外链，目的是让没有文档的类型，直接导航到仓库中，方便用户参考。

用法与 editLink 类似，不过其自定义字符串模板比 editLink 多了一个 {line} ：https://gitlab.example.com/group/repo/{filename}?L={line}

lastUpdated 2.2.2+

• 类型：boolean
• 默认值：true

配置是否在 Markdown 页面内容区域底部展示当前文档的最后更新时间。

文档最后更新时间来源于 Git 提交记录，如果 Markdown 文档还未被 Git 追踪，那么则会展示构建时间；如果你的文档通过 GitHub Action 进行部署，还需要在 actions/checkout 步骤中加上 fetch-depth: 0 参数以检出所有 Git 提交记录，确保可以 dumi 可以拿到正确的最后更新时间，具体可参考 FAQ - 自动部署。

logo

• 类型：string | false
• 默认值：dumi 的 LOGO

配置导航栏上的站点 LOGO，如果需要配置为本地图片文件，可将图片资源放入 public 文件夹，例如放置 public/logo.png，则配置 /logo.png 即可。

配置为 false 时不展示 LOGO。

name

• 类型：string
• 默认值：undefined

配置导航栏上的站点名称，不配置时不展示。

nav

• Navs类型：{ title: '导航标题', link: '导航路由', activePath: '高亮路径' }[] | Record<string, { title: '导航标题', link: '导航路由', activePath: '高亮路径' }[]>
• 类型：Navs | {mode: "override" | "append" | "prepend", value: Navs}
• 默认值：约定式导航

配置导航栏上的导航项，不配置时默认为约定式导航。约定式导航生成规则可参考 约定式路由。

{
  // 单语言时配置数组即可
  nav: [{ title: 'Blog', link: '/blog' }],

  // 多语言时配置对象，key 为语言名
  nav: {
    'zh-CN': [{ title: '博客', link: '/blog' }],
    'en-US': [{ title: 'Blog', link: '/en/blog' }],
  },

  // 支持通过 nav 将路由追加到约定路由前面或后面
  nav: {
    // mode可选值有：override、append、prepend
    // - override: 直接覆盖约定导航，与 nav: [{ title: 'Blog', link: '/blog' }] 配置相同
    // - append: 将 value 中的导航追加到约定路由后面
    // - prepend: 将 value 中的导航添加到约定路由前面
    mode: "append",
    value: [{ title: 'Blog', link: '/blog' }]
  }
}

sidebar

• 类型：Record<'/nav_path', { title: '分组名称（可选）', children: { title: '菜单项', link: '菜单路由' }[] }[]>
• 默认值：约定式侧边菜单

配置侧边栏菜单，key 为导航路由，配置后对该导航下的所有一级子页面生效，例如 { '/guide': [] } 只对 /guide 及 /guide/xxx 生效。

不配置时默认为约定式侧边菜单，约定式侧边菜单生成规则可参考 约定式路由。

footer

• 类型：string | false
• 默认值：Powered by dumi

配置页脚内容，可以是 HTML，配置 false 时不展示。

rtl

• 类型：boolean
• 默认值：false

是否开启 RTL 切换，配置为 true 时导航栏会展示 RTL 按钮，用于将站点文本阅读方向切换为『从右到左』，通常在站点用户群体中有使用希伯来语或阿拉伯语时启用。

showLineNum 2.2.0+

• 类型：boolean
• 默认值：false

是否在代码块中展示行号，配置为 true 时会展示代码行号。

nprogress -2.1.23+

• 类型：boolean
• 默认值：true

切换页面时是否在页面顶部展示进度条，效果如 nprogress。

prefersColor

• 类型：{ default: 'light' | 'dark' | 'auto'; switch: boolean }
• 默认值：{ default: 'light', switch: true }

配置站点的主题色，其中 default 配置项为默认主题色，默认为亮色模式，配置为 auto 时将跟随用户的操作系统配置自动切换；switch 配置项控制主题色切换器的展示与否，配置为 false 时用户将无法主动切换站点主题色。

对于普通文档站点来说，建议保持 switch 的默认值 true，将站点主题色的选择权交给用户，同时可以考虑将 default 设置为 auto 以跟随用户的系统配置：

export default {
  themeConfig: {
    prefersColor: { default: 'auto' },
  },
};

对于组件库文档站点来说，建议根据组件库对暗色模式的适配情况来选择是否配置 switch 为 false，避免用户切换主题色后组件 demo 的样式出现异常。

对于主题开发者来说，可以在 Less 文件中使用 @dark-selector 的全局变量来为主题包的组件增加暗色模式的样式：

.some-container {
  // 亮色模式为白色
  color: #fff;

  // 暗色模式变黑色
  @{dark-selector} & {
    color: #000;
  }
}

socialLinks

如果想要在顶部导航栏右侧增加一些社交网站的外链图标，可以通过 socialLinks 进行配置，目前最多支持配置 5 个外链图标

目前支持以下社交平台图标：

export default {
  themeConfig: {
    socialLinks: {
      github: 'https://github.com/umijs/dumi',
      weibo: 'https://xxxx',
      twitter: 'https://xxxx',
      gitlab: 'https://xxxx',
      facebook: 'https://xxxx',
      zhihu: 'https://xxxx',
      yuque: 'https://xxxx',
      linkedin: 'https://xxxx',
    },
  },
};

Markdown 配置

默认主题提供了如下 Markdown 配置项，用于首页展示。

mobile

• 类型：boolean
• 默认值：true

配置为 false 时可将当前页面的 demo 预览切换回默认主题模式。

features

• 类型：Object
• 默认值：null
• 详细：

配置后该页面将会以首页形式呈现，用于每行 3 个的形式展示组件库的特性，配置格式如下：

features:
  - emoji: 🚀
    title: 性能强大
    link: 可为标题配置超链接
    description: 可以配置 HTML 文本

hero

• 类型：Object
• 默认值：null
• 详细：

配置 hero 后，该页面将会以首页形式呈现。

title

• 类型：String
• 默认值：null
• 详细：

配置首页首屏区域的大标题。

description

• 类型：String
• 默认值：null
• 详细：

配置首页首屏区域的简介文字，可以是 HTML 文本。

actions

• 类型：Array
• 默认值：null
• 详细：

配置首页首屏区域的操作按钮，最后一个按钮会作为主按钮展示，配置格式如下：

hero:
  actions:
    - text: Getting Started
      link: /getting-started

sidebar

• 类型：Boolean
• 默认值：true
• 详细：

控制侧边栏菜单的显示或隐藏。