Aura Theme 主题扩展开发指南：从零开始创建应用适配-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00147/article/details/148577323

Aura Theme 主题扩展开发指南：从零开始创建应用适配

aura-theme ✨ A beautiful dark theme for your favorite apps. 项目地址: https://gitcode.com/gh_mirrors/au/aura-theme

前言

Aura Theme 是一款优雅的代码主题解决方案，其强大的扩展能力允许开发者为其喜爱的应用创建主题适配（Port）。本文将详细介绍如何使用 Aura CLI 工具创建新的应用适配，帮助开发者快速上手主题扩展开发。

开发环境准备

在开始创建应用适配前，请确保已满足以下条件：

已安装 Node.js 和 Yarn
已获取 Aura Theme 项目代码
熟悉基本的命令行操作

创建第一个应用适配

使用 Aura CLI 创建新适配非常简单，只需执行以下命令：

yarn make port 应用名称

例如，要创建名为"awesome-app"的适配：

yarn make port awesome-app

执行后，系统会自动生成以下目录结构：

src/ports/awesome-app
├── index.ts        # 适配主逻辑文件
└── templates       # 模板文件目录
    └── README.md   # 说明文档模板

核心文件解析

index.ts - 适配逻辑核心

这个 TypeScript 文件是适配的核心，负责定义如何处理主题配置。基本结构如下：

import { AuraAPI } from 'core'
import { resolve } from 'path'

export async function AwesomeAppPort(Aura: AuraAPI) {
  // 解构常用工具函数
  const { createPort, createReadme, colorSchemes, constants } = Aura
  const templateFolder = resolve(__dirname, 'templates')
  const { info } = constants

  // 定义基本信息
  const portName = 'AwesomeApp'
  const version = '1.0.0'

  // 创建适配文件
  await createPort({
    template: resolve(templateFolder, 'config.json'),
    replacements: {
      ...colorSchemes.dark,  // 使用暗色主题方案
      ...info,               // 基础信息
      customValue: '示例值'    // 自定义值
    },
  })

  // 生成README文档
  await createReadme({
    template: resolve(templateFolder, 'README.md'),
    replacements: {
      portName,
      version,
    },
  })
}

关键点说明：

createPort 函数用于生成应用特定的主题配置文件
replacements 对象包含所有模板变量
可以使用展开运算符(...)合并多个对象

模板文件 - README.md

模板文件使用 Mustache 语法，支持动态内容替换。示例：

{{{ basic-heading }}}

# 安装指南
1. 第一步说明
2. 第二步说明

# 贡献者
<table>
  <thead>
    <tr>
      {{{ author-thead }}}
    </tr>
  </thead>
  <tbody>
    <tr>
      {{{ author-tbody }}}
    </tr>
  </tbody>
</table>

{{{ footer }}}

模板变量说明：

三花括号{{{}}}表示原样输出，不进行HTML转义
双花括号{{}}会对内容进行HTML转义
系统会自动提供一些基础模板如basic-heading等

开发工作流程

创建模板文件：在templates目录下添加需要的模板
编写适配逻辑：在index.ts中定义处理逻辑
开发模式测试：运行以下命令实时编译

yarn dev only 应用名称

查看输出结果：在packages/应用名称目录下检查生成的文件

高级技巧

动态内容处理

可以通过模板系统实现复杂的动态内容生成。例如创建config.json模板：

{
  "appName": "{{ portName }}",
  "version": "{{ version }}",
  "primaryColor": "{{ accent1 }}",
  "customMessage": "{{ hello }}"
}

然后在index.ts中提供对应的值：

await createPort({
  template: resolve(templateFolder, 'config.json'),
  replacements: {
    ...colorSchemes.dark,
    portName: '我的应用',
    version: '1.0.0',
    hello: '欢迎使用Aura主题!'
  },
})