ConfigProvider 全局配置
给里面的组件统一设置默认尺寸、按钮默认值和弹层层级,也可以切换页面主题。
引入
import { NsConfigProvider } from '@ns/ui'
基础用法
把应用(或其中一块)包起来。里面的组件没写对应属性时,用 ConfigProvider 的设置。
<template>
<NsConfigProvider size="large" :button="{ type: 'primary' }">
<div style="margin-bottom: 12px">
<NsSpace wrap>
<NsButton>大号主要按钮</NsButton>
<NsButton size="small" type="default">自己写的优先</NsButton>
</NsSpace>
</div>
<NsInput placeholder="大号输入框" />
</NsConfigProvider>
</template>
默认尺寸
size 是里面所有带 size 属性的组件的默认尺寸,可选 large、default、small。组件自己写了 size 时以组件为准。切换下面的尺寸,看各种控件一起变化:
<script setup lang="ts">
import { ref } from 'vue'
import {
NsButton,
NsConfigProvider,
NsInput,
NsInputNumber,
NsSegmented,
NsSelect,
NsSpace,
NsSwitch,
NsTag
} from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const size = ref<'large' | 'default' | 'small'>('large')
const city = ref('beijing')
const count = ref(1)
const enabled = ref(true)
const options: SelectOption[] = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSegmented v-model="size" :options="['large', 'default', 'small']" />
<NsConfigProvider :size="size">
<NsSpace wrap>
<NsButton type="primary">按钮</NsButton>
<NsInput placeholder="输入框" style="width: 160px" />
<NsSelect v-model="city" :options="options" style="width: 160px" />
<NsInputNumber v-model="count" :min="0" />
<NsSwitch v-model="enabled" />
<NsTag type="success">标签</NsTag>
<NsButton size="small">自己写了 small</NsButton>
</NsSpace>
</NsConfigProvider>
</NsSpace>
</template>
放在按钮组、头像组、芯片组、表单里时,组或表单写的 size 优先于 ConfigProvider:
<script setup lang="ts">
import { NsConfigProvider, NsForm, NsFormItem, NsInput, NsSelect, NsSpace } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const options: SelectOption[] = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsConfigProvider size="small">
<NsSpace direction="vertical" fill>
<NsSelect :options="options" />
<!-- 表单写了 size,表单里的控件用表单的 -->
<NsForm size="large">
<NsFormItem label="名称">
<NsInput />
</NsFormItem>
</NsForm>
</NsSpace>
</NsConfigProvider>
</template>
按钮默认值
button 设置里面按钮的默认 type 和 size。按钮自己写的、按钮组写的优先;button.size 优先于 ConfigProvider 的 size,只作用于按钮。切换下面的类型看效果:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsConfigProvider, NsSegmented, NsSpace } from '@ns/ui'
import type { ButtonType } from '@ns/ui'
const type = ref<ButtonType>('primary')
const types = ['default', 'primary', 'success', 'warning', 'danger', 'info', 'help']
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSegmented v-model="type" :options="types" />
<NsConfigProvider :button="{ type }">
<NsSpace wrap>
<NsButton>实心</NsButton>
<NsButton variant="outline">描边</NsButton>
<NsButton plain>朴素</NsButton>
<NsButton variant="text">文字</NsButton>
<NsButton type="default">自己写了 default</NsButton>
</NsSpace>
</NsConfigProvider>
</NsSpace>
</template>
button.size 和 size 同时写时,按钮用 button.size,其他控件用 size:
<template>
<NsConfigProvider size="large" :button="{ size: 'small', type: 'primary' }">
<NsSpace wrap>
<NsButton>按钮是 small</NsButton>
<NsInput placeholder="输入框是 large" style="width: 160px" />
<NsButton size="default">自己写了 default</NsButton>
</NsSpace>
</NsConfigProvider>
</template>
弹层层级
zIndex 是里面弹层的 z-index,写在弹层根元素的内联样式上。改大后,对话框、下拉面板能盖住页面上层级较高的固定元素。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsConfigProvider, NsModal, NsSelect } from '@ns/ui'
import type { SelectOption } from '@ns/ui'
const visible = ref(false)
const options: SelectOption[] = [
{ label: '北京', value: 'beijing' },
{ label: '上海', value: 'shanghai' },
{ label: '广州', value: 'guangzhou' }
]
</script>
<template>
<NsConfigProvider :z-index="3000">
<div style="margin-bottom: 12px">
<NsButton @click="visible = true">打开对话框</NsButton>
</div>
<NsSelect :options="options" />
<NsModal v-model="visible" title="提示">内容</NsModal>
</NsConfigProvider>
</template>
响应式和嵌套
属性改了,里面的组件跟着变。ConfigProvider 可以嵌套,内层没写的项继承外层,写了的项以内层为准。切换外层的尺寸:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsConfigProvider, NsSegmented, NsSpace } from '@ns/ui'
const size = ref<'large' | 'default' | 'small'>('large')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSegmented v-model="size" :options="['large', 'default', 'small']" />
<NsConfigProvider :size="size">
<NsSpace wrap>
<NsButton>外层</NsButton>
<NsConfigProvider :z-index="3000" :button="{ type: 'primary' }">
<!-- size 跟着外层变,按钮类型和 zIndex 用内层的 -->
<NsButton>内层:继承尺寸</NsButton>
</NsConfigProvider>
<NsConfigProvider size="small">
<!-- 内层写了 size,不再跟着外层变 -->
<NsButton>内层:固定 small</NsButton>
</NsConfigProvider>
</NsSpace>
</NsConfigProvider>
</NsSpace>
</template>
主题
theme 写在 <html> 的 data-theme 上,等同于自己执行 document.documentElement.setAttribute('data-theme', theme),作用于整个页面,不只是 ConfigProvider 里面。不传 theme 时不修改页面主题;卸载或改成不传时,恢复成接管前的值。一般包在应用的最外层,例如 <NsConfigProvider theme="dark"><App /></NsConfigProvider>。
切到“暗色”后,这一页所有组件都变成暗色;切回“不传”或离开这一页时恢复原来的主题:
<script setup lang="ts">
import { computed, ref } from 'vue'
import {
NsButton,
NsCard,
NsConfigProvider,
NsInput,
NsSegmented,
NsSpace,
NsSwitch,
NsTag
} from '@ns/ui'
import type { SegmentedOption, ThemeMode } from '@ns/ui'
const mode = ref<string | number>('none')
const options: SegmentedOption[] = [
{ value: 'none', label: '不传' },
{ value: 'light', label: '亮色(light)' },
{ value: 'dark', label: '暗色(dark)' }
]
const theme = computed(() => (mode.value === 'none' ? undefined : (mode.value as ThemeMode)))
const enabled = ref(true)
</script>
<template>
<NsSegmented v-model="mode" :options="options" />
<NsConfigProvider :theme="theme">
<NsCard title="卡片" style="margin-top: 16px">
<NsSpace wrap>
<NsButton type="primary">主要按钮</NsButton>
<NsButton>默认按钮</NsButton>
<NsInput placeholder="输入框" style="width: 160px" />
<NsSwitch v-model="enabled" />
<NsTag type="success">标签</NsTag>
</NsSpace>
</NsCard>
</NsConfigProvider>
</template>
在自己的组件里读取配置
import { useGlobalConfig } from '@ns/ui'
// 在 setup 顶层调用;不在 ConfigProvider 里时返回 undefined
const config = useGlobalConfig()
const size = computed(() => config?.value.size ?? 'default')
下面的 ConfigViewer 是一个自己写的组件,显示它读到的配置。放在 ConfigProvider 里时读到外层的设置,跟着变化;放在外面时读到 undefined:
<script setup lang="ts">
import { defineComponent, h, ref } from 'vue'
import { NsConfigProvider, NsSegmented, NsSpace, useGlobalConfig } from '@ns/ui'
const ConfigViewer = defineComponent({
setup() {
const config = useGlobalConfig()
return () =>
h(
'code',
config
? `size: ${config.value.size},zIndex: ${config.value.zIndex},button.type: ${config.value.button.type}`
: '不在 ConfigProvider 里,读到 undefined'
)
}
})
const size = ref<'large' | 'default' | 'small'>('default')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSegmented v-model="size" :options="['large', 'default', 'small']" />
<NsConfigProvider :size="size" :z-index="3000" :button="{ type: 'primary' }">
<ConfigViewer />
</NsConfigProvider>
<ConfigViewer />
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| theme | 'light' | 'dark' | — | 页面主题。不传时不修改页面主题 |
| size | 'large' | 'default' | 'small' | 'default' | 组件的默认尺寸,组件自己写的优先 |
| zIndex | number | 2000 | 弹层的 z-index,见注意事项 |
| button | ButtonConfig | {} | 按钮的默认 size、type |
| locale | Locale | — | 语言包。暂未生效,组件还没有读取 |
| namespace | string | 'ns' | 类名前缀。暂未生效,类名前缀固定是 ns- |
没写的项先继承外层 ConfigProvider,再没有就用表里的默认值。
Slots
| 插槽 | 说明 |
|---|---|
| default | 要应用配置的内容。组件不渲染额外的 DOM 元素 |
类型
import type {
ConfigProviderProps,
ConfigProviderContext,
ButtonConfig,
ThemeMode,
Locale
} from '@ns/ui'
interface ButtonConfig {
size?: 'large' | 'default' | 'small'
type?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help'
}
// useGlobalConfig() 读到的值
interface ConfigProviderContext {
theme: 'light' | 'dark' | undefined // 没有任何一层写 theme 时是 undefined
size: 'large' | 'default' | 'small'
zIndex: number
button: ButtonConfig
locale: Locale | undefined
namespace: string
}
注意事项
- 读取
size的组件:Button、AutoComplete、Avatar、AvatarGroup、Cascader、Chip、ChipGroup、ColorPicker、DatePicker、Descriptions、Form、FormItem、Input、InputNumber、InputTag、List、Mentions、Rate、Segmented、Select、Space、Spin、Switch、Table、Tag、TimePicker、TreeSelect。 - 尺寸的优先级:组件自己写的 > 按钮组、头像组、芯片组、表单项、表单 > ConfigProvider 的
size>'default'。Button 在按钮组之后还会先看button.size。 - 读取
zIndex的弹层:Button 的气泡,AutoComplete、Cascader、ColorPicker、Select、TreeSelect、Mentions 的下拉面板,Dropdown、Popover、Popconfirm、Tooltip,Modal、Drawer,直接写在模板里的NsLoadingComponent。层级写在内联样式上,在 Modal、Drawer 上自己写style="z-index: …"可以覆盖。DatePicker、TimePicker 的面板还没有接入,固定是 2000。 - 不读取
zIndex的:v-loading指令和NsLoadingService(是单独创建的应用,读不到 ConfigProvider,固定是 2000);Message、Notification(固定 9999);MessageBox(从 2001 起递增,可以用zIndex选项指定);Image 预览(用自己的zIndex属性)。 - 所有弹层用同一个层级,不递增。层级相同时,后插入页面的盖住先插入的。
theme是全局的。嵌套时内层写了theme会改掉整个页面的主题,内层卸载后恢复成外层的主题。locale和namespace暂未生效,见上表。