@zving/vue-toolkit v0.0.17

Vue Toolkit

Installation

pnpm install @zving/vue-toolkit

vue-connector

🪡 Connect anything to your vue components.

The idea for this library comes from an article about Presentational and Container Components. If you are wondering whether to use it, I would recommend this article to you.

Usage1

Our purpose is straightforward, connect the state to the Presentational Component, or intercept and preprocess the props of the Presentational Component.

@zving/vue-toolkit has already intercepted props for you. The important thing is that you need to tell it how you get the state, combine it into props, and pass it to the Presentational Component.

import { defineConnector } from '@zving/vue-toolkit'

/**
 * mapStateProps allows you to define reactive props
 * that it will be executed every time props and reactive dependencies inside mapStateProps change
 *
 * @param ownProps - component props
 * @param instance - the current component instance
 */
const mapStateProps = (ownProps, instance) => {
  return {
    // return state props
  }
}

/**
 * since mapStateProps is reactive, you can also define a factory function,
 * which allows you to define some closure variables before mapStateProps is executed
 *
 * Note: mapStatePropsFactory will only be executed once during `setup`
 *
 * @param initialProps - the first props
 * @param instance - the current component instance
 */
const mapStatePropsFactory = (initialProps, instance) => {
  return (ownProps, instance) => {
    return {
      // return state props
    }
  }
}

/**
 * mapStaticProps allows you to define static props
 * that it will only be executed once during `setup`.
 *
 * @param ownProps - component props
 * @param instance - the current component instance
 */
const mapStaticProps = (ownProps, instance) => {
  return {
    // return static props
  }
}

/**
 * mergeProps allows you to customize the merging logic of props,
 * it is eventually passed to the connected component
 *
 * The default is `{ ...ownProps, ...stateProps, ...staticProps }`.
 *
 * @param stateProps - props from mapStateProps
 * @param staticProps - props from mapStaticProps
 * @param ownProps - component props
 */
const mergeProps = (stateProps, staticProps, ownProps) => {
  return {
    // merged props
  }
}

/**
 * Define your connector, which defines how you get the state
 *
 * @param {?mapStateProps|mapStatePropsFactory} mapStateProps
 * @param {?mapStatePropsFactory} mapStatePropsFactory
 * @param {?mergeProps} mergeProps
 */
const connector = defineConnector(mapStateProps, mapStaticProps, mergeProps)

const ConnectComponent = connector(PresentationComponent)

The playground contains usage in conjunction with some popular state libraries.

Usage2

type TPresentationalProps = {preProp: string}
const Presentational = defineComponent<TPresentationalProps, any, any, any, any, any, any, any, any, any>({
  props: {preProp: ''}
})
type TContainerProps = { ctProp: number }
// 定义一个 Connector
const myConnector = defineConnector<Partial<TPresentationalProps>, TContainerProps>(
  (ctProps) => {
    return () => {

      return {
        preProp: ctProps.ctProp > 3 ? '大' : '小'
      }
    }
  });

// 正确用法：Connector 的第2个参数 propsDefinition 必须符合 { ctProp: Number }
const connect1 = myConnector(
  Presentational,
  { ctProp: Number }, // Number 是与类型 PropDefinition<number> 匹配的
  true
);

// 错误用法：Connector 的第2个参数 propsDefinition 类型不匹配
const connect2 = myConnector(
  Presentational,
  { ctProp: String }, // 期望有错误提示: 不能将类型“StringConstructor”分配给类型“PropDefinition<number>”。
  true
);

vue-forward-ref

💫 Make it easier for HOCs to forward refs.

Usage

@zving/vue-toolkit provides two forwarding methods.

The easiest is to use forwardRef to wrap the component you need to forward.

import { forwardRef } from '@zving/vue-toolkit'

defineComponent({
  name: 'Wrapper',
  setup() {
    return () => {
      // The component can be any type used to create a vnode
      // - string
      // - Component
      // - ConcreteComponent
      return forwardRef('div')
    }
  }
})

If you need to extend or override the forward, you can use createForwardRef.

import { createForwardRef } from '@zving/vue-toolkit'

defineComponent({
  name: 'Wrapper',
  setup() {
    const override = {
      // ...
    }
    // Assign `forwardRef` to the component that needs to be forwarded,
    // and the first parameter allows you to pass in the ref already defined
    const forwardRef = createForwardRef(null, override)

    return () => {
      return h(Component, {
        ref: forwardRef
      })
    }
  }
})

Either way, they allow you to customize which component the declaration is forwarded on.

forwardRef(Component, instance)
// or
createForwardRef(null, null, instance)