Ant Design Mini 支持微信小程序啦！

Ant Design Mini

经过一段时间的开发与不断的努力，我们兴奋地宣布，Ant Desigin Mini 组件库中已有 16 个核心组件完成了微信小程序的适配工作！现在你不仅可以在支付宝小程序中使用 Ant Desigin Mini 组件库，也可以在微信小程序中使用了！

目前这项适配正处于 Beta 阶段，我们诚挚地邀请大家前来体验。首批适配的组件包括：Button、Slider、Container、Icon、Loading、Switch、Tag、Input、Calendar、List、Result、Popover、Mask、Stepper、Popup、Checkbox

先来看看 Demo 效果：

我们的官网文档、Demo 都已同步更新双端切换能力：

你可以参考以下文档进行接入：

• 
  
• 接入支付宝小程序：ant-design-mini.antgroup.com/guide/quick…
  
• 接入微信小程序：ant-design-mini.antgroup.com/guide/using…
  
• 使用 uni-app 接入：ant-design-mini.antgroup.com/guide/using…
  

双平台无法对齐的特性

受制于各平台框架设计，以下这些特性存在差异：

• 
  
• 两个平台的事件 API 不同。支付宝小程序可以把实例上通过 props 传递给子组件，而微信需要在 data 里传递函数。视图层的写法也所有不同。
  
  • 
    
  • 下面是 Calendar 在两种平台的使用方式。
    
    • 
      
    • 微信小程序
      
    
    
    
  
  
  

Page({
data:{
handleFormat() {

		}

  }

})


<calendar onFormat="{{handleFormat}}" />

  - 支付宝小程序

Page({
handleFormat() {


  }

})

<calendar onFormat="handleFormat" />

• 
  
• 微信小程序不支持在 slot 为空时显示默认值, 所以我们在微信平台取消了部分 slot，对应会损失一些定制能力。 比如说 Calendar 组件， 在支付宝可以通过 calendarTitle 这个 slot 定制标题，在微信端只能通过 css 来控制样式。
  

<View class="ant-calendar-title-container">

  {/* #if ALIPAY */}
<Slot name="calendarTitle">

    {/* #endif */}
<View class="ant-calendar-title">{currentMonth.title}</View>

    {/* #if ALIPAY */}
</Slot>

  {/* #endif */}
</View>

• 
  
• 微信小程序不支持循环渲染 slot , 所以部分组件无法迁移到微信， 比如说 IndexBar 组件， 使用了 Slot 递归渲染整个组件的内容。这种写法无法迁移到微信。
  

<view a:for="{{items}}">
<slot
value="{{item}}"
index="{{index}}"
name="labelPreview" />
</view>

双平台适配背后的工程技术

下面我们为大家介绍一下 Antd Mini 支持多平台背后的一些工程方案。

中立的模板语法： 使用 tsx 开发小程序

由于支付宝和微信的小程序的语法各有差异，为了解决让 Antd Mini 同时支持两个端，我们团队选择的 tsx 的一个子集作为小程序的模板语言。
使用 tsx 具有以下优势：

• 
  
• 可以直接使用 babel 解析代码，无需自己开发编译器。
  
• 各个 IDE 原生支持 TSX 的类型推导与代码提示。
  
• 视图层和逻辑层可以复用同一份 props 类型。
  
• 可以直接通过 import 导入其他的小程序组件，使用 typescript 进行类型检查。
  
• 视图层脚本也可以享受类型校验，无需依赖平台 IDE
  

由于小程序的视图语法比较受限，从 tsx 向跨平台视图语法转换是比较容易的。我们基于 babel 开发了一个简单的编译器，解析原先 tsx 的语法树以后，将 React 的语法平行转换为可读性比较强的小程序视图语法。
具体举例来看：

• 
  
• 条件判断 : 我们使用了 &&以及 ？： 三元表达式替代了之前的 :if 标签。
  
  • 
    
  • tsx: !!a && <Text>a</Text>
    
  • 微信小程序:<text wx:if="{{ !!a }}" />
    
  • 支付宝小程序:<text wx:if="{{ !!a }}" />
    
  
  
  
• 循环： 我们使用了 map 代替之前的 :for 标签，从源码里自动分析出 :for-item :for-index :key 等标签。
  
  • 
    
  • tsx:
    
  
  
  

{todoList.map((task, taskIndex) => (
<Text
hidden={!mixin.value}
key={task.id}
data-item-id={taskIndex}
data-num={20}

  >

    {taskIndex} {task}
</Text>

))}

• 
  
• 微信小程序：
  

<block
wx:for="{{ todoList }}"
wx:for-index="taskIndex"
wx:for-item="task"
wx:key="{{ task.id }}">

  <!-- display: inline -->
<text
hidden="{{ !mixin.value }}"
data-item-id="{{ taskIndex }}"
data-num="{{ 20 }}"

    >{{ taskIndex }}{{ task }}</text

  >
</block>

• 
  
• 支付宝小程序
  

  <block
a:for="{{ todoList }}"
a:for-index="taskIndex"
a:for-item="task"
a:key="{{ task.id }}">

    <!-- display: inline -->
<text
hidden="{{ !mixin.value }}"
data-item-id="{{ taskIndex }}"
data-num="{{ 20 }}"

      >{{ taskIndex }}{{ task }}</text

    >
</block>

• 
  
• 事件绑定： 我们会按照配置，自动将直接转换为两个平台的格式。
  
  • 
    
  • tsx:<Text onClick="handleClick" />
    
  • 微信小程序: <text bind:click="handleClick" />
    
  • 支付宝小程序: <text onClick="handleClick" />
    
  
  
  
• 视图层脚本
  
  • 
    
  • 我们还规定了以 sjs.ts 作为视图层脚本的文件格式。 在编译时候转换为对应平台的文件格式。
    
    • 
      
    • tsx: import helper from './helper.sjs.ts'
      
    • 微信小程序： <wxs src="./helper.wxs" module="helper" />
      
    • 支付宝小程序： <import-sjs src="./helper.sjs" module="helper" />
      
    
    
    
  
  
  
• 类型方案
  
  • 
    
  • 为了让逻辑层类型与视图层关联，我们设计了一些工具类型。 比如说下面使用的 TSXMLProps，将 IProps 的 onClick 转换成了字符串。
    
  
  
  

// Calendar.axml.tsx
import { TSXMLProps, View } from 'tsxml';


interface IProps {

  className?: string;

  style?: string;
onClick: (e) => void;

}


interface InternalData {
size: number;

}

export default (

  { className, style }: TSXMLProps<IProps>,

  { size }: InternalData

) => (
<View class={`ant-calendar ${className ? className : ''}`} style={style}>

    {size}
</View>

);

// Page.axml.tsx

import Calendar from './Calendar.axml.tsx'

export default () => (<Calendar onClick="handleClick" />)

目前使用 tsx 的这套方案还存在一些限制：

• 
  
• 和小程序相同，一个文件内只能定义一个组件。
  
• 如果使用自定义组件，需要配置组件事件在各个平台的写法。
  

老组件语法转换？用 AI 就行了

在决定使用 tsx 语法之后，我们还面临一个很棘手的工作量问题：如何把历史组件库 axml 代码全量转换为最新的 tsx 语法？
这时候就该 ChatGPT 出场了，我们请 AI 来帮助我们完成这个一次性转换工作。
为了让转换结果更靠谱，我们使用了一些技巧：

• 
  
• 使用了 tsx 编译器等测试用例作为 prompt ，让 AI 可以更好的了解 tsx 的写法。
  
• 除了 tsx 文件以外，我们还将组件的 props.ts 与 config.json 加到了 propmt 里，可以帮助 AI 生成更好的 import 导入。
  

在这里，你可以看到这份转换的完整 prompt。

确保 AI 产出的正确性？再用我们的编译器转回来

为了确保 AI 产出的代码是正确的，我们使用编译器将 AI 编写的 tsx 重新编译回 axml ，再用 git diff 对原始代码做比对，由此即可核查 AI 转换的正确性。

当然，这两次转换的过程不会完全等价，比如转换 map 的过程中会出现一层嵌套的 <block/>。好在这样的差异不多，一般肉眼看一遍就能确认正确性了。

跨平台通用的组件逻辑：小程序函数式组件（functional-mini）

除了视图，我们还需要确保组件逻辑适配到双端。这里我们使用了小程序函数式组件（ functional-mini ）的形式来编写，functional-mini 的源码及文档放置均在 ant-design/functional-mini 。

使用了函数式组件后，Antd Mini 用上了计算属性、useEffect 等特性，也能通过 hooks 来替换原有的大量 mixin 实现，让代码的可维护性提升了一个台阶。

以典型的 Popover 组件为例，逻辑部分适配完成后，它的代码完全变成了 React 风格，数据变更流程一目了然：

const Popover = (props: IPopoverProps) => {
const [value] = useMergedState(props.defaultVisible, {
value: props.visible,

  });
const [popoverStyle, setPopoverStyle] = useState({
popoverContentStyle: '',
adjustedPlacement: '',

  });

useEffect(() => {
setPopoverStyle({
popoverContentStyle: '',
adjustedPlacement: '',

    });

  }, [value, props.autoAdjustOverflow, props.placement]);

return {
adjustedPlacement: popoverStyle.adjustedPlacement,
popoverContentStyle: popoverStyle.popoverContentStyle,

  };

};

关于小程序函数式组件的原理、特性介绍，我们将在后续的分享中另行展开。

写在最后

欢迎大家一起来尝试 Ant Design Mini 的跨平台能力，你可以在 issue 区提出宝贵的建议与 Bug 反馈。

官网： mini.ant.design/

国内镜像：ant-design-mini.antgroup.com/