Merge pull request #99 from ant-design/feat/update

📝 docs: update snippet doc

src/Highlight/components/LanguageTag/index.tsx

@@ -0,0 +1,71 @@
+import { ThemeType } from '@/Highlight/theme/type';
+import { Tag, type TagProps as AntTagProps } from 'antd';
+import Color from 'color';
+import { ReactNode } from 'react';
+import { createStyles } from '../../../theme';
+import { getThemeColor } from '../../theme/colors';
+
+const useStyles = createStyles(({ cx, css, token }, { prefixCls, theme }) => {
+  const prefix = `${prefixCls}`;
+
+  const { colorFillTertiary, colorText, colorTextSecondary } = getThemeColor(theme === 'dark');
+
+  const background = Color(colorFillTertiary)
+    .mix(Color(theme === 'dark' ? 'white' : 'black'), 0.03)
+    .alpha(0.9)
+    .hsl()
+    .string();
+
+  return {
+    small: cx(
+      `${prefix}-tag-small`,
+      css`
+        padding: 2px 6px;
+        line-height: 1;
+      `,
+    ),
+    lang: cx(
+      css`
+        position: absolute;
+        z-index: 2;
+        right: 0;
+        bottom: 8px;
+        background-color: ${background};
+        font-family: ${token.fontFamilyCode};
+        color: ${colorTextSecondary};
+        transition: opacity 0.1s;
+      `,
+    ),
+    tag: cx(
+      `${prefix}-tag`,
+      css`
+        color: ${colorText} !important;
+        border-radius: ${token.borderRadius}px;
+        P &:hover {
+          color: ${colorText};
+          background: ${token.colorFill};
+        }
+      `,
+    ),
+  };
+});
+
+export interface TagProps extends AntTagProps {
+  icon?: ReactNode;
+  size?: 'default' | 'small';
+  theme?: ThemeType;
+  prefixCls?: string;
+}
+
+const LanguageTag: React.FC<TagProps> = (props) => {
+  const { children, size = 'default', theme = 'light', prefixCls } = props || {};
+  const { styles, cx } = useStyles({ theme, prefixCls });
+
+  return (
+    <Tag bordered={false} className={cx(styles.tag, styles.lang, size === 'small' && styles.small)}>
+      {children}
+    </Tag>
+  );
+};
+
+export default LanguageTag;

src/Highlight/defalut.tsx

@@ -3,6 +3,7 @@ import { createRef } from 'react';
 import { getPrefixCls } from '../theme';
 import CopyButton from './components/CopyButton';
 import HighLighter from './components/HighLighter';
+import LanguageTag from './components/LanguageTag';
 import { useKeyDownCopyEvent } from './hooks/useKeyDownCopyEvent';
 import { useStyles } from './style';
 import { THEME_LIGHT, ThemeType } from './theme';
@@ -65,6 +66,10 @@ export interface HighlightProps {
    * 是否需要默认外层 wrapper
    */
   containerWrapper?: boolean;
+  /**
+   * 是否需默认展示语言种类
+   */
+  showLanguage?: boolean;
 }
 
 const HighlightBase: React.FC<HighlightProps> = (props) => {
@@ -75,8 +80,9 @@ const HighlightBase: React.FC<HighlightProps> = (props) => {
     lineNumber = false,
     copyable = true,
     theme = THEME_LIGHT,
-    language,
+    language = 'tsx',
     prefixCls: customPrefixCls,
+    showLanguage = true,
     type = 'block',
     onCopy,
   } = props;
@@ -96,6 +102,11 @@ const HighlightBase: React.FC<HighlightProps> = (props) => {
         {copyable && (
           <CopyButton prefixCls={prefixCls} onCopy={onCopy} theme={theme} content={children} />
         )}
+        {showLanguage && language && (
+          <LanguageTag prefixCls={prefixCls} theme={theme}>
+            {language.toLowerCase()}
+          </LanguageTag>
+        )}
         <HighLighter
           lineNumber={lineNumber}
           language={language}

src/Highlight/index.md

@@ -40,14 +40,15 @@ group: 基础组件
 
 ### Highlight
 
-| 参数       | 说明                                                      | 类型    | 默认值  |
-| :--------- | :-------------------------------------------------------- | :------ | :------ |
-| language   | 指定语言类型，详见下表                                    | string  | -       |
-| theme      | 指定主题，可选 `dark`, `light`                            | string  | `light` |
-| lineNumber | 指定代码块行号是否开启，可选 `true`, `false`              | boolean | false   |
-| copyable   | 指定代码块是否展示复制按钮，可选 `true`, `false`          | boolean | true    |
-| height     | 指定代码块高度，用于需要控制代码块高度固定的场景          | number  | -       |
-| type       | 指定渲染类型，可选 `block`, `pure`, pure 模式去掉容器样式 | `block` | -       |
+| 参数         | 说明                                                      | 类型    | 默认值  |
+| :----------- | :-------------------------------------------------------- | :------ | :------ |
+| language     | 指定语言类型，详见下表                                    | string  | -       |
+| showLanguage | 是否展示语言的 Tag                                        | boolean | true    |
+| theme        | 指定主题，可选 `dark`, `light`                            | string  | `light` |
+| lineNumber   | 指定代码块行号是否开启，可选 `true`, `false`              | boolean | false   |
+| copyable     | 指定代码块是否展示复制按钮，可选 `true`, `false`          | boolean | true    |
+| height       | 指定代码块高度，用于需要控制代码块高度固定的场景          | number  | -       |
+| type         | 指定渲染类型，可选 `block`, `pure`, pure 模式去掉容器样式 | `block` | -       |
 
 ### 目前支持的语言列表
 

src/Highlight/index.tsx

@@ -8,4 +8,6 @@ const Highlight = (props: HighlightProps) => {
   return <HighlightBase {...props} />;
 };
 
+export * from './defalut';
+export * from './wrapper';
 export { Highlight };

src/Highlight/style.ts

@@ -56,6 +56,18 @@ export const useStyles = createStyles(
           border-radius: ${token.borderRadius}px;
           transition: background-color 100ms ${token.motionEaseOut};
 
+          :not(:hover) {
+            .${prefix}-copy {
+              visibility: hidden;
+              opacity: 0;
+            }
+
+            .${prefix}-tag {
+              visibility: hidden;
+              opacity: 0;
+            }
+          }
+
           pre {
             margin: 0 !important;
             padding: ${type === 'pure' ? 0 : `16px 24px`} !important;
@@ -71,7 +83,25 @@ export const useStyles = createStyles(
         min-width: 100px;
         display: flex;
         justify-content: center;
+        span {
+          font-family: ${token.fontFamilyCode} !important;
+        }
       `,
+      lang: cx(
+        css`
+          position: absolute;
+          z-index: 2;
+          right: 0;
+          bottom: 8px;
+
+          font-family: ${token.fontFamilyCode};
+          color: ${token.colorTextSecondary};
+
+          // opacity: 0;
+
+          transition: opacity 0.1s;
+        `,
+      ),
       expandIcon: css`
         color: ${colorText};
         &:hover {

src/Highlight/wrapper.tsx

@@ -33,6 +33,7 @@ export const FullFeatureWrapper = memo<HighlighterWrapperProps & HighlightProps>
     style,
     prefixCls: customPrefixCls,
     theme = THEME_LIGHT,
+    copyable = true,
     type = 'block',
   } = props || {};
   const prefixCls = getPrefixCls('highlight', customPrefixCls);
@@ -73,13 +74,14 @@ export const FullFeatureWrapper = memo<HighlighterWrapperProps & HighlightProps>
           suffixIcon={false}
           value={lang.toLowerCase()}
         />
-        <CopyButton content={children} prefixCls={prefixCls} theme={theme} />
+        {copyable && <CopyButton content={children} prefixCls={prefixCls} theme={theme} />}
       </Flexbox>
       <HighlightBase
         {...props}
         language={lang?.toLowerCase()}
         style={expand ? {} : { height: 0, overflow: 'hidden' }}
         copyable={false}
+        showLanguage={false}
       />
     </div>
   );

src/Snippet/index.md

@@ -1,14 +1,23 @@
 ---
 nav: 组件
-group: Content
-title: Snippet
-description: The Snippet component is used to display a code snippet with syntax highlighting. It can be customized with a symbol before the content and a language for syntax highlighting. The component is also copyable with a CopyButton included by default.
+group: 基础组件
+title: Snippet 代码片段
+description: Snippet 组件用于显示带有语法突出显示的代码片段。可以在内容之前使用符号和语法突出显示的语言进行自定义。该组件还可以通过默认包含的 CopyButton 进行复制
 ---
 
+# Snippet 代码片段
+
 ## Default
 
 <code src="./demos/index.tsx" nopadding></code>
 
 ## APIs
 
-<API></API>
+| 参数      | 说明                   | 类型               | 默认值  |
+| :-------- | :--------------------- | :----------------- | :------ |
+| children  | 组件内显示的内容       | string             | -       |
+| copyable  | 内容是否可以复制       | boolean            | true    |
+| language  | 组件内容的语言         | string             | 'tsx'   |
+| spotlight | 是否添加聚光灯背景效果 | boolean            | false   |
+| symbol    | 组件内容前显示的符号   | string             | -       |
+| type      | 组件的渲染类型         | 'ghost' \| 'block' | 'ghost' |

src/Snippet/index.tsx

@@ -9,30 +9,30 @@ import { useStyles } from './style';
 
 export interface SnippetProps extends DivProps {
   /**
-   * @description The content to be displayed inside the Snippet component
+   * @description 内容区域
    */
   children: string;
   /**
-   * @description Whether the Snippet component is copyable or not
+   * @description 是否支持可复制的能力
    * @default true
    */
   copyable?: boolean;
   /**
-   * @description The language of the content inside the Snippet component
+   * @description 指定渲染的语言类型
    * @default 'tsx'
    */
   language?: string;
   /**
-   * @description Whether add spotlight background
+   * @description 是否添加聚光灯背景
    * @default false
    */
   spotlight?: boolean;
   /**
-   * @description The symbol to be displayed before the content inside the Snippet component
+   * @description 开头渲染的符号标志
    */
   symbol?: string;
   /**
-   * @description The type of the Snippet component
+   * @description 组件的渲染类型
    * @default 'ghost'
    */
   type?: 'ghost' | 'block';
@@ -63,7 +63,7 @@ const Snippet = memo<SnippetProps>((props) => {
     <div className={cx(styles.container, className)} {...rest}>
       {spotlight && <Spotlight />}
       <HighLighter language={language} prefixCls={prefixCls} theme={isDarkMode ? 'dark' : 'light'}>
-        {[symbol, children].filter(Boolean).join(' ')}
+        {symbol ? [symbol, children].join(' ') : children}
       </HighLighter>
       {copyable && <CopyButton content={children} />}
     </div>