# 常见问题

下面是使用时最容易踩到的点，也建议把这一页一并投喂给 AI 助手。

## 组件没有任何样式

组件库的样式是独立文件，必须显式引入一次：

```ts
import 'miao-design/style.css'
```

只写 `import MiaoDesign from 'miao-design'` 不会带出样式。样式文件里同时包含全部 `--m-*` 设计令牌，漏引会导致颜色、圆角、阴影全部失效。

## 换了主题色但组件没变

先确认覆写的是**组件库的令牌名**（`--m-*`），而不是你自己项目的变量：

```css
:root {
  --m-primary: #0f766e;       /* ✅ 组件库认这个 */
  --primary-color: #0f766e;   /* ❌ 没有组件会读它 */
}
```

另外要注意 CSS 的加载顺序：覆写规则要在 `miao-design/style.css` **之后**生效，否则会被原值覆盖。

## 弹层被父容器裁剪 / 层级不对

下拉菜单、日期面板、Tooltip 这类浮层都有明确的层级令牌，遇到被 `overflow: hidden` 裁剪时，检查父链路里有没有设置 `transform` / `filter` / `contain`，它们会创建新的层叠上下文：

| 令牌 | 值 | 用途 |
| --- | --- | --- |
| `--m-z-modal` | `1300` | Dialog / Drawer |
| `--m-z-menu` | `1301` | 下拉面板 |
| `--m-z-tooltip` | `1500` | Tooltip |
| `--m-z-toast` | `1600` | Toast |

## MDivider 默认是纵向的

`vertical` 的默认值是 **`true`**，所以 `<MDivider />` 渲染出来是一条纵线（高度 100%）。要水平分割线必须显式关闭：

```vue
<MDivider :vertical="false" gap="12px" />
```

另外 `width` / `height` 两个 prop 虽然在类型里存在，但实现中没有被引用，改宽度请用外层容器或样式覆盖。

## 组件放进 Group 之后就不生效了

`MCheckbox`、`MRadio` 在组内会**改由父组件管理状态**：

- 必须传 `value`，否则会以 `undefined` 参与比对，选中判断出错；
- 组内子组件自身**不再抛出** `update:modelValue` / `change`，这些事件由父组件（`MCheckboxGroup` / `MRadioGroup`）统一抛出；
- 组内子组件的 `modelValue` 会被忽略。

```vue
<MCheckboxGroup v-model="picked">
  <MCheckbox value="a">选项 A</MCheckbox>
  <MCheckbox value="b">选项 B</MCheckbox>
</MCheckboxGroup>
```

## MTabs 里放不下 MTabPane

`MTabs` / `MVTabs` 是**纯标签栏**，由 `items` 数组驱动，不收集子组件。标签栏与内容区是两个平级组件，靠绑定同一个 `v-model` 联动：

```vue
<script setup>
const active = ref('a')
</script>

<template>
  <MTabs v-model="active" :items="[{ name: 'a', label: 'A' }, { name: 'b', label: 'B' }]" />
  <MTabPanes v-model="active">
    <MTabPane name="a">内容 A</MTabPane>
    <MTabPane name="b">内容 B</MTabPane>
  </MTabPanes>
</template>
```

`MTabPanes` ↔ `MTabPane` 之间才是父子关系（通过 `provide / inject` 注册面板）。

## 按钮点击偶尔不响应

`MButton` 的点击默认有 **200ms 节流**，连点会被丢弃。需要每次都响应时显式关闭：

```vue
<MButton :throttle="0" @click="onClick">立即响应</MButton>
```

`MButton.loading` 或 `disabled` 时按钮处于原生 disabled 状态，`click` 不会触发，这是预期行为。

## MButtonGroup 里的按钮外观不受自己控制

放进 `MButtonGroup` 后：

- `variant` 与 `size` 会被**组的设置覆盖**（组没传 size 时也会写成 `default`）；
- `color` 是「子优先」——子组件自己设了就用子的，没设才取组值；
- `disabled` 取父子并集。

## DatePicker 什么时候会变成「日期时间」选择器

取决于 `format` 字符串里**是否包含时间片段**（大小写敏感）：

| `format` | 结果 |
| --- | --- |
| `YYYY-MM-DD` | 纯日期，点选即关闭面板 |
| `YYYY-MM-DD HH:mm` | 日期 + 时间，点选日期不关闭，需点「确定」 |
| `YYYY-MM-DD HH:mm:ss` | 日期 + 时 / 分 / 秒 |

## Toast 只弹出一次 / 被宿主容器影响

`toast` 是模块级单例，容器在**首次调用时**才懒挂载到 `document.body`。因此在 SSR 场景下不要在模块顶层调用它，放到用户交互里：

```ts
// ❌ SSR 环境会在服务端执行
toast.success('欢迎回来')

// ✅
function onMountedClick() {
  toast.success('欢迎回来')
}
```

## 移到暗色模式后颜色很怪

组件库的暗色不是把浅色简单压暗：语义色会换成 MUI dark palette 的取值（`--m-primary` 由 `#1976d2` 变为 `#90caf9`），`-contrast` 变成深色文字，阴影 alpha 加重。业务样式里**不要硬编码浅色态的具体色值**，始终引用 `--m-*` 变量。

## 仍然找不到答案？

- 在[组件总览](/components/)里搜索对应的组件页，注意看每页底部的「使用建议」。
- 到 [GitHub 仓库](https://github.com/tongmingwang/miao-design/issues) 提 issue，附上最小复现。