Skip to content

Commit

Permalink
docs: fix docs problems (#43622)
Browse files Browse the repository at this point in the history
* docs: fix bug

* docs: fix link

* docs: fix video

* chore: en
  • Loading branch information
zombieJ committed Jul 18, 2023
1 parent 1c14a68 commit cf40fb0
Show file tree
Hide file tree
Showing 16 changed files with 288 additions and 41 deletions.
2 changes: 2 additions & 0 deletions .dumi/rehypeAntd.ts
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,8 @@ function rehypeAntd(): UnifiedTransformer<HastRoot> {
const { tagName } = node;
node.properties.sourceType = tagName;
node.tagName = 'LocaleLink';
} else if (node.type === 'element' && node.tagName === 'video') {
node.tagName = 'VideoPlayer';
}
});
};
Expand Down
22 changes: 18 additions & 4 deletions .dumi/theme/builtins/ImagePreview/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -26,9 +29,8 @@ function isGoodBadImg(imgMeta: any): boolean {
function isCompareImg(imgMeta: any): boolean {
return isGoodBadImg(imgMeta) || imgMeta.inline;
}

const ImagePreview: React.FC<ImagePreviewProps> = (props) => {
const { children } = props;
const { children, className: rootClassName, pure } = props;
const imgs = toArray(children).filter((ele) => ele.type === 'img');

const imgsMeta = imgs.map((img) => {
Expand Down Expand Up @@ -67,21 +69,33 @@ const ImagePreview: React.FC<ImagePreviewProps> = (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 (
<div className={previewClassName}>
{!imgs.length && (
<div
className={imgWrapperCls}
style={pure ? { background: 'transparent', padding: 0 } : {}}
>
{children}
</div>
)}

{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,
});
Expand Down
119 changes: 119 additions & 0 deletions .dumi/theme/builtins/TokenCompare/index.tsx
Original file line number Diff line number Diff line change
@@ -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 (
<Space size={4}>
<div className={styles.dot} style={{ background: color }} />
<div className={styles.dotColor}>{color}</div>
</Space>
);
}

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 (
<div className={styles.container}>
{tokenList.map((data) => (
<div key={data.name} className={styles.row}>
<div className={styles.col}>{data.name}</div>
<div className={styles.col}>
<ColorCircle color={data.light} />
</div>
<div className={classNames(styles.col, styles.colDark)}>
<ColorCircle color={data.dark} />
</div>
</div>
))}
</div>
);
}
77 changes: 77 additions & 0 deletions .dumi/theme/builtins/VideoPlayer/index.tsx
Original file line number Diff line number Diff line change
@@ -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<HTMLVideoElement>) {
const { styles } = useStyles();
const videoRef = React.useRef<HTMLVideoElement>(null);
const [playing, setPlaying] = React.useState(false);

React.useEffect(() => {
if (playing) {
videoRef.current?.play();
} else {
videoRef.current?.pause();
}
}, [playing]);

return (
<div
className={classNames(styles.container, className)}
tabIndex={0}
role="button"
title="play or pause"
onClick={() => {
setPlaying(!playing);
}}
>
<div className={classNames(styles.holder)}>
<video ref={videoRef} className={styles.video} muted loop {...restProps} />

<div className={styles.play}>{playing ? <PauseCircleFilled /> : <PlayCircleFilled />}</div>
</div>
</div>
);
}
8 changes: 4 additions & 4 deletions components/theme/interface/alias.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*/
Expand All @@ -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.
*/
Expand Down
3 changes: 3 additions & 0 deletions components/theme/interface/maps/colors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,15 @@ 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.
*/
colorText: string;

/**
* @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.
*/
Expand Down Expand Up @@ -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.
*/
Expand Down
2 changes: 1 addition & 1 deletion docs/spec/colors.en-US.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ Functional color represents a clear message as well as status, such as success,
### Neutral Color

<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/zos/antfincdn/8yMmB1lcD%24/colors.jpg">
<TokenCompare tokenNames="colorTextHeading|colorText|colorTextSecondary|colorTextDisabled|colorBorder|colorSplit|colorBgLayout"></TokenCompare>
</ImagePreview>

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:
Expand Down
2 changes: 1 addition & 1 deletion docs/spec/colors.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Ant Design 的色板还具备进一步拓展的能力。经过设计师和程序
### 中性色

<ImagePreview>
<img class="preview-img no-padding" src="https://gw.alipayobjects.com/zos/antfincdn/8yMmB1lcD%24/colors.jpg">
<TokenCompare tokenNames="colorTextHeading|colorText|colorTextSecondary|colorTextDisabled|colorBorder|colorSplit|colorBgLayout"></TokenCompare>
</ImagePreview>

Ant Design 的中性色主要被大量的应用在界面的文字部分,此外背景、边框、分割线等场景中也非常常见。产品中性色的定义需要考虑深色背景以及浅色背景的差异,同时结合 WCAG 2.0 标准。Ant Design 的中性色在落地的时候是按照透明度的方式实现的,具体色板如右图:
Expand Down
8 changes: 6 additions & 2 deletions docs/spec/copywriting.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,8 @@ title: 文案
<img class="preview-img no-padding bad" src="https://gw.alipayobjects.com/zos/rmsportal/HBCyJcXZYmtLECZUtjzE.png" alt="错误示范" description="时间信息的描述词不是具体的「日」、「月」,容易让用户产生困扰。">
</ImagePreview>

<table style="font-size:12px;float:right;width:496px;margin-left:60px;margin-bottom:100px;clear:both;">
<ImagePreview className="markdown" pure="true">
<table style="font-size:12px;">
<tr>
<th style="border-bottom: 2px solid #108ee9;width:20%;">使用</th>
<th style="border-bottom: 2px solid #f04134;width:25%;">不使用</th>
Expand Down Expand Up @@ -157,6 +158,7 @@ title: 文案
<td>当要表达当前事物时,「此」更加明确。</td>
</tr>
</table>
</ImagePreview>

通用基本用词要规范,不要写错字,词语表达要完整。

Expand Down Expand Up @@ -286,7 +288,8 @@ title: 文案
### 基本标点规范

<table style="font-size:12px;float:right;width:496px;margin-left:60px;margin-bottom:100px;">
<ImagePreview className="markdown" pure="true">
<table style="font-size:12px;">
<tr>
<th>标点名称</th>
<th>字符</th>
Expand Down Expand Up @@ -324,6 +327,7 @@ title: 文案
<td>多用于替换显示隐私信息。</td>
</tr>
</table>
</ImagePreview>

正确地使用标点符号会让句子看起来更清晰和具有可读性。

Expand Down
Loading

0 comments on commit cf40fb0

Please sign in to comment.