Quantity Field

정확한 물리량을 입력하고 호환되는 표시 단위로 변환합니다.

용법

길이 단위

길이를 입력하고 호환되는 표시 단위 사이를 전환합니다.

<!-- Quantity Field / Length -->
<script setup lang="ts">
import { QuantityFieldRoot, QuantityFieldInput, QuantityFieldValue, createStandardQuantityPolicies } from '@sectile/vue/quantity-field'
import { Check } from '@lucide/vue'
import {
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from '@sectile/vue/select'
import { ref } from 'vue'

const policies = { ...createStandardQuantityPolicies('metre', 'metric') }
const units = [
  { id: 'millimetre', label: 'mm' },
  { id: 'centimetre', label: 'cm' },
  { id: 'metre', label: 'm' },
  { id: 'kilometre', label: 'km' },
]
const unitIDs = units.map(({ id }) => id)
const unitLabel = (id: string) => units.find((unit) => unit.id === id)?.label ?? id
const displayUnit = ref('centimetre')

</script>

<template>
  <QuantityFieldRoot
    v-model:display-unit="displayUnit"
    :policies="policies"
    :default-value="{ value: '1.25', unit: 'metre' }"
  >
    <QuantityFieldInput />
    <SelectRoot
      v-model="displayUnit"
      :items="unitIDs"
      :text-value="unitLabel"
      label="Display unit"
    >
      <SelectTrigger><SelectValue /></SelectTrigger>
      <SelectContent>
        <SelectItem v-for="unit in units" :key="unit.id" :value="unit.id">
          {{ unit.label }}
          <SelectItemIndicator><Check :size="15" aria-hidden="true" /></SelectItemIndicator>
        </SelectItem>
      </SelectContent>
    </SelectRoot>
    <QuantityFieldValue />
  </QuantityFieldRoot>
</template>

온도 단위

물리량은 유지하면서 호환되는 온도 단위로 변환합니다.

<!-- Quantity Field / Temperature -->
<script setup lang="ts">
import { QuantityFieldRoot, QuantityFieldInput, QuantityFieldValue, createStandardQuantityPolicies } from '@sectile/vue/quantity-field'
import { Check } from '@lucide/vue'
import {
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from '@sectile/vue/select'
import { ref } from 'vue'

const policies = { ...createStandardQuantityPolicies('metre', 'metric') }
const units = [
  { id: 'millimetre', label: 'mm' },
  { id: 'centimetre', label: 'cm' },
  { id: 'metre', label: 'm' },
  { id: 'kilometre', label: 'km' },
]
const unitIDs = units.map(({ id }) => id)
const unitLabel = (id: string) => units.find((unit) => unit.id === id)?.label ?? id
const displayUnit = ref('centimetre')

</script>

<template>
  <QuantityFieldRoot
    v-model:display-unit="displayUnit"
    :policies="policies"
    :default-value="{ value: '1.25', unit: 'metre' }"
  >
    <QuantityFieldInput />
    <SelectRoot
      v-model="displayUnit"
      :items="unitIDs"
      :text-value="unitLabel"
      label="Display unit"
    >
      <SelectTrigger><SelectValue /></SelectTrigger>
      <SelectContent>
        <SelectItem v-for="unit in units" :key="unit.id" :value="unit.id">
          {{ unit.label }}
          <SelectItemIndicator><Check :size="15" aria-hidden="true" /></SelectItemIndicator>
        </SelectItem>
      </SelectContent>
    </SelectRoot>
    <QuantityFieldValue />
  </QuantityFieldRoot>
</template>

외부 상태 관리

현재 값은 부모가 관리하고, 허용된 변경을 컴포넌트에 다시 전달합니다.

<!-- Quantity Field / Controlled -->
<script setup lang="ts">
import { QuantityFieldRoot, QuantityFieldInput, QuantityFieldValue, createStandardQuantityPolicies } from '@sectile/vue/quantity-field'
import { Check } from '@lucide/vue'
import {
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from '@sectile/vue/select'
import { ref } from 'vue'

const policies = { ...createStandardQuantityPolicies('metre', 'metric') }
const units = [
  { id: 'millimetre', label: 'mm' },
  { id: 'centimetre', label: 'cm' },
  { id: 'metre', label: 'm' },
  { id: 'kilometre', label: 'km' },
]
const unitIDs = units.map(({ id }) => id)
const unitLabel = (id: string) => units.find((unit) => unit.id === id)?.label ?? id
const displayUnit = ref('centimetre')

</script>

<template>
  <QuantityFieldRoot
    v-model:display-unit="displayUnit"
    :policies="policies"
    :default-value="{ value: '1.25', unit: 'metre' }"
  >
    <QuantityFieldInput />
    <SelectRoot
      v-model="displayUnit"
      :items="unitIDs"
      :text-value="unitLabel"
      label="Display unit"
    >
      <SelectTrigger><SelectValue /></SelectTrigger>
      <SelectContent>
        <SelectItem v-for="unit in units" :key="unit.id" :value="unit.id">
          {{ unit.label }}
          <SelectItemIndicator><Check :size="15" aria-hidden="true" /></SelectItemIndicator>
        </SelectItem>
      </SelectContent>
    </SelectRoot>
    <QuantityFieldValue />
  </QuantityFieldRoot>
</template>

예시

계산식 입력

50-20%를 입력하면 계산 결과인 40으로 확정됩니다.

<!-- Quantity Field / Calculator -->
<script setup lang="ts">
import { QuantityFieldRoot, QuantityFieldInput, QuantityFieldValue, createStandardQuantityPolicies } from '@sectile/vue/quantity-field'
import { createCalculatorExpression } from '@sectile/core/number-field'
import { Check } from '@lucide/vue'
import {
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from '@sectile/vue/select'
import { ref } from 'vue'

const policies = { ...createStandardQuantityPolicies('metre', 'metric'), evaluator: createCalculatorExpression({ precision: 12, rounding: 'half-even' }) }
const units = [
  { id: 'millimetre', label: 'mm' },
  { id: 'centimetre', label: 'cm' },
  { id: 'metre', label: 'm' },
  { id: 'kilometre', label: 'km' },
]
const unitIDs = units.map(({ id }) => id)
const unitLabel = (id: string) => units.find((unit) => unit.id === id)?.label ?? id
const displayUnit = ref('centimetre')

</script>

<template>
  <QuantityFieldRoot
    v-model:display-unit="displayUnit"
    :policies="policies"
    :default-value="{ value: '1.25', unit: 'metre' }"
  >
    <QuantityFieldInput />
    <SelectRoot
      v-model="displayUnit"
      :items="unitIDs"
      :text-value="unitLabel"
      label="Display unit"
    >
      <SelectTrigger><SelectValue /></SelectTrigger>
      <SelectContent>
        <SelectItem v-for="unit in units" :key="unit.id" :value="unit.id">
          {{ unit.label }}
          <SelectItemIndicator><Check :size="15" aria-hidden="true" /></SelectItemIndicator>
        </SelectItem>
      </SelectContent>
    </SelectRoot>
    <QuantityFieldValue />
  </QuantityFieldRoot>
</template>

복합 단위

복합 단위를 해석하면서 하나의 기준 수량을 유지합니다.

<!-- Quantity Field / Compound -->
<script setup lang="ts">
import { QuantityFieldRoot, QuantityFieldInput, QuantityFieldValue, createStandardQuantityPolicies } from '@sectile/vue/quantity-field'
import { createCalculatorExpression } from '@sectile/core/number-field'
import { Check } from '@lucide/vue'
import {
  SelectContent,
  SelectItem,
  SelectItemIndicator,
  SelectRoot,
  SelectTrigger,
  SelectValue,
} from '@sectile/vue/select'
import { ref } from 'vue'

const policies = { ...createStandardQuantityPolicies('metre', 'metric'), evaluator: createCalculatorExpression({ precision: 12, rounding: 'half-even' }) }
const units = [
  { id: 'millimetre', label: 'mm' },
  { id: 'centimetre', label: 'cm' },
  { id: 'metre', label: 'm' },
  { id: 'kilometre', label: 'km' },
]
const unitIDs = units.map(({ id }) => id)
const unitLabel = (id: string) => units.find((unit) => unit.id === id)?.label ?? id
const displayUnit = ref('centimetre')

</script>

<template>
  <QuantityFieldRoot
    v-model:display-unit="displayUnit"
    :policies="policies"
    :default-value="{ value: '1.25', unit: 'metre' }"
  >
    <QuantityFieldInput />
    <SelectRoot
      v-model="displayUnit"
      :items="unitIDs"
      :text-value="unitLabel"
      label="Display unit"
    >
      <SelectTrigger><SelectValue /></SelectTrigger>
      <SelectContent>
        <SelectItem v-for="unit in units" :key="unit.id" :value="unit.id">
          {{ unit.label }}
          <SelectItemIndicator><Check :size="15" aria-hidden="true" /></SelectItemIndicator>
        </SelectItem>
      </SelectContent>
    </SelectRoot>
    <QuantityFieldValue />
  </QuantityFieldRoot>
</template>

API

Vue 패키지: @sectile/vue/quantity-field

컴포넌트

QuantityFieldRoot
QuantityFieldInput
QuantityFieldUnitSelect
QuantityFieldValue

함수

`createStandardQuantityPolicies`

function createStandardQuantityPolicies(canonicalUnit: string, unitSystem?: StandardQuantityUnitSystem): QuantityFieldPolicies

Props

`QuantityFieldRootProps`

as: 타입PrimitiveAs기본값'div'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
defaultDisplayUnit: 타입string기본값undefined
내부 관리 상태에서 처음 사용할 표시 단위입니다.
defaultValue: 타입QuantityValue | null기본값null
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
displayUnit: 타입string기본값undefined
저장된 수량을 표시할 외부 제어 단위입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입QuantityValue | null기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
policies: 타입QuantityFieldPolicies기본값필수
검증, 이동, 선택 동작을 조정하는 정책입니다.
readonly: 타입boolean기본값false
값 확인만 허용하는 읽기 전용 상태 여부입니다.

`QuantityFieldInputProps`

as: 타입PrimitiveAs기본값'input'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
form: 타입string기본값undefined
컨트롤을 연결할 네이티브 form 요소의 ID입니다.
name: 타입string기본값undefined
네이티브 폼 제출에 사용할 이름입니다.
required: 타입boolean기본값false
제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.

`QuantityFieldPartProps`

as: 타입PrimitiveAs기본값파트별로 다름
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

슬롯

`QuantityFieldRootSlotProps`

disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
displayUnit: 타입string
현재 표시 단위입니다.
invalid: 타입boolean
현재 입력이 검증에 실패했는지 여부입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
text: 타입string
현재 값을 표시한 문자열입니다.
value: 타입QuantityValue | null
이 계약이 노출하는 현재 값입니다.

이벤트

`QuantityFieldRoot`

commit: 페이로드{ value: QuantityValue | null; expression: string; displayUnit: string; }
현재 입력을 확정할 때 발생합니다.
update:displayUnit: 페이로드string
새 표시 단위를 요청할 때 발생합니다.
update:modelValue: 페이로드QuantityValue | null
컴포넌트가 외부 제어 값의 변경을 요청할 때 발생합니다.

기타 타입

`StandardQuantityUnitSystem`

type StandardQuantityUnitSystem = 'metric' | 'imperial' | 'all'

`QuantityFieldValueChangeHandler`

type QuantityFieldValueChangeHandler = (value: QuantityValue | null) => void

`QuantityFieldDisplayUnitChangeHandler`

type QuantityFieldDisplayUnitChangeHandler = (value: string) => void

`QuantityFieldCommitHandler`

type QuantityFieldCommitHandler = (details: { value: QuantityValue | null; expression: string; displayUnit: string }) => void

파트

공통 범위: [data-scope="quantity-field"]. 컴포넌트 내부로 스타일을 제한할 때 파트 선택자와 함께 사용합니다.

파트	선택자	역할	추가 속성
`root`	`[data-part="root"]`	컴포넌트 경계와 내부 파트를 묶습니다.	—
`input`	`[data-part="input"]`	편집 값이나 초안을 입력받습니다.	—
`unit-select`	`[data-part="unit-select"]`	숫자 값에 적용할 단위를 선택합니다.	—
`value`	`[data-part="value"]`	현재 확정 값을 표시합니다.	—

키보드 동작

키	동작
`Standard editing keys`	호스트 입력 관례에 따라 텍스트를 편집하고 선택합니다.
`Tab`	기본 텍스트 동작을 유지하며 포커스를 이동합니다.

접근성

이름이 있는 입력이 확정된 수량을 노출하고 단위 선택과 형식화된 출력을 별도로 식별할 수 있게 합니다.

Quantity Field ​

용법 ​

길이 단위 ​

온도 단위 ​

외부 상태 관리 ​

예시 ​

계산식 입력 ​

복합 단위 ​

API ​

함수 ​

createStandardQuantityPolicies ​

Props ​

QuantityFieldRootProps ​

QuantityFieldInputProps ​

QuantityFieldPartProps ​

슬롯 ​

QuantityFieldRootSlotProps ​

이벤트 ​

QuantityFieldRoot ​

기타 타입 ​

StandardQuantityUnitSystem ​

QuantityFieldValueChangeHandler ​

QuantityFieldDisplayUnitChangeHandler ​

QuantityFieldCommitHandler ​

파트 ​

키보드 동작 ​

접근성 ​