feat(api): 增加innerStyle和innerClass，增加样式修改说明 (#153)

* feat(docs): 增加样式修改的说明 * feat(api): 增加innerStyle和innerClass
TDesignOteam · Oct 9, 2024 · aaced37 · aaced37
1 parent a1bf601
commit aaced37
Show file tree

Hide file tree

Showing 22 changed files with 286 additions and 10,487 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/script/plugin-tdoc/md-to-wc.mjs b/script/plugin-tdoc/md-to-wc.mjs
@@ -171,6 +171,7 @@ async function customRender({ source, file, md }) {
     docClass: '',
     lastUpdated,
     designDocLastUpdated: lastUpdated,
+    isGettingStarted: false,
     ...data,
   };
 
@@ -226,7 +227,9 @@ async function customRender({ source, file, md }) {
   } else {
     mdSegment.docMd = md.render.call(
       md,
-      `${pageData.toc ? '[toc]\n' : ''}${content.replace(/<!--[\s\S]+?-->/g, '')}`,
+      `${pageData.toc ? '[toc]\n' : ''}${
+        mdSegment?.isGettingStarted ? content : content.replace(/<!--[\s\S]+?-->/g, '')
+      }`,
     ).html;
   }
 

diff --git a/script/plugin-tdoc/transforms.js b/script/plugin-tdoc/transforms.js
@@ -7,6 +7,8 @@ import mdToWc from './md-to-wc.mjs';
 let demoImports = {};
 let demoCodesImports = {};
 
+const ignoreReplaceDemoRegExp = /getting-started\.md/;
+
 export default {
   before({ source, file }) {
     const resourceDir = path.dirname(file);
@@ -15,17 +17,19 @@ export default {
     demoImports = {};
     demoCodesImports = {};
     // 替换成对应 demo 文件
-    source = source.replace(/\{\{\s+(.+)\s+\}\}/g, (demoStr, demoFileName) => {
-      const jsxDemoPath = path.resolve(resourceDir, `./_example/${demoFileName}.jsx`);
-      const tsxDemoPath = path.resolve(resourceDir, `./_example/${demoFileName}.tsx`);
+    if (!ignoreReplaceDemoRegExp.test(file)) {
+      source = source.replace(/\{\{\s+(.+)\s+\}\}/g, (demoStr, demoFileName) => {
+        const jsxDemoPath = path.resolve(resourceDir, `./_example/${demoFileName}.jsx`);
+        const tsxDemoPath = path.resolve(resourceDir, `./_example/${demoFileName}.tsx`);
 
-      if (!fs.existsSync(jsxDemoPath) && !fs.existsSync(tsxDemoPath)) {
-        console.log('\x1B[36m%s\x1B[0m', `${name} 组件需要实现 _example/${demoFileName}.jsx/tsx 示例!`);
-        return '\n<h3>DEMO (🚧建设中）...</h3>';
-      }
+        if (!fs.existsSync(jsxDemoPath) && !fs.existsSync(tsxDemoPath)) {
+          console.log('\x1B[36m%s\x1B[0m', `${name} 组件需要实现 _example/${demoFileName}.jsx/tsx 示例!`);
+          return '\n<h3>DEMO (🚧建设中）...</h3>';
+        }
 
-      return `\n::: demo _example/${demoFileName} ${name}\n:::\n`;
-    });
+        return `\n::: demo _example/${demoFileName} ${name}\n:::\n`;
+      });
+    }
 
     source.replace(/:::\s*demo\s+([\\/.\w-]+)/g, (demoStr, relativeDemoPath) => {
       const demoPathOnlyLetters = relativeDemoPath.replace(/[^a-zA-Z\d]/g, '');

diff --git a/site/docs/getting-started.md b/site/docs/getting-started.md
@@ -2,6 +2,7 @@
 title: Tdesign Web Components
 description: TDesign 适配桌面端的组件库，可以在任何前端项目中使用。
 spline: explain
+isGettingStarted: true
 ---
 
 ### 安装
@@ -96,6 +97,91 @@ module.exports = {
 }
 ```
 
+### 更改样式
+
+有些业务场景需要更改组件的样式，但是`shadowDOM`具有天然样式隔离的特点，组件外部的样式影响不到组件内部，为此 Tdesign Web Components 提供了几种方式来对样式进行更改：
+
+#### 通过设置`css`属性，来修改样式（推荐）
+
+目前每一个组件，都默认有一个`css`的属性，设置该值时会在`shadowDOM`内部创建`style`标签：
+
+```html
+<t-button css="button.t-button {color: red}">填充按钮</t-button>
+```
+
+会在组件内部，创建`style`标签，改变内部样式：
+
+```html
+<!-- DOM结构 -->
+<t-button
+  #shadow-root
+    <button>...</button>
+    <style>
+      button.t-button {
+        color: red;
+      }
+    </style>
+</t-button>
+```
+
+#### 通过设置`style`、`innerStyle`来改变样式
+
+**任意组件**，均可设置`style`和`innerStyle`，约定`style`只在最外层标签上起作用：
+
+```html
+<!-- 设置style -->
+<t-button style={{ color: 'red' }}>填充按钮</t-button>
+
+<!-- DOM结构 -->
+<t-button style="color: red">
+  #shadow-root
+    <button>...</button>
+</t-button>
+```
+
+约定`innerStyle`只在`shadowDOM`内部第一层标签上起作用：
+
+```html
+<!-- 设置innerStyle -->
+<t-button innerStyle={{ color: 'red' }}>填充按钮</t-button>
+
+<!-- 对应DOM结构 -->
+<t-button>
+  #shadow-root
+    <button style="color: red">...</button>
+</t-button>
+```
+
+#### 通过设置`class`、`innerClass`来改变样式（可以和`css`属性搭配使用）
+
+**任意组件**，均可设置`class`和`innerClass`，约定`class`只在最外层标签上起作用：
+
+```html
+<!-- 设置class -->
+<t-button class="customClass">填充按钮</t-button>
+
+<!-- 对应DOM结构 -->
+<t-button class="customClass">
+  #shadow-root
+    <button>...</button>
+</t-button>
+```
+
+约定`innerClass`只在`shadowDOM`内部第一层标签上起作用：
+
+```html
+<!-- 设置innerStyle -->
+<t-button innerClass="customClass">填充按钮</t-button>
+
+<!-- 对应DOM结构 -->
+<t-button>
+  #shadow-root
+    <button class="customClass">...</button>
+</t-button>
+```
+
+> 后续会推出基于打包工具的样式注入插件，敬请期待...
+
 ### 浏览器兼容性
 
 | [<img src="https://tdesign.gtimg.com/docs/edge_48x48.png" alt="IE / Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/> IE / Edge | [<img src="https://tdesign.gtimg.com/docs/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Firefox | [<img src="https://tdesign.gtimg.com/docs/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Chrome | [<img src="https://tdesign.gtimg.com/docs/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/)<br/>Safari |
@@ -106,4 +192,5 @@ module.exports = {
 
 Q: 是否内置 reset 样式统一页面元素的默认样式 ？
 
-A: 我们不引入 `reset.less`
+A: 我们不引入 `reset.less`
+
diff --git a/src/affix/affix.tsx b/src/affix/affix.tsx
@@ -123,9 +123,9 @@ export default class Affix extends Component<AffixProps> {
   }
 
   render() {
-    const { children, content, style } = this.props;
+    const { children, content, innerStyle, innerClass } = this.props;
     return (
-      <div ref={this.affixWrapRef} className={this.className} style={style}>
+      <div ref={this.affixWrapRef} className={innerClass} style={innerStyle}>
         <div ref={this.affixRef}>{children || content}</div>
       </div>
     );

diff --git a/src/alert/alert.tsx b/src/alert/alert.tsx
@@ -149,7 +149,7 @@ export default class Alert extends Component<AlertProps> {
   }
 
   render(props: AlertProps) {
-    const { className, style, theme, ignoreAttributes } = props;
+    const { innerClass, innerStyle, theme, ignoreAttributes } = props;
     if (ignoreAttributes?.length > 0) {
       ignoreAttributes.forEach((attr) => {
         this.removeAttribute(attr);
@@ -161,10 +161,10 @@ export default class Alert extends Component<AlertProps> {
       {
         [`${this.classPrefix}-is-hidden`]: this.closed.value,
       },
-      className,
+      innerClass,
     ]);
     return (
-      <div ref={this.nodeRef} className={cls} style={style}>
+      <div ref={this.nodeRef} className={cls} style={innerStyle}>
         {this.renderIcon()}
         {this.renderContext()}
         {this.renderClose()}

diff --git a/src/avatar/avatar.tsx b/src/avatar/avatar.tsx
@@ -82,7 +82,23 @@ export default class Avatar extends Component<AvatarProps> {
   render(props: OmiProps<AvatarProps, any>) {
     const { SIZE } = getCommonClassName();
     const { componentName, isImgExist, groupSize, avatarRef, avatarChildrenRef, handleImgLoadError } = this;
-    const { alt, icon, image, shape, size: avatarSize, children, content, style, imageProps, ...avatarProps } = props;
+    const {
+      alt,
+      icon,
+      image,
+      shape,
+      size: avatarSize,
+      children,
+      content,
+      innerClass,
+      innerStyle,
+      imageProps,
+      ...avatarProps
+    } = props;
+
+    delete avatarProps.className;
+    delete avatarProps.style;
+
     const size = avatarSize === undefined ? groupSize : avatarSize;
 
     const numSizeStyle =
@@ -102,11 +118,15 @@ export default class Avatar extends Component<AvatarProps> {
           }
         : {};
 
-    const avatarClass = classNames(componentName, this.className, {
-      [SIZE[size]]: !!SIZE[size],
-      [`${componentName}--${shape}`]: !!shape,
-      [`${componentName}__icon`]: !!icon,
-    });
+    const avatarClass = classNames(
+      componentName,
+      {
+        [SIZE[size]]: !!SIZE[size],
+        [`${componentName}--${shape}`]: !!shape,
+        [`${componentName}__icon`]: !!icon,
+      },
+      innerClass,
+    );
     let renderChildren: string | number | boolean | object;
 
     if (image && isImgExist) {
@@ -127,7 +147,7 @@ export default class Avatar extends Component<AvatarProps> {
       );
     }
     return (
-      <div class={avatarClass} style={{ ...numSizeStyle, ...style }} {...avatarProps} ref={avatarRef}>
+      <div class={avatarClass} style={{ ...numSizeStyle, ...innerStyle }} {...avatarProps} ref={avatarRef}>
         {renderChildren}
       </div>
     );

diff --git a/src/back-top/back-top.tsx b/src/back-top/back-top.tsx
@@ -132,15 +132,15 @@ export default class BackTop extends Component<BackTopProps> {
       target,
       shape,
       size,
-      className,
       container,
       duration,
       content,
       offset,
       children,
       default: cusContent,
-      style,
       onClick,
+      innerClass,
+      innerStyle,
       ignoreAttributes,
     } = props;
     if (ignoreAttributes?.length > 0) {
@@ -151,7 +151,7 @@ export default class BackTop extends Component<BackTopProps> {
     const backTopStyle = {
       insetInlineEnd: offset[0],
       insetBlockEnd: offset[1],
-      ...style,
+      ...innerStyle,
     };
     const classPrefix = getClassPrefix();
     const defaultContent = (
@@ -169,7 +169,7 @@ export default class BackTop extends Component<BackTopProps> {
         [`${classPrefix}-size-s`]: size === 'small',
         [`${classPrefix}-size-m`]: size === 'medium',
       },
-      className,
+      innerClass,
     );
     const renderChildren = children || content || cusContent || defaultContent;
     const clickEventProps = { target, container, duration, onClick } as ClickEventProps;

diff --git a/src/badge/badge.tsx b/src/badge/badge.tsx
@@ -1,7 +1,7 @@
 import { classNames, Component, createRef, tag } from 'omi';
 
 import { getClassPrefix } from '../_util/classname.ts';
-import { StyledProps } from '../common';
+import { StyledProps, Styles } from '../common';
 import { TdBadgeProps } from './type.ts';
 
 export interface BadgeProps extends TdBadgeProps, StyledProps {}
@@ -49,10 +49,10 @@ export default class Badge extends Component<BadgeProps> {
     return count;
   };
 
-  getStyle = () => {
+  getStyle = (styles: Styles) => {
     // 红点偏移逻辑
-    const { style, color, offset } = this.props;
-    const mergedStyle = { ...style };
+    const { color, offset } = this.props;
+    const mergedStyle = { ...styles };
     if (color) {
       mergedStyle.backgroundColor = color;
     }
@@ -68,7 +68,23 @@ export default class Badge extends Component<BadgeProps> {
   };
 
   render(props: BadgeProps) {
-    const { children, content, count, dot, shape, showZero, size, className, ignoreAttributes, ...restProps } = props;
+    const {
+      children,
+      content,
+      count,
+      dot,
+      shape,
+      showZero,
+      size,
+      ignoreAttributes,
+      innerStyle,
+      innerClass,
+      ...restProps
+    } = props;
+
+    delete restProps.style;
+    delete restProps.className;
+
     // 去除父元素属性
     if (ignoreAttributes?.length > 0) {
       ignoreAttributes.forEach((attr) => {
@@ -81,7 +97,7 @@ export default class Badge extends Component<BadgeProps> {
       !childNode && `${this.classPrefix}-badge--static`,
       dot ? `${this.classPrefix}-badge--dot` : `${this.classPrefix}-badge--${shape}`,
       size === 'small' && `${this.classPrefix}-size-s`,
-      !childNode && className,
+      !childNode && innerClass,
     );
 
     // 隐藏逻辑
@@ -90,7 +106,11 @@ export default class Badge extends Component<BadgeProps> {
       isHidden = count < MIN_COUNT && !showZero;
     }
     const badge = !isHidden ? (
-      <span {...(childNode ? {} : restProps)} className={badgeClassName} style={this.getStyle()}>
+      <span
+        {...(childNode ? {} : restProps)}
+        className={badgeClassName}
+        style={this.getStyle(childNode ? {} : innerStyle)}
+      >
         {!dot ? this.getDisplayCount() : null}
       </span>
     ) : null;
@@ -99,7 +119,12 @@ export default class Badge extends Component<BadgeProps> {
       return badge;
     }
     return (
-      <span {...restProps} className={classNames(`${this.classPrefix}-badge`, className)} ref={this.nodeRef}>
+      <span
+        {...restProps}
+        className={classNames(`${this.classPrefix}-badge`, innerClass)}
+        style={innerStyle}
+        ref={this.nodeRef}
+      >
         {childNode}
         {badge}
       </span>