From cf40fb02b9d0862f2824efc320d160e7ea4b3427 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=BA=8C=E8=B4=A7=E7=88=B1=E5=90=83=E7=99=BD=E8=90=9D?= =?UTF-8?q?=E5=8D=9C?= Date: Tue, 18 Jul 2023 18:22:47 +0800 Subject: [PATCH] docs: fix docs problems (#43622) * docs: fix bug * docs: fix link * docs: fix video * chore: en --- .dumi/rehypeAntd.ts | 2 + .dumi/theme/builtins/ImagePreview/index.tsx | 22 +++- .dumi/theme/builtins/TokenCompare/index.tsx | 119 ++++++++++++++++++++ .dumi/theme/builtins/VideoPlayer/index.tsx | 77 +++++++++++++ components/theme/interface/alias.ts | 8 +- components/theme/interface/maps/colors.ts | 3 + docs/spec/colors.en-US.md | 2 +- docs/spec/colors.zh-CN.md | 2 +- docs/spec/copywriting.zh-CN.md | 8 +- docs/spec/data-display.en-US.md | 12 +- docs/spec/data-display.zh-CN.md | 24 +++- docs/spec/font.en-US.md | 8 +- docs/spec/font.zh-CN.md | 2 +- docs/spec/proximity.en-US.md | 16 ++- docs/spec/proximity.zh-CN.md | 16 ++- docs/spec/visual.zh-CN.md | 8 +- 16 files changed, 288 insertions(+), 41 deletions(-) create mode 100644 .dumi/theme/builtins/TokenCompare/index.tsx create mode 100644 .dumi/theme/builtins/VideoPlayer/index.tsx diff --git a/.dumi/rehypeAntd.ts b/.dumi/rehypeAntd.ts index 9db6f65717..fa4733585f 100644 --- a/.dumi/rehypeAntd.ts +++ b/.dumi/rehypeAntd.ts @@ -64,6 +64,8 @@ function rehypeAntd(): UnifiedTransformer { const { tagName } = node; node.properties.sourceType = tagName; node.tagName = 'LocaleLink'; + } else if (node.type === 'element' && node.tagName === 'video') { + node.tagName = 'VideoPlayer'; } }); }; diff --git a/.dumi/theme/builtins/ImagePreview/index.tsx b/.dumi/theme/builtins/ImagePreview/index.tsx index 7ea701a689..7143082cce 100644 --- a/.dumi/theme/builtins/ImagePreview/index.tsx +++ b/.dumi/theme/builtins/ImagePreview/index.tsx @@ -5,6 +5,9 @@ import toArray from 'rc-util/lib/Children/toArray'; interface ImagePreviewProps { children: React.ReactNode[]; + className?: string; + /** Do not show padding & background */ + pure?: boolean; } function isGood(className: string): boolean { @@ -26,9 +29,8 @@ function isGoodBadImg(imgMeta: any): boolean { function isCompareImg(imgMeta: any): boolean { return isGoodBadImg(imgMeta) || imgMeta.inline; } - const ImagePreview: React.FC = (props) => { - const { children } = props; + const { children, className: rootClassName, pure } = props; const imgs = toArray(children).filter((ele) => ele.type === 'img'); const imgsMeta = imgs.map((img) => { @@ -67,21 +69,33 @@ const ImagePreview: React.FC = (props) => { : {}; const hasCarousel = imgs.length > 1 && !comparable; - const previewClassName = classNames({ + const previewClassName = classNames(rootClassName, { 'preview-image-boxes': true, clearfix: true, 'preview-image-boxes-compare': comparable, 'preview-image-boxes-with-carousel': hasCarousel, }); + // ===================== Render ===================== + const imgWrapperCls = 'preview-image-wrapper'; + return (
+ {!imgs.length && ( +
+ {children} +
+ )} + {imagesList.map((_, index) => { if (!comparable && index !== 0) { return null; } const coverMeta = imgsMeta[index]; - const imageWrapperClassName = classNames('preview-image-wrapper', { + const imageWrapperClassName = classNames(imgWrapperCls, { good: coverMeta.isGood, bad: coverMeta.isBad, }); diff --git a/.dumi/theme/builtins/TokenCompare/index.tsx b/.dumi/theme/builtins/TokenCompare/index.tsx new file mode 100644 index 0000000000..7650855e1c --- /dev/null +++ b/.dumi/theme/builtins/TokenCompare/index.tsx @@ -0,0 +1,119 @@ +// 用于 color.md 中的颜色对比 +import React from 'react'; +import classNames from 'classnames'; +import { theme, Space } from 'antd'; +import { TinyColor } from '@ctrl/tinycolor'; +import tokenMeta from 'antd/es/version/token-meta.json'; +import { createStyles } from 'antd-style'; +import useLocale from '../../../hooks/useLocale'; + +const useStyle = createStyles(({ token, css }) => { + const height = token.controlHeightLG; + const dotSize = height / 5; + + return { + container: css` + background: #fff; + border-radius: ${token.borderRadiusLG}px; + overflow: hidden; + `, + + row: css` + display: flex; + align-items: center; + `, + + col: css` + flex: 1 1 33%; + height: ${height}px; + display: flex; + align-items: center; + justify-content: center; + + border-right: 1px solid rgba(0, 0, 0, 0.1); + `, + + colDark: css` + background: #000; + color: #fff; + `, + + dot: css` + border-radius: 100%; + width: ${dotSize}px; + height: ${dotSize}px; + background: #000; + box-shadow: 0 0 0 1px rgba(150, 150, 150, 0.25); + `, + + dotColor: css` + width: ${token.fontSize * 6}px; + white-space: nowrap; + `, + }; +}); + +function color2Rgba(color: string) { + return `#${new TinyColor(color).toHex8().toUpperCase()}`; +} + +interface ColorCircleProps { + color?: string; +} + +function ColorCircle({ color }: ColorCircleProps) { + const { styles } = useStyle(); + + return ( + +
+
{color}
+ + ); +} + +export interface TokenCompareProps { + tokenNames?: string; +} + +export default function TokenCompare(props: TokenCompareProps) { + const { tokenNames = '' } = props; + const [, lang] = useLocale({}); + const { styles } = useStyle(); + + const tokenList = React.useMemo(() => { + const list = tokenNames.split('|'); + + const lightTokens = theme.getDesignToken(); + const darkTokens = theme.getDesignToken({ + algorithm: theme.darkAlgorithm, + }); + + return list.map((tokenName) => { + const meta = tokenMeta.global[tokenName]; + const name = lang === 'cn' ? meta.name : meta.nameEn; + + return { + name: name.replace('颜色', '').replace('色', '').replace('Color', '').trim(), + light: color2Rgba(lightTokens[tokenName]), + dark: color2Rgba(darkTokens[tokenName]), + }; + }); + }, [tokenNames]); + + return ( +
+ {tokenList.map((data) => ( +
+
{data.name}
+
+ +
+
+ +
+
+ ))} +
+ ); +} diff --git a/.dumi/theme/builtins/VideoPlayer/index.tsx b/.dumi/theme/builtins/VideoPlayer/index.tsx new file mode 100644 index 0000000000..02ef594246 --- /dev/null +++ b/.dumi/theme/builtins/VideoPlayer/index.tsx @@ -0,0 +1,77 @@ +import React from 'react'; +import { createStyles, css } from 'antd-style'; +import classNames from 'classnames'; +import { PlayCircleFilled, PauseCircleFilled } from '@ant-design/icons'; + +const useStyles = createStyles(({ cx, token }) => { + const play = css` + position: absolute; + right: ${token.paddingLG}px; + bottom: ${token.paddingLG}px; + font-size: 64px; + display: flex; + align-items: center; + justify-content: center; + color: rgba(0, 0, 0, 0.65); + opacity: 0; + transition: opacity ${token.motionDurationSlow}; + `; + + return { + container: css` + position: relative; + `, + + holder: css` + position: relative; + cursor: pointer; + + &:hover { + .${cx(play)} { + opacity: 1; + } + } + `, + + video: css` + width: 100%; + `, + + play, + }; +}); + +export default function VideoPlayer({ + className, + ...restProps +}: React.HtmlHTMLAttributes) { + const { styles } = useStyles(); + const videoRef = React.useRef(null); + const [playing, setPlaying] = React.useState(false); + + React.useEffect(() => { + if (playing) { + videoRef.current?.play(); + } else { + videoRef.current?.pause(); + } + }, [playing]); + + return ( +
{ + setPlaying(!playing); + }} + > +
+
+
+ ); +} diff --git a/components/theme/interface/alias.ts b/components/theme/interface/alias.ts index a27da4c854..a08f61d008 100644 --- a/components/theme/interface/alias.ts +++ b/components/theme/interface/alias.ts @@ -61,7 +61,7 @@ export interface AliasToken extends MapToken { colorBorderBg: string; /** * @nameZH 分割线颜色 - * @nameEN Separator color + * @nameEN Separator Color * @desc 用于作为分割线的颜色，此颜色和 colorBorderSecondary 的颜色一致，但是用的是透明色。 * @descEN Used as the color of separator, this color is the same as colorBorderSecondary but with transparency. */ @@ -70,21 +70,21 @@ export interface AliasToken extends MapToken { // Text /** * @nameZH 占位文本颜色 - * @nameEN Placeholder text color + * @nameEN Placeholder Text Color * @desc 控制占位文本的颜色。 * @descEN Control the color of placeholder text. */ colorTextPlaceholder: string; /** * @nameZH 禁用字体颜色 - * @nameEN Disabled text color + * @nameEN Disabled Text Color * @desc 控制禁用状态下的字体颜色。 * @descEN Control the color of text in disabled state. */ colorTextDisabled: string; /** * @nameZH 标题字体颜色 - * @nameEN Heading font color + * @nameEN Heading Text Color * @desc 控制标题字体颜色。 * @descEN Control the font color of heading. */ diff --git a/components/theme/interface/maps/colors.ts b/components/theme/interface/maps/colors.ts index ee98286097..2078a32c70 100644 --- a/components/theme/interface/maps/colors.ts +++ b/components/theme/interface/maps/colors.ts @@ -13,6 +13,7 @@ export interface ColorNeutralMapToken { /** * @nameZH 一级文本色 + * @nameEN Text Color * @desc 最深的文本色。为了符合W3C标准，默认的文本颜色使用了该色，同时这个颜色也是最深的中性色。 * @descEN Default text color which comply with W3C standards, and this color is also the darkest neutral color. */ @@ -20,6 +21,7 @@ export interface ColorNeutralMapToken { /** * @nameZH 二级文本色 + * @nameEN Secondary Text Color * @desc 作为第二梯度的文本色，一般用在不那么需要强化文本颜色的场景，例如 Label 文本、Menu 的文本选中态等场景。 * @descEN The second level of text color is generally used in scenarios where text color is not emphasized, such as label text, menu text selection state, etc. */ @@ -91,6 +93,7 @@ export interface ColorNeutralMapToken { /** * @nameZH 布局背景色 + * @nameEN Layout Background Color * @desc 该色用于页面整体布局的背景色，只有需要在页面中处于 B1 的视觉层级时才会使用该 token，其他用法都是错误的 * @descEN This color is used for the background color of the overall layout of the page. This token will only be used when it is necessary to be at the B1 visual level in the page. Other usages are wrong. */ diff --git a/docs/spec/colors.en-US.md b/docs/spec/colors.en-US.md index 40d0e3e5ec..a2991093d5 100644 --- a/docs/spec/colors.en-US.md +++ b/docs/spec/colors.en-US.md @@ -83,7 +83,7 @@ Functional color represents a clear message as well as status, such as success, ### Neutral Color - + Neutral color is mainly used in a large part of the text interface, in addition to the background, borders, dividing lines, and other scenes are also very common. Neutral color definition needs to consider the difference between dark background and light background, while incorporating the WCAG 2.0 standard. The neutral color of Ant Design is based on transparency, as shown on the right: diff --git a/docs/spec/colors.zh-CN.md b/docs/spec/colors.zh-CN.md index bdaf262232..f69dc1e428 100644 --- a/docs/spec/colors.zh-CN.md +++ b/docs/spec/colors.zh-CN.md @@ -91,7 +91,7 @@ Ant Design 的色板还具备进一步拓展的能力。经过设计师和程序 ### 中性色 - + Ant Design 的中性色主要被大量的应用在界面的文字部分，此外背景、边框、分割线等场景中也非常常见。产品中性色的定义需要考虑深色背景以及浅色背景的差异，同时结合 WCAG 2.0 标准。Ant Design 的中性色在落地的时候是按照透明度的方式实现的，具体色板如右图： diff --git a/docs/spec/copywriting.zh-CN.md b/docs/spec/copywriting.zh-CN.md index 9764f82d2b..5348564948 100644 --- a/docs/spec/copywriting.zh-CN.md +++ b/docs/spec/copywriting.zh-CN.md @@ -120,7 +120,8 @@ title: 文案 错误示范 - + +
@@ -157,6 +158,7 @@ title: 文案
使用 不使用当要表达当前事物时，「此」更加明确。
+ 通用基本用词要规范，不要写错字，词语表达要完整。 @@ -286,7 +288,8 @@ title: 文案 ### 基本标点规范 - + +
@@ -324,6 +327,7 @@ title: 文案
标点名称 字符多用于替换显示隐私信息。
+ 正确地使用标点符号会让句子看起来更清晰和具有可读性。 diff --git a/docs/spec/data-display.en-US.md b/docs/spec/data-display.en-US.md index 7e060d1199..e7ca3b41a0 100644 --- a/docs/spec/data-display.en-US.md +++ b/docs/spec/data-display.en-US.md @@ -15,7 +15,7 @@ The suitable way to display data helps users quickly locate and browse data, and ## Table - + The table is recognized as one of the clearest and most efficient forms of presentation data. It is often used in conjunction with other interface elements such as sorting, searching, filtering, and paging, and is suitable for information collection and display, data analysis and induction, and manipulation of structured data. It's structure is simple, it's separation and induction are clear, the information is easier to compare, and the user's receiving efficiency and understanding of the information is greatly improved. @@ -28,7 +28,7 @@ The table is recognized as one of the clearest and most efficient forms of prese ## Collapse - + Collapse guides the user to obtain information in a progressive manner by folding and arranging information, so that the interface is kept clean and the space is effectively utilized. @@ -42,7 +42,7 @@ These components are used extensively in navigation and are also suitable for le ## Card - + A card is a container for carrying information. There is not too much limit to the types of content that can be carried. It makes a type of information centralized, enhances the sense of block and is easier to operate. Cards are usually arranged in a grid or matrix to convey the hierarchical relationship between each other. Cards are suitable for lighter and more personalized information block display. @@ -57,7 +57,7 @@ A card is a container for carrying information. There is not too much limit to t ## Carousel - + As a set of same hierarchy content parallel display mode, often used for picture or card carousel, can be triggered by the user or the system automatically rotates. It is suitable for display blocks such as the official website home page and product introduction page. @@ -72,7 +72,7 @@ As a set of same hierarchy content parallel display mode, often used for picture ## Tree - + "Tree" displays the hierarchical relationship of information in the form of a step-by-step outline, which is efficient and has excellent visual visibility, making the overall information framework clear at a glance. @@ -84,7 +84,7 @@ Users can view and process multiple tree-level content at the same time. Tree is ## Timeline - + Timeline is used to display time-flow information vertically, generally recording events in time by flashback, tracking what the user is doing now and what he has done in the past. diff --git a/docs/spec/data-display.zh-CN.md b/docs/spec/data-display.zh-CN.md index e25bb5d6c8..070ede9b12 100644 --- a/docs/spec/data-display.zh-CN.md +++ b/docs/spec/data-display.zh-CN.md @@ -14,7 +14,9 @@ title: 数据展示 ## 表格（Table） - + + + 表格被公认为是展现数据最为清晰、高效的形式之一。它常和排序、搜索、筛选、分页等其他界面元素一起协同，适用于信息的收集和展示、数据的分析和归纳整理、以及操作结构化数据。它结构简单，分隔归纳明确，使信息之间更易于对比，大大提升了用户对信息的接收效率和理解程度。 @@ -25,7 +27,9 @@ title: 数据展示 ## 折叠面板（Collapse） - + + + 折叠面板通过对信息的分组和收纳，指引用户递进式的获取信息，使界面保持整洁的同时增加空间的有效利用率。 @@ -37,7 +41,9 @@ title: 数据展示 ## 卡片（Card） - + + + 卡片是一种承载信息的容器，对可承载的内容类型无过多限制，它让一类信息集中化，增强区块感的同时更易于操作；卡片通常以网格或矩阵的方式排列，传达相互之间的层级关系。适合较为轻量级和个性化较强的信息区块展示。 @@ -50,7 +56,9 @@ title: 数据展示 ## 走马灯（Carousel） - + + + 作为一组平级内容的并列展示模式，常用于图片或卡片轮播，可由用户主动触发或者系统自动轮播。适合用于官网首页、产品介绍页等展示型区块。 @@ -63,7 +71,9 @@ title: 数据展示 ## 树形控件（Tree） - + + + 『树形控件』通过逐级大纲的形式来展现信息的层级关系，高效且具有极佳的视觉可视性，使得整体信息框架一目了然。 @@ -73,7 +83,9 @@ title: 数据展示 ## 时间轴（Timeline） - + + + 垂直展示的时间流信息，一般按照时间倒叙记录事件，追踪用户当下以及过去做了什么。 diff --git a/docs/spec/font.en-US.md b/docs/spec/font.en-US.md index d58eacd397..1ec0dc11ac 100644 --- a/docs/spec/font.en-US.md +++ b/docs/spec/font.en-US.md @@ -80,11 +80,11 @@ The choice of font weight is also based on the principles of order, stability, a ## Font Color -Text will be difficult to read if it is too close to the background color. To achieve barrier-free design, we follow the WCAG standard, which maintains an AAA level of contrast ratio, i.e. 7:1 or more between body text, title, and background color. + + + -
- -
+Text will be difficult to read if it is too close to the background color. To achieve barrier-free design, we follow the WCAG standard, which maintains an AAA level of contrast ratio, i.e. 7:1 or more between body text, title, and background color. ## Advanced Tips diff --git a/docs/spec/font.zh-CN.md b/docs/spec/font.zh-CN.md index 65e213b16c..019b5666b4 100644 --- a/docs/spec/font.zh-CN.md +++ b/docs/spec/font.zh-CN.md @@ -79,7 +79,7 @@ Ant Design 受到 5 音阶以及自然律的启发定义了 10 个不同尺寸 ## 字体颜色 -字体颜色 + 文本颜色如果和背景颜色太接近就会难以阅读。考虑到无障碍设计的需求，我们参考了 WCAG 的标准，将正文文本、标题和背景色之间保持在了 7:1 以上的 AAA 级对比度。 diff --git a/docs/spec/proximity.en-US.md b/docs/spec/proximity.en-US.md index e8d1bcea4b..71a06e7362 100644 --- a/docs/spec/proximity.en-US.md +++ b/docs/spec/proximity.en-US.md @@ -11,13 +11,17 @@ When several items are in close proximity to each other, they become one visual ## The relation of vertical spacing -Example of the different vertical distance + + Example of the different vertical distance + Divide the hierarchy of information through three formats:「small spacing」, 「middle spacing」and「large spacing」
-Example of added element + + Example of added element + In the case that the three formats are applicable, the hierarchy of information can be separated clearly through adding or cutting down the multiple of 「basic spacing」, or adding elements. @@ -27,12 +31,16 @@ In the case that the three formats are applicable, the hierarchy of information ## Relationship of horizontal spacing -Example of combination and configuration + + Example of combination and configuration + To adapt to screens of different sizes, in the horizontal direction, use grid layout to arrange the components to ensure the flexibility of the layout.
-Example of checkbox + + Example of checkbox + In the inner of a component, the horizontal spacing of elements should differ too. diff --git a/docs/spec/proximity.zh-CN.md b/docs/spec/proximity.zh-CN.md index 532f10b3a0..8628fccd0e 100644 --- a/docs/spec/proximity.zh-CN.md +++ b/docs/spec/proximity.zh-CN.md @@ -11,13 +11,17 @@ title: 亲密性 ## 纵向间距关系 -纵向间距示例 + + 纵向间距示例 + 通过「小号间距」、「中号间距」、「大号间距」这三种规格来划分信息层次结构。
-增加元素示例 + + 增加元素示例 + 在这三种规格不适用的情况下，可以通过加减「基础间距」的倍数，或者增加元素来拉开信息层次。 @@ -27,12 +31,16 @@ title: 亲密性 ## 横向间距关系 -组合排布示例 + + 组合排布示例 + 为了适用不同尺寸的屏幕，在横向采用栅格布局来排布组件，从而保证布局的灵活性。
-复选框内示例 + + 复选框内示例 + 在一个组件内部，元素的横向间距也应该有所不同。 diff --git a/docs/spec/visual.zh-CN.md b/docs/spec/visual.zh-CN.md index f89b69fa09..c2c3836b6d 100644 --- a/docs/spec/visual.zh-CN.md +++ b/docs/spec/visual.zh-CN.md @@ -87,7 +87,7 @@ title: 可视化 AntV 提供了一套默认的图表颜色，包括颜色的用法， -获取更多色板，请前往 [AntV - 设计语言 - 视觉](https://antv.vision/zh/docs/specification/principles/visual/) +获取更多色板，请前往 [AntV - 设计语言 - 视觉](https://antv.vision/specification/language/palette) ### 组件使用建议 @@ -161,9 +161,9 @@ AntV 提供了一套默认的图表颜色，包括颜色的用法， ### 交互 -
- Background -
+ + 动态交互 + 区别于传统数据报表相对静态的表现形式，交互式图表并不停留在信息展示层面。用户通过与图不断产生交互，从数据中获取更深层次的分析和信息。