Merge pull request #1637 from TuSimple/docs

Docs
2024-12-15 04:42:23 +08:00 · 2021-11-21 23:21:28 +08:00 · 2021-11-21 23:21:28 +08:00 · 3a701c10e7
commit 3a701c10e7
parent 2f88cca008 2797bcb46a
9 changed files with 331 additions and 13 deletions
--- a/demo/pages/docs/customize-theme/enUS/index.md
+++ b/demo/pages/docs/customize-theme/enUS/index.md
@ -1,6 +1,6 @@
 <!--anchor:on-->

-# Customizing Theme
+# Customizing theme

 Naive-ui provide `n-config-provider` to customize the theme.

@ -8,7 +8,7 @@ By default all the component is light themed, without any configuration.

 Learn more about `n-config-provider`, see [Config Provider](../components/config-provider).

-## Use Dark Theme
+## Use dark theme

 Set `n-config-provider`'s `theme` prop to `darkTheme` imported from naive-ui to set dark theme inside `n-config-provider`.

@ -35,19 +35,26 @@ If `theme` is `undefined` it won't affect the theme of components inside.
 </script>
 ```

-## Customizing Theme Vars (Design Tokens)
+## Customizing theme vars (design tokens)

 No CSS (Scss, Less) needed.

+The configured global theme variables will overwrite the theme variables that take effect on descendant components.
+
 Set `n-config-provider`'s `theme-overrides` to customize theme vars. Naive-ui exports type `GlobalThemeOverrides` to help you define `theme-overrides`.

 For available vars please follow the type hint of `GlobalThemeOverrides`.

+If you want to view more theme variables, you can view them in the edit button at the bottom right corner of the Naive UI homepage.
+
+You can modify the corresponding theme variable, you can get the themeOverrides object after export.
+
 ```html
 <script>
  import { NConfigProvider } from 'naive-ui'

  /**
+   * Use this for type hints under js file
   * @type import('naive-ui').GlobalThemeOverrides
   */
  const themeOverrides = {
@ -77,9 +84,160 @@ For available vars please follow the type hint of `GlobalThemeOverrides`.
 </template>
 ```

-## Sync Style of the Body Element
+## Customizing theme vars in TypeScript

-For the following reasons, you may need to set some styles on `document.body`
+If you are using ts to write code, this one is more suitable for you.
+
+```html
+<script lang="ts">
+  import { NConfigProvider, GlobalThemeOverrides } from 'naive-ui'
+
+  const themeOverrides: GlobalThemeOverrides = {
+    common: {
+      primaryColor: '#FF0000'
+    },
+    Button: {
+      textColor: '#FF0000'
+    }
+  }
+
+  // ...
+</script>
+
+<template>
+  <n-config-provider :theme-overrides="themeOverrides">
+    <my-app />
+  </n-config-provider>
+</template>
+```
+
+## Customizing component theme vars
+
+The use of component theme variables is the same as the use of global theme variables, and the component theme variables will override the global theme variables.
+
+```html
+<script lang="ts">
+  import { SelectProps, ButtonProps } from 'naive-ui'
+
+  type SelectThemeOverrides = NonNullable<SelectProps['themeOverrides']>
+  type ButtonThemeOverrides = NonNullable<ButtonProps['themeOverrides']>
+
+  const selectThemeOverrides: SelectThemeOverrides = {
+    menuBoxShadow:
+      '0 6px 16px -9px rgba(0, 0, 0, .08), 0 9px 28px 0 rgba(0, 0, 0, .05), 0 12px 48px 16px rgba(0, 0, 0, .03)',
+    peers: {
+      InternalSelection: {
+        textColor: '#FF0000',
+        heightMedium: '42px'
+      }
+    }
+  }
+  const buttonThemeOverrides: ButtonThemeOverrides = {
+    heightMedium: '40px',
+    textColor: 'rgba(24, 127, 231, 1)'
+  }
+
+  // ...
+</script>
+
+<template>
+  <n-select
+    v-model:value="value"
+    :options="options"
+    :theme-overrides="selectThemeOverrides"
+  />
+  <n-button :theme-overrides="buttonThemeOverrides">theme</n-button>
+</template>
+```
+
+## Customizing theme vars under different themes
+
+If you want to use different theme variables on light and dark theme at the same time, you can take a look at this.
+
+```html
+<script>
+  import { NConfigProvider, darkTheme } from 'naive-ui'
+
+  /**
+   * @type import('naive-ui').GlobalThemeOverrides
+   */
+  const lightThemeOverrides = {
+    common: {
+      primaryColor: '#000000'
+    }
+    // ...
+  }
+
+  const darkThemeOverrides = {
+    common: {
+      primaryColor: '#FFFFFF'
+    }
+    // ...
+  }
+
+  const theme = null
+  // ...
+</script>
+
+<template>
+  <n-config-provider
+    :theme="theme"
+    :theme-overrides="theme === null ? lightThemeOverrides : darkThemeOverrides"
+  >
+    <my-app />
+  </n-config-provider>
+</template>
+```
+
+## Use the peers vars
+
+In many cases, another component will be reused inside a component, so the theme variable of peers appears.
+
+The theme variables related to peers have not been exposed yet. Use `GlobalThemeOverrides` to view the peers variables of the corresponding component.
+
+The specific available peers will be updated later.
+
+```html
+<script lang="ts">
+  import { NConfigProvider, GlobalThemeOverrides } from 'naive-ui'
+
+  const themeOverrides: GlobalThemeOverrides = {
+    Select: {
+      peers: {
+        InternalSelection: {
+          textColor: '#FF0000'
+        },
+        InternalSelectMenu: {
+          borderRadius: '6px'
+        }
+      }
+    },
+    DataTable: {
+      paginationMargin: '40px 0 0 0',
+      peers: {
+        Empty: {
+          textColor: '#ccc'
+        },
+        Pagination: {
+          itemTextColor: '#ccc'
+        }
+      }
+    }
+    // ...
+  }
+  // ...
+</script>
+
+<template>
+  <n-config-provider :theme-overrides="themeOverrides">
+    <my-app />
+  </n-config-provider>
+</template>
+```
+
+## Sync style of the body element
+
+For the following reasons, you may need to set some styles on `document.body`.

 1. Naive-ui will mount some global style that is unresponsive (to theme, not media query). For example `font-family`. The style works fine by default, however they won't change when theme is changed.
 2. `n-config-provider` can't sync global style (for example, body's background color) outside it.
@ -95,11 +253,11 @@ You can use `n-global-style` to sync common global style to the body element. In
 </template>
 ```

-## Theme Editor
+## Theme editor

 Naive-ui provides theme editor to help you edit theme and export the corresponding configuration. It can be placed inside `n-config-provider`.

-The theme editor is not included in global installation (`app.use(naive)`). You need to import it explicitly to use it
+The theme editor is not included in global installation (`app.use(naive)`). You need to import it explicitly to use it.

 ```html
 <template>
--- a/demo/pages/docs/customize-theme/zhCN/index.md
+++ b/demo/pages/docs/customize-theme/zhCN/index.md
@ -39,15 +39,22 @@ Naive UI 通过使用 `n-config-provider` 调整主题。

 你不需要写任何 CSS（Scss、Less...）。

+配置的全局主题变量会对后代组件生效的主题变量覆盖。
+
 通过设定 `n-config-provider` 的 `theme-overrides` 来调整主题变量。naive-ui 导出了 `GlobalThemeOverrides` 类型帮助你定义主题。

 具体可使用变量请参考 `GlobalThemeOverrides` 类型提示。

+如果想要查看更多的主题变量，可在 Naive UI 主页的右下角的 edit 按钮查看。
+
+可以修改对应的主题变量，导出后可以拿到 themeOverrides 对象。
+
 ```html
 <script>
  import { NConfigProvider } from 'naive-ui'

  /**
+   * js 文件下使用这个做类型提示
   * @type import('naive-ui').GlobalThemeOverrides
   */
  const themeOverrides = {
@ -77,6 +84,155 @@ Naive UI 通过使用 `n-config-provider` 调整主题。
 </template>
 ```

+## TS 下使用主题变量
+
+如果你正在使用 ts 写代码，这块比较适合你。
+
+```html
+
+<script lang="ts">
+  import { NConfigProvider,  GlobalThemeOverrides } from 'naive-ui'
+
+  const themeOverrides: GlobalThemeOverrides = {
+    common: {
+      primaryColor: '#FF0000'
+    },
+    Button: {
+      textColor: '#FF0000'
+    }
+  }
+
+  // ...
+</script>
+
+<template>
+  <n-config-provider :theme-overrides="themeOverrides">
+    <my-app />
+  </n-config-provider>
+</template>
+```
+
+## 调整组件主题变量
+
+组件主题变量使用方法同全局主题变量使用方法，并且组件主题变量会覆盖全局主题变量。
+
+```html
+<script lang="ts">
+  import { SelectProps, ButtonProps } from 'naive-ui'
+
+  type SelectThemeOverrides = NonNullable<SelectProps['themeOverrides']>
+  type ButtonThemeOverrides = NonNullable<ButtonProps['themeOverrides']>
+
+  const selectThemeOverrides: SelectThemeOverrides = {
+    menuBoxShadow: '0 6px 16px -9px rgba(0, 0, 0, .08), 0 9px 28px 0 rgba(0, 0, 0, .05), 0 12px 48px 16px rgba(0, 0, 0, .03)',
+    peers: {
+      InternalSelection: {
+        textColor: '#FF0000',
+        heightMedium: '42px'
+      }
+    }
+  }
+  const buttonThemeOverrides: ButtonThemeOverrides = {
+    heightMedium: '40px',
+    textColor: 'rgba(24, 127, 231, 1)'
+  }
+
+  // ...
+</script>
+
+<template>
+  <n-select v-model:value="value" :options="options" :theme-overrides="selectThemeOverrides" />
+  <n-button :theme-overrides="buttonThemeOverrides">theme</n-button>
+</template>
+```
+
+## 不同主题下调整主题变量
+
+如果你想要在亮色和暗色上同时使用不同的主题变量，可以来看看这个。
+
+```html
+<script>
+  import { NConfigProvider, darkTheme } from 'naive-ui'
+
+  /**
+   * @type import('naive-ui').GlobalThemeOverrides
+   */
+  const lightThemeOverrides = {
+    common: {
+      primaryColor: '#000000'
+    }
+    // ...
+  }
+
+  const darkThemeOverrides = {
+    common: {
+      primaryColor: '#FFFFFF'
+    }
+    // ...
+  }
+
+  const theme = null
+  // ...
+</script>
+
+<template>
+  <n-config-provider
+    :theme="theme"
+    :theme-overrides="theme === null ? lightThemeOverrides : darkThemeOverrides"
+  >
+    <my-app />
+  </n-config-provider>
+</template>
+```
+
+## 使用 peers 主题变量
+
+很多时候组件内部都会复用另一个组件，因此出现了 peers 的主题变量。
+
+peers 相关的主题变量还没有暴露，使用 `GlobalThemeOverrides` 可以查看对应组件的 peers 变量。
+
+具体哪些可使用的 peers 后续会更新。
+
+```html
+<script lang="ts">
+  import { NConfigProvider, GlobalThemeOverrides } from 'naive-ui'
+
+  const themeOverrides: GlobalThemeOverrides = {
+    Select: {
+      peers: {
+        InternalSelection: {
+          textColor: '#FF0000'
+        },
+        InternalSelectMenu: {
+          borderRadius: '6px',
+        }
+      },
+    },
+    DataTable: {
+      paginationMargin: '40px 0 0 0',
+      peers: {
+        Empty: {
+          textColor: '#ccc'
+        },
+        Pagination: {
+          itemTextColor: '#ccc'
+        }
+      }
+    },
+    // ...
+  }
+  // ...
+</script>
+
+<template>
+  <n-config-provider
+    :theme-overrides="themeOverrides"
+  >
+    <my-app />
+  </n-config-provider>
+</template>
+```
+
 ## 同步 body 元素的样式

 出于以下原因，你可能需要将某些样式设定在 `document.body` 上。
--- a/src/_utils/naive/extract-public-props.ts
+++ b/src/_utils/naive/extract-public-props.ts
@ -5,7 +5,7 @@ type themePropKeys = keyof typeof useTheme.props

 export type ExtractPublicPropTypes<T> = Omit<
 Partial<ExtractPropTypes<T>>,
-themePropKeys | Extract<keyof T, `internal${string}`>
+Exclude<themePropKeys, 'themeOverrides'> | Extract<keyof T, `internal${string}`>
 >

 export type ExtractInternalPropTypes<T> = Partial<ExtractPropTypes<T>>
--- a/src/config-provider/demos/zhCN/namespace.demo.md
+++ b/src/config-provider/demos/zhCN/namespace.demo.md
@ -1,6 +1,6 @@
-# 命名空间（卸载内容的类名）
+# 命名空间（挂载内容的类名）

-组件的一部分是卸载在 `document.body` 上的。如需给这些卸载的元素添加 class，使用 `n-config-provider` 的 `namespace` 属性。打开开发者工具可以看到被卸载的 DOM。
+组件的一部分是挂载在 `document.body` 上的。如需给这些可卸载的元素添加 class，使用 `n-config-provider` 的 `namespace` 属性。打开开发者工具可以看到被卸载的 DOM。

 ```html
 <n-config-provider :namespace="ns">
--- a/src/data-table/demos/enUS/index.demo-entry.md
+++ b/src/data-table/demos/enUS/index.demo-entry.md
@ -75,7 +75,7 @@ striped
 | striped | `boolean` | `false` | Whether to show zebra stripes on rows. |
 | summary | `DataTableCreateSummary` | `undefined` | Data of table summary row. For types, see <n-a href="#DataTableCreateSummary-Type">DataTableCreateSummary Type</n-a>. |
 | table-layout | `'auto' \| 'fixed'` | `'auto'` | Style `table-layout` of the table. When `ellipsis` or `max-height` or `flex-height` are set, it will always be `'fixed'` regardless of what you set. |
-| virtual-scroll | `boolean` | `false` | Whether to use virtual scroll to deal with large data. Make sure `max-height` is set before using it. |
+| virtual-scroll | `boolean` | `false` | Whether to use virtual scroll to deal with large data. Make sure `max-height` is set before using it. When `virtual-scroll` is `true`, `rowSpan` will not take effect. |
 | on-update:checked-row-keys | `(keys: Array<string \| number>) => void` | `undefined` | The callback function triggered when the checked-row-keys value changes. |
 | on-update:filters | `(filters: { [string \| number]: Array<string \| number> \| string \| number }, initiatorColumn: DataTableColumn)` | `undefined` | The callback function triggered when the filters data changes. |
 | on-update:page | `(page: number)` | `undefined` | Callback function triggered when the page changes. |
--- a/src/data-table/demos/enUS/virtual.demo.md
+++ b/src/data-table/demos/enUS/virtual.demo.md
@ -2,6 +2,8 @@

 Use `virtual-scroll` to deal with large date. Note that you need to set `max-height` at the same time.

+**Tip: When `virtual-scroll` is `true`, `rowSpan` will not take effect.**
+
 ```html
 <n-data-table
  ref="table"
--- a/src/data-table/demos/zhCN/index.demo-entry.md
+++ b/src/data-table/demos/zhCN/index.demo-entry.md
@ -77,7 +77,7 @@ striped
 | striped | `boolean` | `false` | 是否使用斑马线条纹 |
 | summary | `DataTableCreateSummary` | `undefined` | 表格总结栏的数据，类型见 <n-a href="#DataTableCreateSummary-Type">DataTableCreateSummary Type</n-a> |
 | table-layout | `'auto' \| 'fixed'` | `'auto'` | 表格的 `table-layout` 样式属性，在设定 `ellipsis` 或 `max-height` 的情况下固定为 `'fixed'` |
-| virtual-scroll | `boolean` | `false` | 是否开启虚拟滚动，应对大规模数据，开启前请设定好 `max-height` |
+| virtual-scroll | `boolean` | `false` | 是否开启虚拟滚动，应对大规模数据，开启前请设定好 `max-height`。当 `virtual-scroll` 为 `true` 时，`rowSpan` 将不生效 |
 | on-update:checked-row-keys | `(keys: Array<string \| number>) => void` | `undefined` | checked-row-keys 值改变时触发的回调函数 |
 | on-update:filters | `(filters: { [string \| number]: Array<string \| number> \| string \| number }, initiatorColumn: DataTableColumn)` | `undefined` | filters 数据改变时触发的回调函数 |
 | on-update:page | `(page: number)` | `undefined` | page 改变时触发的回调函数 |
--- a/src/data-table/demos/zhCN/virtual.demo.md
+++ b/src/data-table/demos/zhCN/virtual.demo.md
@ -2,6 +2,8 @@

 使用 `virtual-scroll` 来应对大量数据，注意需要同时设定 `max-height`。

+**注意：当 `virtual-scroll` 为 `true` 时，`rowSpan` 将不生效。**
+
 ```html
 <n-data-table
  ref="table"
--- a/src/radio/demos/zhCN/index.demo-entry.md
+++ b/src/radio/demos/zhCN/index.demo-entry.md
@ -26,7 +26,7 @@ radio-focus-debug
 | name | `string` | `undefined` | 单选按钮 radio 元素的 name 属性。如果没有设定会使用 `n-radio-group` 的 `name` |
 | size | `'small' \| 'medium' \| 'large'` | `'medium'` | 大小 |
 | value | `string` | `undefined` | 选中的值 |
-| on-update:checked-value | `(checked: boolean) => void` | `undefined` | 发生变化时触发的回调方法 |
+| on-update:checked | `(checked: boolean) => void` | `undefined` | 发生变化时触发的回调方法 |

 ### RadioGroup Props