ZNV Common Style Platform

ZNV 通用样式库，旨在统一主子工程的 UI 风格，并支持动态主题切换。

功能特性

• CSS 变量架构: 支持秒级动态换肤，无需重新加载页面。
• Iframe 同步: 提供 ThemeBridge SDK，自动同步主应用与 Iframe 子应用的主题状态。
• Element UI 适配: 内置 Element UI 组件的样式覆盖，使其符合平台设计规范。
• 公共组件: 提供 .znvTable, .znvDialog 等标准化业务组件样式。

目录结构

dist/
  znv-common.css      # 核心样式文件（包含变量定义、组件样式、Element UI 覆盖）
  theme-bridge.js     # 跨应用通信 SDK
src/
  styles/             # SCSS 源码
  js/                 # JS 源码
examples/             # 演示 Demo

快速开始

1. 安装

npm install znv-common-style

2. 引入 (Vue / ES Modules)

在项目入口文件（如 main.js）或组件中引入样式和 SDK：

// 引入全局样式
import 'znv-common-style/dist/znv-common.css';

// 引入 ThemeBridge SDK
import { ThemeBridge } from 'znv-common-style';

// 初始化 (主应用)
const themeBridge = new ThemeBridge({ 
  role: 'master',
  defaultTheme: 'light' 
});

// 切换主题
function switchTheme(themeName) {
  themeBridge.setTheme(themeName); // 'light' or 'dark'
}

3. 引入 (Script Tag / UMD)

如果不使用构建工具，也可以直接通过 <script> 标签引入：

<!-- 引入样式 -->
<link rel="stylesheet" href="./node_modules/znv-common-style/dist/znv-common.css">
<!-- 引入 SDK -->
<script src="./node_modules/znv-common-style/dist/theme-bridge.js"></script>

<script>
  // 注意：浏览器直接引入时，需使用 ThemeBridge.default 或 ThemeBridge.ThemeBridge
  const themeBridge = new ThemeBridge.default({ 
    role: 'master',
    defaultTheme: 'light' 
  });
</script>

2. 使用公共样式

在 Vue 组件中直接使用定义的 CSS 类名：

<template>
  <div class="znvTable">
    <!-- 你的表格内容 -->
    <el-table ...></el-table>
  </div>
</template>

3. 使用 CSS 变量 (自定义开发)

在编写自己的样式时，请使用 CSS 变量以支持换肤：

.my-custom-box {
  background-color: var(--znv-bg-color-white);
  color: var(--znv-text-color-primary);
  border: 1px solid var(--znv-border-color-base);
}

API 参考

ThemeBridge 类

用于管理主题状态和跨 Iframe 同步。

构造函数 new ThemeBridge(options)

| 参数 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | options | Object | {} | 配置对象 | | options.role | 'master' \| 'slave' | 'slave' | 角色：master 为主控端（主应用），slave 为从属端（子应用）。 | | options.defaultTheme | string | 'light' | 默认主题名称。 |

方法 setTheme(themeName)

切换当前主题。如果是 master 角色，还会向所有 Iframe 广播主题变更消息。

• 参数: themeName (string) - 主题名称（如 'light', 'dark'）。
• 示例: bridge.setTheme('dark')

方法 applyTheme(themeName)

仅将主题应用到当前页面的 DOM (html 标签的 data-theme 属性)，不广播。通常不需要手动调用。

Vue 2 集成指南

1. 全局引入样式

在 src/main.js 中引入 CSS：

import 'znv-common-style/dist/znv-common.css';
import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css'; // 确保 Element 样式在 znv-common 之前或被覆盖

Vue.use(ElementUI);

2. 初始化 ThemeBridge

建议在 App.vue 或 src/main.js 中初始化。

主应用 (App.vue):

import { ThemeBridge } from 'znv-common-style';

export default {
  name: 'App',
  data() {
    return {
      themeBridge: null
    };
  },
  created() {
    this.themeBridge = new ThemeBridge({
      role: 'master',
      defaultTheme: 'light'
    });
  },
  methods: {
    toggleTheme() {
      const newTheme = this.themeBridge.theme === 'light' ? 'dark' : 'light';
      this.themeBridge.setTheme(newTheme);
    }
  }
}

子应用 (App.vue):

import { ThemeBridge } from 'znv-common-style';

export default {
  created() {
    // 自动监听主应用消息并切换主题
    new ThemeBridge({ role: 'slave' });
  }
}

故障排除

样式未生效？

1. 检查是否正确引入了 dist/znv-common.css。
2. 检查 Element UI 样式引入顺序，znv-common-style 应能够覆盖 Element 默认样式。
3. 检查控制台是否有 404 错误。

Iframe 未同步主题？

1. 确保主应用初始化时 role: 'master'。
2. 确保子应用初始化时 role: 'slave'（默认）。
3. 检查是否存在跨域问题（Cross-Origin），postMessage 虽然支持跨域，但需确保页面已加载完成。

找不到类型定义？

确保你的项目支持 TypeScript 或已配置 jsconfig.json。VS Code 会自动读取 package.json 中的 types 字段提供提示。

常见问题与开发体验优化

1. 样式会自动生效吗？

是的，只要在项目入口（如 main.js）引入了 CSS 文件：

import 'znv-common-style/dist/znv-common.css';

以下内容会自动生效：

• Element UI 覆盖样式：所有 Element 组件颜色会自动跟随主题。
• 全局重置样式：滚动条样式、字体等。

注意：对于业务组件样式（如 .znvTable），你需要在 HTML 模板中手动添加类名：

<div class="znvTable">...</div>

2. 如何获得 CSS 类名代码提示？

VS Code 默认不会提示 node_modules 中的 CSS 类名。为了获得更好的开发体验，推荐安装 IntelliSense for CSS class names in HTML 插件。

安装插件后，在项目根目录创建 .vscode/settings.json（如果不存在），添加以下配置：

{
  "html-css-class-completion.includeGlobPattern": "**/*.{css,html,vue}",
  "html-css-class-completion.excludeGlobPattern": "**/node_modules/**/!(znv-common-style)/**/*"
}

这样插件就会扫描 node_modules/znv-common-style 下的 CSS 文件，从而在编写 HTML/Vue 模板时提示 .znvTable、.znvDialog 等类名。

3. 如何在 SCSS 中复用变量？

如果你想在自己的组件样式中使用我们定义的 CSS 变量（如 --znv-primary-color），可以直接使用 var() 函数：

.my-box {
  color: var(--znv-primary-color); // 推荐方式，支持动态换肤
}

如果你需要使用 Sass 变量（$colors）或 Mixins，可以引用源码：

// 在你的组件 SCSS 中
@import 'znv-common-style/src/styles/mixins/utils';

.my-text {
  @include ellipsis; // 使用我们的 mixin
}

开发指南

1. 安装依赖: npm install
2. 构建: npm run build
3. 开发监听: npm run watch:css

已知问题

• sass 编译时会有 @import 弃用警告，这是由于 Dart Sass 的更新，不影响当前产物生成。