Skip to content

docs: 补充快速上手和主题中的配置项的解释 #3163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 11, 2025
Merged

docs: 补充快速上手和主题中的配置项的解释 #3163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
67c0071
docs: 补充快速上手和主题中的配置项的解释
oasis-cloud Apr 10, 2025
6aa9789
docs: 补充官方主题的使用说明
oasis-cloud Apr 10, 2025
d9b969a
Merge branch 'feat_v3.x' into docs/start
oasis-cloud Apr 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions src/sites/sites-react/doc/docs/react/official-theme-react.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,17 @@ NutUI provides multiple sets of official `UI` themes by default, while allowing

## How to use

It is important to note that when configuring the theme, you also need to import the global class files in the entry file to load some global logic and styles for NutUI React:

| theme description | scss file name |
| --- | --- |
| JD APP Theme (Light Mode) | `@nutui/nutui-react/dist/styles/themes/default.css` |
| JD APP Theme (Dark Mode) | `@nutui/nutui-react/dist/styles/themes/dark.css` |
| JD JDesign Theme | `@nutui/nutui-react/dist/styles/themes/jmapp.css` |
| JD JRKF Theme | `@nutui/nutui-react/dist/styles/themes/jrkf.css` |

Currently, only the default theme provides support for dark mode.

### Modify the configuration file of the local project vite or webpack

Modify the **sass-loader** configuration in the vite or webpack configuration file. The following example
Expand Down
13 changes: 13 additions & 0 deletions src/sites/sites-react/doc/docs/react/official-theme-react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,22 @@ NutUI 默认提供多套官方`UI`主题，同时允许在一定程度上定制
| --- | --- |
| 京东 APP 主题（默认） | `variables.scss` |
| 京东 JDesign 主题 ([预览](https://nutui.jd.com/h5/react/jdesign-3x/#/zh-CN/component/button)) | `variables-jmapp.scss` |
| 京东 JRKF 主题 | `variables-jrkf.scss` |


## 使用方式

需要注意的是，配置主题时，你还需要在入口文件中引入 global 类的文件来加载一些 NutUI React 的全局性逻辑和样式：

| 主题说明 | scss 文件名称 |
| --- | --- |
| 京东 APP 主题（明亮模式） | `@nutui/nutui-react/dist/styles/themes/default.css` |
| 京东 APP 主题（暗黑模式） | `@nutui/nutui-react/dist/styles/themes/dark.css` |
| 京东 JDesign 主题 | `@nutui/nutui-react/dist/styles/themes/jmapp.css` |
| 京东 JRKF 主题 | `@nutui/nutui-react/dist/styles/themes/jrkf.css` |

目前只有默认主题提供了暗黑模式的支持。

### 修改本地项目 vite 或者 webpack 的配置文件

修改 vite 或者 webpack 配置文件中 **sass-loader** 的配置。如下示例
Expand Down
5 changes: 4 additions & 1 deletion src/sites/sites-react/doc/docs/react/start-react.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,10 @@ export default defineConfig({
{
libName: '@nutui/nutui-react',
style: (name) => {
// Handling on-demand import of CSS files, choose one of the two methods
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style/css`
// Handling on-demand import of SCSS files, choose one of the two methods
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style`
},
replaceOldImport: false,
camel2DashComponentName: false,
Expand Down Expand Up @@ -132,7 +135,7 @@ babel config：
'import',
{
libraryName: '@nutui/nutui-react',
style: 'css',
style: 'css', // Here are the CSS files for on-demand import. If you need to import SCSS files, you can set the style to true.
camel2DashComponentName: false,
customName: (name, file) => {
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}`
Expand Down
5 changes: 4 additions & 1 deletion src/sites/sites-react/doc/docs/react/start-react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,10 @@ export default defineConfig({
{
libName: '@nutui/nutui-react',
style: (name) => {
// 按需引入 css 文件的处理，两种方式择其一
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style/css`
// 按需引入 scss 文件的处理，两种方式择其一
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style`
Comment on lines 93 to +97
Copy link

@coderabbitai coderabbitai bot Apr 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

建议优化返回语句逻辑
在 vite-plugin-imp 的配置示例中，style 函数内存在连续两个 return 语句，其中第一个 return 会使第二个返回永远无法执行。这可能会给用户造成困惑。建议将其中一个返回语句注释掉，并提供详细说明，让用户根据需要选择对应的导入方式。例如，可以保留“按需引入 CSS 文件”的 return，而将“按需引入 SCSS 文件”的返回语句注释掉，并在注释中说明如何切换。

-          style: (name) => {
-            // 按需引入 css 文件的处理，两种方式择其一
-            return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style/css`
-            // 按需引入 scss 文件的处理，两种方式择其一
-            return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style`
-          },
+          style: (name) => {
+            // 根据需要选择导入方式，注释掉不使用的方案：
+            // 方案一：按需引入 CSS 文件
+            // return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style/css`;
+            // 方案二：按需引入 SCSS 文件
+            return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style`;
+          },
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
style: (name) => {
// 按需引入 css 文件的处理，两种方式择其一
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style/css`
// 按需引入 scss 文件的处理，两种方式择其一
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style`
style: (name) => {
// 根据需要选择导入方式，注释掉不使用的方案：
// 方案一：按需引入 CSS 文件
// return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style/css`;
// 方案二：按需引入 SCSS 文件
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}/style`;
},

},
replaceOldImport: false,
camel2DashComponentName: false,
Expand Down Expand Up @@ -132,7 +135,7 @@ babel 配置：
'import',
{
libraryName: '@nutui/nutui-react',
style: 'css',
style: 'css', // 这里是按需引入的 css 文件，如果需要引入 scss 文件，可将 style 设置为 true
camel2DashComponentName: false,
customName: (name, file) => {
return `@nutui/nutui-react/dist/es/packages/${name.toLowerCase()}`
Expand Down
2 changes: 2 additions & 0 deletions src/sites/sites-react/doc/docs/react/theme-react.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ We recommend replacing [CSS Vars] (https://developer.mozilla.org/zh-CN/docs/Web/

Create a new 'SCSS' file 'custom_theme.scss' in your local project.

**When customizing themes using SCSS files, you need to set the on-demand import to the SCSS file method. Refer to the description in the automatic on-demand loading configuration in the quick start guide.**

```scss
// Dominant tone
$color-primary: #fa2c19;
Expand Down
2 changes: 2 additions & 0 deletions src/sites/sites-react/doc/docs/react/theme-react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ NutUI-React 支持灵活的样式定制，满足多种视觉业务和品牌需

在本地项目中新建一个 `SCSS` 文件 `custom_theme.scss` 进行自定义。

**使用 SCSS 文件自定义主题时，需将按需引入设置为 scss 文件的方式，参考快速入手中的自动按需加载配置项中的描述**

```scss
// 主色调
$color-primary: #fa2c19;
Expand Down
11 changes: 11 additions & 0 deletions src/sites/sites-react/doc/docs/taro/official-theme-react.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,17 @@ NutUI provides multiple sets of official `UI` themes by default, while allowing

## How to use

It is important to note that when configuring the theme, you also need to import the global class files in the entry file to load some global logic and styles for NutUI React:

| theme description | scss file name |
| --- | --- |
| JD APP Theme (Light Mode) | `@nutui/nutui-react-taro/dist/styles/themes/default.css` |
| JD APP Theme (Dark Mode) | `@nutui/nutui-react-taro/dist/styles/themes/dark.css` |
| JD JDesign Theme | `@nutui/nutui-react-taro/dist/styles/themes/jmapp.css` |
| JD JRKF Theme | `@nutui/nutui-react-taro/dist/styles/themes/jrkf.css` |

Currently, only the default theme provides support for dark mode.

### Modify the configuration file of the local project vite or webpack

Modify the **sass-loader** configuration in the vite or webpack configuration file. The following example
Expand Down
11 changes: 11 additions & 0 deletions src/sites/sites-react/doc/docs/taro/official-theme-react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,17 @@ NutUI 默认提供多套官方`UI`主题，同时允许在一定程度上定制

## 使用方式

需要注意的是，配置主题时，你还需要在入口文件中引入 global 类的文件来加载一些 NutUI React 的全局性逻辑和样式：

| 主题说明 | scss 文件名称 |
| --- | --- |
| 京东 APP 主题（明亮模式） | `@nutui/nutui-react-taro/dist/styles/themes/default.css` |
| 京东 APP 主题（暗黑模式） | `@nutui/nutui-react-taro/dist/styles/themes/dark.css` |
| 京东 JDesign 主题 | `@nutui/nutui-react-taro/dist/styles/themes/jmapp.css` |
| 京东 JRKF 主题 | `@nutui/nutui-react-taro/dist/styles/themes/jrkf.css` |

目前只有默认主题提供了暗黑模式的支持。

### 修改本地项目 vite 或者 webpack 的配置文件

修改 vite 或者 webpack 配置文件中 **sass-loader** 的配置。如下示例
Expand Down
2 changes: 1 addition & 1 deletion src/sites/sites-react/doc/docs/taro/start-react.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ plugins: [
'import',
{
libraryName: '@nutui/nutui-react-taro',
style: 'css',
style: 'css', // Here are the CSS files for on-demand import. If you need to import SCSS files, you can set the style to true.
camel2DashComponentName: false,
customName: (name, file) => {
return `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}`
Expand Down
2 changes: 1 addition & 1 deletion src/sites/sites-react/doc/docs/taro/start-react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ module.exports = {
'import',
{
libraryName: '@nutui/nutui-react-taro',
style: 'css',
style: 'css', // 这里是按需引入的 css 文件，如果需要引入 scss 文件，可将 style 设置为 true
camel2DashComponentName: false,
customName: (name, file) => {
return `@nutui/nutui-react-taro/dist/es/packages/${name.toLowerCase()}`
Expand Down
4 changes: 3 additions & 1 deletion src/sites/sites-react/doc/docs/taro/theme-react.en-US.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ We recommend replacing [CSS Vars] (https://developer.mozilla.org/zh-CN/docs/Web/

Create a new 'SCSS' file 'custom_theme.scss' in your local project.

**When customizing themes using SCSS files, you need to set the on-demand import to the SCSS file method. Refer to the description in the automatic on-demand loading configuration in the quick start guide.**

```scss
// Dominant tone
$color-primary: #fa2c19;
Expand All @@ -32,7 +34,7 @@ $color-primary-end: #fa6419;

#### Step 2: Modify the configuration file of the local project webpack or vite

Modify the ** ass-loader** configuration in the 'vite' or 'webpack' configuration file. The following example
Modify the ** sass-loader** configuration in the 'vite' or 'webpack' configuration file. The following example

#### vite

Expand Down
2 changes: 2 additions & 0 deletions src/sites/sites-react/doc/docs/taro/theme-react.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ NutUI-React 支持灵活的样式定制，满足多种视觉业务和品牌需

在本地项目中新建一个 `SCSS` 文件 `custom_theme.scss` 进行自定义。

**使用 SCSS 文件自定义主题时，需将按需引入设置为 scss 文件的方式，参考快速入手中的自动按需加载配置项中的描述**

```scss
// 主色调
$color-primary: #fa2c19;
Expand Down
Loading