Skip to content

Commit

Permalink
大量优化文档表达 (#1048)
Browse files Browse the repository at this point in the history 
* feat: 优化文档表达

* feat: 优化文档表达

* docs: 修复文档

* docs: 更新文档

* docs: 更新文档

* docs: 更新文档

* docs: 更新文档

* docs: 更新文档

---------

Co-authored-by: xiaofeng.mxf <[email protected]>
Co-authored-by: DiamondYuan <[email protected]>
  • Loading branch information
@ottomao
3 people authored Feb 2, 2024
1 parent 2c1b754 commit 6331e7e
Show file tree
Hide file tree
Showing 52 changed files with 1,302 additions and 1,206 deletions.
87 changes: 41 additions & 46 deletions docs/guide/contribute.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,78 +6,77 @@ toc: false

### 1. 克隆代码

代码仓库： https://github.com/ant-design/ant-design-mini/
代码仓库: https://github.com/ant-design/ant-design-mini/

```
```bash
$ git clone [email protected]:ant-design/ant-design-mini.git
```

### 2. 安装依赖

```
```bash
$ npm i
```

### 3. 启动项目编译

运行 dev 将源码编译到 compiled 目录下。
运行 `dev` 命令将源码编译到 `compiled` 目录下。

```
```bash
$ npm run dev
```

### 3. 使用 IDE 编辑
### 4. 使用 IDE 编辑

#### 在微信小程序开发者工具中运行

直接用微信开发者工具打开项目的根目录。
直接使用微信开发者工具打开项目的根目录。

打开项目后，进入微信目录安装依赖
打开项目后，进入微信目录并安装依赖：

```
```bash
$ cd compiled/wechat
$ npm i
```

安装好依赖后，点击微信开发者工具中的菜单栏：工具 --> 构建 npm。构建完成后, 项目就可以正常运行了。
安装好依赖后，点击微信开发者工具中的菜单栏：“工具 --> 构建 npm”。构建完成后，项目就可以正常运行了。

#### 在支付宝小程序开发者工具中运行

直接用支付宝小程序开发者工具打开项目根目录即可运行。
直接使用支付宝小程序开发者工具打开项目根目录即可运行。

### 5. 预览文档

```
```bash
$ npm run dev:doc
```

### 6. Commit 规范

提交 commit 时，需要遵循以下原则：

- 最小化代码变更：保证每个 commit 的逻辑独立、原子化。一个 commit 只做一件事，哪怕这件事只改了 1 行代码，你也应该独立 commit 这次变更；
- 遵循 [Conventional Commits 原则](https://www.conventionalcommits.org/zh-hans/v1.0.0/)：避免没有意义、看不懂的 Commit Message 引入，并且在代码提交的时候会有 Commit Message 格式校验。一般情况下，你会大量的使用到：
1. 使用 feat(scope): xxx 来描述一个 feature 的 commit；
2. 使用 fix(scope): xxx 来描述一个 bug fixes 的 commit；
3. 使用 chore(scope): xxx 来来描述一个无关 feature 和 bug fixes 的小调整；
- issue：如果改动与 issue 相关，请在 Commit Message 中带上 issue 参数，如：fix(scope): [#1] xxxxxx；
- 在提交 Pull Request 之前, 需要执行 `npm run build:tsxml`, 将源码编译到各个平台，然后将 `compiled/` 下的编译产物添加到 git 里。
- 最小化代码变更：保证每个 commit 的逻辑独立且原子化。即使变动只有 1 行代码，也应该独立 commit；
- 遵循 [Conventional Commits 原则](https://www.conventionalcommits.org/zh-hans/v1.0.0/)，避免无意义的 Commit Message。代码提交时会有 Commit Message 格式校验，通常你会大量使用：
1. `feat(scope): xxx` 来描述一个 feature 的 commit；
2. `fix(scope): xxx` 来描述一个 bug fixes 的 commit；
3. `chore(scope): xxx` 来描述与 feature 和 bug fixes 无关的小调整；
- 提及 issue：如果改动与 issue 相关，在 Commit Message 中请注明 issue 号，例如：`fix(scope): [#1] xxxxxx`。

## Ant Design Mini 的工程方案

### 函数式组件

从 v2 版本起，我们逐渐使用“React 函数式组件”的形式来开发小程序自定义组件，它的背后依赖了 [functional-mini](https://github.com/ant-design/functional-mini) 这个 SDK。一个典型的案例是日历组件（ [Calendar/index.ts](https://github.com/ant-design/ant-design-mini/blob/master/src/Calendar/index.ts) ）。
从 v2 版本开始，我们逐步采用“React 函数式组件”开发模式来开发小程序自定义组件，背后依托 [functional-mini](https://github.com/ant-design/functional-mini) 这个 SDK。如日历组件（参见 [Calendar/index.ts](https://github.com/ant-design/ant-design-mini/blob/master/src/Calendar/index.ts)）。

[functional-mini](https://github.com/ant-design/functional-mini) 是纯运行时 SDK，它接管了小程序的逻辑层代码，但又不侵入视图层，为我们在项目架构复杂度和编码习惯上带来了平衡。函数式组件的基本特性也因此得以施展，提升了代码可维护度，如更易组装数据加工逻辑、更方便实现 hooks 逻辑复用等。
[functional-mini](https://github.com/ant-design/functional-mini) 作为运行时 SDK，接管小程序的逻辑层代码，但并不影响视图层，为我们在项目架构复杂度和编码习惯上带来平衡。借此，函数式组件的基本特性得以运用，提升代码可维护性，如数据加工逻辑组装、hooks 逻辑复用等。

我们欢迎你一同参与 Ant Design Mini 的函数式组件开发，共同探索更优质的小程序工程形态。
欢迎你一同参与 Ant Design Mini 函数式组件开发，探索更佳的小程序工程形态。

### 使用 tsx 语法编写视图层

我们使用 tsx 语法编写视图层，通过编译器解析 tsx 语法，生成小程序视图层代码。这样做的好处是：
我们使用 tsx 语法编写视图层。编译器解析 tsx 语法后，生成小程序视图层代码。这意味着：

- 可以使用 import 语法引入其他组件，享受自定义组件的类型提示
- 可以用 import 语法引入其他组件，享有自定义组件类型提示：

```tsx | pure
import AntButton from '../../../src/Button/index.axml';
Expand All @@ -87,46 +86,42 @@ import AntButton from '../../../src/Button/index.axml';
</AntButton>;
```

- 只需要编写一份代码，就可以同时生成支付宝小程序与微信小程序的视图层代码
- 编写一份代码，同时生成支付宝与微信小程序视图层代码：

```tsx | pure
export default ({ a, b }: TSXMLProps<Props>) => (
<View>
{!!a && <Text>a</Text>}
{!!a && b && <Text> a & b</Text>}
{a && <Text>a</Text>}
{a && b && <Text>a & b</Text>}
{a ? <Text>a</Text> : <Text>!a</Text>}
{<Text class={a ? '1' : '2'}></Text>}
<Text class={`1 ${a ? '1' + '2' : 2} 2`}></Text>
<Text class={`1 ${a ? '1' + '2' : '2'} 2`}></Text>
</View>
);
```

微信小程序：

```xml
<view>
<!-- display: inline -->
<text wx:if="{{ !!a }}">a</text>
<!-- display: inline -->
<text wx:if="{{ !!a && b }}">a & b</text>
<!-- display: inline -->
<text wx:if="{{ a }}">a</text>
<!-- display: inline -->
<text wx:if="{{a}}">a</text>
<text wx:if="{{a && b}}">a & b</text>
<text wx:if="{{a}}">a</text>
<text wx:else>!a</text>
<text class="{{ a ? '1' : '2' }}" />
<text class="1 {{ a ? '1' + '2' : 2 }} 2" />
<text class="{{a ? '1' : '2'}}"></text>
<text class="1 {{a ? '1' + '2' : '2'}} 2"></text>
</view>
```

支付宝小程序：

```xml
<view>
<!-- display: inline -->
<text a:if="{{ !!a }}">a</text>
<!-- display: inline -->
<text a:if="{{ !!a && b }}">a & b</text>
<!-- display: inline -->
<text a:if="{{ a }}">a</text>
<!-- display: inline -->
<text a:if="{{a}}">a</text>
<text a:if="{{a && b}}">a & b</text>
<text a:if="{{a}}">a</text>
<text a:else>!a</text>
<text class="{{ a ? '1' : '2' }}" />
<text class="1 {{ a ? '1' + '2' : 2 }} 2" />
<text class="{{a ? '1' : '2'}}"></text>
<text class="1 {{a ? '1' + '2' : '2'}} 2"></text>
</view>
```
26 changes: 14 additions & 12 deletions docs/guide/cooperation.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,34 @@
---

toc: false

---

## 参与 antd-mini 建设

antd-mini 的发展离不开社区的每一位用户，这里有一些信息可以帮助你参与共建。
antd-mini 的发展离不开社区的每一位用户。为了帮助你参与共建，这里列出了一些必要的信息。

### 项目运作流程

### issue
#### issue

如果你有组件库的相关使用问题或需求，可以前往 issue 区域搜索或者提问。我们提供了多种 issue 模板，请根据需要选择对应模板。同时，也非常欢迎你为其他同学解惑。
当你碰到组件库使用中的问题或需求时，可前往 issue 区查阅或提问。我们准备了多样的 issue 模板，请根据实际情况挑选适用的一种。同时，如果你能帮助解决他人的疑惑，我们也会非常感激。

#### feature request

如果现有的组件不能满足你的开发需求，请提交 issue 来描述你的需求。当然，并不是每一个 FR 都会实现。因为 antd-mini 的定位是一个基础组件库，而非业务组件库。我们会讨论每一个 FR，确认是一个基础组件需求后，我们就会进入开发流程。
如果当前组件库无法满足你的开发需求，请通过提交 issue 来阐述你所需的功能。不过，请注意，并非所有提交的需求都一定会得到实现。antd-mini 定位于基础组件库，不包含业务类组件。我们会讨论每个提交的需求，一旦确认是基础功能所需，我们便会启动开发流程。

#### bug
#### bug 反馈

提交 issue 时，请尽可能多地提供 bug 相关信息，以帮助我们更快地复现并解决。
提交 bug 反馈时，请尽量完整提供相关信息，方便我们迅速复现与解决该问题。

下面是一些注意事项：
以下是提交时的一些注意事项：

- 设备信息、客户端版本、组件库版本、组件等
- 你期望的组件行为是什么，实际上组件的行为是什么
- 详细描述复现步骤
- 尽可能提供能够复现 demo 以方便我们快速定位问题
- 提供设备信息、客户端版本、组件库版本以及具体组件等；
- 说明你期望的组件行为和实际发生的行为；
- 详细描述重现问题的步骤；
- 如果可行，提供可以复现问题的示例或 demo，以加速问题定位。

### 贡献代码

非常欢迎各位为 antd-mini 贡献代码，这里有一份[贡献指南](./contribute.md)。在贡献代码之前，请提交 RFC issue 并详细描述你的改动，以便我们能够在 RFC 中充分讨论，节省双方的时间。
我们诚挚地邀请你为 antd-mini 贡献代码。请参阅[贡献指南](./contribute.md)了解详细信息。在贡献代码前，务必先提交一个 RFC issue 并详尽描述你的修改内容，这样我们能在 RFC 中充分讨论，以节省双方的时间。
57 changes: 29 additions & 28 deletions docs/guide/customize-theme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@ toc: false

## 定制主题

antd-mini 可使用less自定义主题。antd-mini 内置了两套主题，一套基础主题，一套深色主题。自定义less变量，可使用不同的主题、修改主题颜色。
antd-mini 支持使用 less 来自定义主题。antd-mini 内置了两套主题：基础主题和深色主题。通过自定义 less 变量，可以使用不同的主题或修改主题颜色。

## 使用方式
> 需要小程序开发者工具IDE >= 3.0.0、命令行工具 CLI >= 1.4.0

1. 使用 `antd-mini/less/组件`
> 小程序开发者工具 IDE 版本需不低于 3.0.0，命令行工具 CLI 版本需不低于 1.4.0。
1. 使用 `antd-mini/less/组件`：

```json
{
Expand All @@ -19,7 +20,8 @@ antd-mini 可使用less自定义主题。antd-mini 内置了两套主题，一
}
```

2. 在 `mini.project.json` 里可使用 modifyVars 修改 less变量，比如修改 `theme`：
2. 在 `mini.project.json` 文件中可通过 `modifyVars` 修改 less 变量，例如修改 `theme`：

```json
{
"format": 2,
Expand All @@ -32,27 +34,26 @@ antd-mini 可使用less自定义主题。antd-mini 内置了两套主题，一
}
}
```



## less变量
| 名称 | 说明 | 默认值 |
| -----|-----|-----|
| theme | 主题，可选 `default`, `dark` | default |
| rpx | rpx | 0.5px |
| colorPrimary | 品牌色，默认值分别为 `default`, `dark` 对应 | #1677ff, #3086FF |
| colorWathet | 浅蓝色 | #E7F1FF, #0D2543 |
| colorRed | 红色 | #FF3141, #FF4A58 |
| colorYellow | 黄色 | #FF9F18, #FFA930 |
| colorGreen | 绿色 | #22B35E, #34B368 |
| colorTextPrimary | 主信息 | #333333, #E6E6E6 |
| colorWhite | 白色 | #FFFFFF, #FFFFFF |
| colorOrange | 橙色 | #FF6430, #E65A2B |
| colorBlack | 黑色 | #000000, #000000 |
| colorTextAssist | 辅助信息 | #999999, #808080 |
| colorBorder | 边界线 | #EEEEEE, #2B2B2B |
| colorBackground | 全局背景 | #F5F5F5, #0A0A0A |
| colorTextWeak | 弱信息 | #CCCCCC, #4D4D4D |
| colorCard | 卡片 | #FFFFFF, #1A1A1A |
| colorTextSecondary | 副信息 | #666666, #B3B3B3 |
| colorGreyCard | 灰色的卡片 | #F5F5F5, #2B2B2B |

## less 变量

| 名称 | 说明 | 默认值 |
| ---------------- | --------------------------- | --------------------------------- |
| theme | 主题，可选择 `default`、`dark` | `default` |
| rpx | rpx 单位对应值 | `0.5px` |
| colorPrimary | 主品牌色，对应 `default` 和 `dark` 的默认值 | `#1677ff`、`#3086FF` |
| colorWathet | 浅蓝色 | `#E7F1FF`、`#0D2543` |
| colorRed | 红色 | `#FF3141`、`#FF4A58` |
| colorYellow | 黄色 | `#FF9F18`、`#FFA930` |
| colorGreen | 绿色 | `#22B35E`、`#34B368` |
| colorTextPrimary | 主要文本信息颜色 | `#333333`、`#E6E6E6` |
| colorWhite | 白色 | `#FFFFFF`、`#FFFFFF` |
| colorOrange | 橙色 | `#FF6430`、`#E65A2B` |
| colorBlack | 黑色 | `#000000`、`#000000` |
| colorTextAssist | 辅助性文本信息颜色 | `#999999`、`#808080` |
| colorBorder | 边框颜色 | `#EEEEEE`、`#2B2B2B` |
| colorBackground | 全局背景色 | `#F5F5F5`、`#0A0A0A` |
| colorTextWeak | 弱信息 | `#CCCCCC`、`#4D4D4D` |
| colorCard | 卡片颜色 | `#FFFFFF`、`#1A1A1A` |
| colorTextSecondary | 副级文本信息颜色 | `#666666`、`#B3B3B3` |
| colorGreyCard | 灰色卡片 | `#F5F5F5`、`#2B2B2B` |
39 changes: 23 additions & 16 deletions docs/guide/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,24 @@ toc: false

## 常见问题

### 能否 0.x 跟 1.0 一起使用
### 2.x 能否和 1.x, 0.x 一起使用

可以使用别名，比如 `antd-mini-v1` 进行安装：
因为 1.x 升级到 2.x 没有迁移成本，所以你可以直接从 1.x 升级到 2.x
对于 0.x, 你可以使用 antd-mini-v0 这个 npm 包, 产物内容和 [email protected] 一模一样。

```
$ npm install antd-mini-v1@npm:antd-mini --save
$ npm install antd-mini-v0 antd-mini
```

```
"antd-mini": "^0.0.25",
"antd-mini-v1": "npm:antd-mini"
在 `package.json` 文件中是这样定义的：

```json
{
"dependencies": {
"antd-mini": "^2.25.0",
"antd-mini-v0": "^0.0.26"
}
}
```

使用：
Expand All @@ -23,31 +30,31 @@ $ npm install antd-mini-v1@npm:antd-mini --save
{
"usingComponents": {
"button": "antd-mini/es/Button/index",
"button-v1": "antd-mini-v1/es/Button/index"
"button-v0": "antd-mini-v0/es/Button/index"
}
}
```

```html
<button>这是0.x antd-mini</button> <button-v1>这是1.0 antd-mini</button-v1>
<button>这是2.x antd-mini</button>
<antd-mini-v0>这是0.x antd-mini</antd-mini-v0>
```

### 在支付宝小程序 Page 里覆盖 antd-mini 的样式不生效
### 在支付宝小程序页面中，如何覆盖 antd-mini 的样式并确保其生效

新版支付宝小程序开发者工具在创建页面时会默认加上 `styleIsolation: 'apply-shared'`, 此时页面的样式无法影响到外部。
新版支付宝小程序开发者工具默认为创建的页面配置了 `styleIsolation: 'apply-shared'`，这将导致页面样式无法影响到外部组件。

可以在 `page.json` 里设置 `styleIsolation: 'shared'`。
您可以通过修改对应 page.json 的样式隔离配置来解决此问题：

```json
{
"styleIsolation": "shared"
}
```

styleIsolation 配置有两种模式：

`apply-shared`: 表示 app.acss 样式以及其他（设置了 shared 的其他页面和自定义组件）的样式将影响到当前页面，但当前页面 acss 中指定的样式不会影响外部。
`styleIsolation` 配置项有如下两种模式可供选择：

`shared`（默认）表示 app.acss 样式以及其他（设置了 shared 的其他页面和自定义组件）的样式将影响到当前页面，当前页面 acss 中指定的样式也会影响到外部。
- `apply-shared`：这意味着 app.acss 样式和其它设定了 `shared` 的页面或自定义组件样式会影响当前页面，但当前页面 acss 中的样式不会作用于外部。
- `shared`（默认）：表示 app.acss 样式和其它设定了 `shared` 的页面或自定义组件样式会影响当前页面，同时当前页面 acss 中的样式也会作用于外部。

参考: https://opendocs.alipay.com/mini/framework/page-acss#%E9%A1%B5%E9%9D%A2%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB
官方文档参考链接：[页面样式隔离](https://opendocs.alipay.com/mini/framework/page-acss#%E9%A1%B5%E9%9D%A2%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB)
Loading

0 comments on commit 6331e7e

Please sign in to comment.