使用 VueUse useTextDirection 为 airi 应用实现响应式 LTR/RTL 文本方向【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本文聚焦 airi 项目所采用的 VueUse Browser 类别 composable 之一 ——useTextDirection系统讲解如何以响应式方式读取并双向控制 DOM 元素的dir全局属性从而在中文、日文、韩文等 LTR 语境与阿拉伯语、希伯来语等 RTL 语境之间动态切换排版方向。读完本文你将掌握useTextDirection的默认行为、全部 Options 参数、返回值语义与底层实现原理并能将其接入 airi 各 stage 应用的多语言i18n体系为未来的 RTL 语言支持做好准备。认识 useTextDirection对dir属性的响应式封装useTextDirection是 VueUse 中用于「元素文本方向」的响应式工具其官方定位为Reactive dir of the elements text.它围绕 HTML 的dir全局属性 建模。dir属性用于声明元素文本的书写方向可取三个值ltrleft-to-right从左到右绝大多数语言含中文、英文、日文、韩文的默认方向rtlright-to-left从右到左用于阿拉伯语、希伯来语、波斯语等语言auto由浏览器根据元素内容自动推断方向。在 airi 仓库中该函数被收录在 .agents/skills/vueuse-functions/SKILL.md 的 Browser 分类下Invocation规则为AUTO即当开发 Vue.js / Nuxt 功能时若需求匹配即可直接采用其详细参考文档位于 .agents/skills/vueuse-functions/references/useTextDirection.md。仓库本身通过 pnpm workspace 的 catalog 机制统一管理 VueUse 依赖版本pnpm-workspace.yaml 中声明vueuse/core: ^14.4.0这意味着 airi 下的多个应用与包如 apps/stage-tamagotchi/package.json、apps/stage-web/package.json、apps/stage-pocket/package.json、packages/stage-layouts/package.json、packages/electron-vueuse/package.json 等均以vueuse/core: catalog:的方式引用同一份 14.4.x 版本useTextDirection在这些应用中可直接导入使用。快速上手一行代码读取当前文本方向useTextDirection的默认用法极为简洁import { useTextDirection } from vueuse/core const dir useTextDirection() // Refltr | rtl | auto不传任何参数时它默认以html标签为目标元素。也就是说返回的dir引用会反映html元素上dir属性的当前值。参考文档给出了两种典型场景!--ltr-- html ... /html !--rtl-- html dirrtl ... /html当页面根节点html未设置dir时函数返回初始值默认ltr当html dirrtl被设置后dir引用即变为rtl。由于返回值是一个WritableComputedRef见下文「返回值与类型声明」你既可以读取方向也可以直接赋值来切换方向赋值会同步写回目标元素的dir属性。Options 参数详解selector、observe 与 initialValueuseTextDirection接受一个可选的UseTextDirectionOptions配置对象共三个参数import { useTextDirection } from vueuse/core const mode useTextDirection({ selector: body }) // Refltr | rtl | auto参数类型默认值作用selectorstringhtml目标元素的 CSS 选择器决定读取/写入dir的元素observebooleanfalse是否用MutationObserver观察目标元素上dir属性的变化从而让返回值随外部修改自动更新initialValueUseTextDirectionValueltr目标元素未设置dir属性时使用的初始值三个参数各自的适用场景如下selector默认作用于整个文档根节点html适合「全局排版方向」这种页面级语义当需要让某个容器例如对话消息区、代码面板独立于全局采用相反方向时可改为selector: body、selector: .chat-panel等任意合法 CSS 选择器。observe默认false时返回值只在组件内部赋值时更新设为true后函数内部通过MutationObserver监听目标元素dir属性的变化即使方向由组件外部的代码如框架级 i18n 插件、浏览器扩展修改返回值也会保持同步。initialValue当目标元素完全未声明dir时作为回退值。由于大多数语言默认即ltr默认值ltr在绝大多数场景下无需修改若你的应用默认面向 RTL 语言可显式传入rtl。返回值与类型声明useTextDirection的类型签名如下源自参考文档的 Type Declarationsexport type UseTextDirectionValue ltr | rtl | auto export interface UseTextDirectionOptions extends ConfigurableDocument { /** * CSS Selector for the target element applying to * * default html */ selector?: string /** * Observe document.querySelector(selector) changes using MutationObserver * * default false */ observe?: boolean /** * Initial value * * default ltr */ initialValue?: UseTextDirectionValue } /** * Reactive dir of the elements text. * * __NO_SIDE_EFFECTS__ */ export declare function useTextDirection( options?: UseTextDirectionOptions, ): WritableComputedRefUseTextDirectionValue, UseTextDirectionValue值得注意的语义细节值域收窄UseTextDirectionValue严格限定为ltr | rtl | auto三个字面量类型系统会在编译期拦截非法赋值。可写计算引用返回类型是WritableComputedRefUseTextDirectionValue, UseTextDirectionValue这意味着dir既是一个响应式「读」入口也是一个响应式「写」入口。例如// 读取 console.log(dir.value) // ltr | rtl | auto // 写入切换为 RTL并同步更新目标元素属性 dir.value rtl继承ConfigurableDocumentOptions 接口扩展自ConfigurableDocument因此在需要时也可以传入自定义的document实例例如iframe.contentDocument或测试环境中的模拟 DOM从而把方向控制限定在特定文档上下文中。底层实现原理从类型声明反推工作方式参考文档并未直接给出函数体源码但从其类型声明与行为描述可以清晰推断其实现脉络目标元素解析通过document.querySelector(selector)selector默认html定位要操作的元素。这与useCssVar、useElementBounding等 VueUse 元素类 composable 的取址方式一致。读取与回退读取目标元素的dir属性值若属性缺失则回退到initialValue默认ltr。这解释了「html未标注方向时返回ltr」的默认行为。写入同步返回值是WritableComputedRef其 setter 会调用setAttribute(dir, value)写回目标元素保证「ref 赋值 → DOM 属性变更」的闭环。响应式观察当observe: true时内部挂载一个MutationObserver观察目标元素的dir属性attributes变化一旦外部修改属性立即把新值推回流中更新 ref组件卸载时自动断开观察避免泄漏。基于上述机制从源码结构可以推断useTextDirection本质上是「DOM 属性 ↔ 响应式 ref」的双向绑定层行为语义与useDark主题类名双向绑定同构只是把操作对象从class换成了dir属性并额外提供了MutationObserver这一可选的外部变更监听通道。在 airi 多语言应用中的落地场景airi 是一个自带多语言内容体系的项目docs 下同时维护en、ja、ko、zh-Hans等多份语言文档其各 stage 应用Web / Electron 桌面端 / 移动端均实现了语言检测逻辑。以 apps/stage-tamagotchi/src/renderer/modules/i18n.ts、apps/stage-web/src/modules/i18n.ts 为例语言初始化逻辑形如language navigator.language || en即优先读取浏览器/系统语言作为兜底。而 apps/stage-tamagotchi/src/renderer/composables/use-language.ts 则负责在 Electron 渲染进程与主进程配置之间同步语言选择并带有「首次启动时不把navigator.language回写进主进程配置」的保护逻辑。useTextDirection恰好可以在这套语言体系中充当「方向层」import { useTextDirection } from vueuse/core import { useI18n } from vue-i18n const { locale } useI18n() const dir useTextDirection({ observe: true }) // 语言切换时同步更新页面书写方向 const RTL_LOCALES [ar, he, fa, ur] // 示例RTL 语言标签集合 watch(locale, (value) { dir.value RTL_LOCALES.some(code value.startsWith(code)) ? rtl : ltr })同时方向属性可以配合 CSS 的选择器能力实现样式自适应。当dir被设置到html或具体容器上后CSS 可通过属性选择器[dirrtl]或:dir(rtl)伪类编写双向布局规则例如.chat-log[dirrtl] { direction: rtl; text-align: right; }dir属性本身还具备继承语义设置在html上的方向会作用于整棵文档树而局部容器可覆盖为dirltr以强制某块内容如代码块、URL、电话号码保持从左到右的排版这符合 HTML 规范对dir的级联规则。使用注意事项SSR 场景useTextDirection属于浏览器 DOM 类 composable服务端渲染阶段不存在document应仅在客户端挂载后使用或参考useMounted/tryOnMounted的时机约定延迟初始化这正是其 Options 继承ConfigurableDocument的意义所在——必要时可注入可用的文档实现。observe 的开销MutationObserver默认false是有意为之。只有当你确实需要「外部修改dir属性也能反向驱动 ref」时才开启避免在非必要场景下为每个目标元素维护观察器。与相关 composable 的区分useTextDirection关注的是元素自身的dir属性若需求变为「根据用户首选语言推断方向」可组合usePreferredLanguages与useTextDirection使用前者读取navigator.languages后者负责把结论落到dir属性上二者职责互补。值域校验由于返回值类型收窄为ltr | rtl | auto赋值非法字符串会在类型检查阶段被拦截这也是一种编译期安全保证。小结useTextDirection是 VueUse 面向「文本方向」这一细分领域提供的标准答案默认以html为目标支持通过selector精确指定任意元素通过observe开启MutationObserver双向同步通过initialValue控制缺失属性时的回退值并返回一个可读可写的WritableComputedRefltr | rtl | auto。在 airi 这类具备多语言内容与多端形态Web / Electron / Capacitor的项目中将其接入现有 i18n 语言切换逻辑即可低成本地为未来的 RTL 语言版本铺平排版基础。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考