API 导入
让 API 无需手写 import 即可使用
自动引用机制可以让你在应用文件中直接使用 API，而不必重复显式 import。Oiyo 会根据 scan.apis 扫描规则启用自动引用机制。
主要解决：
- 按需引入。
- 减少样板代码。
- 获得类型提示和检查。
扫描源
采用 glob 语法进行文件匹配，扫描源按 使用侧 的导入来源声明。
运行时 API
Oiyo 已内置 Runtime API 的扫描源，可以直接使用它们。
src/App.vue
<script setup>
// 无需手动导入类型: import type { Ref } from '@skiyee/oiyo/runtime';
// 无需手动导入方法: import { ref, onLaunch } from '@skiyee/oiyo/runtime';
const title: Ref<string> = ref('Hello Oiyo')
const count = ref(0)
onLaunch(() => {
console.log('App Launch, title:', title.value)
})
</script>
这里无需导入 ref 或 onLaunch，因为 Oiyo 会通过自动引用机制处理这些来源。
在 Vue 文件中使用只是示例，你可以在 应用的任意文件 中进行使用。
本地 API
Oiyo 已内置 composables/*.ts 作为约定扫描源，无需再次配置。
对于非约定目录，可以在 oiyo.config.ts 中显式配置：
oiyo.config.ts
import { defineOiyoConfig } from '@skiyee/oiyo/config'
export default defineOiyoConfig({
scan: {
apis: [
'utils/*.ts',
{ from: 'shared/*.ts', types: true },
],
},
})
扫描路径均基于
<srcDir> 目录。即 utils/*.ts 将扫描 src/utils 下第一层 TypeScript 文件。避免使用 Barrel Files（index 桶文件）进行模块重导出，否则可能造成重复扫描。
定义
export function useSystemDark() {
const { hostTheme } = uni.getSystemInfoSync()
const isDark = ref(hostTheme === 'dark')
return readonly(isDark)
}
export function sleep(ms = 300) {
return new Promise<void>(resolve => setTimeout(resolve, ms))
}
export type DeepPartial<T> = { [P in keyof T]?: _DeepPartial<T[P]> }
type _DeepPartial<T> = T extends Function
? T
: T extends Array<infer U>
? Array<_DeepPartial<U>>
: T extends object
? DeepPartial<T>
: T | undefined
使用
src/App.vue
interface Config {
name: string
titles: {
first: string
}
delay: number
}
const config: DeepPartial<Config> = {
delay: 1000,
}
const isDark = useSystemDark()
async function mockSleep() {
await sleep(config.delay ?? 300)
console.log({
title: config.titles?.first ?? 'default title',
dark: isDark.value,
})
}
mockSleep()
第三方 API
假设要扫描 pinia 包，可以这样显式配置该库的扫描源：
oiyo.config.ts
import { defineOiyoConfig } from '@skiyee/oiyo/config'
export default defineOiyoConfig({
scan: {
apis: [
'pinia',
],
},
})
效果：
defineStore、createPinia、setActivePinia可以在应用文件中直接使用。
扫描源的声明与显式导入的 来源 保持一致。
import { defineStore } from 'pinia':pinia。import { useUser } from 'package/composables':package/composables。
显式导入
自动引用机制并不禁止显式 import，可以根据团队约定选择。
以下情况推荐显式 import：
- 希望文件依赖关系更明确。
- 避免同名导出冲突。
- 使用未加入扫描系统的模块。
- 只在极少数文件中使用。
Oiyo 的自动引用机制适合高频、稳定、约定明确的 API。
验证可用
如果 API 不可用，检查：
- 文件是否在扫描路径内。
- 是否使用命名导出。
- 扫描源 glob 是否写对。
- 是否重新运行
oiyo dev命令。
使用原则
使用时遵循这些原则：
- 若文件放在约定目录，优先利用内置扫描。
- 非约定目录或第三方库，通过
oiyo.config.ts显式配置。 - 需要自动导入的内容使用命名导出。
- 避免使用
Barrel Files进行模块重导出。