feat(core): supports CSS objects and style functions

Author: akinoccc

packages/core/src/styled.ts

@@ -44,8 +44,15 @@ export type PropsDefinition<T> = {
   [K in keyof T]: T[K]
 }
 
+// CSS样式对象类型
+type CSSStyleObject = Record<string, string | number>
+
+// 样式函数类型
+type StyleFunction<T> = (props: BaseContext<T>) => CSSStyleObject
+
 // 定义 styledComponent 类型
 interface StyledComponent<T extends object> {
+  // 支持模板字符串
   <P>(
     styles: TemplateStringsArray,
     ...expressions: (
@@ -54,12 +61,20 @@ interface StyledComponent<T extends object> {
     )[]
   ): DefineSetupFnComponent<{ as?: string, props?: P } & TransformProps<T> & P & HTMLAttributes>
 
+  // 支持CSS对象
+  <P>(
+    styles: CSSStyleObject | StyleFunction<P & TransformProps<T>>
+  ): DefineSetupFnComponent<{ as?: string, props?: P } & TransformProps<T> & P & HTMLAttributes>
+
   attrs: <A = object>(
     attrs: A | ((props: TransformProps<T> & A) => A),
   ) => StyledComponent<A & T>
 
   // 支持泛型参数的类型定义
   <P extends object>(props: PropsDefinition<P>): StyledComponent<P & T>
+
+  // 支持单独的props函数链式调用
+  props: <P extends object>(propsDefinition: PropsDefinition<P>) => StyledComponent<P & T>
 }
 
 // 类型辅助函数，用于在编译时转换 props 类型
@@ -91,15 +106,34 @@ function baseStyled<T extends object>(target: string | InstanceType<any>, propsD
   }
   let defaultAttrs: unknown
   function styledComponent<P>(
-    stylesOrProps: TemplateStringsArray | PropsDefinition<P>,
+    stylesOrProps: TemplateStringsArray | PropsDefinition<P> | CSSStyleObject | StyleFunction<P & TransformProps<T>>,
     ...expressions: (
       | ExpressionType<BaseContext<P & TransformProps<T>>>
       | ExpressionType<BaseContext<P & TransformProps<T>>>[]
     )[]
   ): any {
-    // 处理泛型参数的情况，如 styled.div<Props>
+    // 处理样式函数
+    if (typeof stylesOrProps === 'function') {
+      const styleFunction = stylesOrProps as StyleFunction<BaseContext<P & TransformProps<T>>>
+      return createStyledComponentFromFunction<P>(styleFunction)
+    }
+
+    // 处理CSS对象或props定义
     if (!Array.isArray(stylesOrProps)) {
-      return baseStyled(target, { ...propsDefinition, ...stylesOrProps } as PropsDefinition<T & P>) as StyledComponent<T & P>
+      // 检查是否为props定义（包含type、required、default等属性）
+      const hasPropsDefinitionKeys = Object.values(stylesOrProps).some(value =>
+        value && typeof value === 'object' && ('type' in value || 'required' in value || 'default' in value),
+      )
+
+      if (!hasPropsDefinitionKeys) {
+        // 是CSS对象
+        const cssObject = stylesOrProps as CSSStyleObject
+        return createStyledComponentFromObject<P>(cssObject)
+      }
+      else {
+        // 是props定义
+        return baseStyled(target, { ...propsDefinition, ...stylesOrProps } as PropsDefinition<T & P>) as StyledComponent<T & P>
+      }
     }
 
     // 正常的样式模板字符串处理
@@ -114,6 +148,39 @@ function baseStyled<T extends object>(target: string | InstanceType<any>, propsD
     return styledComponent
   }
 
+  // 添加props方法支持链式调用
+  styledComponent.props = function <P extends object>(newPropsDefinition: PropsDefinition<P>) {
+    return baseStyled(target, { ...propsDefinition, ...newPropsDefinition } as PropsDefinition<T & P>) as StyledComponent<T & P>
+  }
+
+  // 将CSS对象转换为CSS字符串
+  function cssObjectToString(cssObject: CSSStyleObject): string {
+    return Object.entries(cssObject)
+      .map(([key, value]) => {
+        // 将驼峰命名转换为kebab-case
+        const kebabKey = key.replace(/([A-Z])/g, '-$1').toLowerCase()
+        return `${kebabKey}: ${value};`
+      })
+      .join(' ')
+  }
+
+  // 从CSS对象创建组件
+  function createStyledComponentFromObject<P>(cssObject: CSSStyleObject) {
+    const cssString = cssObjectToString(cssObject)
+    const cssWithExpression = [cssString] as ExpressionType<any>[]
+    return createStyledComponent<P>(cssWithExpression)
+  }
+
+  // 从样式函数创建组件
+  function createStyledComponentFromFunction<P>(styleFunction: StyleFunction<BaseContext<P & TransformProps<T>>>) {
+    // 创建一个表达式函数，在运行时调用样式函数
+    const cssWithExpression = [(props: BaseContext<P & TransformProps<T>>) => {
+      const cssObject = styleFunction(props)
+      return cssObjectToString(cssObject)
+    }] as ExpressionType<any>[]
+    return createStyledComponent<P>(cssWithExpression)
+  }
+
   function createStyledComponent<P>(cssWithExpression: ExpressionType<any>[]) {
     let type: string = target
     if (isVueComponent(target)) {

packages/docs/.vitepress/en.ts

@@ -57,6 +57,7 @@ function sidebarGuide() {
       text: 'Advances',
       base: '/guide/advances/',
       items: [
+        { text: 'CSS Objects and Functions', link: 'css-objects-and-functions' },
         { text: 'Theming', link: 'theming' },
         { text: 'Global Styles', link: 'global-style' },
         { text: 'CSS Mixin', link: 'css-mixin' },

packages/docs/.vitepress/zh.ts

@@ -81,6 +81,7 @@ function sidebarGuide() {
       text: '进阶',
       base: '/zh/guide/advances/',
       items: [
+        { text: 'CSS对象和样式函数', link: 'css-objects-and-functions' },
         { text: '主题', link: 'theming' },
         { text: '全局样式', link: 'global-style' },
         { text: '样式复用', link: 'css-mixin' },

packages/docs/guide/advances/css-objects-and-functions.md

@@ -0,0 +1,222 @@
+---
+outline: deep
+---
+
+# CSS Objects and Style Functions
+
+Starting from version v1.12.0, `@vue-styled-components/core` supports CSS objects and style functions, providing more flexible ways to define component styles.
+
+## CSS Object Support
+
+You can now pass CSS objects directly to styled components instead of template literals.
+
+:::demo
+
+```vue
+<script setup lang="ts">
+import { styled } from '@vue-styled-components/core'
+
+const StyledDiv = styled.div({
+  color: 'red',
+  fontSize: '16px',
+  backgroundColor: 'blue',
+  padding: '10px',
+  borderRadius: '8px',
+  textAlign: 'center'
+})
+</script>
+
+<template>
+  <StyledDiv>CSS Object Styled Component</StyledDiv>
+</template>
+```
+
+:::
+
+### Benefits
+
+- **Type Safety**: Better TypeScript support with autocomplete for CSS properties
+- **Dynamic Values**: Easier to work with computed values and variables
+- **Readability**: More structured and readable for complex styles
+
+## Style Functions
+
+Style functions allow you to create dynamic styles based on component props.
+
+:::demo
+
+```vue
+<script setup lang="ts">
+import { styled } from '@vue-styled-components/core'
+import { ref } from 'vue'
+
+const buttonProps = {
+  disabled: Boolean,
+  size: String
+}
+
+const StyledButton = styled.button.props(buttonProps)(({ disabled, size }) => ({
+  color: disabled ? '#fff' : '#007bff',
+  padding: size === 'large' ? '12px 24px' : size === 'small' ? '4px 8px' : '8px 16px',
+  fontSize: size === 'large' ? '16px' : size === 'small' ? '12px' : '14px',
+  border: 'none',
+  borderRadius: '4px',
+  backgroundColor: disabled ? '#ccc' : '#f8f9fa',
+  cursor: disabled ? 'not-allowed' : 'pointer',
+  transition: 'all 0.2s ease'
+}))
+
+const disabled = ref(false)
+const size = ref<'small' | 'medium' | 'large'>('medium')
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px; align-items: flex-start;">
+    <StyledButton :disabled="disabled" :size="size">
+      Dynamic Button ({{ size }})
+    </StyledButton>
+    
+    <div style="display: flex; gap: 8px;">
+      <button @click="size = 'small'">Small</button>
+      <button @click="size = 'medium'">Medium</button>
+      <button @click="size = 'large'">Large</button>
+      <button @click="disabled = !disabled">
+        {{ disabled ? 'Enable' : 'Disable' }}
+      </button>
+    </div>
+  </div>
+</template>
+```
+
+:::
+
+## Props Chain Calling
+
+You can use the `.props()` method to define component props separately, then chain with element methods.
+
+:::demo
+
+```vue
+<script setup lang="ts">
+import { styled } from '@vue-styled-components/core'
+import { ref } from 'vue'
+
+const StyledInput = styled
+  .input
+  .props({
+    borderColor: { type: String, default: '#ccc' },
+    size: { type: String, default: 'medium' }
+  })(({ borderColor, size }) => ({
+    border: `1px solid ${borderColor}`,
+    padding: size === 'large' ? '12px' : size === 'small' ? '4px' : '8px',
+    fontSize: size === 'large' ? '16px' : size === 'small' ? '12px' : '14px',
+    borderRadius: '4px',
+    outline: 'none',
+    transition: 'border-color 0.2s ease',
+    width: '100%'
+  }))
+
+const borderColor = ref('#ccc')
+const size = ref('medium')
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <StyledInput 
+      :borderColor="borderColor" 
+      :size="size" 
+      placeholder="Type something..."
+      @focus="borderColor = '#007bff'"
+      @blur="borderColor = '#ccc'"
+    />
+    
+    <div style="display: flex; gap: 8px;">
+      <button @click="size = 'small'">Small</button>
+      <button @click="size = 'medium'">Medium</button>
+      <button @click="size = 'large'">Large</button>
+    </div>
+  </div>
+</template>
+```
+
+:::
+
+## Combined Usage
+
+You can combine props definition with style functions for more complex components.
+
+:::demo
+
+```vue
+<script setup lang="ts">
+import { styled } from '@vue-styled-components/core'
+import { ref } from 'vue'
+
+const StyledCard = styled
+  .div
+  .props({
+    elevation: { type: Number, default: 1 },
+    rounded: { type: Boolean, default: true },
+    variant: { type: String, default: 'default' }
+  })(({ elevation, rounded, variant }) => ({
+    boxShadow: `0 ${elevation * 2}px ${elevation * 4}px rgba(0,0,0,0.1)`,
+    borderRadius: rounded ? '8px' : '0',
+    padding: '16px',
+    backgroundColor: variant === 'primary' ? '#007bff' : variant === 'success' ? '#28a745' : 'white',
+    color: variant === 'default' ? '#333' : 'white',
+    border: variant === 'default' ? '1px solid #e9ecef' : 'none',
+    transition: 'all 0.2s ease',
+    cursor: 'pointer'
+  }))
+
+const elevation = ref(1)
+const rounded = ref(true)
+const variant = ref('default')
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; gap: 16px;">
+    <StyledCard 
+      :elevation="elevation" 
+      :rounded="rounded" 
+      :variant="variant"
+    >
+      This is a {{ variant }} card, shadow level {{ elevation }}, rounded: {{ rounded }}
+    </StyledCard>
+    
+    <div style="display: flex; flex-wrap: wrap; gap: 8px;">
+      <div>
+        <label>阴影级别: </label>
+        <input 
+          type="range" 
+          min="0" 
+          max="5" 
+          v-model.number="elevation"
+        />
+        {{ elevation }}
+      </div>
+      
+      <label>
+        <input type="checkbox" v-model="rounded" />
+        圆角
+      </label>
+      
+      <select v-model="variant">
+        <option value="default">默认</option>
+        <option value="primary">主要</option>
+        <option value="success">成功</option>
+      </select>
+    </div>
+  </div>
+</template>
+```
+
+:::
+
+## Key Features
+
+1. **CSS Object Conversion**: Automatically converts camelCase CSS properties to kebab-case
+2. **Style Functions**: Support functions that receive props and return CSS objects
+3. **Props Chain Calling**: Define component props through `.props()` method, then chain with element methods
+4. **Type Safety**: Full TypeScript support ensuring type safety for props and styles
+5. **Backward Compatibility**: Maintains full compatibility with existing template string syntax