`turtle` — 海龜繪圖¶

引言¶

海龜繪圖是 Logo 中引入的流行幾何繪圖工具的實現，由 Wally Feurzeig、Seymour Papert 和 Cynthia Solomon 於 1967 年開發。

開始使用¶

想象一隻機器海龜從 x-y 平面上的 (0, 0) 開始。在 import turtle 之後，給它命令 turtle.forward(15)，它就會（在螢幕上！）向前移動 15 畫素，並沿著它所面向的方向畫一條線。給它命令 turtle.right(25)，它就會原地順時針旋轉 25 度。

在 Python 中，海龜繪圖提供了一個物理“海龜”（一個帶有筆的小機器人）的表示，它在地板上的一張紙上繪圖。

它是一種有效且經過驗證的方法，讓學習者能夠接觸程式設計概念並與軟體互動，因為它提供了即時、可見的反饋。它還提供了對圖形輸出的通用便捷訪問。

海龜繪圖最初是作為一種教育工具建立的，供教師在課堂上使用。對於需要生成一些圖形輸出的程式設計師來說，它可以在不引入更復雜或外部庫的情況下完成此操作。

教程¶

新使用者應從這裡開始。在本教程中，我們將探討海龜繪圖的一些基礎知識。

啟動海龜環境¶

在 Python shell 中，匯入 turtle 模組的所有物件

from turtle import *

如果遇到 No module named '_tkinter' 錯誤，則必須在系統上安裝 Tk 介面包。

基本繪圖¶

讓海龜向前移動 100 步

forward(100)

您應該會看到（很可能在顯示器上的新視窗中）海龜繪製的一條向東的線。改變海龜的方向，使其向左（逆時針）旋轉 120 度

left(120)

讓我們繼續繪製一個三角形

forward(100)
left(120)
forward(100)

請注意，海龜（由箭頭表示）在您操縱它時會指向不同的方向。

嘗試使用這些命令，以及 backward() 和 right()。

筆控制¶

嘗試更改顏色（例如，color('blue')）和線的寬度（例如，width(3)），然後再次繪圖。

您還可以透過抬起筆在不繪圖的情況下移動海龜：在移動前使用 up()。要再次開始繪圖，請使用 down()。

海龜的位置¶

讓您的海龜回到起點（如果它從螢幕上消失了，這很有用）

home()

主位置位於海龜螢幕的中心。如果您需要知道它們，請使用以下命令獲取海龜的 x-y 座標

pos()

主位置在 (0, 0)。

過一段時間，清理視窗以重新開始可能會有所幫助

clearscreen()

製作演算法圖案¶

使用迴圈，可以構建幾何圖案

for steps in range(100):
    for c in ('blue', 'red', 'green'):
        color(c)
        forward(steps)
        right(30)

——當然，這隻受想象力限制！

讓我們繪製本頁頂部的星形。我們想要紅線，填充黃色

color('red')
fillcolor('yellow')

正如 up() 和 down() 決定是否繪製線條一樣，填充也可以開啟和關閉

begin_fill()

接下來我們將建立一個迴圈

while True:
    forward(200)
    left(170)
    if abs(pos()) < 1:
        break

abs(pos()) < 1 是一個很好的方法來知道海龜何時回到其主位置。

最後，完成填充

end_fill()

（請注意，填充只有在您發出 end_fill() 命令時才會實際發生。）

如何……¶

本節介紹了一些典型的海龜用例和方法。

儘快開始¶

海龜繪圖的樂趣之一是來自簡單命令的即時、視覺化反饋——它是向孩子們介紹程式設計概念的絕佳方式，開銷最小（當然，不僅僅是孩子們）。

turtle 模組透過將其所有基本功能作為函式公開，並可以透過 from turtle import * 使用，從而實現這一點。海龜繪圖教程涵蓋了這種方法。

值得注意的是，許多海龜命令也有更簡潔的等價物，例如 forward() 的 fd()。這些在與打字不熟練的學習者一起工作時特別有用。

您需要在系統上安裝 Tk 介面包 才能使海龜繪圖正常工作。請注意，這並非總是那麼簡單，因此如果您計劃與學習者一起使用海龜繪圖，請提前檢查。

自動開始和結束填充¶

從 Python 3.14 開始，您可以使用 fill() 上下文管理器，而不是 begin_fill() 和 end_fill() 來自動開始和結束填充。以下是一個示例

with fill():
    for i in range(4):
        forward(100)
        right(90)

forward(200)

上面的程式碼等價於

begin_fill()
for i in range(4):
    forward(100)
    right(90)
end_fill()

forward(200)

使用 `turtle` 模組名稱空間¶

使用 from turtle import * 很方便——但請注意，它會匯入大量物件，如果您除了海龜繪圖之外還做其他事情，則可能會遇到名稱衝突（如果您在匯入其他模組的指令碼中使用海龜繪圖，則此問題會變得更加嚴重）。

解決方案是使用 import turtle —— fd() 變為 turtle.fd()，width() 變為 turtle.width() 等等。（如果重複輸入“turtle”變得很麻煩，可以使用例如 import turtle as t。）

在指令碼中使用海龜繪圖¶

建議使用上面立即描述的 turtle 模組名稱空間，例如

import turtle as t
from random import random

for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

然而，還需要另一步——指令碼一結束，Python 也會關閉海龜視窗。將

t.mainloop()

新增到指令碼的末尾。指令碼現在將等待被關閉，並且在它被終止之前不會退出，例如透過關閉海龜繪圖視窗。

使用面向物件的海龜繪圖¶

參見

面向物件介面的解釋

除了非常基本的入門目的，或者儘可能快地嘗試事物之外，使用面向物件的方法進行海龜繪圖更常見，功能也更強大。例如，這允許螢幕上同時出現多個海龜。

在這種方法中，各種海龜命令是物件（主要是 Turtle 物件）的方法。您*可以*在 shell 中使用面向物件的方法，但在 Python 指令碼中更典型。

上面的例子就變成了

from turtle import Turtle
from random import random

t = Turtle()
for i in range(100):
    steps = int(random() * 100)
    angle = int(random() * 360)
    t.right(angle)
    t.fd(steps)

t.screen.mainloop()

注意最後一行。t.screen 是 Screen 的一個例項，一個 Turtle 例項存在於其上；它與海龜一起自動建立。

海龜的螢幕可以定製，例如

t.screen.title('Object-oriented turtle demo')
t.screen.bgcolor("orange")

海龜繪圖參考¶

備註

在以下文件中，給出了函式的引數列表。方法當然有額外的第一個引數*self*，此處省略。

海龜方法¶

海龜移動

移動和繪製: forward() | fd()

backward() | bk() | back()

right() | rt()

left() | lt()

goto() | setpos() | setposition()

teleport()

setx()

sety()

setheading() | seth()

home()

circle()

dot()

stamp()

clearstamp()

clearstamps()

undo()

speed()
獲取海龜狀態: position() | pos()

towards()

xcor()

ycor()

heading()

distance()
設定和測量: degrees()

radians()

畫筆控制

繪圖狀態: pendown() | pd() | down()

penup() | pu() | up()

pensize() | width()

pen()

isdown()
顏色控制: color()

pencolor()

fillcolor()
填充: filling()

fill()

begin_fill()

end_fill()
更多繪圖控制: reset()

clear()

write()

海龜狀態

可見性: showturtle() | st()

hideturtle() | ht()

isvisible()
外觀: shape()

resizemode()

shapesize() | turtlesize()

shearfactor()

tiltangle()

tilt()

shapetransform()

get_shapepoly()

使用事件

onclick()
onrelease()
ondrag()

特殊的海龜方法

poly()
begin_poly()
end_poly()
get_poly()
clone()
getturtle() | getpen()
getscreen()
setundobuffer()
undobufferentries()

TurtleScreen/Screen 的方法¶

視窗控制: bgcolor()

bgpic()

clearscreen()

resetscreen()

screensize()

setworldcoordinates()
動畫控制: no_animation()

delay()

tracer()

update()
使用螢幕事件: listen()

onkey() | onkeyrelease()

onkeypress()

onclick() | onscreenclick()

ontimer()

mainloop() | done()
設定和特殊方法: mode()

colormode()

getcanvas()

getshapes()

register_shape() | addshape()

turtles()

window_height()

window_width()
輸入方法: textinput()

numinput()
Screen 特有的方法: bye()

exitonclick()

save()

setup()

title()

RawTurtle/Turtle 的方法及相應的函式¶

本節中的大多數示例都指的是名為 turtle 的 Turtle 例項。

海龜移動¶

turtle.forward(distance)¶

turtle.fd(distance)¶

引數:: distance – 一個數字（整數或浮點數）

讓海龜沿著其當前方向向前移動指定的 *distance*。

>>> turtle.position()
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
>>> turtle.forward(-75)
>>> turtle.position()
(-50.00,0.00)

turtle.back(distance)¶

turtle.bk(distance)¶

turtle.backward(distance)¶

引數:: distance – 一個數字

讓海龜向後移動 *distance*，方向與海龜當前方向相反。不改變海龜的方向。

>>> turtle.position()
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00,0.00)

turtle.right(angle)¶

turtle.rt(angle)¶

引數:: angle – 一個數字（整數或浮點數）

讓海龜向右轉 *angle* 個單位。（預設單位是度，但可以透過 degrees() 和 radians() 函式設定單位。）角度方向取決於海龜模式，請參見 mode()。

>>> turtle.heading()
22.0
>>> turtle.right(45)
>>> turtle.heading()
337.0

turtle.left(angle)¶

turtle.lt(angle)¶

引數:: angle – 一個數字（整數或浮點數）

讓海龜向左轉 *angle* 個單位。（預設單位是度，但可以透過 degrees() 和 radians() 函式設定單位。）角度方向取決於海龜模式，請參見 mode()。

>>> turtle.heading()
22.0
>>> turtle.left(45)
>>> turtle.heading()
67.0

turtle.goto(x, y=None)¶

turtle.setpos(x, y=None)¶

turtle.setposition(x, y=None)¶

引數:

x – 一個數字或一對/向量的數字
y – 一個數字或 None

如果 *y* 是 None，則 *x* 必須是一對座標或一個 Vec2D（例如 pos() 返回的值）。

將海龜移動到絕對位置。如果筆放下，則畫線。不改變海龜的方向。

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
>>> turtle.setpos((20,80))
>>> turtle.pos()
(20.00,80.00)
>>> turtle.setpos(tp)
>>> turtle.pos()
(0.00,0.00)

turtle.teleport(x, y=None, *, fill_gap=False)¶

引數:

x – 一個數字或 None
y – 一個數字或 None
fill_gap – 一個布林值

將海龜移動到絕對位置。與 goto(x, y) 不同，不會繪製線條。海龜的方向不會改變。如果當前正在填充，則離開後將填充從其中傳送的多邊形，並在傳送後重新開始填充。這可以透過 fill_gap=True 停用，這使得傳送過程中想象的線充當填充屏障，就像在 goto(x, y) 中一樣。

>>> tp = turtle.pos()
>>> tp
(0.00,0.00)
>>> turtle.teleport(60)
>>> turtle.pos()
(60.00,0.00)
>>> turtle.teleport(y=10)
>>> turtle.pos()
(60.00,10.00)
>>> turtle.teleport(20, 30)
>>> turtle.pos()
(20.00,30.00)

3.12 新版功能.

turtle.setx(x)¶

引數:: x – 一個數字（整數或浮點數）

將海龜的第一個座標設定為 *x*，第二個座標不變。

>>> turtle.position()
(0.00,240.00)
>>> turtle.setx(10)
>>> turtle.position()
(10.00,240.00)

turtle.sety(y)¶

引數:: y – 一個數字（整數或浮點數）

將海龜的第二個座標設定為 *y*，第一個座標不變。

>>> turtle.position()
(0.00,40.00)
>>> turtle.sety(-10)
>>> turtle.position()
(0.00,-10.00)

turtle.setheading(to_angle)¶

turtle.seth(to_angle)¶

引數:: to_angle – 一個數字（整數或浮點數）

將海龜的方向設定為 *to_angle*。以下是一些常見的角度方向

標準模式	Logo 模式
0 - 東	0 - 北
90 - 北	90 - 東
180 - 西	180 - 南
270 - 南	270 - 西

>>> turtle.setheading(90)
>>> turtle.heading()
90.0

turtle.home()¶

將海龜移動到原點——座標 (0,0)——並將其方向設定為其起始方向（這取決於模式，參見 mode()）。

>>> turtle.heading()
90.0
>>> turtle.position()
(0.00,-10.00)
>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0

turtle.circle(radius, extent=None, steps=None)¶

引數:

radius – 一個數字
extent – 一個數字（或 None）
steps – 一個整數（或 None）

繪製一個給定 *radius* 的圓。圓心在海龜左側 *radius* 個單位；*extent*——一個角度——決定了圓的哪一部分被繪製。如果未給出 *extent*，則繪製整個圓。如果 *extent* 不是一個完整的圓，則弧線的一個端點是當前畫筆位置。如果 *radius* 為正，則以逆時針方向繪製弧線，否則以順時針方向繪製。最後，海龜的方向會因 *extent* 的大小而改變。

由於圓由內接正多邊形近似，*steps* 決定了使用的步數。如果未給出，將自動計算。可用於繪製正多邊形。

>>> turtle.home()
>>> turtle.position()
(0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(50)
>>> turtle.position()
(-0.00,0.00)
>>> turtle.heading()
0.0
>>> turtle.circle(120, 180)  # draw a semicircle
>>> turtle.position()
(0.00,240.00)
>>> turtle.heading()
180.0

turtle.dot()¶

turtle.dot(size)

turtle.dot(color, /)

turtle.dot(size, color, /)

turtle.dot(size, r, g, b, /)

引數:

size – 一個整數 >= 1（如果給定）
color – 一個顏色字串或一個數字顏色元組

繪製一個直徑為 *size*，使用 *color* 的圓形點。如果未給出 *size*，則使用 pensize+4 和 2*pensize 的最大值。

>>> turtle.home()
>>> turtle.dot()
>>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50)
>>> turtle.position()
(100.00,-0.00)
>>> turtle.heading()
0.0

turtle.stamp()¶

在當前海龜位置將海龜形狀的副本蓋章到畫布上。返回該印章的 stamp_id，可用於透過呼叫 clearstamp(stamp_id) 將其刪除。

>>> turtle.color("blue")
>>> stamp_id = turtle.stamp()
>>> turtle.fd(50)

turtle.clearstamp(stampid)¶

引數:: stampid – 一個整數，必須是之前 stamp() 呼叫的返回值

刪除給定 *stampid* 的印章。

>>> turtle.position()
(150.00,-0.00)
>>> turtle.color("blue")
>>> astamp = turtle.stamp()
>>> turtle.fd(50)
>>> turtle.position()
(200.00,-0.00)
>>> turtle.clearstamp(astamp)
>>> turtle.position()
(200.00,-0.00)

turtle.clearstamps(n=None)¶

引數:: n – 一個整數（或 None）

刪除海龜的所有或前/後 *n* 個印章。如果 *n* 是 None，則刪除所有印章；如果 *n* > 0，則刪除前 *n* 個印章；否則，如果 *n* < 0，則刪除後 *n* 個印章。

>>> for i in range(8):
...     unused_stamp_id = turtle.stamp()
...     turtle.fd(30)
>>> turtle.clearstamps(2)
>>> turtle.clearstamps(-2)
>>> turtle.clearstamps()

turtle.undo()¶

撤銷（重複）最後的海龜操作。可用撤銷操作的數量由撤銷緩衝區的大小決定。

>>> for i in range(4):
...     turtle.fd(50); turtle.lt(80)
...
>>> for i in range(8):
...     turtle.undo()

turtle.speed(speed=None)¶

引數:: speed – 一個介於 0..10 之間的整數或一個速度字串（參見下文）

將海龜的速度設定為 0..10 範圍內的整數值。如果未給出引數，則返回當前速度。

如果輸入數字大於 10 或小於 0.5，則速度設定為 0。速度字串與速度值的對映如下

“fastest”: 0
“fast”: 10
“normal”: 6
“slow”: 3
“slowest”: 1

速度從 1 到 10 逐漸加快線條繪製和海龜轉彎的動畫速度。

注意：*speed* = 0 意味著 *沒有* 動畫發生。向前/向後使海龜跳躍，向左/向右使海龜立即轉向。

>>> turtle.speed()
3
>>> turtle.speed('normal')
>>> turtle.speed()
6
>>> turtle.speed(9)
>>> turtle.speed()
9

告知海龜狀態¶

turtle.position()¶

turtle.pos()¶

返回海龜的當前位置 (x,y)（作為 Vec2D 向量）。

>>> turtle.pos()
(440.00,-0.00)

turtle.towards(x, y=None)¶

引數:

x – 一個數字或一對/向量的數字或一個海龜例項
y – 如果 *x* 是數字，則為數字；否則為 None

返回從海龜位置到 (x,y) 指定位置的線、向量或另一隻海龜之間的角度。這取決於海龜的起始方向，起始方向又取決於模式——“標準”/“世界”或“Logo”。

>>> turtle.goto(10, 10)
>>> turtle.towards(0,0)
225.0

turtle.xcor()¶

返回海龜的 x 座標。

>>> turtle.home()
>>> turtle.left(50)
>>> turtle.forward(100)
>>> turtle.pos()
(64.28,76.60)
>>> print(round(turtle.xcor(), 5))
64.27876

turtle.ycor()¶

返回海龜的 y 座標。

>>> turtle.home()
>>> turtle.left(60)
>>> turtle.forward(100)
>>> print(turtle.pos())
(50.00,86.60)
>>> print(round(turtle.ycor(), 5))
86.60254

turtle.heading()¶

返回海龜的當前方向（值取決於海龜模式，參見 mode()）。

>>> turtle.home()
>>> turtle.left(67)
>>> turtle.heading()
67.0

turtle.distance(x, y=None)¶

引數:

x – 一個數字或一對/向量的數字或一個海龜例項
y – 如果 *x* 是數字，則為數字；否則為 None

返回海龜到 (x,y)、給定向量或給定其他海龜的距離，單位為海龜步長。

>>> turtle.home()
>>> turtle.distance(30,40)
50.0
>>> turtle.distance((30,40))
50.0
>>> joe = Turtle()
>>> joe.forward(77)
>>> turtle.distance(joe)
77.0

測量設定¶

turtle.degrees(fullcircle=360.0)¶

引數:: fullcircle – 一個數字

設定角度測量單位，即設定一個完整圓的“度數”。預設值為 360 度。

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0

>>> # Change angle measurement unit to grad (also known as gon,
>>> # grade, or gradian and equals 1/100-th of the right angle.)
>>> turtle.degrees(400.0)
>>> turtle.heading()
100.0
>>> turtle.degrees(360)
>>> turtle.heading()
90.0

turtle.radians()¶

將角度測量單位設定為弧度。等價於 degrees(2*math.pi)。

>>> turtle.home()
>>> turtle.left(90)
>>> turtle.heading()
90.0
>>> turtle.radians()
>>> turtle.heading()
1.5707963267948966

筆控制¶

繪圖狀態¶

turtle.pendown()¶
turtle.pd()¶
turtle.down()¶: 放下筆——移動時繪圖。

turtle.penup()¶
turtle.pu()¶
turtle.up()¶: 抬起筆——移動時不繪圖。

turtle.pensize(width=None)¶

turtle.width(width=None)¶

引數:: width – 一個正數

設定或返回線條粗細 *width*。如果 resizemode 設定為“auto”且海龜形狀為多邊形，則該多邊形將以相同的線條粗細繪製。如果未給出引數，則返回當前 pensize。

>>> turtle.pensize()
1
>>> turtle.pensize(10)   # from here on lines of width 10 are drawn

turtle.pen(pen=None, **pendict)¶

引數:

pen – 包含以下部分或全部鍵的字典
pendict – 一個或多個以以下鍵作為關鍵字的關鍵字引數

返回或設定筆的屬性，以“筆字典”的形式，包含以下鍵/值對

“shown”: True/False
“pendown”: True/False
“pencolor”: color-string 或 color-tuple
“fillcolor”: color-string 或 color-tuple
“pensize”: 正數
“speed”: 0..10 範圍內的數字
“resizemode”: “auto” 或 “user” 或 “noresize”
“stretchfactor”: (正數, 正數)
“outline”: 正數
“tilt”: 數字

此字典可作為後續呼叫 pen() 的引數，以恢復先前的筆狀態。此外，可以提供一個或多個這些屬性作為關鍵字引數。這可用於在一個語句中設定多個筆屬性。

>>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
>>> sorted(turtle.pen().items())
[('fillcolor', 'black'), ('outline', 1), ('pencolor', 'red'),
 ('pendown', True), ('pensize', 10), ('resizemode', 'noresize'),
 ('shearfactor', 0.0), ('shown', True), ('speed', 9),
 ('stretchfactor', (1.0, 1.0)), ('tilt', 0.0)]
>>> penstate=turtle.pen()
>>> turtle.color("yellow", "")
>>> turtle.penup()
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
>>> turtle.pen(penstate, fillcolor="green")
>>> sorted(turtle.pen().items())[:3]
[('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]

turtle.isdown()¶

如果筆放下，則返回 True，如果抬起，則返回 False。

>>> turtle.penup()
>>> turtle.isdown()
False
>>> turtle.pendown()
>>> turtle.isdown()
True

顏色控制¶

turtle.pencolor()¶

turtle.pencolor(color, /)

turtle.pencolor(r, g, b, /)

返回或設定畫筆顏色。

允許四種輸入格式

pencolor(): 將當前畫筆顏色作為顏色規範字符串或元組返回（參見示例）。可用作另一個 color/pencolor/fillcolor/bgcolor 呼叫的輸入。
pencolor(顏色字串): 將畫筆顏色設定為 *colorstring*，它是一個 Tk 顏色規範字符串，例如 "red"、"yellow" 或 "#33cc8c"。
pencolor((r, g, b)): 將畫筆顏色設定為由 *r*、*g* 和 *b* 元組表示的 RGB 顏色。*r*、*g* 和 *b* 各自必須在 0..colormode 範圍內，其中 colormode 為 1.0 或 255（參見 colormode()）。
pencolor(r, g, b): 將畫筆顏色設定為由 *r*、*g* 和 *b* 表示的 RGB 顏色。*r*、*g* 和 *b* 各自必須在 0..colormode 範圍內。

如果海龜形狀是一個多邊形，則該多邊形的輪廓將以新設定的畫筆顏色繪製。

>>> colormode()
1.0
>>> turtle.pencolor()
'red'
>>> turtle.pencolor("brown")
>>> turtle.pencolor()
'brown'
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
(0.2, 0.8, 0.5490196078431373)
>>> colormode(255)
>>> turtle.pencolor()
(51.0, 204.0, 140.0)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)

turtle.fillcolor()¶

turtle.fillcolor(color, /)

turtle.fillcolor(r, g, b, /)

返回或設定填充顏色。

允許四種輸入格式

fillcolor(): 將當前填充顏色作為顏色規範字符串返回，可能為元組格式（參見示例）。可用作另一個 color/pencolor/fillcolor/bgcolor 呼叫的輸入。
fillcolor(顏色字串): 將填充顏色設定為 *colorstring*，它是一個 Tk 顏色規範字符串，例如 "red"、"yellow" 或 "#33cc8c"。
fillcolor((r, g, b)): 將填充顏色設定為由 *r*、*g* 和 *b* 元組表示的 RGB 顏色。*r*、*g* 和 *b* 各自必須在 0..colormode 範圍內，其中 colormode 為 1.0 或 255（參見 colormode()）。
fillcolor(r, g, b): 將填充顏色設定為由 *r*、*g* 和 *b* 表示的 RGB 顏色。*r*、*g* 和 *b* 各自必須在 0..colormode 範圍內。

如果海龜形狀是一個多邊形，則該多邊形的內部將以新設定的填充顏色繪製。

>>> turtle.fillcolor("violet")
>>> turtle.fillcolor()
'violet'
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor((50, 193, 143))  # Integers, not floats
>>> turtle.fillcolor()
(50.0, 193.0, 143.0)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)

turtle.color()¶

turtle.color(color, /)

turtle.color(r, g, b, /)

turtle.color(pencolor, fillcolor, /)

返回或設定畫筆顏色和填充顏色。

允許多種輸入格式。它們使用 0 到 3 個引數，如下所示

color(): 返回當前畫筆顏色和當前填充顏色，作為 pencolor() 和 fillcolor() 返回的顏色規範字符串或元組對。
color(colorstring)、color((r,g,b))、color(r,g,b): 輸入與 pencolor() 相同，將填充顏色和畫筆顏色都設定為給定值。
color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2)): 等價於 pencolor(colorstring1) 和 fillcolor(colorstring2)，如果使用其他輸入格式則類似。

如果海龜形狀是一個多邊形，則該多邊形的輪廓和內部將以新設定的顏色繪製。

>>> turtle.color("red", "green")
>>> turtle.color()
('red', 'green')
>>> color("#285078", "#a0c8f0")
>>> color()
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))

另請參見：螢幕方法 colormode()。

填充¶

turtle.filling()¶

返回填充狀態（如果正在填充則為 True，否則為 False）。

>>> turtle.begin_fill()
>>> if turtle.filling():
...    turtle.pensize(5)
... else:
...    turtle.pensize(3)

turtle.fill()¶

填充在 with turtle.fill(): 塊中繪製的形狀。

>>> turtle.color("black", "red")
>>> with turtle.fill():
...     turtle.circle(80)

使用 fill() 等價於在填充塊之前新增 begin_fill()，在填充塊之後新增 end_fill()

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

在 3.14 版本加入。

turtle.begin_fill()¶: 在繪製要填充的形狀之前呼叫。

turtle.end_fill()¶

填充上次呼叫 begin_fill() 後繪製的形狀。

自相交多邊形或多個形狀的重疊區域是否被填充取決於作業系統圖形、重疊型別和重疊次數。例如，上面的海龜星形可能全部是黃色，也可能有一些白色區域。

>>> turtle.color("black", "red")
>>> turtle.begin_fill()
>>> turtle.circle(80)
>>> turtle.end_fill()

海龜狀態¶

可見性¶

turtle.hideturtle()¶

turtle.ht()¶

使海龜不可見。在進行復雜繪圖時這樣做是個好主意，因為隱藏海龜會明顯加快繪圖速度。

>>> turtle.hideturtle()

turtle.showturtle()¶

turtle.st()¶

使海龜可見。

>>> turtle.showturtle()

turtle.isvisible()¶

如果海龜顯示，則返回 True，如果隱藏，則返回 False。

>>> turtle.hideturtle()
>>> turtle.isvisible()
False
>>> turtle.showturtle()
>>> turtle.isvisible()
True

外觀¶

turtle.shape(name=None)¶

引數:: name – 一個有效的形狀名稱字串

將海龜形狀設定為給定 *name* 的形狀，如果未給出名稱，則返回當前形狀的名稱。名稱為 *name* 的形狀必須存在於 TurtleScreen 的形狀字典中。最初有以下多邊形形狀：“arrow”、“turtle”、“circle”、“square”、“triangle”、“classic”。要了解如何處理形狀，請參見 Screen 方法 register_shape()。

>>> turtle.shape()
'classic'
>>> turtle.shape("turtle")
>>> turtle.shape()
'turtle'

turtle.resizemode(rmode=None)¶

引數:: rmode – 字串“auto”、“user”或“noresize”之一

將 resizemode 設定為以下值之一：“auto”、“user”、“noresize”。如果未給出 *rmode*，則返回當前 resizemode。不同的 resizemode 具有以下效果

“auto”：根據畫筆大小的值調整海龜的外觀。
“user”：根據由 shapesize() 設定的 stretchfactor 和 outlinewidth（輪廓）的值調整海龜的外觀。
“noresize”：不調整海龜的外觀。

當 shapesize() 與引數一起使用時，將呼叫 resizemode("user")。

>>> turtle.resizemode()
'noresize'
>>> turtle.resizemode("auto")
>>> turtle.resizemode()
'auto'

turtle.shapesize(stretch_wid=None, stretch_len=None, outline=None)¶

turtle.turtlesize(stretch_wid=None, stretch_len=None, outline=None)¶

引數:

stretch_wid – 正數
stretch_len – 正數
outline – 正數

返回或設定筆的屬性 x/y 縮放因子和/或輪廓。將 resizemode 設定為“user”。當且僅當 resizemode 設定為“user”時，海龜將根據其縮放因子顯示拉伸：*stretch_wid* 是垂直於其方向的縮放因子，*stretch_len* 是沿其方向的縮放因子，*outline* 決定形狀輪廓的寬度。

>>> turtle.shapesize()
(1.0, 1.0, 1)
>>> turtle.resizemode("user")
>>> turtle.shapesize(5, 5, 12)
>>> turtle.shapesize()
(5, 5, 12)
>>> turtle.shapesize(outline=8)
>>> turtle.shapesize()
(5, 5, 8)

turtle.shearfactor(shear=None)¶

引數:: shear – 數字（可選）

設定或返回當前的剪下因子。根據給定的剪下因子 shear 剪下海龜形狀，shear 是剪下角的正切。不*改變*海龜的航向（移動方向）。如果未給出 shear：返回當前的剪下因子，即剪下角的正切，透過該角度，平行於海龜航向的線條被剪下。

>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.shearfactor(0.5)
>>> turtle.shearfactor()
0.5

turtle.tilt(angle)¶

引數:: angle – 一個數字

將海龜形狀從其當前傾斜角度旋轉 *angle*，但 *不* 改變海龜的方向（移動方向）。

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(30)
>>> turtle.fd(50)
>>> turtle.tilt(30)
>>> turtle.fd(50)

turtle.tiltangle(angle=None)¶

引數:: angle – 一個數字（可選）

設定或返回當前的傾斜角。如果給定了角度，則無論其當前傾斜角如何，都將海龜形狀旋轉到由角度指定的方向。不*改變*海龜的航向（移動方向）。如果未給出角度：返回當前的傾斜角，即海龜形狀方向與海龜航向（其移動方向）之間的角度。

>>> turtle.reset()
>>> turtle.shape("circle")
>>> turtle.shapesize(5,2)
>>> turtle.tilt(45)
>>> turtle.tiltangle()
45.0

turtle.shapetransform(t11=None, t12=None, t21=None, t22=None)¶

引數:

t11 – 一個數字（可選）
t12 – 一個數字（可選）
t21 – 一個數字（可選）
t12 – 一個數字（可選）

設定或返回海龜形狀的當前變換矩陣。

如果未給出任何矩陣元素，則將變換矩陣作為 4 個元素的元組返回。否則設定給定元素，並根據由第一行 t11、t12 和第二行 t21、t22 組成的矩陣變換海龜形狀。行列式 t11 * t22 - t12 * t21 不得為零，否則會引發錯誤。根據給定矩陣修改 stretchfactor、shearfactor 和 tiltangle。

>>> turtle = Turtle()
>>> turtle.shape("square")
>>> turtle.shapesize(4,2)
>>> turtle.shearfactor(-0.5)
>>> turtle.shapetransform()
(4.0, -1.0, -0.0, 2.0)

turtle.get_shapepoly()¶

以座標對元組的形式返回當前形狀多邊形。這可用於定義新形狀或複合形狀的組成部分。

>>> turtle.shape("square")
>>> turtle.shapetransform(4, -1, 0, 2)
>>> turtle.get_shapepoly()
((50, -20), (30, 20), (-50, 20), (-30, -20))

使用事件¶

turtle.onclick(fun, btn=1, add=None)

引數:

fun – 一個帶有兩個引數的函式，將使用畫布上點選點的座標呼叫該函式
btn – 滑鼠按鈕的編號，預設為 1（左鍵）
add – True 或 False – 如果為 True，則將新增新的繫結，否則它將替換先前的繫結

將 *fun* 繫結到此海龜上的滑鼠點選事件。如果 *fun* 為 None，則移除現有繫結。匿名海龜的示例，即過程方式

>>> def turn(x, y):
...     left(180)
...
>>> onclick(turn)  # Now clicking into the turtle will turn it.
>>> onclick(None)  # event-binding will be removed

turtle.onrelease(fun, btn=1, add=None)¶

引數:

fun – 一個帶有兩個引數的函式，將使用畫布上點選點的座標呼叫該函式
btn – 滑鼠按鈕的編號，預設為 1（左鍵）
add – True 或 False – 如果為 True，則將新增新的繫結，否則它將替換先前的繫結

將 *fun* 繫結到此海龜上的滑鼠按鈕釋放事件。如果 *fun* 是 None，則移除現有繫結。

>>> class MyTurtle(Turtle):
...     def glow(self,x,y):
...         self.fillcolor("red")
...     def unglow(self,x,y):
...         self.fillcolor("")
...
>>> turtle = MyTurtle()
>>> turtle.onclick(turtle.glow)     # clicking on turtle turns fillcolor red,
>>> turtle.onrelease(turtle.unglow) # releasing turns it to transparent.

turtle.ondrag(fun, btn=1, add=None)¶

引數:

fun – 一個帶有兩個引數的函式，將使用畫布上點選點的座標呼叫該函式
btn – 滑鼠按鈕的編號，預設為 1（左鍵）
add – True 或 False – 如果為 True，則將新增新的繫結，否則它將替換先前的繫結

將 *fun* 繫結到此海龜上的滑鼠移動事件。如果 *fun* 是 None，則移除現有繫結。

備註：海龜上滑鼠移動事件的每個序列都以海龜上的滑鼠點選事件開頭。

>>> turtle.ondrag(turtle.goto)

隨後，點選並拖動海龜將在螢幕上移動它，從而產生手繪圖（如果畫筆放下）。

特殊海龜方法¶

turtle.poly()¶

記錄在 with turtle.poly(): 塊中繪製的多邊形的頂點。第一個和最後一個頂點將連線起來。

>>> with turtle.poly():
...     turtle.forward(100)
...     turtle.right(60)
...     turtle.forward(100)

在 3.14 版本加入。

turtle.begin_poly()¶: 開始記錄多邊形的頂點。當前烏龜位置是多邊形的第一個頂點。

turtle.end_poly()¶: 停止記錄多邊形的頂點。當前烏龜位置是多邊形的最後一個頂點。這將與第一個頂點連線。

turtle.get_poly()¶

返回最後記錄的多邊形。

>>> turtle.home()
>>> turtle.begin_poly()
>>> turtle.fd(100)
>>> turtle.left(20)
>>> turtle.fd(30)
>>> turtle.left(60)
>>> turtle.fd(50)
>>> turtle.end_poly()
>>> p = turtle.get_poly()
>>> register_shape("myFavouriteShape", p)

turtle.clone()¶

建立並返回一個烏龜克隆，其位置、朝向和烏龜屬性相同。

>>> mick = Turtle()
>>> joe = mick.clone()

turtle.getturtle()¶

turtle.getpen()¶

返回 Turtle 物件本身。唯一合理的用法：作為返回“匿名烏龜”的函式。

>>> pet = getturtle()
>>> pet.fd(50)
>>> pet
<turtle.Turtle object at 0x...>

turtle.getscreen()¶

返回烏龜正在繪製的 TurtleScreen 物件。然後可以對該物件呼叫 TurtleScreen 方法。

>>> ts = turtle.getscreen()
>>> ts
<turtle._Screen object at 0x...>
>>> ts.bgcolor("pink")

turtle.setundobuffer(size)¶

引數:: size – 一個整數或 None

設定或停用撤消緩衝區。如果 size 是一個整數，則安裝一個給定大小的空撤消緩衝區。size 給出可以透過 undo() 方法/函式撤消的最大烏龜運算元。如果 size 是 None，則停用撤消緩衝區。

>>> turtle.setundobuffer(42)

turtle.undobufferentries()¶

返回撤消緩衝區中的條目數。

>>> while undobufferentries():
...     undo()

複合形狀¶

要使用由不同顏色的多個多邊形組成的複合烏龜形狀，您必須明確使用輔助類 Shape，如下所述：

建立一個型別為“compound”的空 Shape 物件。

使用 addcomponent() 方法向此物件新增任意數量的元件。

例如:

>>> s = Shape("compound")
>>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s.addcomponent(poly1, "red", "blue")
>>> poly2 = ((0,0),(10,-5),(-10,-5))
>>> s.addcomponent(poly2, "blue", "red")

現在將 Shape 新增到螢幕的形狀列表並使用它

>>> register_shape("myshape", s)
>>> shape("myshape")

備註

Shape 類在內部以不同方式被 register_shape() 方法使用。應用程式設計師僅在使用如上所示的複合形狀時才需要處理 Shape 類！

TurtleScreen/Screen 的方法和相應的函式¶

本節中的大多數示例都引用了一個名為 screen 的 TurtleScreen 例項。

視窗控制¶

turtle.bgcolor()¶

turtle.bgcolor(color, /)

turtle.bgcolor(r, g, b, /)

返回或設定 TurtleScreen 的背景顏色。

允許四種輸入格式

bgcolor(): 將當前背景顏色作為顏色規範字符串或作為元組返回（參見示例）。可用作另一個 color/pencolor/fillcolor/bgcolor 呼叫的輸入。
bgcolor(colorstring): 將背景顏色設定為 colorstring，這是一個 Tk 顏色規範字符串，例如 "red"、"yellow" 或 "#33cc8c"。
bgcolor((r, g, b)): 將背景顏色設定為由 r、g 和 b 的元組表示的 RGB 顏色。r、g 和 b 中的每一個都必須在 0..colormode 範圍內，其中 colormode 是 1.0 或 255（參見 colormode()）。
bgcolor(r, g, b): 將背景顏色設定為由 r、g 和 b 表示的 RGB 顏色。r、g 和 b 中的每一個都必須在 0..colormode 範圍內。

>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor("#800080")
>>> screen.bgcolor()
(128.0, 0.0, 128.0)

turtle.bgpic(picname=None)¶

引數:: picname – 一個字串，影像檔案（PNG、GIF、PGM 和 PPM）的名稱或 "nopic"，或 None

設定背景影像或返回當前背景影像的名稱。如果 picname 是檔名，則將相應的影像設定為背景。如果 picname 是 "nopic"，如果存在，則刪除背景影像。如果 picname 是 None，則返回當前背景影像的檔名。

>>> screen.bgpic()
'nopic'
>>> screen.bgpic("landscape.gif")
>>> screen.bgpic()
"landscape.gif"

turtle.clear(): 備註

此 TurtleScreen 方法僅以 clearscreen 名稱作為全域性函式可用。全域性函式 clear 是另一個源自 Turtle 方法 clear 的函式。

turtle.clearscreen()¶: 從 TurtleScreen 中刪除所有繪圖和所有烏龜。將現在空的 TurtleScreen 重置為其初始狀態：白色背景，無背景影像，無事件繫結和追蹤。

turtle.reset(): 備註

此 TurtleScreen 方法僅以 resetscreen 名稱作為全域性函式可用。全域性函式 reset 是另一個源自 Turtle 方法 reset 的函式。

turtle.resetscreen()¶: 將螢幕上的所有烏龜重置為其初始狀態。

turtle.screensize(canvwidth=None, canvheight=None, bg=None)¶

引數:

canvwidth – 正整數，畫布的新寬度（以畫素為單位）
canvheight – 正整數，畫布的新高度（以畫素為單位）
bg – 顏色字串或顏色元組，新的背景顏色

如果未給出任何引數，則返回當前（canvaswidth，canvasheight）。否則，調整烏龜繪製的畫布大小。不改變繪圖視窗。要觀察畫布的隱藏部分，請使用捲軸。使用此方法，可以使之前超出畫布的繪圖部分可見。

>>> screen.screensize()
(400, 300)
>>> screen.screensize(2000,1500)
>>> screen.screensize()
(2000, 1500)

例如，搜尋意外逃脫的烏龜 ;-)

turtle.setworldcoordinates(llx, lly, urx, ury)¶

引數:

llx – 一個數字，畫布左下角的 x 座標
lly – 一個數字，畫布左下角的 y 座標
urx – 一個數字，畫布右上角的 x 座標
ury – 一個數字，畫布右上角的 y 座標

設定使用者定義的座標系並在必要時切換到“世界”模式。這將執行 screen.reset()。如果“世界”模式已經啟用，則所有繪圖將根據新座標重新繪製。

注意：在使用者定義的座標系中，角度可能會出現扭曲。

>>> screen.reset()
>>> screen.setworldcoordinates(-50,-7.5,50,7.5)
>>> for _ in range(72):
...     left(10)
...
>>> for _ in range(8):
...     left(45); fd(2)   # a regular octagon

動畫控制¶

turtle.no_animation()¶

暫時停用烏龜動畫。no_animation 塊內編寫的程式碼將不會被動畫；一旦程式碼塊退出，繪圖將出現。

>>> with screen.no_animation():
...     for dist in range(2, 400, 2):
...         fd(dist)
...         rt(90)

在 3.14 版本加入。

turtle.delay(delay=None)¶

引數:: delay – 正整數

設定或返回以毫秒為單位的繪圖 delay。（這大約是兩次連續畫布更新之間的時間間隔。）繪圖延遲越長，動畫越慢。

可選引數

>>> screen.delay()
10
>>> screen.delay(5)
>>> screen.delay()
5

turtle.tracer(n=None, delay=None)¶

引數:

n – 非負整數
delay – 非負整數

開啟/關閉烏龜動畫並設定更新繪圖的延遲。如果給出 n，則只執行每第 n 次常規螢幕更新。（可用於加速複雜圖形的繪製。）不帶引數呼叫時，返回當前儲存的 n 值。第二個引數設定延遲值（參見 delay()）。

>>> screen.tracer(8, 25)
>>> dist = 2
>>> for i in range(200):
...     fd(dist)
...     rt(90)
...     dist += 2

turtle.update()¶: 執行 TurtleScreen 更新。在關閉追蹤器時使用。

另請參見 RawTurtle/Turtle 方法 speed()。

使用螢幕事件¶

turtle.listen(xdummy=None, ydummy=None)¶: 將焦點設定在 TurtleScreen 上（以便收集按鍵事件）。提供虛擬引數是為了能夠將 listen() 傳遞給 onclick 方法。

turtle.onkey(fun, key)¶

turtle.onkeyrelease(fun, key)¶

引數:

fun – 一個無引數的函式或 None
key – 字串：鍵（例如“a”）或鍵符號（例如“space”）

將 fun 繫結到按鍵的鬆開事件。如果 fun 是 None，則刪除事件繫結。注意：為了能夠註冊按鍵事件，TurtleScreen 必須具有焦點。（參見方法 listen()。）

>>> def f():
...     fd(50)
...     lt(60)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onkeypress(fun, key=None)¶

引數:

fun – 一個無引數的函式或 None
key – 字串：鍵（例如“a”）或鍵符號（例如“space”）

如果給出 key，則將 fun 繫結到按鍵的按下事件；如果未給出 key，則繫結到任何按鍵的按下事件。注意：為了能夠註冊按鍵事件，TurtleScreen 必須具有焦點。（參見方法 listen()。）

>>> def f():
...     fd(50)
...
>>> screen.onkey(f, "Up")
>>> screen.listen()

turtle.onclick(fun, btn=1, add=None)¶

turtle.onscreenclick(fun, btn=1, add=None)¶

引數:

fun – 一個帶有兩個引數的函式，將使用畫布上點選點的座標呼叫該函式
btn – 滑鼠按鈕的編號，預設為 1（左鍵）
add – True 或 False – 如果為 True，則將新增新的繫結，否則它將替換先前的繫結

將 fun 繫結到此螢幕上的滑鼠點選事件。如果 fun 是 None，則刪除現有繫結。

名為 screen 的 TurtleScreen 例項和名為 turtle 的 Turtle 例項的示例

>>> screen.onclick(turtle.goto) # Subsequently clicking into the TurtleScreen will
>>>                             # make the turtle move to the clicked point.
>>> screen.onclick(None)        # remove event binding again

備註

此 TurtleScreen 方法僅以 onscreenclick 名稱作為全域性函式可用。全域性函式 onclick 是另一個源自 Turtle 方法 onclick 的函式。

turtle.ontimer(fun, t=0)¶

引數:

fun – 一個無引數的函式
t – 一個 >= 0 的數字

安裝一個計時器，在 t 毫秒後呼叫 fun。

>>> running = True
>>> def f():
...     if running:
...         fd(50)
...         lt(60)
...         screen.ontimer(f, 250)
>>> f()   ### makes the turtle march around
>>> running = False

turtle.mainloop()¶

turtle.done()¶

啟動事件迴圈 - 呼叫 Tkinter 的 mainloop 函式。必須是海龜繪圖程式中的最後一條語句。如果指令碼在 IDLE 的 -n 模式（無子程序）下執行 - 用於互動式使用海龜繪圖，則不得使用此函式。

>>> screen.mainloop()

輸入方法¶

turtle.textinput(title, prompt)¶

引數:

title – 字串
prompt – 字串

彈出一個對話視窗，用於輸入字串。引數 title 是對話視窗的標題，prompt 是主要描述要輸入什麼資訊的文字。返回輸入的字串。如果對話方塊被取消，則返回 None。

>>> screen.textinput("NIM", "Name of first player:")

turtle.numinput(title, prompt, default=None, minval=None, maxval=None)¶

引數:

title – 字串
prompt – 字串
default – 數字（可選）
minval – 數字（可選）
maxval – 數字（可選）

彈出一個對話視窗，用於輸入數字。title 是對話視窗的標題，prompt 是主要描述要輸入什麼數字資訊的文字。default：預設值，minval：輸入的最小值，maxval：輸入的整數。如果給定，輸入的數字必須在 minval..maxval 範圍內。如果不是，將發出提示並保持對話方塊開啟以進行更正。返回輸入的數字。如果對話方塊被取消，則返回 None。

>>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000)

設定和特殊方法¶

turtle.mode(mode=None)¶

引數:: mode – 字串之一：“standard”、“logo”或“world”

設定烏龜模式（“standard”、“logo”或“world”）並執行重置。如果未給出模式，則返回當前模式。

“standard”模式與舊的 turtle 相容。“logo”模式與大多數 Logo 烏龜圖形相容。“world”模式使用使用者定義的“世界座標”。注意：在此模式下，如果 x/y 單位比率不等於 1，角度可能會出現扭曲。

模式	初始烏龜朝向	正角度
“standard”	向右（東）	逆時針
“logo”	向上（北）	順時針

>>> mode("logo")   # resets turtle heading to north
>>> mode()
'logo'

turtle.colormode(cmode=None)¶

引數:: cmode – 值 1.0 或 255 之一

返回顏色模式或將其設定為 1.0 或 255。隨後，顏色三元組的 r、g、b 值必須在 0..*cmode* 範圍內。

>>> screen.colormode(1)
>>> turtle.pencolor(240, 160, 80)
Traceback (most recent call last):
     ...
TurtleGraphicsError: bad color sequence: (240, 160, 80)
>>> screen.colormode()
1.0
>>> screen.colormode(255)
>>> screen.colormode()
255
>>> turtle.pencolor(240,160,80)

turtle.getcanvas()¶

返回此 TurtleScreen 的 Canvas。對了解 Tkinter Canvas 用法的內部人員很有用。

>>> cv = screen.getcanvas()
>>> cv
<turtle.ScrolledCanvas object ...>

turtle.getshapes()¶

返回所有當前可用烏龜形狀名稱的列表。

>>> screen.getshapes()
['arrow', 'blank', 'circle', ..., 'turtle']

turtle.register_shape(name, shape=None)¶

turtle.addshape(name, shape=None)¶

此函式有四種不同的呼叫方式：

name 是影像檔案（PNG、GIF、PGM 和 PPM）的名稱，shape 是 None：安裝相應的影像形狀。
```
>>> screen.register_shape("turtle.gif")
```
備註

影像形狀在烏龜轉向時不會旋轉，因此它們不會顯示烏龜的朝向！
name 是任意字串，shape 是影像檔案（PNG、GIF、PGM 和 PPM）的名稱：安裝相應的影像形狀。
```
>>> screen.register_shape("turtle", "turtle.gif")
```
備註

影像形狀在烏龜轉向時不會旋轉，因此它們不會顯示烏龜的朝向！
name 是任意字串，shape 是座標對的元組：安裝相應的多邊形形狀。
```
>>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3)))
```
name 是任意字串，shape 是（複合）Shape 物件：安裝相應的複合形狀。

將烏龜形狀新增到 TurtleScreen 的形狀列表。只有這樣註冊的形狀才能透過發出命令 shape(shapename) 使用。

版本 3.14 中已更改: 添加了對 PNG、PGM 和 PPM 影像格式的支援。可以指定形狀名稱和影像檔名。

turtle.turtles()¶

返回螢幕上的烏龜列表。

>>> for turtle in screen.turtles():
...     turtle.color("red")

turtle.window_height()¶

返回烏龜視窗的高度。

>>> screen.window_height()
480

turtle.window_width()¶

返回烏龜視窗的寬度。

>>> screen.window_width()
640

Screen 特有的方法，未從 TurtleScreen 繼承¶

turtle.bye()¶: 關閉海龜圖形視窗。

turtle.exitonclick()¶

將 bye() 方法繫結到螢幕上的滑鼠點選事件。

如果配置字典中的值“using_IDLE”為 False（預設值），則也進入主迴圈。注意：如果使用帶有 -n 開關（無子程序）的 IDLE，則此值應在 turtle.cfg 中設定為 True。在這種情況下，IDLE 自己的主迴圈也對客戶端指令碼處於活動狀態。

turtle.save(filename, overwrite=False)¶

將當前烏龜繪圖（和烏龜）儲存為 PostScript 檔案。

引數:

filename – 儲存的 PostScript 檔案的路徑
overwrite – 如果為 False 且已存在具有給定檔名的檔案，則函式將引發 FileExistsError。如果為 True，則將覆蓋檔案。

>>> screen.save("my_drawing.ps")
>>> screen.save("my_drawing.ps", overwrite=True)

在 3.14 版本加入。

turtle.setup(width=_CFG['width'], height=_CFG['height'], startx=_CFG['leftright'], starty=_CFG['topbottom'])¶

設定主視窗的大小和位置。引數的預設值儲存在配置字典中，可以透過 turtle.cfg 檔案更改。

引數:

width – 如果是整數，則為畫素大小；如果是浮點數，則為螢幕的一部分；預設為螢幕的 50%
height – 如果是整數，則為畫素高度；如果是浮點數，則為螢幕的一部分；預設為螢幕的 75%
startx – 如果為正，則為距螢幕左邊緣的起始位置（以畫素為單位）；如果為負，則為距右邊緣的起始位置；如果為 None，則水平居中視窗
starty – 如果為正，則為距螢幕上邊緣的起始位置（以畫素為單位）；如果為負，則為距下邊緣的起始位置；如果為 None，則垂直居中視窗

>>> screen.setup (width=200, height=200, startx=0, starty=0)
>>>              # sets window to 200x200 pixels, in upper left of screen
>>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
>>>              # sets window to 75% of screen by 50% of screen and centers

turtle.title(titlestring)¶

引數:: titlestring – 顯示在海龜繪圖視窗標題欄中的字串

將海龜視窗的標題設定為 titlestring。

>>> screen.title("Welcome to the turtle zoo!")

公共類¶

class turtle.RawTurtle(canvas)¶

class turtle.RawPen(canvas)¶

引數:: canvas – 一個 tkinter.Canvas、一個 ScrolledCanvas 或一個 TurtleScreen

建立一個烏龜。該烏龜具有上述所有“Turtle/RawTurtle 方法”中描述的方法。

class turtle.Turtle¶: RawTurtle 的子類，具有相同的介面，但會在第一次需要時自動在預設的 Screen 物件上繪圖。

class turtle.TurtleScreen(cv)¶

引數:: cv – 一個 tkinter.Canvas

提供面向螢幕的方法，例如 bgcolor() 等，如上所述。

class turtle.Screen¶: TurtleScreen 的子類，增加了四個方法。

class turtle.ScrolledCanvas(master)¶

引數:: master – 包含 ScrolledCanvas 的 Tkinter 小部件，即帶有捲軸的 Tkinter 畫布

由 Screen 類使用，因此自動提供 ScrolledCanvas 作為烏龜的遊樂場。

class turtle.Shape(type_, data)¶

引數:: type_ – 字串之一：“polygon”、“image”、“compound”

建模形狀的資料結構。對 (type_, data) 必須遵循此規範：

type_	資料
“polygon”	多邊形元組，即座標對的元組
“image”	影像（此形式僅在內部使用！）
“compound”	`None`（複合形狀必須使用 `addcomponent()` 方法構建）

addcomponent(poly, fill, outline=None)¶

引數:

poly – 多邊形，即數字對的元組
fill – poly 將填充的顏色
outline – 多邊形輪廓的顏色（如果給出）

示例

>>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
>>> s = Shape("compound")
>>> s.addcomponent(poly, "red", "blue")
>>> # ... add more components and then use register_shape()

參見複合形狀。

class turtle.Vec2D(x, y)¶

一個二維向量類，用作實現海龜圖形的輔助類。可能對海龜圖形程式也有用。派生自元組，所以向量是一個元組！

提供（對於 a, b 向量，k 數字）

a + b 向量加法
a - b 向量減法
a * b 內積
k * a 和 a * k 與標量相乘
abs(a) a 的絕對值
a.rotate(angle) 旋轉

解釋¶

烏龜物件在螢幕物件上繪製，烏龜面向物件介面中有許多關鍵類可用於建立它們並使它們相互關聯。

如果不存在 Screen 例項，Turtle 例項將自動建立一個。

Turtle 是 RawTurtle 的子類，它不會自動建立繪圖表面——需要為其提供或建立一個畫布。該畫布可以是 tkinter.Canvas、ScrolledCanvas 或 TurtleScreen。

TurtleScreen 是烏龜的基本繪圖表面。Screen 是 TurtleScreen 的子類，幷包含一些附加方法，用於管理其外觀（包括大小和標題）和行為。TurtleScreen 的建構函式需要一個 tkinter.Canvas 或一個 ScrolledCanvas 作為引數。

海龜圖形的函式式介面使用 Turtle 和 TurtleScreen/Screen 的各種方法。在幕後，每當呼叫源自 Screen 方法的函式時，都會自動建立一個螢幕物件。類似地，每當呼叫源自 Turtle 方法的任何函式時，都會自動建立一個烏龜物件。

要在螢幕上使用多個烏龜，必須使用面向物件的介面。

幫助和配置¶

如何使用幫助¶

Screen 和 Turtle 類的公共方法透過文件字串進行了廣泛記錄。因此，這些方法可以透過 Python 幫助設施用作線上幫助。

在使用 IDLE 時，工具提示會顯示鍵入的函式/方法呼叫的簽名和文件字串的第一行。

對方法或函式呼叫 help() 會顯示文件字串

>>> help(Screen.bgcolor)
Help on method bgcolor in module turtle:

bgcolor(self, *args) unbound turtle.Screen method
    Set or return backgroundcolor of the TurtleScreen.

    Arguments (if given): a color string or three numbers
    in the range 0..colormode or a 3-tuple of such numbers.


    >>> screen.bgcolor("orange")
    >>> screen.bgcolor()
    "orange"
    >>> screen.bgcolor(0.5,0,0.5)
    >>> screen.bgcolor()
    "#800080"

>>> help(Turtle.penup)
Help on method penup in module turtle:

penup(self) unbound turtle.Turtle method
    Pull the pen up -- no drawing when moving.

    Aliases: penup | pu | up

    No argument

    >>> turtle.penup()

派生自方法的函式的文件字串具有修改後的形式

>>> help(bgcolor)
Help on function bgcolor in module turtle:

bgcolor(*args)
    Set or return backgroundcolor of the TurtleScreen.

    Arguments (if given): a color string or three numbers
    in the range 0..colormode or a 3-tuple of such numbers.

    Example::

      >>> bgcolor("orange")
      >>> bgcolor()
      "orange"
      >>> bgcolor(0.5,0,0.5)
      >>> bgcolor()
      "#800080"

>>> help(penup)
Help on function penup in module turtle:

penup()
    Pull the pen up -- no drawing when moving.

    Aliases: penup | pu | up

    No argument

    Example:
    >>> penup()

這些修改後的文件字串在匯入時與派生自方法的函式定義一起自動建立。

文件字串翻譯成不同語言¶

有一個實用程式可以建立一個字典，其鍵是方法名稱，值是 Screen 和 Turtle 類公共方法的文件字串。

turtle.write_docstringdict(filename='turtle_docstringdict')¶

引數:: filename – 字串，用作檔名

建立文件字串字典並將其寫入具有給定檔名的 Python 指令碼。此函式必須顯式呼叫（海龜圖形類不使用它）。文件字串字典將寫入 Python 指令碼 filename.py。它旨在用作將文件字串翻譯成不同語言的模板。

如果您（或您的學生）希望使用 turtle 並在您的母語中獲得線上幫助，您必須翻譯文件字串並將生成的檔案儲存為例如 turtle_docstringdict_german.py。

如果您在 turtle.cfg 檔案中有相應的條目，則此字典將在匯入時讀取並替換原始的英文文件字串。

撰寫本文時，有德語和義大利語的文件字串字典。（請求請傳送至 glingl@aon.at。）

如何配置螢幕和烏龜¶

內建的預設配置模仿了舊海龜模組的外觀和行為，以保持最佳的相容性。

如果您想使用不同的配置，更好地反映此模組的特性或更適合您的需求（例如，在課堂上使用），您可以準備一個配置檔案 turtle.cfg，該檔案將在匯入時讀取並根據其設定修改配置。

內建配置將對應於以下 turtle.cfg

width = 0.5
height = 0.75
leftright = None
topbottom = None
canvwidth = 400
canvheight = 300
mode = standard
colormode = 1.0
delay = 10
undobuffersize = 1000
shape = classic
pencolor = black
fillcolor = black
resizemode = noresize
visible = True
language = english
exampleturtle = turtle
examplescreen = screen
title = Python Turtle Graphics
using_IDLE = False

所選條目的簡要說明

前四行對應於 Screen.setup 方法的引數。
第 5 行和第 6 行對應於方法 Screen.screensize 的引數。
shape 可以是任何內建形狀，例如：箭頭、烏龜等。有關更多資訊，請嘗試 help(shape)。
如果您不想使用填充顏色（即讓烏龜透明），您必須寫入 fillcolor = ""（但所有非空字串在 cfg 檔案中不得帶引號）。
如果您想反映烏龜的狀態，您必須使用 resizemode = auto。
如果您設定例如 language = italian，則文件字串字典 turtle_docstringdict_italian.py 將在匯入時載入（如果存在於匯入路徑中，例如與 turtle 相同的目錄中）。
條目 exampleturtle 和 examplescreen 定義了這些物件在文件字串中出現的名稱。方法文件字串到函式文件字串的轉換將從文件字串中刪除這些名稱。
using_IDLE：如果您經常使用 IDLE 及其 -n 開關（“無子程序”），請將其設定為 True。這將阻止 exitonclick() 進入主迴圈。

turtle 儲存的目錄中可以有一個 turtle.cfg 檔案，當前工作目錄中也可以有一個附加檔案。後者將覆蓋第一個檔案的設定。

Lib/turtledemo 目錄包含一個 turtle.cfg 檔案。您可以將其作為示例進行研究，並在執行演示時檢視其效果（最好不要從演示檢視器中執行）。

`turtledemo` — 演示指令碼¶

turtledemo 包包含一組演示指令碼。這些指令碼可以使用隨附的演示檢視器執行和檢視，如下所示：

python -m turtledemo

或者，您可以單獨執行演示指令碼。例如，

python -m turtledemo.bytedesign

turtledemo 包目錄包含：

一個演示檢視器 __main__.py，可用於同時檢視指令碼原始碼並執行它們。
多個指令碼演示了 turtle 模組的不同功能。示例可透過“示例”選單訪問。它們也可以獨立執行。
一個 turtle.cfg 檔案，作為如何編寫和使用此類檔案的示例。

演示指令碼是：

名稱	描述	特性
bytedesign	複雜的經典海龜圖形圖案	`tracer()`, delay, `update()`
chaos	繪製 Verhulst 動力學，表明計算機的計算有時會產生與常識預期相悖的結果	世界座標
clock	顯示您計算機時間的模擬時鐘	烏龜作為時鐘指標，ontimer
colormixer	r、g、b 實驗	`ondrag()`
forest	3 棵廣度優先樹	隨機化
fractalcurves	Hilbert & Koch 曲線	遞迴
lindenmayer	民族數學 (印度 kolams)	L-系統
minimal_hanoi	漢諾塔	矩形烏龜作為漢諾盤（形狀，形狀大小）
nim	與電腦玩經典的尼姆遊戲，三堆火柴。	烏龜作為尼姆棒，事件驅動（滑鼠，鍵盤）
paint	超級簡約的繪圖程式	`onclick()`
peace	基本	烏龜：外觀和動畫
penrose	用風箏和飛鏢進行非週期性平鋪	`stamp()`
planet_and_moon	引力系統模擬	複合形狀，`Vec2D`
rosette	來自維基百科關於烏龜圖形的文章中的圖案	`clone()`, `undo()`
round_dance	跳舞的烏龜成對反向旋轉	複合形狀，克隆形狀大小，傾斜，獲取形狀多邊形，更新
sorting_animate	不同排序方法的視覺化演示	簡單對齊，隨機化
tree	一個（圖形）廣度優先樹（使用生成器）	`clone()`
two_canvases	簡單設計	兩個畫布上的烏龜
yinyang	另一個基本示例	`circle()`

玩得開心！

自 Python 2.6 以來的更改¶

方法 Turtle.tracer、Turtle.window_width 和 Turtle.window_height 已被刪除。具有這些名稱和功能的方法現在僅作為 Screen 的方法可用。派生自這些方法的函式仍然可用。（實際上，在 Python 2.6 中，這些方法僅僅是相應的 TurtleScreen/Screen 方法的重複。）
方法 Turtle.fill() 已被刪除。begin_fill() 和 end_fill() 的行為略有改變：現在每個填充過程都必須以 end_fill() 呼叫結束。
添加了一個方法 Turtle.filling。它返回一個布林值：如果正在進行填充過程，則為 True，否則為 False。此行為對應於 Python 2.6 中不帶引數的 fill() 呼叫。

自 Python 3.0 以來的更改¶

已新增 Turtle 方法 shearfactor()、shapetransform() 和 get_shapepoly()。因此，現在可以使用完整範圍的常規線性變換來變換烏龜形狀。tiltangle() 的功能已增強：它現在可用於獲取或設定傾斜角度。
已新增 Screen 方法 onkeypress() 作為 onkey() 的補充。由於後者將操作繫結到按鍵釋放事件，因此也為其添加了一個別名：onkeyrelease()。
已新增 Screen.mainloop 方法，因此在使用 Screen 和 Turtle 物件時，不再需要使用獨立的 mainloop() 函式。
已新增兩種輸入方法：Screen.textinput 和 Screen.numinput。這些方法會彈出輸入對話方塊，並分別返回字串和數字。

turtle — 海龜繪圖¶

引言¶

開始使用¶

教程¶

啟動海龜環境¶

基本繪圖¶

筆控制¶

海龜的位置¶

製作演算法圖案¶

如何……¶

儘快開始¶

自動開始和結束填充¶

使用 turtle 模組名稱空間¶

在指令碼中使用海龜繪圖¶

使用面向物件的海龜繪圖¶

海龜繪圖參考¶

海龜方法¶

TurtleScreen/Screen 的方法¶

RawTurtle/Turtle 的方法及相應的函式¶

海龜移動¶

告知海龜狀態¶

測量設定¶

筆控制¶

繪圖狀態¶

顏色控制¶

填充¶

更多繪圖控制¶

海龜狀態¶

可見性¶

外觀¶

使用事件¶

特殊海龜方法¶

複合形狀¶

TurtleScreen/Screen 的方法和相應的函式¶

視窗控制¶

動畫控制¶

使用螢幕事件¶

輸入方法¶

設定和特殊方法¶

Screen 特有的方法，未從 TurtleScreen 繼承¶

公共類¶

解釋¶

幫助和配置¶

如何使用幫助¶

文件字串翻譯成不同語言¶

如何配置螢幕和烏龜¶

turtledemo — 演示指令碼¶

自 Python 2.6 以來的更改¶

自 Python 3.0 以來的更改¶

`turtle` — 海龜繪圖¶

使用 `turtle` 模組名稱空間¶

`turtledemo` — 演示指令碼¶