Tham chiếu API

Công cụ tùy chỉnh sử dụng main() để trả về cây View. Ở đây chúng tôi giới thiệu cấu trúc tập lệnh, giao diện chạy và các thành phần bản vẽ, đồng thời cung cấp lối vào cho các API khác nhau.

đối tượng toàn cầu

CapDrive cung cấp trực tiếp các đối tượng chung sau trong tập lệnh thiết bị mà không cần phải tự nhập hoặc tạo chúng. Chúng có thể được đọc trong main() và được sử dụng để lấy dữ liệu, thích ứng với môi trường hiển thị, lưu trạng thái tạm thời và ghi nhật ký đầu ra.

sự vật	Mục đích và phương pháp truy cập chung
$data	Dữ liệu lái xe. Đọc mẫu hiện tại qua `$data.current` và đọc mẫu trong 30 giây cuối cùng của chuyến đi này qua `$data.history`.
$env	Môi trường hiển thị của nhạc cụ hiện tại, bao gồm các kích thước có sẵn, màu sắc chủ đề, đơn vị, ngôn ngữ và chế độ hiển thị, chẳng hạn như `$env.width`, `$env.foreground`.
$sessionStorage	Trạng thái tạm thời của phiên bản công cụ hiện tại trong chuyến đi hiện tại. Sử dụng `get(key)` để đọc và `set(key, value)` để lưu; rõ ràng khi kết thúc chuyến đi hoặc tải lại nhạc cụ.
console	Nhật ký kịch bản. Sử dụng `console.log(...)`, `console.warn(...)` và các phương pháp khác để xuất dữ liệu và thông tin chẩn đoán.

$data và $env được Ứng dụng cập nhật và là đầu vào chỉ đọc. Giá trị này được đọc mỗi lần main() được gọi; việc sửa đổi bản sao đã đọc của dữ liệu sẽ không thay đổi dữ liệu lái xe thực tế. $ là một phần của tên đối tượng, hãy sử dụng trực tiếp $env.width và không cần phải viết dưới dạng lệnh gọi hàm.

Xác định nội dung bản vẽ

main() trong tập lệnh công cụ sẽ trả về màn hình được mô tả bởi JSX. Mỗi nút JSX là một View tích hợp sẵn, với các thuộc tính kiểm soát kích thước, màu sắc và các hành vi vẽ khác cũng như các mối quan hệ lồng nhau tạo thành bức tranh cuối cùng.

Kịch bản hoàn chỉnh bên dưới vẽ một số và một hàng đơn vị. VStack sắp xếp hai Text lên xuống, spacing đặt khoảng cách, fontSize đặt cỡ chữ và màu sắc do môi trường hiển thị hiện tại cung cấp.

function main() {
  return (
    <VStack spacing={6}>
      <Text fontSize={48} color={$env.foreground}>
        78
      </Text>
      <Text fontSize={14} color={$env.accent}>
        km/h
      </Text>
    </VStack>
  );
}

Biểu thức JavaScript có thể được sử dụng trong {} của JSX. Thay thế 78 cố định bằng kết quả tính toán và văn bản sẽ thay đổi theo đầu vào; kết quả tính toán cũng có thể được chuyển đến các thuộc tính như màu sắc, kích thước hoặc góc cung.

$data: dữ liệu lái xe

Các trường $data.current đến từ mã định danh đầu vào của công cụ này. Điền giá trị gốc vào Cài đặt đồng hồ → Liên kết đầu vào hoặc chọn tham số OBD và đưa vào định nghĩa quản lý Cấu hình tham số. Điều sau đây giả định rằng mã định danh tương ứng đã được xác định.

Phương thức truy cập ví dụ	Định nghĩa đầu vào và trả về nội dung
`$data.current.speed`	Nhập tốc độ cơ bản, trả về `{ value, unit }`.
`$data.current.gForce`	Đầu vào giá trị G cơ bản, bao gồm `longitudinal`, `lateral`, `combined` và các đơn vị.
`$data.current.location`	Đầu vào vị trí cơ bản, bao gồm kinh độ, vĩ độ và đơn vị.
`$data.current.elapsed`	Đầu vào thời lượng được ghi cơ bản, tính bằng giây.
`$data.current.recording`	Đầu vào trạng thái bản ghi cơ bản, trả về giá trị Boolean.
`$data.current.coolant`	OBD được nhập và trả về `{ value, unit }` hoặc `null` sau khi ràng buộc các thông số của xe.
`$data.current.limit`	Đầu vào dạng số trả về một số trực tiếp.
`$data.current.label`	Nhập văn bản trả về một chuỗi trực tiếp.
`$data.current.showUnit`	Chuyển đổi đầu vào và trả về trực tiếp giá trị Boolean.
`$data.current.style`	Chọn một mục và trả về chuỗi đã chọn.

$data.history bao gồm 30 giây cuối cùng của chuyến đi hiện tại, được sắp xếp từ cũ đến mới và trường lấy mẫu nhất quán với current; đầu vào cố định sử dụng cấu hình hiện tại. Cửa sổ có thể trống hoặc chứa các bài kiểm tra bị thiếu. Giá trị của OBD có thể là một chữ bản đồ, loại này phải được kiểm tra trước tiên. Số 0 có ý nghĩa khác với null. Đầy đủ đầu vào, đơn vị và quy tắc lịch sử.

$env: Môi trường hiển thị

$env mô tả khu vực hiển thị nơi đặt thiết bị hiện tại. Sau khi thay đổi kích thước thẻ, chuyển chủ đề hoặc nhập HUD, Ứng dụng sẽ cung cấp một môi trường cập nhật. Các phép tính dựa trên các giá trị này phải được đặt trong main().

Cánh đồng	Ý nghĩa và cách sử dụng
`$env.width`、`$env.height`	Chiều rộng và chiều cao có sẵn của thiết bị hiện tại nằm trong các điểm trên màn hình. Có thể được sử dụng để tính toán kích thước phông chữ, đường kính hoặc tọa độ điểm cuối.
`$env.foreground`、`$env.accent`	Màu văn bản và màu nhấn của chủ đề hiện tại có thể được chuyển trực tiếp tới `color`, `stroke`, `background` và các thuộc tính màu khác.
`$env.dark`	Có nên sử dụng giao diện tối màu hay không, loại là boolean.
`$env.mode`	Chế độ hiển thị, giá trị là `'instruments'` hoặc `'hud'`.
`$env.speedUnit`	Đơn vị hiển thị tốc độ hiện tại, giá trị là `'km/h'` hoặc `'mph'`. Khi số đọc có đơn vị riêng, `unit` của số đọc sẽ được sử dụng trước tiên.
`$env.language`	Mã nhận dạng ngôn ngữ hiện tại của ứng dụng, chẳng hạn như `'zh-Hans'`.
`$env.reduceMotion`	Cho dù hệ thống đã bật hiệu ứng động giảm hay chưa, bạn có thể điều chỉnh hoạt ảnh lặp lại cho phù hợp.
`$env.obdDevice`	`{ id, name }` cho thiết bị hiện được kết nối hoặc `null` nếu chưa có thiết bị nào sẵn sàng.

Ví dụ: sử dụng Math.min($env.width, $env.height) để có đường kính tối đa phù hợp để đặt một vòng tròn hoàn hảo và sử dụng $env.foreground để làm cho văn bản theo chủ đề. Định nghĩa môi trường hiển thị đầy đủ.

Ví dụ: Làm việc với môi trường dữ liệu và hiển thị

Chọn tốc độ trong cài đặt đồng hồ. Tập lệnh sau đây đọc tốc độ hiện tại, tính toán kích thước phông chữ dựa trên chiều rộng và chiều cao của thẻ, sử dụng màu chủ đề và hiển thị đơn vị do kết quả đọc cung cấp. Một đường ngang được hiển thị khi thiếu vận tốc; số 0 hợp lệ được hiển thị là 0.

function main() {
  const speed = $data.current.speed;
  const fontSize = Math.min(64, $env.width * 0.25, $env.height * 0.5);

  return (
    <VStack spacing={6}>
      <Text fontSize={fontSize} color={$env.foreground}>
        {speed?.value == null ? '—' : Math.round(speed.value)}
      </Text>
      <Text fontSize={14} color={$env.accent}>
        {speed?.unit ?? $env.speedUnit}
      </Text>
    </VStack>
  );
}

Khi dữ liệu được cập nhật, tốc độ mới sẽ được sử dụng cho cuộc gọi tiếp theo; khi kích thước thẻ hoặc chủ đề thay đổi, kích thước phông chữ và màu sắc sẽ sử dụng các giá trị môi trường mới. Nếu bạn cần tích lũy các giá trị đỉnh và các trạng thái khác trong cùng một chuyến đi, bạn có thể tiếp tục sử dụng $sessionStorage; nếu bạn cần kiểm tra đầu vào thực tế, bạn có thể sử dụng console.log('speed', speed) để xuất nhật ký trong quá trình gỡ lỗi.

Cập nhật màn hình

Khi đầu vào hiện tại, định nghĩa đầu vào hoặc môi trường hiển thị thay đổi, CapDrive sẽ cung cấp $data và $env mới nhất, thực thi toàn bộ tệp trong phạm vi cục bộ mới và sau đó gọi main() được xác định lần này. Các phép tính cấp cao nhất cũng được thực hiện lại và các biến thông thường không được giữ lại theo thời gian. Đầu vào giống hệt nhau được bỏ qua; chỉ đầu vào đang chờ xử lý mới nhất được giữ lại trong quá trình xử lý. Chỉ riêng việc bảo trì cửa sổ lịch sử và thay đổi thời gian mẫu nội bộ không kích hoạt quá trình thực thi; những thay đổi đầu vào thời gian được xác định rõ ràng.

Không có tần suất cố định cho chữ viết; cập nhật thực tế phụ thuộc vào đầu vào và thời gian xử lý. Sử dụng $sessionStorage cho trạng thái nhịp; sử dụng animations để chuyển đổi thuộc tính, được thực hiện độc lập ở đầu bản vẽ. main() phải được hoàn thành đồng bộ để tránh các vòng lặp liên tục hoặc chờ đợi chặn.

Các giao diện vận hành liên quan

main(): Nhập kịch bản. Đọc thông tin đầu vào này và trả về đồng bộ View, mảng hoặc nội dung trống cần rút ra.
animations: Đặt các hành vi chuyển tiếp như thời lượng, đường cong và sự lặp lại cho các thay đổi thuộc tính của View.
Color / Gradient: Xây dựng màu, màu HDR, gradient tuyến tính, gradient xuyên tâm và gradient góc.
Nhập và chia sẻ: Hiểu cấu hình, tập lệnh, tài nguyên và phương thức xuất của gói công cụ.

Vẽ các thành phần

Sắp xếp các màn hình thông qua các vùng chứa và đặt các chế độ xem văn bản, đồ họa và dữ liệu vào chúng. Sau đây liệt kê tất cả View tích hợp sẵn theo mục đích; mỗi trang thành phần giải thích cách sử dụng, thuộc tính, hành vi mặc định và các ví dụ kết hợp.

nội dung

Hiển thị số đọc, đơn vị, biểu tượng và hình ảnh hoặc sử dụng khu vực nội dung đồng hồ đo có tiêu đề.

Text

Hiển thị cách đọc, đơn vị hoặc văn bản mô tả. Có thể đặt phông chữ, cỡ chữ, căn chỉnh, ngắt dòng và cắt bớt; nội dung được chuyển đổi thống nhất thành một chuỗi và các giá trị trống được hiển thị dưới dạng trống.

Symbol

Sử dụng SF Symbols để vẽ các biểu tượng hệ thống, chẳng hạn như đồng hồ tốc độ, nhiệt kế. Kích thước phông chữ biểu tượng, trọng lượng phông chữ và phương pháp tô màu có thể được đặt. Biểu tượng cụ thể có sẵn hay không tùy thuộc vào hệ thống thiết bị.

Image

Hiển thị hình ảnh từ tài nguyên thước đo, chẳng hạn như logo, nền trang trí hoặc họa tiết ô xếp. source Sử dụng tên tài nguyên để đặt phương pháp chia tỷ lệ, cắt xén hoặc lặp lại theo kích thước có sẵn.

CardContent

Cung cấp cấu trúc công cụ có tiêu đề, nội dung phù hợp và nội dung. Văn bản renderer sẽ nhận được contentSize trừ đi tiêu đề và lề, có thể được sử dụng để sắp xếp các hình, đồ thị hoặc biểu đồ.

cách trình bày

Sắp xếp nhiều View, phân bổ không gian còn lại và tạo bố cục ngang, dọc, xếp chồng và chia tỷ lệ.

HStack

Sắp xếp phụ đề View từ trái sang phải, phù hợp với sự kết hợp theo chiều ngang của biểu tượng và số, số và đơn vị, v.v. spacing đặt khoảng cách liền kề, alignment đặt căn chỉnh trên cùng và dưới cùng hoặc căn chỉnh đường cơ sở của văn bản trong dòng này.

VStack

Sắp xếp phụ đề View từ trên xuống dưới, phù hợp với sự kết hợp dọc giữa tiêu đề, số chính và đơn vị. spacing đặt khoảng cách liền kề và alignment đặt căn chỉnh trái và phải trong cột này.

ZStack

Xếp chồng nhiều View trong cùng một khu vực, phù hợp với các chỉ số nền, tỷ lệ và trung tâm. Các phần con View được vẽ tuần tự và alignment đặt vị trí căn chỉnh chung của chúng trong vùng chứa.

Spacer

Phân bổ không gian còn lại trong Ngăn xếp để đẩy nội dung sang cả hai bên hoặc dành khoảng cách linh hoạt cho nội dung. minLength đặt độ dài tối thiểu, width hoặc height rõ ràng có thể cố định kích thước theo hướng tương ứng.

RadialLayout

Phân phối tỷ lệ, số hoặc ký hiệu xung quanh một vòng tròn. radius kiểm soát khoảng cách từ tâm đến tâm bố cục của View, còn startAngle và sweepAngle kiểm soát phạm vi phân phối.

RepeatedLayout

Sao chép định kỳ một mẫu trong cửa sổ cắt xén, phù hợp với thang đo và la bàn di chuyển liên tục. period đặt khoảng thời gian lặp lại, value và anchor xác định vị trí căn chỉnh giá trị hiện tại.

đồ họa

Vẽ các dấu tích, tiến trình, đường kẻ và đường viền tùy chỉnh cũng như kiểm soát giao diện bằng các thuộc tính như nền, nét và góc.

Rectangle

Vẽ một hình chữ nhật với các góc bo tròn tùy chọn để sử dụng với nền, thanh tiến trình và đường viền. background lấp đầy phần bên trong, stroke nét, lineWidth và strokePosition kiểm soát độ rộng và vị trí của nét.

Circle

Vẽ một vòng tròn hoặc vòng cung hoàn hảo trong khu vực có sẵn, phù hợp với tiến trình vòng tròn và thang đo mét. Đường kính lấy giá trị nhỏ hơn của chiều rộng và tâm. startAngle và sweepAngle điều khiển phạm vi hiển thị. Khi toàn bộ vòng tròn được đóng lại, nền có thể được lấp đầy.

Ellipse

Vẽ một hình elip hoặc hình cung elip trong một chiều rộng và chiều cao nhất định. Thang hình elip hoặc đường viền trang trí có thể được hình thành bằng góc bắt đầu, góc quét, tô và nét.

Arc

Vẽ một cung hình elip theo góc bắt đầu và góc quét, phù hợp với các cung tỷ lệ và hiển thị tiến trình. Đường viền được xác định bởi chiều rộng và chiều cao. Chiều rộng, điểm cuối và vị trí của nét có thể được cấu hình và nền được phép lấp đầy khi đóng hoàn toàn.

Line

Vẽ một đường thẳng giữa hai điểm cuối trong tọa độ cục bộ. Thích hợp cho các đường chỉ báo, dấu tích và dải phân cách, bạn có thể đặt kiểu màu, chiều rộng, dấu gạch ngang và điểm cuối.

Polyline

Vẽ một đường đa tuyến bằng cách nối một tập hợp các điểm theo trình tự. closed có thể nối điểm cuối cùng và điểm đầu tiên để tạo thành một đường viền khép kín và cho phép lấp đầy; tọa độ sử dụng số điểm trong View hiện tại.

Path

Xây dựng đường dẫn bằng các lệnh như di chuyển, đường thẳng, hình tứ giác, hình khối, hình cung và đóng. Thích hợp để tùy chỉnh con trỏ, đường cong và đường viền kết hợp cũng như thiết lập các quy tắc tô và nét.

Sự kết hợp và vật liệu

Áp dụng các hiệu ứng tổng thể cho nội dung kết hợp hoặc sơn bề mặt vật liệu kính mờ.

Group

Kết hợp nhiều View thành một tổng thể, áp dụng thống nhất độ trong suốt, xoay hoặc các hiệu ứng đặc biệt khác. Con View tuân theo các quy tắc sắp xếp của vùng chứa bên ngoài và các hiệu ứng đặc biệt được áp dụng cho toàn bộ tập hợp kết quả tổng hợp.

Material

Vẽ bề mặt của vật liệu kính mờ, có thể chồng lên văn bản và đồ họa để tạo thành vùng nội dung. type hiện hỗ trợ làm mờ, style kiểm soát độ dày vật liệu; hiệu ứng có thể nhìn thấy phụ thuộc vào nội dung đằng sau nó.

Biểu đồ và Bản đồ

Vẽ chuỗi dữ liệu thành các đường cong và biểu đồ hoặc hiển thị vị trí và tuyến đường.

LineChart

Vẽ chuỗi dữ liệu với các giá trị x/y thực tế dưới dạng đường cong. Phù hợp với các xu hướng như tốc độ và thời gian, hỗ trợ phạm vi tọa độ, trục và nhãn; thiếu giá trị y sẽ làm đứt đoạn dòng.

BarChart

Vẽ từng mục dữ liệu dưới dạng thanh, phù hợp để so sánh các giá trị phân loại. Nó có thể được sắp xếp theo chiều ngang hoặc chiều dọc, đặt phạm vi số, nhãn danh mục và nhãn số, đồng thời hỗ trợ các giá trị dương và âm.

Map

Hiển thị bản đồ, vị trí và tuyến đường trong đồng hồ. Có thể đặt trung tâm máy ảnh, hướng, thu phóng và kiểu bản đồ bằng cách sử dụng path để cung cấp các điểm tuyến đường; theo dõi vị trí của người dùng yêu cầu dữ liệu định vị hợp lệ.

Tệp gõ và khai báo

Các loại phổ biến xác định tập trung các cấu trúc như kích thước, lề, biến đổi, nét, hoạt ảnh và dữ liệu biểu đồ. Trình chỉnh sửa cung cấp các gợi ý loại cho cùng một API và các tệp khai báo cũng có thể được tải xuống để các trình chỉnh sửa bên ngoài sử dụng.

Kiểu dùng chung

capdrive.d.ts