fix: update doc and fix typo

sonofmagic · Jul 29, 2023 · f9b1aed · f9b1aed
1 parent a188f9b
commit f9b1aed
Showing 1 changed file with 172 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,23 @@
 # weapp-pandacss
 
 [![codecov](https://codecov.io/gh/sonofmagic/weapp-pandacss/branch/main/graph/badge.svg?token=vnU71Pxj3P)](https://codecov.io/gh/sonofmagic/weapp-pandacss)
+![star](https://badgen.net/github/stars/sonofmagic/weapp-pandacss)
+![dm0](https://badgen.net/npm/dm/weapp-pandacss)
+![license](https://badgen.net/npm/license/weapp-pandacss)
 
 - [weapp-pandacss](#weapp-pandacss)
   - [介绍](#介绍)
   - [快速开始](#快速开始)
-    - [panda css 安装和配置](#panda-css-安装和配置)
+    - [pandacss 安装和配置](#pandacss-安装和配置)
+      - [0. 安装和初始化 pandacss](#0-安装和初始化-pandacss)
+      - [1. 配置 postcss](#1-配置-postcss)
+      - [2. 检查你的 panda.config.ts](#2-检查你的-pandaconfigts)
+      - [3. 修改 package.json 脚本](#3-修改-packagejson-脚本)
+      - [4. 全局 css 注册 pandacss](#4-全局-css-注册-pandacss)
+      - [5. 配置的优化与别名](#5-配置的优化与别名)
     - [weapp-pandacss 配置](#weapp-pandacss-配置)
+      - [0. 回到 postcss 进行注册](#0-回到-postcss-进行注册)
+      - [1. 回到 package.json 添加生成脚本](#1-回到-packagejson-添加生成脚本)
   - [跨平台注意事项](#跨平台注意事项)
   - [小程序预览事项](#小程序预览事项)
   - [配置项](#配置项)
@@ -15,28 +26,158 @@
 
 ## 介绍
 
-[`panda css`](https://panda-css.com/) 是个优秀的 `CSS-in-JS` 编译时框架，原子化和 `[jt]sx?` 文件相结合的写法灵活而又令我犹如沐浴春风，尤其是它的提取器令我印象深刻。
-
-而 `weapp-pandacss` 就是让你在小程序开发中使用它。
+[`pandacss`](https://panda-css.com/) 是个优秀的 `CSS-in-JS` 编译时框架，原子化和 `[jt]sx?` 文件相结合的写法灵活而又令人印象深刻，而 `weapp-pandacss` 就是让你在小程序开发中使用它。
 
 ## 快速开始
 
-### panda css 安装和配置
+### pandacss 安装和配置
+
+#### 0. 安装和初始化 pandacss
 
-首先我们需要把 `@pandacss/dev` 这些都安装和配置好:
+首先我们需要把 `@pandacss/dev` 这些都安装和配置好，这里我们以 `tarojs` 项目为例：
 
 ```bash
-npm install -D @pandacss/dev weapp-pandacss # 或者 yarn / pnpm
+npm install -D @pandacss/dev weapp-pandacss postcss # 或者 yarn / pnpm
 npx panda init
 ```
 
-接着你按照 `panda css` 的安装教程，按照你不同的框架注册方式走一遍: <https://panda-css.com/docs/installation/postcss>
+此时会在当前目录生成一个 `panda.config.ts` 和一个包含大量文件的 `styled-system`。
+
+> `panda.config.ts` 是 `pandacss` 的配置文件，`styled-system` 文件夹里的是 `pandacss` 的运行时 `js`。
+
+把 `styled-system` 加入我们的 `.gitignore` 中去。
+
+```diff
+# .gitignore
++ styled-system
+```
+
+#### 1. 配置 postcss
+
+接着在根目录里，添加一个 `postcss.config.cjs` 文件，写入以下代码注册 `pandacss`:
+
+```js
+module.exports = {
+  plugins: {
+    '@pandacss/dev/postcss': {}
+  }
+}
+```
+
+#### 2. 检查你的 panda.config.ts
+
+生成的配置文件大概长下面这样，尤其注意 `include` 是用来告诉 `pandacss` 从哪些文件中提取原子类的，所以这个配置一定要准确
+
+```ts
+import { defineConfig } from "@pandacss/dev"
+
+export default defineConfig({
+  // 小程序不需要
+  preflight: process.env.TARO_ENV === 'h5',
+  include: ["./src/**/*.{js,jsx,ts,tsx}"],
+  exclude: [],
+  theme: {
+    extend: {}
+  },
+  outdir: "styled-system",
+})
+```
+
+#### 3. 修改 package.json 脚本
+
+然后，我们添加下方 `prepare` 脚本在我们的 `package.json` 的 `scripts` 块中:
+
+```diff
+{
+  "scripts": {
++    "prepare": "panda codegen",
+  }
+}
+```
+
+这样我们每次重新 `npm i / yarn /pnpm i` 的时候，都会执行这个方法，重新生成 `styled-system`，当然你也可以直接通过 `npm run prepare` 直接执行这个脚本。
+
+#### 4. 全局 css 注册 pandacss
 
-配置好了之后，此时 `h5` 平台已经生效了，接下来进入 `weapp-pandacss` 的插件配置，不用担心，也非常简单。
+然后在我们的全局样式文件 `src/app.scss` 中注册 `pandacss`:
+
+```css
+@layer reset, base, tokens, recipes, utilities;
+```
+
+配置好了之后，此时 `pandacss` 在 `h5` 平台已经生效了，你可以 `npm run dev:h5` 在 `h5` 平台初步使用了，但是为了开发体验，我们还有一些优化项要做。
+
+#### 5. 配置的优化与别名
+
+来到根目录的 `tsconfig.json` 添加:
+
+```diff
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": [
+        "src/*"
+      ],
++      "styled-system/*": [
++        "styled-system/*"
++      ]
+    }
+  },
+  "include": [
+    "./src",
+    "./types",
+    "./config",
++    "styled-system"
+  ],
+}
+```
+
+接着来到 `config/index.ts` 添加 `alias`([参考链接](https://taro-docs.jd.com/docs/config-detail#alias)):
+
+```ts
+import path from 'path'
+
+{
+  alias: {
+    'styled-system': path.resolve(__dirname, '..', 'styled-system')
+  },
+}
+```
+
+这样我们就不需要使用相对路径来使用 `pandacss` 了，同时 `ts` 智能提示也有了，你可以这样使用它:
+
+```ts
+import { View, Text } from "@tarojs/components";
+import { css } from "styled-system/css";
+
+const styles = css({
+  bg: "yellow.200",
+  rounded: "9999px",
+  fontSize: "90px",
+  p: "10px 15px",
+  color: "pink.500",
+});
+
+export default function Index() {
+  return (
+    <View className={styles}>
+      <Text>Hello world!</Text>
+    </View>
+  );
+}
+```
+
+> 此部分参考的官方链接 <https://panda-css.com/docs/installation/postcss>
+
+接下来进入 `weapp-pandacss` 的插件配置，不用担心，相比前面那些繁琐的步骤，这个可简单多了。
 
 ### weapp-pandacss 配置
 
-在项目根目录的 `postcss.config.cjs` 添加 `weapp-pandacss` 以下配置:
+> 记得安装好 `weapp-pandacss` !
+
+#### 0. 回到 postcss 进行注册
+
+回到项目根目录的 `postcss.config.cjs` 注册 `weapp-pandacss`，添加以下配置:
 
 ```diff
 module.exports = {
@@ -47,6 +188,8 @@ module.exports = {
 }
 ```
 
+#### 1. 回到 package.json 添加生成脚本
+
 然后去 `package.json` 你添加 `prepare` 脚本的地方，加点代码
 
 ```diff
@@ -66,7 +209,20 @@ module.exports = {
 npm run prepare
 ```
 
-重新生成 `styled-system`，这样 `weapp-pandacss` 相关的转义代码就被注入进去了，此时 `panda css` 生成的类就兼容小程序平台啦，是不是很简单?
+来重新生成 `styled-system`, 此时你会发现 `pandacss` 的命令行输出中多了 `2` 行:
+
+```diff
+✔️ `src/styled-system/css`: the css function to author styles
+✔️ `src/styled-system/tokens`: the css variables and js function to query your tokens
+✔️ `src/styled-system/patterns`: functions to implement apply common layout patterns
+✔️ `src/styled-system/jsx`: styled jsx elements for react
++ ✔️ `src/styled-system/weapp-panda`: the core escape function for weapp
++ ✔️ `src/styled-system/helpers.mjs`: inject escape function into helpers
+```
+
+这代表着小程序相关的转义逻辑已经被注入进去，此时 `panda css` 生成的类就兼容小程序平台啦，是不是很简单?
+
+当然为了防止你配置失败，我也给出了参考项目: [taro-react-pandacss-template](https://github.com/sonofmagic/taro-react-pandacss-template) 方便进行排查纠错。
 
 ## 跨平台注意事项
 
@@ -76,22 +232,24 @@ npm run prepare
 
 `process.env.TARO_ENV === 'h5'` 的时候，不去加载 `weapp-pandacss/postcss` (根据环境变量动态加载 `postcss` 插件)
 
-同时你也可以执行 `weapp-panda rollback` 把 `css` 方法进行回滚到最原始的状态。
+同时你也可以执行 `weapp-panda rollback` 把 `css` 方法进行回滚到最原始适配 `h5` 平台的状态。
 
-当然你恢复到小程序版本也只需要 `weapp-panda codegen`
+当然你恢复到小程序版本也只需要执行 `weapp-panda codegen` 就会重新注入了。
 
 ## 小程序预览事项
 
 当小程序预览时会出现 `Error: 非法的文件，错误信息：invalid file: pages/index/index.js, 565:24, SyntaxError: Unexpected token . if (variants[key]?.[value])` 错误。
 
-这是因为 `panda` 生成的文件 `cva.mjs` 使用了 [`Optional chaining (?.)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining)语法，这个语法小程序原生不支持，这时候可以开启勾选 `将JS编译成ES5` 功能再进行预览，或者使用 `babel` 预先进行转义再上传预览。
+这是因为 `panda` 生成的文件 `cva.mjs` 使用了 [`Optional chaining (?.)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining)语法，这个语法小程序原生不支持，这时候可以开启勾选 `将JS编译成ES5` 功能再进行预览，或者使用 `babel` 预先进行处理再上传预览。
 
 ## 配置项
 
 详见 [types](./src/types.ts)
 
 ## 参考示例
 
+[taro-react-pandacss-template](https://github.com/sonofmagic/taro-react-pandacss-template)
+
 [Taro-app](./examples/taro-app)
 
 [Uni-app vue3 vite](./examples/uni-app-vue3/)