跳转到正文

Vue 与浏览器工具 ​

交互示例 ​

更改示例元素的颜色和尺寸,查看类名、查询和样式的结果。还可以开始或停止 Vue 作用域,转换内置 PNG,下载样例文件或打开打印预览。

在新标签页运行此示例

查看示例源码
tsx
import { useI18n, useSiderScroll } from '@/hooks'
import {
  arrayBufferToBase64Image,
  autoPrefixStyle,
  call,
  colorToRgba,
  completeSize,
  downloadAnyFile,
  downloadBase64File,
  effectDispose,
  fileToBase64,
  hasClass,
  positionSelectedMenuItem,
  printDom,
  queryElements,
  removeClass,
  removeStyle,
  renderNode,
  setClass,
  setStyle,
  unrefElement,
  watchEffectWithTarget,
} from '@/utils'
import { NButton, NCard, NFlex, NInput, NSwitch } from 'naive-ui'
import { effectScope } from 'vue'
import DemoPage from './components/DemoPage'
import DemoResult from './components/DemoResult'

const png =
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+j9x0AAAAASUVORK5CYII='

export default defineComponent({
  name: 'DocsBrowserUtils',
  setup() {
    const { t } = useI18n('docsExamples')
    const text = (key: string) => t<string>(key)
    const target = ref<HTMLElement>()
    const result = ref('')
    const color = ref('#3b63d9')
    const size = ref('150')
    const zero = ref(true)
    const log = ref<string[]>([])
    const count = ref(0)
    const observed = ref<number>()
    const cleaned = ref(false)
    const running = ref(false)
    const dataUrl = ref('')
    const fileResult = ref('')
    const scrollSidebar = useSiderScroll()
    let scope: ReturnType<typeof effectScope> | undefined

    const change = (apply: boolean) => {
      const node = unrefElement(target)

      if (!node) return

      const actionScope = effectScope()

      actionScope.run(() => {
        if (apply) {
          setClass(node, 'docs-utility-marked')
          setStyle(node, {
            color: colorToRgba(color.value, 1, '#3b63d9'),
            width: completeSize(size.value),
          })
        } else {
          removeClass(node, 'docs-utility-marked')
          removeStyle(node, ['color', 'width'])
        }

        result.value = JSON.stringify(
          {
            hasClass: hasClass(node, 'docs-utility-marked').value,
            matched: queryElements('attr:data-docs-utility')?.length,
            style: node.getAttribute('style'),
            prefixes: autoPrefixStyle('transform'),
          },
          null,
          2,
        )
      })
      actionScope.stop()
    }

    const start = () => {
      if (running.value) return

      scope = effectScope()
      cleaned.value = false
      running.value = true
      scope.run(() => {
        watchEffectWithTarget(() => {
          observed.value = count.value
        })
        effectDispose(() => {
          cleaned.value = true
          running.value = false
        })
      })
    }
    const stop = () => scope?.stop()

    onScopeDispose(stop)

    const convert = async () => {
      try {
        const bytes = Uint8Array.from(atob(png), (char) => char.charCodeAt(0))

        dataUrl.value = arrayBufferToBase64Image(bytes.buffer)
        const data = await fileToBase64(
          new File([bytes], 'ray-example.png', { type: 'image/png' }),
        )

        fileResult.value =
          data === dataUrl.value ? text('browser.matchingDataUrl') : data
      } catch (error) {
        fileResult.value = String(error)
      }
    }

    return () => (
      <DemoPage
        title={text('browser.title')}
        description={text('browser.intro')}
      >
        <div class="r-demo-grid">
          <NCard title={text('browser.dom')}>
            <NFlex>
              <NInput
                v-model:value={color.value}
                aria-label={text('browser.color')}
              />
              <NInput
                v-model:value={size.value}
                aria-label={text('browser.width')}
              />
              <NButton onClick={() => change(true)}>
                {text('browser.apply')}
              </NButton>
              <NButton onClick={() => change(false)}>
                {text('browser.remove')}
              </NButton>
            </NFlex>
            <p ref={target} data-docs-utility="">
              {text('browser.target')}
            </p>
            <DemoResult label={text('browser.domResult')}>
              <pre>{result.value}</pre>
            </DemoResult>
            <NFlex>
              <NButton onClick={() => scrollSidebar(0, 0)}>
                {text('browser.sidebarTop')}
              </NButton>
              <NButton onClick={positionSelectedMenuItem}>
                {text('browser.locateMenu')}
              </NButton>
            </NFlex>
          </NCard>
          <NCard title={text('browser.vue')}>
            <NFlex align="center">
              <NSwitch
                v-model:value={zero.value}
                aria-label={text('browser.renderZero')}
              />
              <span>
                {renderNode(zero.value ? 0 : null, {
                  defaultElement: text('browser.fallback'),
                })()}
              </span>
              <NButton
                onClick={() => {
                  log.value = []
                  call(
                    [
                      (n: number) => log.value.push(`A:${n}`),
                      (n: number) => log.value.push(`B:${n}`),
                    ],
                    count.value,
                  )
                }}
              >
                {text('browser.callBoth')}
              </NButton>
            </NFlex>
            <NFlex>
              <NButton disabled={running.value} onClick={start}>
                {text('browser.start')}
              </NButton>
              <NButton onClick={() => count.value++}>
                {text('browser.increment')}
              </NButton>
              <NButton disabled={!running.value} onClick={stop}>
                {text('browser.stop')}
              </NButton>
            </NFlex>
            <DemoResult label={text('browser.vueResult')}>
              <code>
                {JSON.stringify({
                  count: count.value,
                  observed: observed.value,
                  cleaned: cleaned.value,
                  calls: log.value,
                })}
              </code>
            </DemoResult>
          </NCard>
          <NCard title={text('browser.files')}>
            <NFlex>
              <NButton onClick={convert}>{text('browser.convert')}</NButton>
              <NButton
                disabled={!dataUrl.value}
                onClick={() =>
                  downloadBase64File(dataUrl.value, 'ray-example.png')
                }
              >
                {text('browser.downloadPng')}
              </NButton>
              <NButton
                onClick={() =>
                  downloadAnyFile(
                    new Blob(['Ray Template\n'], { type: 'text/plain' }),
                    'ray-example.txt',
                  )
                }
              >
                {text('browser.downloadBlob')}
              </NButton>
              <NButton
                onClick={async () => {
                  fileResult.value = String(await printDom(target))
                }}
              >
                {text('browser.print')}
              </NButton>
            </NFlex>
            <DemoResult label={text('browser.fileResult')}>
              {fileResult.value}
            </DemoResult>
          </NCard>
        </div>
      </DemoPage>
    )
  },
})

Vue 目标解析 ​

BasicTarget<T> 可为元素、组件实例、ref、getter 或空值,unrefElement(target, fallback?) 在调用时解包;组件优先返回 $el。多根组件的 $el 未必是可操作的元素。截图、全屏、样式操作请优先绑定明确的原生 DOM ref。

工具行为
call(fnOrFns, ...args)调用一个函数或按顺序调用回调数组,透传参数。
renderNode(value, { defaultElement }?)规范化成渲染函数。仅 null 或 undefined 用回退,0 和空字符串保留。
effectDispose(cleanup)有当前 effect scope 时登记清理并返回 true,否则返回 false,需调用方自行释放。
watchEffectWithTarget(effect, options?)对 Vue watchEffect 的兼容入口,返回停止句柄;在有效作用域创建时会随作用域停止。

DOM、样式和尺寸 ​

API行为
setClass(target, names) / removeClass(target, names)作用于当前和后续替换的目标。支持空白分隔字符串或数组;移除时 removeAllClass 清空 class。
hasClass(target, names)返回响应式布尔值,任一完整类名匹配即为真。只随目标引用更新,外部改 class 属性本身不会触发重算。
setStyle(target, styles)支持样式对象、声明字符串或字符串数组,保留其他行内样式。支持 camelCase、CSS 自定义属性与 !important。
removeStyle(target, names)按 CSS 名称或 camelCase 删除行内样式。
autoPrefixStyle(name)返回原属性和历史前缀名的兼容映射,不执行 DOM 操作。
completeSize(value, unit = 'px')数字、纯数字字符串补单位,保留百分比、CSS 关键字和表达式。
colorToRgba(color, alpha = 1, fallback?)支持逗号形式 RGB/HSL 与常见 Hex。带透明度的 Hex 保留其透明度,未知格式回退到指定值或原字符串。
queryElements(selector, { defaultElement }?)返回 DOM 元素数组。attr:data-id 等同于属性选择器。无匹配返回空数组,空或非法选择器无回退时返回 null。
positionSelectedMenuItem()将已渲染且超出可视区的当前菜单滚入视野。调用前展开父级并等待 DOM 渲染。

类名与样式函数内部监听目标变化,在组件 setup 或 effect scope 内创建。SSR 下访问 document、window 的方法应推迟到挂载后。

文件、下载和打印 ​

API行为
fileToBase64(file)返回带 MIME 的 Data URL Promise,读取错误或中止会拒绝。
arrayBufferToBase64Image(buffer)把 PNG 字节加上 PNG Data URL 前缀,不转换其他图像格式。
downloadBase64File(url, fileName)以临时链接触发下载,清理链接。
downloadAnyFile(data, fileName)接收 Data URL、Blob、File、ArrayBuffer。二进制使用临时对象 URL;Promise 完成表示已发起下载。
printDom(target, { printOptions?, domToImageOptions? })先将 DOM 截成 JPEG,再发起打印预览。返回 Promise<boolean>;失败记录错误并返回 false,若存在全局 Loading Bar 会同步状态。
ts
import { downloadAnyFile, fileToBase64 } from '@/utils'

export const previewFile = (file: File) => fileToBase64(file)
export const downloadReport = (pdf: Blob) => downloadAnyFile(pdf, 'report.pdf')

DOM 工具 · 文件工具 · Vue 工具 · 截图与打印 Hooks