feat(docs): 将ui 框架的处理挪到业务去做，不混杂在插件里面

cocos-creator · Dec 4, 2024 · c184de6 · c184de6
1 parent 728f0ca
commit c184de6
Show file tree

Hide file tree

Showing 15 changed files with 57 additions and 46 deletions.
diff --git a/.npmrc b/.npmrc
@@ -1,5 +1,5 @@
-registry=https://registry.npmmirror.com
-# registry=https://registry.npmjs.org
+# registry=https://registry.npmmirror.com
+registry=https://registry.npmjs.org
 # @cocos-fe:registry=https://registry.npmjs.org
 @editor:registry=http://creator-npm.cocos.org:7001/
 

diff --git a/packages/create-cocos-plugin/package.json b/packages/create-cocos-plugin/package.json
@@ -1,6 +1,6 @@
 {
     "name": "create-cocos-plugin",
-    "version": "1.0.12",
+    "version": "1.0.13",
     "type": "module",
     "license": "MIT",
     "author": "cocos fe-team",

diff --git a/packages/create-cocos-plugin/templates/react-ts/package.json b/packages/create-cocos-plugin/templates/react-ts/package.json
@@ -13,7 +13,7 @@
         "react-dom": "^18.3.1"
     },
     "devDependencies": {
-        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.4",
+        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.5",
         "@cocos/creator-types": "^3.8.4",
         "@eslint/js": "^9.9.0",
         "@types/react": "^18.3.3",

diff --git a/packages/create-cocos-plugin/templates/vanilla/package.json b/packages/create-cocos-plugin/templates/vanilla/package.json
@@ -9,7 +9,7 @@
         "build": "vite build"
     },
     "devDependencies": {
-        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.4",
+        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.5",
         "rollup-plugin-node-externals": "^7.1.3",
         "vite": "^5.4.1",
         "@cocos/creator-types": "^3.8.4"

diff --git a/packages/create-cocos-plugin/templates/vue-element-plus/package-lock.json b/packages/create-cocos-plugin/templates/vue-element-plus/package-lock.json
diff --git a/packages/create-cocos-plugin/templates/vue-element-plus/package.json b/packages/create-cocos-plugin/templates/vue-element-plus/package.json
@@ -13,7 +13,7 @@
         "vue": "^3.4.37"
     },
     "devDependencies": {
-        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.4",
+        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.5",
         "@cocos/creator-types": "^3.8.4",
         "@vitejs/plugin-vue": "^5.2.1",
         "rollup-plugin-node-externals": "^7.1.3",
@@ -45,8 +45,8 @@
             "size": {
                 "min-width": 400,
                 "min-height": 300,
-                "width": 600,
-                "height": 500
+                "width": 800,
+                "height": 700
             }
         }
     }

diff --git a/packages/create-cocos-plugin/templates/vue-element-plus/vite.config.js b/packages/create-cocos-plugin/templates/vue-element-plus/vite.config.js
@@ -50,7 +50,13 @@ export default defineConfig(({ mode }) => {
                 optDeps: true,
             }),
             cocosPanelConfig(),
-            cocosPanelCss({ ui: 'element-plus' }),
+            cocosPanelCss({
+                transform: (css) => {
+                    // element-plus 的全局变量是作用在 :root , 需要改成 :host
+                    // 黑暗模式它是在 html 添加 dark 类名，我们应该在最外层的 #app 添加 class="dark"
+                    return css.replaceAll(':root', ':host').replaceAll('html.dark', '#app.dark');
+                },
+            }),
             AutoImport({
                 resolvers: [ElementPlusResolver()],
             }),

diff --git a/packages/create-cocos-plugin/templates/vue-ts/package.json b/packages/create-cocos-plugin/templates/vue-ts/package.json
@@ -10,7 +10,7 @@
         "build": "vue-tsc -b && vite build"
     },
     "devDependencies": {
-        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.4",
+        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.5",
         "@cocos/creator-types": "^3.8.4",
         "@vitejs/plugin-vue": "^5.1.2",
         "rollup-plugin-node-externals": "^7.1.3",

diff --git a/packages/create-cocos-plugin/templates/vue/package.json b/packages/create-cocos-plugin/templates/vue/package.json
@@ -13,7 +13,7 @@
     },
     "devDependencies": {
         "@vitejs/plugin-vue": "^5.1.2",
-        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.4",
+        "@cocos-fe/vite-plugin-cocos-panel": "^0.0.1-beta.5",
         "@cocos/creator-types": "^3.8.4",
         "rollup-plugin-node-externals": "^7.1.3",
         "typescript": "^5.5.3",

diff --git a/packages/vite-plugin-cocos-panel/README.md b/packages/vite-plugin-cocos-panel/README.md
@@ -22,7 +22,14 @@ export default defineConfig(({ mode }) => {
         },
         plugins: [
             cocosPanelConfig(), // 调整配置文件
-            cocosPanelCss({ ui: 'element-plus' }), // 处理第三方组件库的 css
+            cocosPanelCss({
+                transform: (css) => {
+                    // 如果使用了 element-plus 等 UI 库，需要做些 css 的转换工作
+                    // element-plus 的全局变量是作用在 :root , 需要改成 :host
+                    // 黑暗模式它是在 html 添加 dark 类名，我们应该在最外层的 #app 添加 class="dark"
+                    return css.replaceAll(':root', ':host').replaceAll('html.dark', '#app.dark');
+                },
+            }),
         ],
     };
 });

diff --git a/packages/vite-plugin-cocos-panel/index.ts b/packages/vite-plugin-cocos-panel/index.ts
@@ -5,8 +5,6 @@ import { walk } from 'estree-walker'; // walk ast
 import { generate } from 'astring'; // ast to code
 import { extname, basename } from 'node:path';
 
-import { cssTransform } from './ui-hack-element-plus.js';
-
 export function cocosPanelConfig(): Plugin {
     return {
         name: 'cocos-panel-config',
@@ -24,7 +22,7 @@ export function cocosPanelConfig(): Plugin {
     };
 }
 
-export function cocosPanelCss(option: { ui?: 'element-plus' } = {}): Plugin {
+export function cocosPanelCss(option: { transform?: (css: string) => string } = {}): Plugin {
     const styleMap: { [k: string]: string } = {};
 
     return {
@@ -68,14 +66,8 @@ export function cocosPanelCss(option: { ui?: 'element-plus' } = {}): Plugin {
                 let styleCode = styleMap[key];
 
                 if (styleCode) {
-                    if (typeof option.ui === 'string') {
-                        switch (option.ui) {
-                            case 'element-plus':
-                                styleCode = cssTransform(styleCode);
-                                break;
-                            default:
-                                break;
-                        }
+                    if (typeof option.transform === 'function') {
+                        styleCode = option.transform(styleCode);
                     }
                 }
                 if (

diff --git a/packages/vite-plugin-cocos-panel/package.json b/packages/vite-plugin-cocos-panel/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@cocos-fe/vite-plugin-cocos-panel",
-    "version": "0.0.1-beta.4",
+    "version": "0.0.1-beta.5",
     "description": "a vite plugin for build cocos panel",
     "type": "module",
     "main": "./dist/index.js",

diff --git a/packages/vite-plugin-cocos-panel/ui-hack-ant-design.ts b/packages/vite-plugin-cocos-panel/ui-hack-ant-design.ts
diff --git a/packages/vite-plugin-cocos-panel/ui-hack-element-plus.ts b/packages/vite-plugin-cocos-panel/ui-hack-element-plus.ts
diff --git a/projects/document/docs/create-cocos-plugin/index.md b/projects/document/docs/create-cocos-plugin/index.md
@@ -440,18 +440,24 @@ import HelloWorld from './components/HelloWorld.vue';
 
 -   css 样式里的 :root 需要改成 :host 这样我们才能在 web-component 里面让 elment-plus 的样式生效
 
-    我们在 [@cocos-fe/vite-plugin-cocos-panel](https://www.npmjs.com/package/@cocos-fe/vite-plugin-cocos-panel) 里做了针对 element-plus 的样式处理， ant-design 还没时间去弄，原则上原理是一样的。
+    我们在 [@cocos-fe/vite-plugin-cocos-panel](https://www.npmjs.com/package/@cocos-fe/vite-plugin-cocos-panel) 里提供了 css 的转换钩子，如果你需要使用 element-plus，你需要传入 `transform` 来转换它，使其能够在 web-component 里正常渲染 。
     你可以配置里面加如下的参数：
 
-    ```js {8}
+    ```js {8-14}
     import { defineConfig } from 'vite';
     import { cocosPanelConfig, cocosPanelCss } from '@cocos-fe/vite-plugin-cocos-panel';
 
     export default defineConfig(({ mode }) => {
         return {
             plugins: [
                 cocosPanelConfig(), // 调整配置文件
-                cocosPanelCss({ ui: 'element-plus' }), // 处理第三方组件库的 css
+                cocosPanelCss({
+                    transform: (css) => {
+                        // element-plus 的全局变量是作用在 :root , 需要改成 :host
+                        // 黑暗模式它是在 html 添加 dark 类名，我们应该在最外层的 #app 添加 class="dark"
+                        return css.replaceAll(':root', ':host').replaceAll('html.dark', '#app.dark');
+                    },
+                }),
             ],
         };
     });
@@ -461,7 +467,7 @@ import HelloWorld from './components/HelloWorld.vue';
 
 ::: code-group
 
-```js [vite.config.js] {53}
+```js [vite.config.js] {53-59}
 import { defineConfig } from 'vite';
 import { nodeExternals } from 'rollup-plugin-node-externals';
 import vue from '@vitejs/plugin-vue';
@@ -514,7 +520,13 @@ export default defineConfig(({ mode }) => {
                 optDeps: true,
             }),
             cocosPanelConfig(),
-            cocosPanelCss({ ui: 'element-plus' }),
+            cocosPanelCss({
+                transform: (css) => {
+                    // element-plus 的全局变量是作用在 :root , 需要改成 :host
+                    // 黑暗模式它是在 html 添加 dark 类名，我们应该在最外层的 #app 添加 class="dark"
+                    return css.replaceAll(':root', ':host').replaceAll('html.dark', '#app.dark');
+                },
+            }),
             AutoImport({
                 resolvers: [ElementPlusResolver()],
             }),
@@ -526,7 +538,7 @@ export default defineConfig(({ mode }) => {
 });
 ```
 
-```js [panel.js] {19-26}
+```js [panel.js] {11,19-26}
 import App from './App.vue';
 import { createApp } from 'vue';
 import './style.css';
@@ -537,7 +549,7 @@ import { ElMessage } from 'element-plus';
 const weakMap = new WeakMap();
 
 export default Editor.Panel.define({
-    template: '<div id="app" class="dark"></div>', // 只留一个 div 用于 vue 的挂载
+    template: '<div id="app" class="dark"></div>', // 加了 dark 类名，模拟黑暗模式
     $: {
         root: '#app',
     },