admin/wot-design-uni
1
0
Fork 0
mirror of https://gitee.com/wot-design-uni/wot-design-uni.git synced 2025-12-06 17:18:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 修复 Button/Icon/ConfigProvider/Popup 组件文档不一致问题 (#1190)

Browse Source 
* docs(button): 更新按钮组件文档对开放能力的描述

- 修改 session-message-title 和 session-message-path 属性名称
- 新增 chooseavatar 和 agreeprivacyauthorization 事件回调

* docs(icon): 更新图标组件文档

- 调整属性描述，明确 name 属性可用于图标名称或图片链接
- 添加事件列表，明确 click 事件的参数
- 移除英文示例代码中不必要的示例和图标列表
- 优化文档结构和格式，使信息更加清晰

* docs(config-provider): 更新全局配置组件文档

- 调整文档中的强调样式，使用加粗替代下划线
- 完善英文文档缺失的内容，保持和中文文档一致

* docs(component): 更新 Popup 组件文档

- 调整文档结构，优化标题层级
- 添加 v-model 使用示例，明确组件绑定值
- 移除冗余的代码示例，精简文档内容
- 更新属性表格，统一属性描述
- 添加防止滚动穿透的解决方案说明
This commit is contained in:
TAYUN 2025-08-09 15:12:23 +08:00 committed by GitHub
parent 2bb28f361c
commit 04d0d11849
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 194 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/component/button.md
View File

@ -137,8 +137,8 @@
| hover-stop-propagation | 指定是否阻止本节点的祖先节点出现点击态 | boolean | - | false | - |
| lang | 指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文 | string | zh_CN / zh_TW | en | - |
| session-from | 会话来源，open-type="contact"时有效 | string | - | - | - |
| session-message-title | 会话内消息卡片标题，open-type="contact"时有效 | string | - | 当前标题 | - |
| session-message-path | 会话内消息卡片点击跳转小程序路径，open-type="contact"时有效 | string | - | 当前分享路径 | - |
| send-message-title | 会话内消息卡片标题，open-type="contact"时有效 | string | - | 当前标题 | - |
| send-message-path | 会话内消息卡片点击跳转小程序路径，open-type="contact"时有效 | string | - | 当前分享路径 | - |
| send-message-img | 会话内消息卡片图片，open-type="contact"时有效 | string | - | 截图 | - |
| app-parameter | 打开 APP 时，向 APP 传递的参数，open-type=launchApp 时有效 | string | - | - | - |
| show-message-card | 是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，open-type="contact"时有效 | boolean | - | false | - |
@ -174,6 +174,8 @@
| error | 当使用开放能力时，发生错误的回调，open-type=launchApp 时有效 | `detail` | - |
| launchapp | 打开 APP 成功的回调，open-type=launchApp 时有效 | `detail` | - |
| opensetting | 在打开授权设置页后回调，open-type=openSetting 时有效 | `detail` | - |
| chooseavatar | 获取用户头像回调，open-type=chooseAvatar 时有效 | `detail` | - |
| agreeprivacyauthorization | 用户同意隐私协议回调，open-type=agreePrivacyAuthorization 时有效 | `detail` | - |
## 外部样式类

2
docs/component/config-provider.md
View File

@ -104,7 +104,7 @@ export default {
```
### 在 TypeScript 中使用
在 TypeScript 中定义 `themeVars` 时，建议使用 __wot-design-uni__ 提供的 __ConfigProviderThemeVars__ 类型，可以提供完善的类型提示：
在 TypeScript 中定义 `themeVars` 时，建议使用 **wot-design-uni** 提供的 **ConfigProviderThemeVars** 类型，可以提供完善的类型提示：
```ts
import type { ConfigProviderThemeVars } from 'wot-design-uni';

8
docs/component/icon.md
View File

@ -68,12 +68,18 @@
## Attributes
| 参数 | 说明 | 类型 | 可选值 | 默认值 | 最低版本 |
|-----|------|-----|-------|-------|---------|
| name | 使用的图标名字，可以使用链接图片 | string | - | - | - |
| name | 图标名称或图片链接 | string | - | - | - |
| color | 图标的颜色 | string | - | inherit | - |
| size | 图标的字体大小 | string | - | inherit | - |
| classPrefix | 类名前缀，用于使用自定义图标 | string | - | 'wd-icon' | 0.1.27 |
| custom-style | 根节点样式 | string | - | - | - |
## Events
| 事件名称 | 说明 | 参数 | 最低版本 |
|---------|------|------|---------|
| click | 点击图标时触发 | event | - |
## 外部样式类
| 类名 | 说明 | 最低版本 |

7
docs/component/popup.md
View File

@ -1,4 +1,4 @@
# Popup 弹出层
# Popup 弹出层
弹出层组件，用于展示弹窗、信息提示等内容。
@ -48,7 +48,6 @@
<wd-popup v-model="show" position="bottom" :close-on-click-modal="false" closable custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
## 禁用遮罩
通过设置 `modal` 属性为 `false`，你可以禁用遮罩层，使用户可以与底层内容进行交互。
@ -117,11 +116,11 @@ h5 滚动穿透不需要处理，组件已默认开启 `lock-scroll`。
| custom-style | 自定义弹出层样式 | string | - | - | - |
| modal | 是否显示遮罩 | boolean | - | true | - |
| modal-style | 自定义modal蒙层样式 | string | - | - | - |
| hide-when-close | 是否当关闭时将弹出层隐藏（display: none) | boolean | - | true | - |
| hide-when-close | 是否当关闭时将弹出层隐藏(display: none) | boolean | - | true | - |
| lazy-render | 弹层内容懒渲染，触发展示时才渲染内容 | boolean | - | true | - |
| safe-area-inset-bottom | 弹出面板是否设置底部安全距离（iphone X 类型的机型） | boolean | - | false | - |
| transition | 动画类型，参见 wd-transition 组件的name | string | fade / fade-up / fade-down / fade-left / fade-right / slide-up / slide-down / slide-left / slide-right / zoom-in | - | - |
| lockScroll | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | boolean | - | true | 0.1.30 |
| lock-scroll | 是否锁定背景滚动，锁定时蒙层里的内容也将无法滚动 | boolean | - | true | 0.1.30 |
| root-portal | 是否从页面中脱离出来，用于解决各种 fixed 失效问题 | boolean | - | false | 1.11.0 |
## Events

6
docs/en-US/component/button.md
View File

@ -137,8 +137,8 @@ Use the `custom-class` and `custom-style` attributes to customize the button's s
| hover-stop-propagation | Specifies whether to prevent the ancestor node of this node from appearing in the clicked state | boolean | - | false | - |
| lang | Specifies the language of the returned user information, zh_CN for Simplified Chinese, zh_TW for Traditional Chinese, en for English | string | zh_CN / zh_TW | en | - |
| session-from | Session source, valid when open-type="contact" | string | - | - | - |
| session-message-title | Session message card title, valid when open-type="contact" | string | - | Current title | - |
| session-message-path | Session message card click jump Mini Program path, valid when open-type="contact" | string | - | Current share path | - |
| send-message-title | Session message card title, valid when open-type="contact" | string | - | Current title | - |
| send-message-path | Session message card click jump Mini Program path, valid when open-type="contact" | string | - | Current share path | - |
| send-message-img | Session message card image, valid when open-type="contact" | string | - | Screenshot | - |
| app-parameter | Parameters passed to the APP when opening the APP, valid when open-type=launchApp | string | - | - | - |
| show-message-card | Whether to display the message card in the session, setting this parameter to true will show a prompt "May want to send Mini Program" in the bottom right corner when the user enters the customer service session, and the user can quickly send the Mini Program message after clicking, valid when open-type="contact" | boolean | - | false | - |
@ -176,6 +176,8 @@ WeChat Mini Program open capabilities, see [WeChat Mini Program Button](https://
| error | Error callback when using open capabilities, valid when open-type=launchApp | `detail` | - |
| launchapp | Callback for successfully opening APP, valid when open-type=launchApp | `detail` | - |
| opensetting | Callback after opening authorization settings page, valid when open-type=openSetting | `detail` | - |
| chooseavatar | Get user avatar callback, valid when open-type=chooseAvatar | `detail` | - |
| agreeprivacyauthorization | User agrees to privacy agreement callback, valid when open-type=agreePrivacyAuthorization | `detail` | - |
## External Style Classes

69
docs/en-US/component/config-provider.md
View File

@ -104,10 +104,11 @@ export default {
```
### Using with TypeScript
When defining `themeVars` in TypeScript, it's recommended to use the __ConfigProviderThemeVars__ type provided by __wot-design-uni__, which can provide comprehensive type hints:
When defining `themeVars` in TypeScript, it's recommended to use the **ConfigProviderThemeVars** type provided by **wot-design-uni**, which can provide comprehensive type hints:
```ts
import type { ConfigProviderThemeVars } from 'wot-design-uni';
import type { ConfigProviderThemeVars } from 'wot-design-uni'
const themeVars: ConfigProviderThemeVars = {
colorTheme: 'red'
@ -125,6 +126,7 @@ Note: ConfigProvider only affects the styles of its child components, not the gl
### Installation
::: code-group
```bash [npm]
npm i -D @uni-ku/root
```
@ -136,6 +138,7 @@ yarn add -D @uni-ku/root
```bash [pnpm]
pnpm add -D @uni-ku/root
```
:::
### Import
@ -188,11 +191,65 @@ const { theme, themeVars } = useTheme({
<template>
<div>Hello AppKuVue</div>
<!-- Assuming WdConfigProvider component is registered -->
<WdConfigProvider :theme="theme" :theme-vars="themeVars">
<!-- Ensure WdConfigProvider component is registered -->
<wd-config-provider :theme="theme" :theme-vars="themeVars">
<KuRootView />
</WdConfigProvider>
</wd-config-provider>
</template>
```
2. Write a composable function for theme control
2. Write a composable function for theme control
```ts
// src/composables/useTheme.ts
import type { ConfigProviderThemeVars } from 'wot-design-uni'
import { ref } from 'vue'
const theme = ref<'light' | 'dark'>()
const themeVars = ref<ConfigProviderThemeVars>()
export function useTheme(vars?: ConfigProviderThemeVars) {
vars && (themeVars.value = vars)
function toggleTheme(mode?: 'light' | 'dark') {
theme.value = mode || (theme.value === 'light' ? 'dark' : 'light')
}
return {
theme,
themeVars,
toggleTheme
}
}
```
3. Use theme switching in any view file
```vue
<!-- src/pages/*.vue -->
<script setup lang="ts">
import { useTheme } from '@/composables/useTheme'
const { theme, toggleTheme } = useTheme()
</script>
<template>
<button @click="toggleTheme">Toggle theme, current mode: {{ theme }}</button>
</template>
```
## Attributes
| Parameter | Description | Type | Options | Default | Version |
| ---------- | --------------------------------------------------------------------- | ------------------------- | -------------- | ------- | ------- |
| theme | Theme style, set to `dark` to enable dark mode, takes effect globally | string | `dark`/`light` | - | - |
| theme-vars | Custom theme variables | `ConfigProviderThemeVars` | - | - | - |
## External Style Classes
| Class Name | Description | Version |
| ------------ | --------------- | ------- |
| custom-class | Root node style | 1.3.9 |
| custom-style | Root node style | 1.3.9 |

38
docs/en-US/component/icon.md
View File

@ -8,10 +8,6 @@ Set the `name` attribute to use the built-in icons.
```html
<wd-icon name="add-circle"></wd-icon>
<wd-icon name="add"></wd-icon>
<wd-icon name="arrow-down"></wd-icon>
<wd-icon name="arrow-right"></wd-icon>
<wd-icon name="camera"></wd-icon>
```
## Icon Color
@ -46,34 +42,30 @@ First, you need to define your own font icon library, and then set the `class-pr
### 2. Using Image Icons
Set the `custom` attribute to use image icons, and set the `name` attribute to the image URL.
Set the `name` attribute to an image URL to use image icons. The component automatically detects URLs containing `/`.
```html
<wd-icon custom name="https://example.com/icon.png"></wd-icon>
<wd-icon name="https://example.com/icon.png"></wd-icon>
```
## Icon List
<icon-list></icon-list>
## Attributes
| Attribute | Description | Type | Default | Version |
|---------|---------|---------|---------|------|
| name | Icon name | string | - | - |
| color | Icon color | string | - | - |
| size | Icon size | string | - | - |
| class-prefix | Custom icon class prefix | string | wd-icon | - |
| custom | Whether to use custom image icon | boolean | false | - |
| Attribute | Description | Type | Default | Version |
| ------------ | ------------------------ | ------ | ------- | ------- |
| name | Icon name or image URL | string | - | - |
| color | Icon color | string | - | - |
| size | Icon size | string | - | - |
| class-prefix | Custom icon class prefix | string | wd-icon | - |
| custom-style | Custom root node style | string | - | - |
## Events
| Event Name | Description | Parameters | Version |
|---------|---------|---------|------|
| click | Triggered when the icon is clicked | event: Event | - |
| Event Name | Description | Parameters | Version |
| ---------- | ---------------------------------- | ------------ | ------- |
| click | Triggered when the icon is clicked | event: Event | - |
## External Style Classes
| Class Name | Description | Version |
|---------|---------|------|
| custom-class | Root node custom class | - |
| Class Name | Description | Version |
| ------------ | ---------------------- | ------- |
| custom-class | Root node custom class | - |

187
docs/en-US/component/popup.md
View File

@ -1,88 +1,80 @@
# Popup
A popup layer that displays content on top of the current page.
A popup layer component used to display popups, information prompts, and other content.
## Basic Usage
The `visible` attribute controls whether the popup is displayed. The `position` attribute sets the popup position, which can be 'center', 'top', 'right', 'bottom', 'left', default is 'center'.
`v-model` is the binding value that indicates whether to display the popup layer.
```html
<wd-popup :visible.sync="show" position="bottom">
<view style="height: 200px; text-align: center; line-height: 200px;">
Content
</view>
<wd-popup v-model="show" custom-style="border-radius:32rpx;" @close="handleClose">
<text class="custom-txt">Pop Pop Pop</text>
</wd-popup>
```
```css
.custom-txt {
color: black;
width: 400rpx;
height: 400rpx;
display: flex;
justify-content: center;
align-items: center;
font-size: 40rpx;
border-radius: 32rpx;
}
```
## Popup Position
Set `position`, default is 'center', optional values are 'top', 'right', 'bottom', 'left'.
```html
<wd-popup v-model="show" position="top" custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
## Close Button
Set the `closable` attribute to display a close button in the popup.
Set the `closable` attribute.
```html
<wd-popup :visible.sync="show" position="bottom" closable>
<view style="height: 200px; text-align: center; line-height: 200px;">
Content
</view>
</wd-popup>
```
## Close Button Position
Set the `close-position` attribute to customize the position of the close button, which can be 'top-left', 'top-right', 'bottom-left', 'bottom-right', default is 'top-right'.
```html
<wd-popup :visible.sync="show" position="bottom" closable close-position="top-left">
<view style="height: 200px; text-align: center; line-height: 200px;">
Content
</view>
</wd-popup>
```
## Custom Close Icon
Set the `close-icon` attribute to customize the close icon.
```html
<wd-popup :visible.sync="show" position="bottom" closable close-icon="check">
<view style="height: 200px; text-align: center; line-height: 200px;">
Content
</view>
</wd-popup>
```
## Rounded Corners
Set the `border-radius` attribute to customize the border radius of the popup. This attribute is only valid when the position is 'top', 'right', 'bottom', 'left'.
```html
<wd-popup :visible.sync="show" position="bottom" border-radius="16px">
<view style="height: 200px; text-align: center; line-height: 200px;">
Content
</view>
</wd-popup>
<wd-popup v-model="show" position="bottom" closable custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
## Disable Mask Click
Set the `close-on-click-modal` attribute to `false` to disable closing the popup when clicking the mask.
By setting the `close-on-click-modal` attribute to `false`, you can disable the function of closing the popup layer when the user clicks the mask layer.
```html
<wd-popup :visible.sync="show" position="bottom" :close-on-click-modal="false">
<view style="height: 200px; text-align: center; line-height: 200px;">
Content
</view>
</wd-popup>
<wd-popup v-model="show" position="bottom" :close-on-click-modal="false" closable custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
## Disable Mask
By setting the `modal` attribute to `false`, you can disable the mask layer, allowing users to interact with the underlying content.
```html
<wd-popup v-model="show" position="bottom" :modal="false" closable custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
## Enable Bottom Safe Area
By setting the `safe-area-inset-bottom` attribute to `true`, you can ensure that the popup layer is not blocked by the bottom safe area when displayed at the bottom.
```html
<wd-popup v-model="show" position="bottom" :safe-area-inset-bottom="true" custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
## root-portal
When the `root-portal` attribute is set to `true`, the popup will be teleported to the page root node, which can avoid the influence of parent component's transform, filter and other CSS properties on the fixed positioning of the popup.
When the `root-portal` attribute is set to `true`, the popup will be detached from the page, which can avoid the influence of parent component's transform, filter and other CSS properties on the fixed positioning of the popup.
Different platforms use different implementation schemes:
- **H5**: Use Vue 3's teleport feature
- **APP**: Use renderjs to move elements to the uni-app root node
- **WeChat Mini Program/Alipay Mini Program**: Use root-portal component
- **Other platforms**: root-portal feature is not supported
- **Other platforms**: This feature is not supported
```html
<wd-popup v-model="show" root-portal position="center" custom-style="height: 200px;" @close="handleClose">
@ -94,45 +86,60 @@ Different platforms use different implementation schemes:
This feature is mainly used to solve layering and positioning issues of popups in complex layouts, and it is recommended to enable it only when needed.
:::
## Prevent Scroll Penetration
When using the component, you will find that when the content part scrolls to the bottom, continuing to swipe will cause the underlying page to scroll, which is scroll penetration.
Currently, the component can handle some scroll penetration issues through the `lock-scroll` attribute. However, due to the reasons of the mini-program and APP platforms themselves, scroll penetration will still occur in the popup content area. However, we provide developers with a recommended solution to completely solve scroll penetration:
You can use the [page-meta](https://uniapp.dcloud.net.cn/component/page-meta#page-meta) component to dynamically modify the `overflow` attribute of `page-meta`.
```html
<!-- page-meta can only be the first node in the page -->
<page-meta :page-style="`overflow:${show ? 'hidden' : 'visible'};`"></page-meta>
<wd-popup v-model="show" lock-scroll position="bottom" :safe-area-inset-bottom="true" custom-style="height: 200px;" @close="handleClose"></wd-popup>
```
:::tip Tip
H5 scroll penetration does not need to be handled, the component has enabled `lock-scroll` by default.
:::
## Attributes
| Attribute | Description | Type | Default | Version |
|---------|---------|---------|---------|------|
| visible | Whether to display the popup, supports the .sync modifier | boolean | false | - |
| position | Popup position | string | center | - |
| closable | Whether to display the close button | boolean | false | - |
| close-position | Close button position | string | top-right | - |
| close-icon | Close button icon | string | close | - |
| modal | Whether to display the mask | boolean | true | - |
| modal-style | Custom mask style | object | - | - |
| modal-class | Custom mask class | string | - | - |
| z-index | z-index | number | 10 | - |
| lazy-render | Whether to lazily render the popup | boolean | true | - |
| close-on-click-modal | Whether to close the popup when clicking the mask | boolean | true | - |
| duration | Animation duration | number | 300(ms) | - |
| custom-style | Custom popup style | object | - | - |
| border-radius | Border radius of the popup | string | 0 | - |
| safe-area-inset-bottom | Whether to enable bottom safe area adaptation | boolean | false | - |
| root-portal | Whether to break away from the page to solve various fixed failure issues | boolean | false | 1.11.0 |
|Attribute|Description|Type|Optional Values|Default|Version|
|---|---|---|---|---|---|
|v-model|Whether to show popup|boolean|-|-|-|
|position|Popup position|string|center/top/right/bottom/left|center|-|
|closable|Whether to show close button|boolean|-|false|-|
|close-on-click-modal|Whether to close when clicking mask|boolean|-|true|-|
|duration|Animation duration|number/boolean|-|300(ms)|-|
|z-index|Popup z-index|number|-|10|-|
|custom-style|Custom popup style|string|-|-|-|
|modal|Whether to show mask|boolean|-|true|-|
|modal-style|Custom mask style|string|-|-|-|
|hide-when-close|Whether to hide when closed|boolean|-|true|-|
|lazy-render|Whether to enable lazy rendering|boolean|-|true|-|
|safe-area-inset-bottom|Whether to enable bottom safe area|boolean|-|false|-|
|transition|Transition type|string|fade/fade-up/fade-down/fade-left/fade-right/slide-up/slide-down/slide-left/slide-right/zoom-in|-|-|
|lock-scroll|Whether to lock background scroll|boolean|-|true|0.1.30|
|root-portal|Whether to mount to root node|boolean|-|false|1.11.0|
## Events
| Event Name | Description | Parameters | Version |
|---------|---------|---------|------|
| open | Triggered when the popup is opened | - | - |
| opened | Triggered when the popup opening animation ends | - | - |
| close | Triggered when the popup is closed | - | - |
| closed | Triggered when the popup closing animation ends | - | - |
| click-modal | Triggered when the mask is clicked | - | - |
## Slots
| Name | Description | Version |
|---------|---------|------|
| default | Content of the popup | - |
|Event|Description|Parameters|Version|
|---|---|---|---|
|close|Triggered when popup is closed|-|-|
|click-modal|Triggered when mask is clicked|-|-|
|before-enter|Triggered before enter transition starts|-|-|
|enter|Triggered when enter transition starts|-|-|
|after-enter|Triggered when enter transition ends|-|-|
|before-leave|Triggered before leave transition starts|-|-|
|leave|Triggered when leave transition starts|-|-|
|after-leave|Triggered when leave transition ends|-|-|
## External Style Classes
| Class Name | Description | Version |
|---------|---------|------|
| custom-class | Root node custom class | - |
|Class Name|Description|Version|
|---|---|---|
|custom-class|Root node style|-|